csspilot 0.5.0 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 > [TestPilot](https://github.com/3lin9/css-test-pilot) CLI —— AI Native 跨端业务测试基础设施:让 AI 能理解、生成、校验并执行业务测试。
 
-`csspilot` 把一套**可校验、可执行、可取证**的端到端测试工作流带进你的业务项目:用 YAML DSL 描述用例,同时驱动 **Web(Playwright)** 与**微信小程序(WeChat DevTools)** 两端,产出截图 / video / trace 证据与 JSON + HTML 报告;并随包附带 AI Skill,安装后让 AI 助手按同一套规范生成和维护用例。
+`csspilot` 把一套**可校验、可执行、可取证**的端到端测试工作流带进你的业务项目:用 YAML DSL 描述用例,同时驱动 **Web(Playwright)**、**微信小程序(WeChat DevTools)** 与 **HTTP API**,产出截图 / video / trace 证据与 JSON + HTML 报告;并随包附带 AI Skill,安装后让 AI 助手按同一套规范生成和维护用例。
 
 [![npm version](https://img.shields.io/npm/v/csspilot.svg)](https://www.npmjs.com/package/csspilot)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/3lin9/css-test-pilot/blob/main/LICENSE)
@@ -10,11 +10,13 @@
 
 ## 特性
 
-- **一套 DSL,跨端执行**:`target: miniapp | web` 自由切换,变量跨端传递(小程序下单 → extract 订单号 → Web 后台 assert)
+- **一套 DSL,跨端执行**:`target: miniapp | web | api` 自由切换,变量跨端传递(小程序下单 → extract 订单号 → Web 后台 assert)
 - **先校验后执行**:用例在运行前经过 DSL schema / action / locator / 变量引用 / adapter 支持的完整校验
 - **全程取证**:每一步可留 screenshot,运行留 video / trace / 日志,证据按 run 归档在 `.testpilot/artifacts/runs/<id>/`
-- **JSON + HTML 报告**:`csspilot report` 一步生成,支持按 run id 回看
-- **AI Native**:内置 TestPilot Skill(规则 + 工作流),`init` 后 AI 助手即可按规范帮你写用例、跑测试、分析结果
+- **JSON + HTML 报告**:单次 run 报告,或 `--summary` 跨 run 汇总;`--open` 生成后打开浏览器
+- **账号凭据不进 Case**:`accountRef` 引用环境凭据,本地用 `TESTPILOT_ACCOUNT_*` 注入,明文密码禁止写进 YAML
+- **AI Native**:内置 TestPilot Skill(规则 + 工作流 + 项目级 references),`init` 后 AI 助手即可按规范帮你写用例、跑测试、分析结果
+- **幂等接入与升级**:`init` 不覆盖已有配置与用例;`update` 只同步 Skill / `.env.example`,不碰 `.env` 与 `tests/e2e`
 
 ## 安装
 
@@ -32,40 +34,69 @@ Web 端执行依赖 Playwright 浏览器:
 npx playwright install chromium
 ```
 
+CLI 启动时会加载项目根目录的 `.env`(真实环境变量优先于文件)。`testpilot.yaml` 里的 `${VAR}` 在运行时注入。
+
 ## 快速开始
 
 ```bash
-# 1. 在业务项目根目录接入 TestPilot(装 AI Skill、初始化 .testpilot/、生成 testpilot.yaml)
+# 1. 在业务项目根目录接入 TestPilot
+#    (检测项目与 Adapter、生成 testpilot.yaml / .env.example / .testpilot/、
+#     创建 tests/e2e/{cases,fixtures,data}、安装 Skill、自动 doctor)
 csspilot init
+# 可选:关联 TestPilot Server
+# csspilot init --server http://127.0.0.1:3000
+
+# 2. 复制 .env.example 为 .env,填入 TEST_BASE_URL 等真实值(.env 已写入 .gitignore)
 
-# 2. 在 tests/e2e/cases/ 下写用例(可让 AI 按 Skill 规范生成)
+# 3. 在 tests/e2e/cases/ 下写用例(可让 AI 按 Skill 规范生成)
 
-# 3. 校验用例
+# 4. 校验用例
 csspilot validate
 
-# 4. 执行
+# 5. 执行
 csspilot run
 
-# 5. 生成报告
+# 6. 生成报告
 csspilot report
 ```
 
-不确定环境是否就绪?`csspilot doctor` 一键体检(Node / Playwright / WeChat DevTools / 项目配置)。
+不确定环境是否就绪?`csspilot doctor` 一键体检(Runtime / 项目配置 / 用例 / Skill / Adapter / 环境变量 / Server)。
+
+`init` 全程幂等:已有 `testpilot.yaml`、用例目录、Skill references 一律保留,不重置 `projectId`。
 
 ## 命令
 
-| 命令                                    | 作用                                                                                                                                       |
-| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `csspilot init`                         | 把 TestPilot 接入当前业务项目(装 Skill 到 `.agents/skills/testpilot/`、初始化 `.testpilot/`、创建/复用 `tests/e2e`、生成 `testpilot.yaml`) |
-| `csspilot validate [paths...]`          | 校验用例(DSL schema / action / locator / 变量引用 / adapter 支持)                                                                          |
-| `csspilot list [--tag <tag>]`           | 列出用例                                                                                                                                   |
-| `csspilot run [paths...] [--tag <tag>]` | 执行用例(Case Loader → Validator → Engine → Adapter → Evidence → Reporter)                                                                 |
-| `csspilot report [--run <id>]`          | 生成 JSON + HTML 报告(`.testpilot/artifacts/runs/<id>/`)                                                                                   |
-| `csspilot doctor`                       | 环境体检(Node / Playwright / WeChat DevTools / 项目配置)                                                                                   |
+| 命令 | 作用 |
+| --- | --- |
+| `csspilot init [--server <url>]` | 把 TestPilot 接入当前业务项目(幂等)。装 Skill 到 `.agents/skills/testpilot/`、初始化 `.testpilot/`、创建/复用 `tests/e2e`、生成 `testpilot.yaml` 与 `.env.example`,并跑一次 doctor。`--server` 写入关联地址(默认读 `TESTPILOT_SERVER_URL`) |
+| `csspilot validate [paths...]` | 校验用例(DSL schema / action / locator / 变量引用 / adapter 支持);不传路径则按 `testpilot.yaml` 的 cases 目录 |
+| `csspilot list [--tag <tag>]` | 列出用例(含无效文件提示) |
+| `csspilot run [paths...] [--tag <tag>]` | 执行用例;校验失败的文件跳过。本地账号凭据来自 `TESTPILOT_ACCOUNT_<REF>` |
+| `csspilot report [--run <id>] [--open] [--summary] [--last <n>]` | 生成 JSON + HTML。默认最近一次 run;`--summary` 生成跨 run 汇总(`summary.html` / `summary.json`),窗口默认最近 30 次 |
+| `csspilot doctor` | 健康检查(Runtime / Project / Test / Skill / Adapter / 环境变量 / Server) |
+| `csspilot update [--force]` | 把 Skill 主体与 `.env.example` 同步到当前 CLI 版本。不覆盖 `.env`、用例、`testpilot.yaml`、`references/`。版本一致时需 `--force` 才覆盖本地 Skill 修改 |
+| `csspilot ci init` | 生成 `.github/workflows/testpilot.yml`(validate + sync-metadata);已有则跳过,不改动其他 CI |
+| `csspilot sync-metadata [--server <url>]` | 把当前 Git commit 的 Case Metadata 快照同步到 TestPilot Server。面向 CI / git push,本地未 push 的 Case 不应进入团队视图 |
+
+版本:`csspilot -v` 或 `-V`。
+
+## 配置与环境变量
+
+`init` 生成的 `testpilot.yaml` 是项目配置源。环境相关字段只放 `${VAR}` 引用,真实值写在 `.env`:
+
+| 变量 | 用途 |
+| --- | --- |
+| `TEST_BASE_URL` / `STAGING_BASE_URL` | `environment` 段的 baseUrl |
+| `WEB_BASE_URL` | Web 端相对 url 基准(需在 yaml 启用 `web` 段) |
+| `MINIAPP_PROJECT_PATH` / `MINIAPP_CLI_PATH` | 小程序项目目录与开发者工具 CLI(需启用 `miniapp` 段) |
+| `TESTPILOT_SERVER_URL` | TestPilot Server(Control Plane);也可写在 yaml 的 `server.baseUrl` |
+| `TESTPILOT_ACCOUNT_<REF>` | 本地账号凭据。Case 里 `accountRef: test-user` 对应 `TESTPILOT_ACCOUNT_TEST_USER='{"username":"a","password":"b"}'`(`-` 转 `_`,大写) |
+| `WECHAT_DEVTOOLS_CLI` | 微信开发者工具 CLI 可执行文件路径(doctor / adapter 检测) |
+| `TESTPILOT_SKILL_DIR` | 覆盖内置 Skill 源目录(开发/调试用) |
 
 ## DSL 速览
 
-九个基础 Action:`launch` `navigate` `click` `input` `select` `wait` `assert` `extract` `screenshot`。Action 是通用测试原语;业务动作(登录 / 下单 / 支付)永远是业务项目里的 Case。
+十个稳定 Action:`launch` `navigate` `click` `input` `select` `wait` `assert` `extract` `screenshot` `request`。Action 是通用测试原语;业务动作(登录 / 下单 / 支付)永远是业务项目里的 Case。执行端:`miniapp` | `web` | `api`。
 
 ```yaml
 # tests/e2e/cases/order-create.yaml
@@ -88,6 +119,11 @@ steps:
     locator:
       css: ".submit-btn"
 
+  - target: miniapp
+    action: wait
+    locator:
+      css: ".order-id"
+
   # 提取订单号,存入上下文变量
   - target: miniapp
     action: extract
@@ -96,21 +132,38 @@ steps:
     variable: orderId
 
   # Web 端:后台验证该订单(locator 支持 ${var} 引用)
+  - target: web
+    action: navigate
+    url: /orders
+
   - target: web
     action: assert
     locator:
-      css: "tr[data-order='${orderId}']"
+      css: ".order-row-${orderId}"
+    expected: "${orderId}"
 ```
 
+`target: api` 用 `request` / `extract` / `assert` 做接口造数与校验,相对 url 按 `testpilot.yaml` 的 `api.baseUrl` 解析。完整字段以 `@testpilot/dsl` schema 为准。
+
 ## AI Skill
 
 `csspilot init` 会把随包分发的 TestPilot Skill 安装到业务项目 `.agents/skills/testpilot/`,包含:
 
 - `SKILL.md` —— 能力总览与使用约定
-- `rules/` —— 用例设计 / DSL 书写 / 断言 / locator 规范
-- `workflows/` —— 创建用例、校验、执行、结果分析的完整工作流
+- `manifest.yaml` —— Skill 版本(供 `update` / `doctor` 比对)
+- `rules/` —— 用例设计 / DSL / 断言 / locator 规范
+- `workflows/` —— 需求评审、创建用例、校验、执行、结果分析
+- `references/` —— **项目级**上下文(`project.md` / `test-conventions.md` / `adapters.md`),升级 Skill 时不会被覆盖
+
+安装后,你的 AI 助手(Claude Code、Cursor 等)即可按这套规范生成、修改和运行用例。可选:按所用 Agent 复制到 `.cursor/skills/`、`.claude/skills/` 等目录。
+
+Skill 落后于当前 CLI 时,`doctor` 会提示,执行 `csspilot update` 并提交 `.agents/skills/` 即可。
+
+## CI 与 Server
 
-安装后,你的 AI 助手(Claude Code、Cursor 等)即可按这套规范生成、修改和运行用例。
+- `csspilot ci init` 生成 GitHub Actions:在 `main` 上 push 后跑 `validate`,若配置了 `TESTPILOT_SERVER_URL` Secret 再跑 `sync-metadata`。执行用例步骤默认注释,需要时自行打开。
+- `sync-metadata` 需要 Git 仓库(含 commit / branch)以及 Server 注册过的 `projectId`(本地模式无法同步)。
+- 未配置 Server 时,`init` 以本地模式关联项目;`doctor` 跳过 Server 段。
 
 ## 相关链接