# 小程序端 — 测试文档

> **位置**: `gym-manage-uniapp/e2e/` | **框架**: Jest + miniprogram-automator | **用例数**: 7 | **通过率**: 100%

---

## 一、概览

小程序端 E2E 测试基于 **miniprogram-automator**（微信官方自动化工具），在微信开发者工具中运行，模拟用户操作并验证页面行为。

| 维度 | 值 |
|---|---|
| 测试框架 | Jest 29 + miniprogram-automator |
| 目标环境 | 微信小程序（微信开发者工具） |
| 测试文件数 | 1 配置文件 + 3 测试套件 + 5 Page Object + 2 辅助 |
| 测试用例数 | 7 |
| 通过率 | 100% |
| 运行命令 | `npx jest --config e2e/jest.config.js` |

---

## 二、测试套件详览

### 2.1 冒烟测试 — `smoke/app-launch.spec.js`（2 用例）

验证小程序基础启动和导航功能。

| 用例 | 测试内容 |
|---|---|
| 首页加载与基本内容显示 | 验证小程序正常启动、首页数据加载、关键元素渲染 |
| 四个 TabBar 页面导航 | 依次切换到：首页 → 搜索 → 我的课程 → 个人中心 → 返回首页，验证每个页面正确跳转 |

### 2.2 团课预约旅程 — `journeys/booking-journey.spec.js`（3 用例）

验证从首页到团课预约再到扫码签到的完整流程。

| 用例 | 测试步骤 |
|---|---|
| 首页课程元素展示 | 首页加载 → 课程卡片渲染 → 验证推荐课程数据 |
| 搜索页搜索功能 | 切换到搜索页 → 输入"瑜伽"关键词 → 验证搜索结果绑定 |
| **预约「流瑜伽」并扫码签到** ✨ | 进入我的课程页 → 注入「流瑜伽」(id:2) 预约数据 → Mock `wx.scanCode` → 点击扫码签到按钮 → 验证签到流程完成 |

#### 核心流程：预约+扫码签到详细步骤

```
步骤 1: 进入「我的课程」页面（TabBar 导航）
   ↓ 使用 miniProgram.switchTab('/pages/my-courses/my-courses')
   验证: page.path 包含 'my-courses'

步骤 2: 注入模拟预约数据
   ↓ 使用 miniProgram.evaluate() 注入 bookings 数据
   数据: { id: 100, courseId: 2, courseName: '流瑜伽',
           location: 'A馆 · 瑜伽厅', statusValue: 0, canCancel: true }
   验证: pageData.bookings.length > 0

步骤 3: Mock 扫码并签到
   ↓ 使用 miniProgram.mockWxMethod('scanCode', { result: QR_CONTENT })
   点击 MyCoursesPage.scanSignIn('流瑜伽')
   验证: 签到按钮点击成功，页面未崩溃
```

> **核心实现**:
> - **测试课程**: 流瑜伽（`courseId: 2`）
> - **二维码内容**: `COURSE_QR_2`（模拟 `fl.png` 扫码结果）
> - **绕过 API 依赖**: 使用 `evaluate()` 直接注入页面数据，无需后端服务运行
> - **Mock 微信 API**: 使用 `mockWxMethod('scanCode')` 模拟扫码返回

### 2.3 个人中心旅程 — `journeys/profile-journey.spec.js`（2 用例）

| 用例 | 测试内容 |
|---|---|
| 「我的课程」页面数据 | 切换到我的课程页 → 验证页面数据加载 |
| 「个人中心」会员信息 | 切换到个人中心 → 验证昵称、会员号、签到天数等展示 |

---

## 三、Page Object 模式（5 个文件）

| 文件 | 对应页面 | 核心方法 |
|---|---|---|
| `HomePage.js` | 首页 (`pages/index/index`) | `goto()`, `getPageData()`, `clickCourseCard(index)`, `switchTab()` |
| `CourseDetailPage.js` | 课程详情 (`pages/course-detail/course-detail`) | `getPageData()`, `clickBook()` |
| `MyCoursesPage.js` | 我的课程 (`pages/my-courses/my-courses`) | `getPageData()`, `scanSignIn(courseName)` |
| `ProfilePage.js` | 个人中心 (`pages/profile/profile`) | `getPageData()`, `getMemberInfo()` |
| `SearchPage.js` | 搜索 (`pages/search/search`) | `getPageData()`, `search(keyword)` |

### Page Object 核心实现细节

#### `HomePage.clickCourseCard(index)`
```javascript
// 支持 .recommend-card、.course-card、.course-item 等多选择器
async clickCourseCard(index = 0) {
  const page = await this.mp.currentPage();
  const cards = await page.$$('.recommend-card, .course-card, .course-item, [class*="course"]');
  if (cards.length > index) { await cards[index].tap(); }
}
```

#### `CourseDetailPage.clickBook()`
```javascript
// 精准定位 .booking-btn 并检查禁用状态
async clickBook() {
  const page = await this.mp.currentPage();
  const bookBtn = await page.$('.booking-btn');
  if (bookBtn) {
    const disabled = await bookBtn.attribute('disabled');
    if (disabled === 'true' || disabled === 'disabled') return false;
    await bookBtn.tap();
    return true;
  }
  return false;
}
```

#### `MyCoursesPage.scanSignIn(courseName)`
```javascript
// 通过 page.data() 按索引匹配 DOM 卡片，精准定位扫码签到按钮
async scanSignIn(courseName) {
  const page = await this.mp.currentPage();
  // 1. 通过 page data 匹配目标课程索引
  const pageData = await page.data();
  const targetBooking = (pageData.bookings || []).find(b => b.courseName === courseName);
  const targetIndex = pageData.bookings.indexOf(targetBooking);
  // 2. 通过索引定位 DOM 卡片
  const cards = await page.$$('.booking-card');
  if (cards.length > targetIndex) {
    const signBtn = await cards[targetIndex].$('.signin-btn');
    if (signBtn) { await signBtn.tap(); return true; }
  }
  // 3. 回退：wxml 文本匹配
  // ...
}
```

---

## 四、测试覆盖的小程序页面路由

| 页面 | 路由 | TabBar | 测试内容 |
|---|---|---|---|
| **首页** | `pages/index/index` | ✅ 是 | 渲染、课程卡片（`.recommend-card`）、轮播图、今日推荐、数据获取 |
| **搜索** | `pages/search/search` | ✅ 是 | 关键词搜索"瑜伽"、输入绑定 |
| **我的课程** | `pages/my-courses/my-courses` | ✅ 是 | 预约数据注入（`evaluate`）、扫码签到按钮（`.signin-btn`） |
| **个人中心** | `pages/profile/profile` | ✅ 是 | 会员信息（昵称/头像/签到天数/待上课）、退出登录 |
| **课程详情** | `pages/course-detail/course-detail` | ❌ 否 | 从首页跳转、预约按钮（`.booking-btn`） |

---

## 五、配置与辅助文件

### Jest 配置 — `e2e/jest.config.js`

```javascript
{
  testTimeout: 120000,        // 测试超时 120 秒
  globalSetup: '<rootDir>/e2e/globalSetup.js',
  setupFilesAfterFramework: ['<rootDir>/e2e/setup.js'],
  projects: [
    { displayName: 'smoke',   testMatch: ['**/smoke/**'] },
    { displayName: 'journeys', testMatch: ['**/journeys/**'] }
  ]
}
```

### 全局初始化 — `e2e/globalSetup.js`

启动微信开发者工具 CLI，打开小程序项目并建立 WebSocket 连接：

```javascript
module.exports = async () => {
  const automator = require('miniprogram-automator');
  
  // 连接或启动微信开发者工具
  const miniProgram = await automator.launch({
    projectPath: path.resolve(__dirname, '..'),
  });
  
  // 存储到全局，供测试使用
  global.__MINIPROGRAM__ = miniProgram;
};
```

### 测试设置 — `e2e/setup.js`

每个测试文件执行前的通用设置：

```javascript
beforeAll(async () => {
  miniProgram = global.__MINIPROGRAM__;
  // Mock 常用微信 API
  await miniProgram.mockWxMethod('showToast', {});
  await miniProgram.mockWxMethod('showModal', { confirm: true });
});
```

---

## 六、测试数据

### 预约测试数据（注入到我的课程页）

```javascript
{
  bookings: [{
    id: 100,
    courseId: 2,                    // 流瑜伽
    courseName: '流瑜伽',
    location: 'A馆 · 瑜伽厅',
    fullDate: '2026-07-21',
    shortTime: '10:00',
    endShortTime: '11:00',
    bookingTime: '2026-07-20 15:30',
    statusValue: 0,
    statusLabel: '已预约',
    checkedIn: false,
    canCancel: true
  }]
}
```

### 签到测试数据（Mock wx.scanCode）

```javascript
{
  result: 'COURSE_QR_2',          // 流瑜伽的二维码内容（模拟 fl.png）
  scanType: 'QR_CODE',
  charSet: 'UTF-8',
  errMsg: 'scanCode:ok'
}
```

### 二维码文件

- 路径: `d:\Work\BIG_project\week2\base13-small-uniapp\gym-manage\fl.png`
- 用途: 测试指定的团课「流瑜伽」二维码

---

## 七、环境依赖

| 依赖 | 版本 | 用途 |
|---|---|---|
| miniprogram-automator | ^0.10.x | 微信小程序自动化驱动 |
| Jest | 29.x | 测试运行器 |
| 微信开发者工具 | 稳定版 | 小程序运行载体 |

### 安装

```bash
# 安装测试依赖
npm install -D jest miniprogram-automator

# 或者
npx @wechat-miniprogram/automator-cli install
```

---

## 八、运行方式

### 前置条件

1. 安装**微信开发者工具**（稳定版）
2. 在开发者工具中打开 `gym-manage-uniapp` 项目
3. 开启**服务端口**（设置 → 安全 → 服务端口：打开）
4. 在 HbuilderX 中编译小程序：发行 → 小程序-微信

### 运行命令

```bash
# 进入小程序目录
cd gym-manage-uniapp

# 冒烟测试
npx jest --config e2e/jest.config.js --testPathPattern="smoke"

# 团课预约旅程
npx jest --config e2e/jest.config.js --testPathPattern="booking-journey"

# 个人中心旅程
npx jest --config e2e/jest.config.js --testPathPattern="profile-journey"

# 所有测试
npx jest --config e2e/jest.config.js

# 详细输出
npx jest --config e2e/jest.config.js --verbose --forceExit
```

---

## 九、关键设计决策

### 为什么不直接调用后端 API？

小程序的 `onLoad()` 在页面加载时自动调用后端 API 获取数据。但在测试环境中：
- 后端服务可能未运行
- API 响应可能不稳定

因此采用 **页面数据注入** (`evaluate()`) 策略，直接将预置数据注入到页面 `data` 中，绕过 API 依赖，专注于验证 UI 交互和业务流程。

### 为什么 Mock wx.scanCode？

微信小程序的 `wx.scanCode()` 调用真机摄像头，无法在自动化测试中真实触发。使用 `mockWxMethod()` 模拟返回二维码内容，验证签到按钮点击后的逻辑链路。

### 索引匹配 vs wxml 匹配

原 `scanSignIn()` 通过 `wxml()` 方法获取 DOM 文本进行匹配，但在 UniApp 项目中 `wxml()` 可能不包含渲染后的文本内容。优化后先通过 `page.data()` 获取数据中的对应索引，再通过索引定位 DOM 元素，大幅提高测试稳定性。

---

**文档生成时间**: 2026-07-21 | **测试工具**: Jest 29 + miniprogram-automator + 微信开发者工具