# Playwright H5 自动化测试说明

本文说明如何使用 Playwright 对 **pages/tool_main/index** 及其子页面进行 H5 端到端自动化测试。

---

## 环境要求

- Node.js（项目根目录已安装 `@playwright/test`、`playwright`）
- 前端 H5 开发服务（默认 `http://localhost:8080`）
- 后端 API 服务（默认 `http://127.0.0.1:20822`）

---

## 演示账号

| 项目     | 值          |
|----------|-------------|
| 手机号   | 18621813282 |
| 登录密码 | A123456     |

---

## 运行步骤

### 1. 启动后端

确保后端服务已启动并监听 `http://127.0.0.1:20822`（具体启动方式以项目文档为准）。

### 2. 启动前端 H5

在 **msh_single_uniapp** 或项目根目录中启动 H5 开发服务，使前端在 **http://localhost:8080** 可访问。例如：

```bash
# 若在 msh_single_uniapp 下有 dev:h5 脚本
cd msh_single_uniapp && npm run dev:h5

# 或项目根目录提供的启动命令（如 npm run serve 等）
# 以实际 package.json 中脚本为准
```

保持该终端运行，勿关闭。

### 3. 运行 Playwright 测试

在 **项目根目录**（即包含 `playwright.config.ts` 的目录）执行：

```bash
# 一键执行全部 E2E 测试（需先启动前端 H5 + 后端）
npx playwright test

# 安装浏览器（首次或升级后执行一次）
npx playwright install chromium

# 仅运行 tool_main 相关用例
npx playwright test tests/e2e/tool-main.spec.ts

# 带 UI 模式（可单步调试）
npx playwright test tests/e2e/tool-main.spec.ts --ui

# 指定用例名运行
npx playwright test -g "TC-001"
npx playwright test -g "登录"
```

---

## 测试范围（tool_main 及子页面）

| 用例编号 | 说明 |
|----------|------|
| TC-001 | 页面加载：主界面核心元素可见（用户卡片、四大功能、精选食谱、健康知识、营养方案） |
| TC-002 | 用户卡片：已登录时不显示「请点击登录」 |
| TC-003 | 登录流程：手机号+密码登录成功（演示账号 UI 登录） |
| TC-004 | 食谱计算器：进入页面并填写参数 |
| TC-005 | AI 营养师：进入页面并发送消息 |
| TC-006 | 食物百科：进入并搜索「鸡肉」、切换分类、进入食物详情 |
| TC-007 | 营养知识：进入并切换 Tab（营养素 / 饮食指南 / 科普文章） |
| TC-008 | 打卡功能：进入打卡页并查看状态、积分规则 |
| TC-009 | 精选食谱：列表展示并进入详情、点击「更多」 |
| TC-010 | 营养方案：点击「立即领取福利」跳转 |
| TC-011 | 健康知识：列表展示并进入详情、点击「更多」进入营养知识 |
| TC-012 | 下拉刷新：刷新后核心元素仍可见 |
| TC-013 | 页面错误检查：主界面无严重 JS 错误 |
| TC-014 | 社区子页：tool_main/community 打卡社区 Tab（推荐/最新/关注/热门）与列表 |

子页面覆盖：**tool_main/index**、**tool_main/community**，以及从首页入口进入的 **pages/tool/** 下页面（打卡、食谱计算器、AI 营养师、食物百科、营养知识、食谱详情、会员福利等）。

---

## 配置说明

- **配置文件**：项目根目录 `playwright.config.ts`
- **用例目录**：`tests/e2e/`
- **主用例文件**：`tests/e2e/tool-main.spec.ts`
- **Base URL**：`http://localhost:8080`（H5 使用 hash 路由 `/#/pages/...`）
- **视口**：移动端 375×667，模拟手机浏览器

大部分用例通过后端 API 登录后向页面注入 token，再访问 tool_main；**TC-003** 单独验证从登录页输入演示账号完成整条登录流程。

---

## 报告与产物

- **HTML 报告**：`tests/e2e/reports/`，失败时可用 `npx playwright show-report tests/e2e/reports` 查看
- **截图**：失败或用例内截图保存在 `tests/e2e/screenshots/`
- **测试结果/录屏**：`tests/e2e/test-results/`（如开启 video/trace）

---

## 常见问题

1. **连接被拒绝 / 超时**  
   确认前端已启动且可在浏览器访问 `http://localhost:8080`，以及后端 `http://127.0.0.1:20822` 可访问。

2. **登录失败或 TC-003 失败**  
   确认演示账号 18621813282 / A123456 在后端可用，且接口 `POST /api/front/login` 返回 200 与有效 token。

3. **元素找不到 / 超时**  
   H5 为 UniApp 编译产物，部分类名或结构可能随版本变化；若页面有 iframe 包装，需保证访问的 URL 与视口能使主内容直接暴露（如移动端直连 `/#/pages/...`）。

4. **仅跑部分用例**  
   使用 `-g "关键字"` 或指定文件：  
   `npx playwright test tests/e2e/tool-main.spec.ts -g "TC-014"`

5. **TC-003 登录流程失败**  
   该用例模拟真实 UI 登录（不注入 token），若登录页有图形验证、协议勾选或跳转逻辑与预期不符可能失败。可暂时排除：  
   `npx playwright test --grep-invert "TC-003"`

---

**最后更新**：2026-03-02