ykq-playwright-ci 0.1.0 → 0.1.1

package/README.md

@@ -1,261 +1,111 @@
-# Playwright CI 使用说明
+# Playwright CI
 
-独立 Playwright 自动化测试工程。当前工程用于承接医生端 PC 的 E2E 自动化测试，不把 Playwright 依赖直接放进医生端 Vue2 / Node 14 业务仓。
+一个本地 Playwright Runner：按项目名拉取对应用例库，然后在测试环境跑自动化用例。
 
-## 适用范围
-
-当前优先覆盖医生端测试环境的基础链路：
-
-- 登录页是否能正常渲染。
-- 未登录访问首页是否按路由守卫跳回登录页。
-- 用户协议页是否允许未登录访问。
-- 登录表单的基础校验是否符合 `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：
+当前默认项目是医生端 PC：
 
 ```text
-.env
-playwright/.auth/*.json
-GIT_PASSWORD
-```
-
-## 环境准备
-
-进入工程目录：
-
-```bash
-cd /Users/huangcongqiang/Desktop/products/playwright-ci
+doctor-pc -> https://git.int.ybm100.com/ykq/doctor-pc-web-test-store
 ```
 
-安装依赖：
-
-```bash
-npm install
-```
+## 先跑起来
 
-如果使用 `nvm`：
+需要先准备：
 
-```bash
-nvm use
-```
+- Node.js `22+`
+- npm
+- Git，并且能访问 `git.int.ybm100.com`
+- 能访问目标测试环境，例如 `https://ys-test.heyejk.com`
 
-安装浏览器：
-
-```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
+playwright-ci init
 ```
 
-查看某个项目详情：
+安装浏览器：
 
 ```bash
-npm run project:show -- doctor-pc
+playwright-ci install chromium
 ```
 
-交互式更新项目配置：
+运行医生端用例：
 
 ```bash
-npm run project:update -- doctor-pc
+playwright-ci run doctor-pc
 ```
 
-删除项目配置：
+如果 Git 需要账号密码：
 
 ```bash
-npm run project:delete -- doctor-pc
+GIT_USERNAME=你的用户名 GIT_PASSWORD='你的密码或访问令牌' playwright-ci run doctor-pc
 ```
 
-后台无头运行测试环境基础用例：
-
-```bash
-npm run doctor:test
-```
+不要把账号密码写进 `projects.config.json`。
 
-打开浏览器窗口，看 Playwright 实际操作：
+## 常用命令
 
-```bash
-npm run doctor:test:headed
-```
+| 命令 | 用途 |
+| --- | --- |
+| `playwright-ci init` | 在当前目录生成 `projects.config.json` |
+| `playwright-ci list` | 查看已有项目 |
+| `playwright-ci run doctor-pc` | 后台运行医生端用例 |
+| `playwright-ci run doctor-pc --headed` | 打开浏览器窗口运行 |
+| `playwright-ci run doctor-pc --debug` | 调试模式运行 |
+| `playwright-ci run doctor-pc --ui` | 打开 Playwright UI |
+| `playwright-ci add` | 交互式新增项目 |
+| `playwright-ci show doctor-pc` | 查看项目配置 |
+| `playwright-ci update doctor-pc` | 修改项目配置 |
+| `playwright-ci delete doctor-pc` | 删除项目配置 |
+| `playwright-ci install chromium` | 安装 Chromium 浏览器 |
 
-调试模式，适合逐步看定位、点击和断言：
+也可以不全局安装，直接用 `npx`：
 
 ```bash
-npm run doctor:test:debug
+npx ykq-playwright-ci init
+npx ykq-playwright-ci run doctor-pc
 ```
 
-打开 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"]
-    }
-  }
-}
+playwright-ci run doctor-pc
 ```
 
-`doctor-pc` 已配置为远程用例库。首次运行会拉取到：
+流程是：
 
 ```text
-.case-repos/doctor-pc
+读取当前目录的 projects.config.json
+拉取 doctor-pc 对应的 Git 用例库
+缓存到 .case-repos/doctor-pc
+设置 DOCTOR_BASE_URL 等环境变量
+调用 Playwright 跑测试
 ```
 
-如果 Git 需要登录，可以用本机 Git 凭据管理，也可以临时通过环境变量传入：
+默认是无头浏览器，所以不会弹窗口。要看真实页面操作，用：
 
 ```bash
-GIT_USERNAME=你的用户名 GIT_PASSWORD='你的密码或访问令牌' npm run doctor:test
+playwright-ci run doctor-pc --headed
 ```
 
-不要把账号密码写进 `projects.config.json`、README、脚本或 Git remote URL。
+## 默认医生端配置
 
-远程用例库配置示例：
+`playwright-ci init` 生成的 `doctor-pc` 配置大致是：
 
 ```json
 {
@@ -271,283 +121,164 @@ GIT_USERNAME=你的用户名 GIT_PASSWORD='你的密码或访问令牌' npm run
 }
 ```
 
-运行时逻辑：
+当前基础用例会访问：
 
 ```text
-npm run doctor:test
-  -> 读取 projects.config.json 的 doctor-pc
-  -> 如果 repo 不为空，clone / pull 到 .case-repos/doctor-pc
-  -> 设置 DOCTOR_BASE_URL 等环境变量
-  -> 执行 Playwright
+https://ys-test.heyejk.com/physician-admin/login
+https://ys-test.heyejk.com/physician-admin/home
+https://ys-test.heyejk.com/physician-admin/serviceAgreement
 ```
 
-`.case-repos/` 是本地缓存目录，已加入 `.gitignore`，不要提交。
+当前基础用例不需要真实医生账号，不会真的登录、开方或提交处方。
+
+## 项目配置怎么改
 
-如果本地用例库有未提交改动，runner 会停止自动拉取，避免覆盖你调试中的用例。确认不需要这些改动后，再自己处理对应用例库的 Git 状态。
+查看：
 
-通用运行方式：
+```bash
+playwright-ci show doctor-pc
+```
+
+交互式修改：
 
 ```bash
-npm run project:test -- doctor-pc
-npm run project:test -- doctor-pc --headed
-npm run project:test -- doctor-pc --debug
+playwright-ci update doctor-pc
 ```
 
-项目配置增删改查：
+新增一个项目：
 
 ```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
+playwright-ci add
 ```
 
-新增和更新会依次询问：
+新增或修改时会问这些内容：
 
 - 项目名
 - 用例库 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
+projects.config.json
 ```
 
-## 当前测试用例
-
-文件位置：
+用例库缓存目录是：
 
 ```text
-cases/doctor-pc/test-env/doctor-master-basic.spec.ts
+.case-repos/
 ```
 
-当前包含 4 条用例：
+`.case-repos/` 只是本地缓存，不需要提交。
 
-| 用例 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
-```
-
-处理：
+通过 npm 安装使用时，可以在运行目录打开报告：
 
 ```bash
-npx playwright install chromium
+npx playwright show-report playwright-report
 ```
 
-### 测试环境访问慢
-
-如果测试偶发超时，先用可视化模式看页面是否真的打开：
+## 常见问题
 
-```bash
-npm run doctor:test:headed
-```
+### 提示缺少浏览器
 
-再打开报告看失败证据：
+执行：
 
 ```bash
-npm run report
+playwright-ci install chromium
 ```
 
-### 断言找到了多个元素
+### 拉取用例库失败
 
-Playwright 默认严格模式下，一个定位器只能匹配一个元素。比如 `验证码` 可能同时匹配 `图形验证码` 和 `验证码`。这种情况需要把定位器写得更精确，例如：
+先确认当前机器能访问内部 Git。需要账号密码时这样跑：
 
-```ts
-page.getByPlaceholder('验证码', { exact: true })
+```bash
+GIT_USERNAME=你的用户名 GIT_PASSWORD='你的密码或访问令牌' playwright-ci run doctor-pc
 ```
 
-## 如何新增用例
+### 当前目录缺少 projects.config.json
 
-医生端测试环境基础用例优先放在：
+先执行：
 
-```text
-cases/doctor-pc/test-env/
-```
-
-建议命名：
-
-```text
-模块-场景-预期.spec.ts
+```bash
+playwright-ci init
 ```
 
-示例：
+### 本地用例库有未提交改动
 
-```text
-login-form-validation.spec.ts
-home-route-guard.spec.ts
-```
-
-每条用例建议补充 `annotateCase`，方便报告里追踪用例 ID：
+Runner 会停止自动 `pull`，避免覆盖你正在调试的用例。处理 `.case-repos/项目名` 里的 Git 状态后再运行。
 
-```ts
-annotateCase(testInfo, {
-  caseId: 'PW-TEST-005',
-  evidenceId: 'TEST-some-business-evidence',
-  priority: 'Smoke'
-});
-```
+## 在源码仓库里开发
 
-写用例时优先使用接近用户行为的定位方式：
+如果你是维护这个 runner 本身：
 
-```ts
-page.getByRole('button', { name: '登录' })
-page.getByPlaceholder('手机号')
-page.getByText('荷叶医生')
+```bash
+git clone https://git.int.ybm100.com/ykq/playwright-ci
+cd playwright-ci
+npm install
+npx playwright install chromium
 ```
 
-不要优先依赖样式类名、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
+npm run doctor:test
+npm run doctor:test:headed
+npm run doctor:test:debug
 ```
 
-在打开的浏览器里完成登录后关闭窗口，后续已登录用例可复用该 storageState。
-
-注意：`playwright/.auth/*.json` 包含登录态，已被 `.gitignore` 排除，不要提交。
-
-## CI 或服务器运行
-
-服务器不需要显示器，可以直接跑无头模式：
+检查代码：
 
 ```bash
-npm ci
-npx playwright install --with-deps chromium
-npm run doctor:test
+npm run lint
+npm run typecheck
 ```
 
-CI 建议归档：
+## 当前基础用例
 
-```text
-playwright-report/
-test-results/
-```
+医生端测试环境基础用例包括：
 
-不要归档或提交：
+| 用例 | 验证内容 |
+| --- | --- |
+| `PW-TEST-001` | 登录页控件是否渲染 |
+| `PW-TEST-002` | 未登录访问 `/home` 是否跳回登录页 |
+| `PW-TEST-003` | `/serviceAgreement` 是否允许未登录访问 |
+| `PW-TEST-004` | 登录表单基础校验 |
 
-```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/               # 命令封装脚本
+.env
+playwright/.auth/*.json
+账号密码
+访问令牌
+npm token
 ```
 
-## 维护原则
-
-- 先用少量稳定 Smoke 验证页面和路由，再扩展登录后 P0 链路。
-- 用例失败必须能留下截图、视频或 trace。
-- 不在测试工程里硬编码真实账号密码。
-- 不把 Playwright 依赖塞回医生端业务仓。
-- 涉及处方、问诊、药品、自动关诊等业务链路时，要先确认测试数据和登录态方案。
+登录后业务用例需要额外准备测试账号、验证码绕过方案，或 `playwright/.auth/doctor.json` 登录态文件。

package/bin/playwright-ci.mjs

@@ -3,14 +3,18 @@
 
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const packageRootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(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 packageJson = JSON.parse(fs.readFileSync(path.join(packageRootDir, 'package.json'), 'utf8'));
+const playwrightCliPath = path.join(path.dirname(require.resolve('@playwright/test/package.json')), 'cli.js');
 
 const configActions = new Set(['list', 'show', 'add', 'update', 'delete', 'remove']);
 
@@ -22,11 +26,13 @@ function printHelp() {
   playwright-ci add [project]
   playwright-ci update <project>
   playwright-ci delete <project>
+  playwright-ci install [browser]
   playwright-ci run <project> [playwright args]
   playwright-ci <project> [playwright args]
 
 Examples:
   playwright-ci init
+  playwright-ci install chromium
   playwright-ci run doctor-pc --headed
   GIT_USERNAME=user GIT_PASSWORD=token playwright-ci run doctor-pc`);
 }
@@ -69,6 +75,23 @@ function runNodeScript(scriptName, args) {
   });
 }
 
+function runPlaywright(args) {
+  const child = spawn(process.execPath, [playwrightCliPath, ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    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);
 
@@ -77,11 +100,21 @@ function main() {
     return;
   }
 
+  if (command === 'version' || command === '--version' || command === '-v') {
+    console.log(packageJson.version);
+    return;
+  }
+
   if (command === 'init') {
     initConfig();
     return;
   }
 
+  if (command === 'install') {
+    runPlaywright(['install', ...(args.length ? args : ['chromium'])]);
+    return;
+  }
+
   if (command === 'run' || command === 'project:test') {
     ensureConfigExists();
     runNodeScript('run-project.mjs', args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ykq-playwright-ci",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Company-level Playwright E2E test project for doctor PC workflows.",
   "bin": {
     "playwright-ci": "bin/playwright-ci.mjs"