csspilot 0.5.0 → 0.6.0

package/dist/skills/testpilot/SKILL.md

@@ -21,7 +21,7 @@ Use TestPilot when the user wants to:
 ## Core workflow
 
 1. Understand user requirement
-2. Review requirements & produce test points (`workflows/test-requirements-review.md`)
+2. Review requirements, expand the rule matrix, and map QA coverage (`workflows/test-requirements-review.md`)
 3. Inspect project
 4. Identify test target
 5. Create TestPilot Case (`tests/e2e/cases/*.yaml`, linked to test point IDs)
@@ -38,6 +38,8 @@ Use TestPilot when the user wants to:
 - Prefer existing project conventions.
 - Never invent locators without evidence.
 - Validate before running.
+- Generate only evidence-backed `requires`; never assume every project has accounts, coupons, promotions, or PPM.
+- Use data-driven Case groups only when the steps are the same and each row remains one decidable rule/data point.
 
 ## CLI
 
@@ -66,6 +68,8 @@ Read `references/` first (generated by `csspilot init` for this project):
 - `.agents/skills/testpilot/` — this skill (AI usage spec)
 - `.testpilot/` — TestPilot runtime state and artifacts
 - `tests/e2e/cases/` — business cases
+- `tests/e2e/data/` — YAML/JSON fixtures and dataset rows
+- `tests/e2e/reviews/` — requirement matrix and QA coverage artifacts
 - `testpilot.yaml` — project-level TestPilot config
 
 ## Further reading

package/dist/skills/testpilot/manifest.yaml

@@ -2,7 +2,7 @@
 # `npx csspilot init` 会把整个 skills/testpilot/ 安装到业务项目 .agents/skills/testpilot/
 id: testpilot
 name: TestPilot
-version: 0.5.0
+version: 0.6.0
 
 description: >
   AI Native cross-platform testing skill.

package/dist/skills/testpilot/rules/assertion.md

@@ -4,3 +4,11 @@
 - `expected` 支持 `${variable}` 变量引用,变量来自之前的 `extract` 步骤(存于 ExecutionContext,可跨端传递,如小程序提取订单号 → Web 端断言)。
 - 断言必须对应真实业务预期(如订单号出现在 Web 后台),不写恒真断言。
 - 断言失败不一定是 Case 错误:先分析 Evidence(截图 / trace / log),判断是用例问题还是产品 bug,再决定修改 Case 还是上报问题。
+
+## 请求次数断言
+
+- UI 操作需要验证“只请求一次”时使用 `expectRequests`,不要用 wait 或页面文案间接推断。
+- 匹配条件是可选 `method` + 必填 `urlContains`;`count` 是精确次数,不是最小次数。
+- `windowMs` 是动作完成后的观察窗口,应取业务可合理完成的最小值。
+- Web 和 MiniApp 观察器必须透明调用真实请求,不得 mock 响应或改变业务行为。
+- URL 证据会隐藏 query 值;Case 中不要把 token 等秘密直接写入 `urlContains`。

package/dist/skills/testpilot/rules/case-design.md

@@ -6,6 +6,14 @@
 - 一个 Case 描述一条完整的业务流程(如:创建订单、提交退款),不是单个页面操作。
 - `id` 使用 kebab-case,与文件名一致:`order-create.yaml` → `id: order-create`。
 
+## Case 与数据行
+
+- 默认一条独立业务流程一个 Case。
+- 多个测试点的步骤模板完全相同、差异仅为输入数据和可判定预期时,允许合并为一个 data-driven Case。
+- 每个 dataset 行必须有稳定唯一的 rowId,并仍保持“一个可判定规则/数据点”粒度。
+- 不同页面路径、不同角色权限流程、不同清理策略或不同断言结构不得为了减少 Case 数量而强行合并。
+- 报告按 `caseId#rowId` 标识执行结果;统计时每个数据行算一次执行。
+
 ## AI 不能凭空生成测试
 
 正确路径:
@@ -26,4 +34,8 @@
 ## 业务数据
 
 - 不要把业务账号、密码硬编码进 Case。
-- 测试数据放业务项目 `tests/e2e/fixtures/` 或 `tests/e2e/data/`,Case 中通过变量引用。
+- 测试参数统一放业务项目 `tests/e2e/data/` 的 YAML/JSON 文件,Case 通过 `${fixture.*}` / `${dataset.*}` 引用。
+- `requires` 只声明当前 Case 有证据支持的静态依赖。AI 必须从 PRD/Spec、代码、配置、已有 Case 或 QA 用例识别,不得因为业务名称自动发明账号、优惠券、PPM 等字段。
+- `.env` 提供当前环境的实际值;只有 `testpilot.yaml variables` 白名单映射的值可通过 `${variable.*}` 暴露给 Case。
+- 缺失依赖会使该数据行 `skipped(dependency-not-ready)`,这只表示静态值未就绪,不保证远端业务对象有效。
+- setup/teardown 优先使用 API 造数和清理;teardown 必须可重复执行。

package/dist/skills/testpilot/rules/dsl.md

@@ -6,11 +6,29 @@ Case 是 YAML 文件,V0.1 顶层结构:
 id: order-create      # kebab-case,与文件名一致
 name: 用户创建订单      # 人类可读名称
 accountRef: test-user # 可选:引用环境凭据,用 ${account.username} 等变量,禁止明文密码
+fixtures:             # 可选:项目相对路径,仅允许 tests/e2e/data 下的 YAML/JSON
+  - tests/e2e/data/products.yaml
+datasets:             # 可选:同一 steps 按对象数组逐行执行
+  file: tests/e2e/data/checkout-rows.yaml
+  idField: id
+requires:             # 可选:逐行执行前的静态依赖契约
+  - fixture.product.styleNo
+  - dataset.expectedTotal
+  - variable.ppmProjectId
+setup:                # 可选:主步骤前执行
+  - target: api
+    action: request
+    url: /test-support/cart/clear
 steps:                # 有序步骤列表
   - target: miniapp   # 执行端:miniapp | web | api
     action: click     # 见下方 Action 表
     locator:          # 定位器(见 rules/locator.md)
       text: 提交订单
+teardown:             # 可选:setup 开始后始终执行
+  - target: api
+    action: request
+    url: /test-support/cart
+    method: DELETE
 ```
 
 ## V0.1 稳定 Action
@@ -30,6 +48,50 @@ steps:                # 有序步骤列表
 
 字段定义最终以 `packages/dsl` 的 zod schema 为准;不要使用表中之外的字段。
 
+## Data-driven、fixture 与 variables
+
+- fixture 文件根必须是对象;多个文件按顺序深合并,字段冲突直接校验失败。
+- dataset 文件根必须是对象数组;`idField` 默认 `id`,每行值必须非空且唯一。
+- 每个数据行有独立 ExecutionContext,同一 Case 的行之间不能共享 extract 变量。
+- 可用作用域:
+  - `${fixture.*}`:合并后的共享 fixture
+  - `${dataset.*}`:当前数据行
+  - `${account.*}`:`accountRef` 对应凭据
+  - `${variable.*}`:`testpilot.yaml variables` 白名单
+  - `${name}`:之前 `extract` 产生的运行时变量
+- 禁止 `${env.*}` 或其他方式任意读取进程环境变量。
+
+`requires` 只检查路径存在且不是 `null`、空字符串或未解析的 `${ENV_VAR}`。缺失时该行不执行任何阶段,结果为 `skipped`,原因 `dependency-not-ready`。
+
+## setup / steps / teardown
+
+执行顺序固定:
+
+1. `requires` 预检
+2. `setup`
+3. `steps`
+4. `teardown`
+
+setup 失败时主结果 failed、跳过主步骤并执行 teardown;主步骤失败也执行 teardown。teardown 失败记 warning,不改变主结果。
+
+## UI 请求次数断言
+
+`expectRequests` 可附在 web/miniapp 的 `navigate`、`click`、`input`、`select`:
+
+```yaml
+- target: web
+  action: click
+  locator:
+    css: .submit
+  expectRequests:
+    - method: POST
+      urlContains: /api/orders
+      count: 1
+      windowMs: 1000
+```
+
+它只观察并计数,不拦截、不修改响应。断言失败时报告实际次数和已脱敏的匹配 URL。
+
 ## api 端(HTTP 接口测试与造数)
 
 `target: api` 走 HTTP 执行端:相对 `url` 按 `testpilot.yaml` 的 `api.baseUrl` 解析。典型用法:API 造数 → UI 操作 → API/JSON 断言的混合编排。

package/dist/skills/testpilot/workflows/analyze-result.md

@@ -2,7 +2,7 @@
 
 1. 执行 `npx csspilot report` 生成报告。
 2. 产物位于 `.testpilot/artifacts/runs/<run-id>/`:
-   - `report.json` —— 结构化结果,AI 优先读这个:`{ generatedAt, summary: { runId, status, totals, cases: [{ caseId, status, steps: [{ index, target, action, status, durationMs, error?, screenshot?, extracted? }] }] }, history(最近 12 次运行趋势), failures(失败分类明细:category / caseId / message) }`;失败步骤的 `category` ∈ assert / element / adapter / env / timeout / other
+   - `report.json` —— 结构化结果,AI 优先读这个:`{ generatedAt, summary: { runId, status, totals, cases: [{ caseId, rowId, status, skipReason?, missingDependencies?, warnings?, steps: [{ phase, index, target, action, status, durationMs, error?, screenshot?, extracted?, requestAssertions? }] }] }, history(最近 12 次运行趋势), failures(失败分类明细:category / caseId / message) }`;失败步骤的 `category` ∈ assert / element / adapter / env / timeout / other
    - `report.html` —— 交互式报告(步骤树、失败分类筛选、历史趋势)
    - `screenshots/`、`videos/`、`traces/`、`logs/` —— 失败取证
 3. 失败分析顺序:report.json 中失败步骤的 `category` 与 `error` → 对应 `screenshot` → `logs/run.log` → `events.ndjson`。
@@ -10,4 +10,6 @@
    - Case 问题(locator 过期、步骤错误)→ 修改 Case,重新 validate → run
    - 产品 bug → 停止修改 Case,向用户报告证据与结论
 5. 历史趋势中出现反复失败的用例(intermittent / flaky)要在结论中单独标注。
-6. 不要在未分析 Evidence 的情况下盲目重跑或修改 Case。
+6. `skipped(dependency-not-ready)` 先按 missingDependencies 补数据,不归类为产品 bug;teardown warning 单独报告,不把已通过主流程改判 failed。
+7. 请求次数断言失败时比较 `actualCount/count` 和匹配请求摘要,排查重复绑定、重试或双击。
+8. 不要在未分析 Evidence 的情况下盲目重跑或修改 Case。

package/dist/skills/testpilot/workflows/create-case.md

@@ -8,8 +8,12 @@
 4. 针对测试点收集证据(读代码 / DOM / 现有测试),确定业务路径:从入口到业务结果页的完整步骤。
 5. 按 DSL 规范生成 Case,写入 `tests/e2e/cases/<case-id>.yaml`:
    - 一条 Case 覆盖一个测试点(或一组强关联测试点)
+   - 多个测试点步骤完全一致、仅数据和预期不同,使用 `datasets` 形成 data-driven Case;否则保持独立 Case
    - Case 的 `description` 注明关联的测试点编号(如 `测试点: TP-001`),保持需求可溯源
    - 按评审产出的平台执行信息声明 `accountRef` / `workspace`;发现 `.env` 缺少某平台的地址或凭据变量时,向用户索取后写入 `.env`,**不写进 Case**
+   - 从需求与项目证据中识别最小 `requires`;项目没有账号/优惠/PPM 等概念时不要生成对应依赖
+   - 公共参数写入 `tests/e2e/data/` fixture;环境参数先加入 `testpilot.yaml variables` 白名单
+   - 造数与清理使用 `setup` / `teardown`;UI 动作需验证接口调用次数时使用 `expectRequests`
 6. 执行 `npx csspilot validate tests/e2e/cases/<case-id>.yaml`。
 7. 校验失败则修复 Case 后重新 validate,直到通过。
 

package/dist/skills/testpilot/workflows/run-case.md

@@ -17,4 +17,7 @@ CLI → Case Loader → DSL Validator → Execution Engine → Adapter(Playwrigh
 - 只通过 testpilot CLI 执行测试,不要直接调用 playwright 或 wechat-devtools。
 - 被测服务需先就绪(如业务后端、本地页面服务),`navigate` 的相对 url 基于 testpilot.yaml 的 `web.baseUrl` 解析。
 - 环境变量来源:shell / CI secrets,或项目根目录 `.env` 文件(CLI 自动加载,真实环境变量优先);`.env` 含敏感信息,确认已加入 .gitignore。
+- Case 只能读取 `testpilot.yaml variables` 白名单映射后的 `${variable.*}`,不能直接访问任意环境变量。
+- 运行前按 dataset 行展开并预检 `requires`;依赖缺失的行显示 `skipped(dependency-not-ready)`,不是产品失败。
+- 每行按 setup → steps → teardown 执行;teardown warning 不改变主结果。
 - 运行产物写入 `.testpilot/artifacts/runs/<run-id>/`(screenshots / traces / logs)。

package/dist/skills/testpilot/workflows/test-requirements-review.md

@@ -1,7 +1,7 @@
 # Workflow:测试需求评审(可测性评审 + 测试点分析)
 
 输入:需求文档 / PRD / 用户的一句话(如"帮我测试用户下单")。
-产出:**测试点清单** + **平台执行信息表** + 澄清问题 + 评审结论。测试点清单是 `create-case` 的正式输入。
+产出:**原子规则清单** + **规则矩阵** + **测试点清单** + **QA → TestPilot Coverage Map** + **平台执行信息表** + 澄清问题 + 评审结论。测试点清单是 `create-case` 的正式输入。
 
 ## 步骤
 
@@ -13,7 +13,14 @@
    - 数据准备可行性:测试账号、mock 数据、上下游依赖是否可用
    - 平台与入口:miniapp / web 的页面路径与入口是否真实存在(不确定时先看项目代码)
    - 回归范围:改动是否影响现有功能,需要哪些已有 Case 回归
-4. **输出测试点清单**,每条包含:
+4. **拆解原子规则**:从验收标准中提取一条条可独立判定的规则或数据点。粒度必须是“一个输入/条件组合对应一个可判断预期”,不能把多个折扣、角色或状态变化塞进一个测试点。
+5. **建立规则矩阵**:
+   - 识别需求中的“类型 × 组合”维度,如折扣类型 × 账号等级 × 门槛边界 × 是否叠加
+   - 列出每个维度的值域、来源证据和约束
+   - 展开全部有效组合,每个有效组合至少生成一个测试点
+   - 互斥、不适用或业务禁止的组合不能静默删除,必须记录排除理由及需求证据
+   - 项目没有账号、优惠、PPM 等概念时不得自动添加这些维度
+6. **输出测试点清单**,每条包含:
 
    | 字段 | 说明 |
    | --- | --- |
@@ -24,12 +31,47 @@
    | 优先级 | P0 / P1 / P2 |
    | 平台 | miniapp / web / 双端 |
 
-5. **澄清阻塞项**:需求缺失、矛盾、不可判定时,列出问题向用户提问。**不猜测**。
-6. **给出评审结论**:
+7. **对标 QA 用例库**(用户提供时):
+   - 将每条 QA 用例映射到一个或多个 TP
+   - 标记 `covered` / `partial` / `missing` / `conflict`
+   - QA 有而 TestPilot 无的覆盖形成待补 checklist
+   - TestPilot 有而 QA 无的覆盖保留并说明来源,不得为追求一致而删除
+   - 将完整结果写入 `tests/e2e/reviews/<需求-slug>-coverage.md`,回复中只给摘要和文件路径
+8. **澄清阻塞项**:需求缺失、矛盾、不可判定时,列出问题向用户提问。**不猜测**。
+9. **给出评审结论**:
    - 可测:测试点清单完整,直接进入 `create-case`
    - 有条件可测:部分测试点依赖澄清,先对可执行部分建 Case
    - 不可测:说明缺口,等待需求补充
 
+## 规则矩阵模板
+
+```markdown
+| 维度 | 值域 | 来源证据 | 约束 |
+| --- | --- | --- | --- |
+| discountType | percentage / fixed | PRD §3.2 | fixed 不参与 VIP 加码 |
+| accountLevel | normal / vip | account.ts:L10-L16 | 游客不可下单 |
+
+| 组合 ID | discountType | accountLevel | 有效性 | 预期 / 排除理由 | TP |
+| --- | --- | --- | --- | --- | --- |
+| C-001 | percentage | vip | 有效 | 折扣后再加 VIP 优惠 | TP-001 |
+| C-002 | fixed | vip | 排除 | PRD §3.2 明确 fixed 不叠加 | — |
+```
+
+矩阵只使用需求、代码、配置、已有 Case 或 QA 用例中的真实维度。缺少证据时提出问题,不得套用电商默认字段。
+
+## QA → TestPilot Coverage Map 模板
+
+```markdown
+| QA Case | 对应 TP | 覆盖状态 | 差异 / 冲突 | 行动 |
+| --- | --- | --- | --- | --- |
+| QA-101 | TP-001 | covered | — | 无 |
+| QA-102 | TP-004 | partial | 缺少上边界 | 补 dataset 行 |
+| QA-103 | — | missing | TestPilot 无对应 TP | 新增 TP 和 Case |
+
+## Missing coverage checklist
+- [ ] QA-103: 新增……
+```
+
 ## 多平台:平台执行信息澄清
 
 需求涉及多个平台时,**每个平台都必须澄清以下三项**;缺任何一项,该平台相关测试点只能标记"有条件可测",不得开始写 Case:

package/dist/skills/testpilot/workflows/validate.md

@@ -16,6 +16,10 @@ npx csspilot validate <file>       # 指定文件
 - locator 是否合法
 - 必填字段
 - 变量引用
+- fixture/dataset 路径必须位于 `tests/e2e/data/`,格式与 rowId 合法且 fixture 无冲突
+- `requires` 路径语法与可用作用域
+- setup/steps/teardown 的变量定义顺序
+- `expectRequests` 仅用于支持的 UI 动作
 - 当前 adapter 是否支持该 action
 
 输出 `ValidationResult`;有错误时修复 Case 后重新校验,全部通过才允许 run。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "csspilot",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "TestPilot — AI Native 跨端业务测试基础设施 CLI",
   "license": "MIT",
   "repository": {
@@ -17,23 +17,23 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "node build.mjs",
+    "dev": "tsx src/bin.ts",
+    "start": "tsx src/bin.ts",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
     "miniprogram-automator": "^0.12.0",
     "playwright": "^1.53.0"
   },
   "devDependencies": {
+    "@testpilot/core": "workspace:^",
+    "@testpilot/sdk": "workspace:^",
     "@types/node": "^22.0.0",
     "commander": "^12.0.0",
     "esbuild": "^0.25.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.5.0",
-    "@testpilot/core": "^0.1.0",
-    "@testpilot/sdk": "^0.1.0"
-  },
-  "scripts": {
-    "build": "node build.mjs",
-    "dev": "tsx src/bin.ts",
-    "start": "tsx src/bin.ts",
-    "typecheck": "tsc --noEmit"
+    "typescript": "^5.5.0"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 TestPilot contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.