ykq-playwright-ci 0.1.0

package/.env.example

@@ -0,0 +1,25 @@
+# Target environment name used in reports.
+TEST_ENV=test
+
+# Deployed doctor PC base URL, for example:
+# DOCTOR_BASE_URL=https://doctor-test.example.com
+DOCTOR_BASE_URL=
+
+# App paths under DOCTOR_BASE_URL.
+DOCTOR_PUBLIC_PATH=/
+DOCTOR_LOGIN_PATH=/login
+
+# Local auth state generated by `npm run auth:doctor` or manual codegen.
+DOCTOR_STORAGE_STATE=playwright/.auth/doctor.json
+
+# Optional UI login credentials. Leave empty if auth is still manual.
+DOCTOR_USERNAME=
+DOCTOR_PASSWORD=
+DOCTOR_OTP=
+
+# Optional service endpoints for future data seeding and API assertions.
+API_BASE_URL=
+TEST_DATA_API_URL=
+
+# Build metadata shown in attachments and CI artifacts.
+BUILD_SHA=local

package/.nvmrc

@@ -0,0 +1 @@
+22

package/README.md

@@ -0,0 +1,553 @@
+# Playwright CI 使用说明
+
+独立 Playwright 自动化测试工程。当前工程用于承接医生端 PC 的 E2E 自动化测试，不把 Playwright 依赖直接放进医生端 Vue2 / Node 14 业务仓。
+
+## 适用范围
+
+当前优先覆盖医生端测试环境的基础链路：
+
+- 登录页是否能正常渲染。
+- 未登录访问首页是否按路由守卫跳回登录页。
+- 用户协议页是否允许未登录访问。
+- 登录表单的基础校验是否符合 `doctor-master` 逻辑。
+
+这些用例不需要真实医生账号，也不会真的登录、开方或提交处方。登录后业务链路需要先解决测试账号、验证码或登录态方案。
+
+## 环境要求
+
+本地使用这个 runner 前，需要准备这些环境：
+
+| 环境 | 要求 | 说明 |
+| --- | --- | --- |
+| Node.js | 建议使用 `.nvmrc` 指定的 `22` | 本工具运行在 Node 侧，不受医生端业务仓 Node 14 限制 |
+| npm | 随 Node 安装即可 | 推荐用 `npm ci` 或 `npm install` 安装依赖 |
+| Git | 需要可执行 `git clone`、`git fetch`、`git pull` | 用于拉取各项目的用例库 |
+| Git 权限 | 需要能访问 `git.int.ybm100.com` | 可用本机 Git 凭据，也可临时传 `GIT_USERNAME` / `GIT_PASSWORD` |
+| 浏览器 | Playwright Chromium | 首次运行前执行 `npx playwright install chromium` |
+| 网络 | 需要访问 Git 仓库和目标测试环境 | 医生端默认访问 `https://ys-test.heyejk.com` |
+
+当前基础用例不需要医生测试账号。后续如果跑登录后链路，还需要测试医生账号、验证码绕过方案，或 `playwright/.auth/doctor.json` 登录态文件。
+
+不要把账号、密码、token、登录态写进 Git：
+
+```text
+.env
+playwright/.auth/*.json
+GIT_PASSWORD
+```
+
+## 环境准备
+
+进入工程目录：
+
+```bash
+cd /Users/huangcongqiang/Desktop/products/playwright-ci
+```
+
+安装依赖：
+
+```bash
+npm install
+```
+
+如果使用 `nvm`：
+
+```bash
+nvm use
+```
+
+安装浏览器：
+
+```bash
+npx playwright install chromium
+```
+
+如果机器已经装过对应版本，Playwright 会复用缓存。
+
+## 通过 npm 安装使用
+
+npm 包名使用 `ykq-playwright-ci`。`playwright-ci` 这个包名已经被 npm 上其它作者占用，所以本工具发布时不能继续使用原仓库名。
+
+全局安装：
+
+```bash
+npm install -g ykq-playwright-ci
+```
+
+首次在某个目录使用时，先初始化项目配置：
+
+```bash
+mkdir playwright-runner
+cd playwright-runner
+playwright-ci init
+```
+
+初始化后会在当前目录生成：
+
+```text
+projects.config.json
+```
+
+之后可以直接按项目运行：
+
+```bash
+playwright-ci list
+playwright-ci run doctor-pc
+playwright-ci run doctor-pc --headed
+playwright-ci run doctor-pc --debug
+```
+
+也可以使用项目配置命令：
+
+```bash
+playwright-ci add
+playwright-ci show doctor-pc
+playwright-ci update doctor-pc
+playwright-ci delete doctor-pc
+```
+
+如果不想全局安装，发布后也可以用 `npx`：
+
+```bash
+npx ykq-playwright-ci init
+npx ykq-playwright-ci run doctor-pc
+```
+
+从 npm 安装后，Git 用例库仍然拉到当前工作目录的 `.case-repos/`，`projects.config.json` 也保存在当前工作目录，不会写到全局 `node_modules` 目录。
+
+## 最常用命令
+
+查看已配置的项目：
+
+```bash
+npm run project:list
+```
+
+交互式新增项目配置：
+
+```bash
+npm run project:add
+```
+
+查看某个项目详情：
+
+```bash
+npm run project:show -- doctor-pc
+```
+
+交互式更新项目配置：
+
+```bash
+npm run project:update -- doctor-pc
+```
+
+删除项目配置：
+
+```bash
+npm run project:delete -- doctor-pc
+```
+
+后台无头运行测试环境基础用例：
+
+```bash
+npm run doctor:test
+```
+
+打开浏览器窗口，看 Playwright 实际操作：
+
+```bash
+npm run doctor:test:headed
+```
+
+调试模式，适合逐步看定位、点击和断言：
+
+```bash
+npm run doctor:test:debug
+```
+
+打开 Playwright UI，适合筛选、重跑、查看每一步：
+
+```bash
+npm run doctor:test:ui
+```
+
+查看最近一次测试报告：
+
+```bash
+npm run report
+```
+
+## 命令说明
+
+| 命令 | 用途 | 是否打开浏览器窗口 |
+| --- | --- | --- |
+| `npm run project:list` | 查看当前 runner 已配置的项目 | 否 |
+| `npm run project:show -- doctor-pc` | 查看单个项目完整配置 | 否 |
+| `npm run project:add` | 交互式新增项目配置 | 否 |
+| `npm run project:update -- doctor-pc` | 交互式更新项目配置 | 否 |
+| `npm run project:delete -- doctor-pc` | 删除项目配置，需要输入 `delete` 确认 | 否 |
+| `npm run project:test -- doctor-pc` | 按项目名运行用例 | 否 |
+| `npm run doctor:test` | 跑医生端测试环境基础用例，适合日常验证和 CI | 否 |
+| `npm run doctor:test:headed` | 跑同一批用例，同时显示浏览器窗口 | 是 |
+| `npm run doctor:test:debug` | 调试用例，可暂停、逐步执行 | 是 |
+| `npm run doctor:test:ui` | 打开 Playwright UI 选择和重跑用例 | 是 |
+| `npm run doctor:test:local` | 不拉远程仓库，直接跑当前 runner 内置医生端用例 | 否 |
+| `npm run patient:test` | 跑患者端用例库；需要先配置 repo | 否 |
+| `npm run admin:test` | 跑后台用例库；需要先配置 repo | 否 |
+| `npm run report` | 打开 HTML 测试报告 | 是 |
+| `npm run typecheck` | TypeScript 类型检查 | 否 |
+| `npm run lint` | ESLint 检查 | 否 |
+
+## 多项目用例库
+
+本工程现在是一个本地 Playwright Runner。Runner 负责：
+
+- 管理 Playwright 版本、浏览器、报告和通用命令。
+- 按项目名读取配置。
+- 如果项目配置了 Git 用例库，运行前自动 clone 或 `git pull --ff-only`。
+- 根据项目配置设置测试环境变量。
+- 调用 Playwright 执行对应用例目录。
+
+医生端用例库：
+
+```text
+https://git.int.ybm100.com/ykq/doctor-pc-web-test-store
+```
+
+项目配置文件：
+
+```text
+projects.config.json
+```
+
+当前结构：
+
+```json
+{
+  "caseCacheDir": ".case-repos",
+  "projects": {
+    "doctor-pc": {
+      "repo": "https://git.int.ybm100.com/ykq/doctor-pc-web-test-store",
+      "branch": "master",
+      "caseDir": ".case-repos/doctor-pc",
+      "env": {
+        "DOCTOR_BASE_URL": "https://ys-test.heyejk.com",
+        "DOCTOR_PUBLIC_PATH": "/physician-admin/",
+        "DOCTOR_LOGIN_PATH": "/physician-admin/login"
+      },
+      "playwrightArgs": ["--project=chromium", "--no-deps"]
+    }
+  }
+}
+```
+
+`doctor-pc` 已配置为远程用例库。首次运行会拉取到：
+
+```text
+.case-repos/doctor-pc
+```
+
+如果 Git 需要登录，可以用本机 Git 凭据管理，也可以临时通过环境变量传入：
+
+```bash
+GIT_USERNAME=你的用户名 GIT_PASSWORD='你的密码或访问令牌' npm run doctor:test
+```
+
+不要把账号密码写进 `projects.config.json`、README、脚本或 Git remote URL。
+
+远程用例库配置示例：
+
+```json
+{
+  "repo": "https://git.int.ybm100.com/ykq/doctor-pc-web-test-store",
+  "branch": "master",
+  "caseDir": ".case-repos/doctor-pc",
+  "env": {
+    "DOCTOR_BASE_URL": "https://ys-test.heyejk.com",
+    "DOCTOR_PUBLIC_PATH": "/physician-admin/",
+    "DOCTOR_LOGIN_PATH": "/physician-admin/login"
+  },
+  "playwrightArgs": ["--project=chromium", "--no-deps"]
+}
+```
+
+运行时逻辑：
+
+```text
+npm run doctor:test
+  -> 读取 projects.config.json 的 doctor-pc
+  -> 如果 repo 不为空，clone / pull 到 .case-repos/doctor-pc
+  -> 设置 DOCTOR_BASE_URL 等环境变量
+  -> 执行 Playwright
+```
+
+`.case-repos/` 是本地缓存目录，已加入 `.gitignore`，不要提交。
+
+如果本地用例库有未提交改动，runner 会停止自动拉取，避免覆盖你调试中的用例。确认不需要这些改动后，再自己处理对应用例库的 Git 状态。
+
+通用运行方式：
+
+```bash
+npm run project:test -- doctor-pc
+npm run project:test -- doctor-pc --headed
+npm run project:test -- doctor-pc --debug
+```
+
+项目配置增删改查：
+
+```bash
+npm run project:list
+npm run project:show -- doctor-pc
+npm run project:add
+npm run project:update -- doctor-pc
+npm run project:delete -- doctor-pc
+```
+
+新增和更新会依次询问：
+
+- 项目名
+- 用例库 Git 地址
+- 分支
+- 本地用例缓存目录
+- 项目说明
+- Playwright 参数
+- 环境变量
+
+写入后会更新 `projects.config.json`。账号密码不要写进项目配置，运行时通过本机 Git 凭据或临时环境变量传入：
+
+```bash
+GIT_USERNAME=你的用户名 GIT_PASSWORD='你的密码或访问令牌' npm run project:test -- 项目名
+```
+
+如果只想跑 runner 内置的临时本地用例，不拉远程用例库：
+
+```bash
+npm run doctor:test:local
+```
+
+## 默认测试环境
+
+医生端测试环境命令默认使用：
+
+```text
+DOCTOR_BASE_URL=https://ys-test.heyejk.com
+DOCTOR_PUBLIC_PATH=/physician-admin/
+DOCTOR_LOGIN_PATH=/physician-admin/login
+```
+
+也就是说，基础用例会访问：
+
+```text
+https://ys-test.heyejk.com/physician-admin/login
+https://ys-test.heyejk.com/physician-admin/home
+https://ys-test.heyejk.com/physician-admin/serviceAgreement
+```
+
+如果要临时切换环境，可以在命令前覆盖变量：
+
+```bash
+DOCTOR_BASE_URL=https://your-test-host npm run doctor:test
+```
+
+如果路径也不同，可以一起覆盖：
+
+```bash
+DOCTOR_BASE_URL=https://your-test-host \
+DOCTOR_PUBLIC_PATH=/physician-admin/ \
+DOCTOR_LOGIN_PATH=/physician-admin/login \
+npm run doctor:test
+```
+
+## 当前测试用例
+
+文件位置：
+
+```text
+cases/doctor-pc/test-env/doctor-master-basic.spec.ts
+```
+
+当前包含 4 条用例：
+
+| 用例 ID | 验证内容 | 方式 |
+| --- | --- | --- |
+| `PW-TEST-001` | 登录页控件渲染：手机号、图形验证码、短信验证码、协议、登录按钮 | 直接访问登录路由 |
+| `PW-TEST-002` | 未登录访问 `/home` 会被路由守卫跳到 `/login` | 直接访问受保护路由 |
+| `PW-TEST-003` | `/serviceAgreement` 在白名单内，未登录可访问 | 直接访问白名单路由 |
+| `PW-TEST-004` | 登录表单校验：必填、手机号格式、未勾协议提示 | 真实输入和点击 |
+
+前 3 条主要验证路由和页面状态；第 4 条包含真实输入和点击。
+
+## 如何看结果
+
+命令行里看到类似结果表示通过：
+
+```text
+4 passed
+```
+
+失败时，Playwright 会在这些目录生成证据：
+
+```text
+test-results/
+playwright-report/
+```
+
+常用查看方式：
+
+```bash
+npm run report
+```
+
+失败报告里通常包含：
+
+- 失败截图
+- 操作视频
+- trace 回放
+- 报错堆栈
+- 失败前后的页面状态
+
+trace 可以帮助判断到底是页面没出来、定位器没找到、跳转不符合预期，还是网络/环境问题。
+
+## 第一次运行常见问题
+
+### 缺少 Chromium
+
+报错类似：
+
+```text
+Executable doesn't exist
+Please run the following command to download new browsers:
+npx playwright install
+```
+
+处理：
+
+```bash
+npx playwright install chromium
+```
+
+### 测试环境访问慢
+
+如果测试偶发超时，先用可视化模式看页面是否真的打开：
+
+```bash
+npm run doctor:test:headed
+```
+
+再打开报告看失败证据：
+
+```bash
+npm run report
+```
+
+### 断言找到了多个元素
+
+Playwright 默认严格模式下，一个定位器只能匹配一个元素。比如 `验证码` 可能同时匹配 `图形验证码` 和 `验证码`。这种情况需要把定位器写得更精确，例如：
+
+```ts
+page.getByPlaceholder('验证码', { exact: true })
+```
+
+## 如何新增用例
+
+医生端测试环境基础用例优先放在：
+
+```text
+cases/doctor-pc/test-env/
+```
+
+建议命名：
+
+```text
+模块-场景-预期.spec.ts
+```
+
+示例：
+
+```text
+login-form-validation.spec.ts
+home-route-guard.spec.ts
+```
+
+每条用例建议补充 `annotateCase`，方便报告里追踪用例 ID：
+
+```ts
+annotateCase(testInfo, {
+  caseId: 'PW-TEST-005',
+  evidenceId: 'TEST-some-business-evidence',
+  priority: 'Smoke'
+});
+```
+
+写用例时优先使用接近用户行为的定位方式：
+
+```ts
+page.getByRole('button', { name: '登录' })
+page.getByPlaceholder('手机号')
+page.getByText('荷叶医生')
+```
+
+不要优先依赖样式类名、DOM 层级或 `nth-child`。如果页面没有稳定语义定位，再考虑让业务仓补 `data-testid`。
+
+## 登录后用例怎么做
+
+当前基础用例不需要登录。后续要测登录后页面，比如首页、问诊列表、处方 tab、开方、撤回处方，需要先满足至少一种方案：
+
+- 后端提供测试登录接口。
+- 测试环境提供固定验证码或验证码绕过能力。
+- 手工生成 `playwright/.auth/doctor.json` 登录态。
+
+手工登录态方式参考：
+
+```bash
+npx playwright codegen --save-storage=playwright/.auth/doctor.json https://ys-test.heyejk.com/physician-admin/login
+```
+
+在打开的浏览器里完成登录后关闭窗口，后续已登录用例可复用该 storageState。
+
+注意：`playwright/.auth/*.json` 包含登录态，已被 `.gitignore` 排除，不要提交。
+
+## CI 或服务器运行
+
+服务器不需要显示器，可以直接跑无头模式：
+
+```bash
+npm ci
+npx playwright install --with-deps chromium
+npm run doctor:test
+```
+
+CI 建议归档：
+
+```text
+playwright-report/
+test-results/
+```
+
+不要归档或提交：
+
+```text
+playwright/.auth/*.json
+.env
+```
+
+## 项目结构
+
+```text
+cases/doctor-pc/       # 医生端业务用例
+src/fixtures/          # Playwright fixtures 和登录态工具
+src/pages/doctor-pc/   # Page Object
+src/flows/doctor-pc/   # 跨页面业务流程
+src/api/               # API 和测试数据客户端
+src/mocks/             # route / websocket mock
+docs/                  # 运行、登录、测试数据、选择器和 CI 说明
+scripts/               # 命令封装脚本
+```
+
+## 维护原则
+
+- 先用少量稳定 Smoke 验证页面和路由，再扩展登录后 P0 链路。
+- 用例失败必须能留下截图、视频或 trace。
+- 不在测试工程里硬编码真实账号密码。
+- 不把 Playwright 依赖塞回医生端业务仓。
+- 涉及处方、问诊、药品、自动关诊等业务链路时，要先确认测试数据和登录态方案。

package/bin/playwright-ci.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/* global console, process */
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const defaultConfigPath = path.join(packageRootDir, 'projects.config.json');
+const userConfigPath = process.env.PROJECTS_CONFIG_PATH
+  ? path.resolve(process.env.PROJECTS_CONFIG_PATH)
+  : path.resolve(process.cwd(), 'projects.config.json');
+
+const configActions = new Set(['list', 'show', 'add', 'update', 'delete', 'remove']);
+
+function printHelp() {
+  console.log(`Usage:
+  playwright-ci init
+  playwright-ci list
+  playwright-ci show <project>
+  playwright-ci add [project]
+  playwright-ci update <project>
+  playwright-ci delete <project>
+  playwright-ci run <project> [playwright args]
+  playwright-ci <project> [playwright args]
+
+Examples:
+  playwright-ci init
+  playwright-ci run doctor-pc --headed
+  GIT_USERNAME=user GIT_PASSWORD=token playwright-ci run doctor-pc`);
+}
+
+function ensureConfigExists() {
+  if (fs.existsSync(userConfigPath)) {
+    return;
+  }
+
+  throw new Error(`当前目录缺少 projects.config.json，请先执行：playwright-ci init\n目标路径：${userConfigPath}`);
+}
+
+function initConfig() {
+  if (fs.existsSync(userConfigPath)) {
+    console.log(`配置文件已存在：${userConfigPath}`);
+    return;
+  }
+
+  fs.copyFileSync(defaultConfigPath, userConfigPath);
+  console.log(`已创建配置文件：${userConfigPath}`);
+}
+
+function runNodeScript(scriptName, args) {
+  const child = spawn(process.execPath, [path.join(packageRootDir, 'scripts', scriptName), ...args], {
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      PROJECTS_CONFIG_PATH: userConfigPath
+    },
+    stdio: 'inherit'
+  });
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+
+    process.exit(code ?? 1);
+  });
+}
+
+function main() {
+  const [command = 'help', ...args] = process.argv.slice(2);
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (command === 'init') {
+    initConfig();
+    return;
+  }
+
+  if (command === 'run' || command === 'project:test') {
+    ensureConfigExists();
+    runNodeScript('run-project.mjs', args);
+    return;
+  }
+
+  if (command.startsWith('project:')) {
+    const action = command.slice('project:'.length);
+    if (!configActions.has(action)) {
+      throw new Error(`未知命令：${command}`);
+    }
+    ensureConfigExists();
+    runNodeScript('configure-project.mjs', [action, ...args]);
+    return;
+  }
+
+  if (configActions.has(command)) {
+    ensureConfigExists();
+    runNodeScript('configure-project.mjs', [command, ...args]);
+    return;
+  }
+
+  ensureConfigExists();
+  runNodeScript('run-project.mjs', [command, ...args]);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+}

package/cases/doctor-pc/auth/doctor-auth.setup.ts

@@ -0,0 +1,15 @@
+import { test } from '../../../src/fixtures/base.fixture';
+import { saveDoctorAuthState } from '../../../src/fixtures/auth.fixture';
+import { LoginFlow } from '../../../src/flows/doctor-pc/login.flow';
+import { hasDoctorBaseURL, hasDoctorCredentials } from '../../../src/utils/env';
+
+test.skip(!hasDoctorBaseURL(), 'DOCTOR_BASE_URL is required to generate doctor auth state.');
+test.skip(
+  !hasDoctorCredentials(),
+  'DOCTOR_USERNAME and DOCTOR_PASSWORD are required unless auth is generated manually.'
+);
+
+test('PW-AUTH-SETUP generate doctor storageState @auth', async ({ page }) => {
+  await new LoginFlow(page).loginWithConfiguredCredentials();
+  await saveDoctorAuthState(page);
+});