csspilot 0.1.0

package/dist/skills/testpilot/SKILL.md

@@ -0,0 +1,64 @@
+# TestPilot
+
+## What is TestPilot
+
+TestPilot is an AI Native cross-platform testing infrastructure.
+
+It lets AI understand, generate, validate and run business tests for Web and Mini Program apps.
+
+TestPilot is a **tool, not a business test project**. Business cases always belong to the project (`tests/e2e/cases/`), never to TestPilot itself.
+
+## When to use
+
+Use TestPilot when the user wants to:
+
+- create business test cases
+- validate test cases
+- run tests
+- inspect test results
+
+## Core workflow
+
+1. Understand user requirement
+2. Inspect project
+3. Identify test target
+4. Create TestPilot Case (`tests/e2e/cases/*.yaml`)
+5. Validate Case (`npx testpilot validate`)
+6. Run Case (`npx testpilot run`)
+7. Analyze result (`npx testpilot report`)
+
+## Important rules
+
+- Never directly control Playwright.
+- Never directly control WeChatIDE.
+- Use TestPilot DSL to describe tests.
+- Business cases belong to the project.
+- Prefer existing project conventions.
+- Never invent locators without evidence.
+- Validate before running.
+
+## CLI
+
+```bash
+npx testpilot init      # install TestPilot into the current project
+npx testpilot validate  # validate cases against the DSL
+npx testpilot list      # list cases (--tag smoke)
+npx testpilot run       # run cases (file paths / --tag)
+npx testpilot report    # generate JSON + HTML report
+npx testpilot doctor    # check environment
+```
+
+## Directory map (business project)
+
+- `.ai/skills/testpilot/` — this skill (AI usage spec)
+- `.testpilot/` — TestPilot runtime state and artifacts
+- `tests/e2e/cases/` — business cases
+- `testpilot.yaml` — project-level TestPilot config
+
+## Further reading
+
+- `rules/case-design.md` — what a case is, evidence-first generation
+- `rules/dsl.md` — case structure and the V0.1 action set
+- `rules/locator.md` — locator forms and the no-invention rule
+- `rules/assertion.md` — assertions and variable references
+- `workflows/` — step-by-step workflows (create / validate / run / analyze)

package/dist/skills/testpilot/manifest.yaml

@@ -0,0 +1,37 @@
+# TestPilot Skill 清单(源文件)
+# `npx testpilot init` 会把整个 skills/testpilot/ 安装到业务项目 .ai/skills/testpilot/
+id: testpilot
+name: TestPilot
+version: 0.1.0
+
+description: >
+  AI Native cross-platform testing skill.
+
+capabilities:
+  - create-case
+  - validate
+  - run
+  - list
+  - report
+
+runtime:
+  cli: testpilot
+
+permissions:
+  filesystem:
+    read:
+      - src/**
+      - pages/**
+      - tests/**
+      - testpilot.yaml
+
+    write:
+      - tests/e2e/**
+      - .testpilot/**
+
+  shell:
+    allow:
+      - npx
+      - pnpm
+      - npm
+      - testpilot

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

@@ -0,0 +1,6 @@
+# 断言规范
+
+- 断言使用 `action: assert`,配合 `locator` + `expected`。
+- `expected` 支持 `${variable}` 变量引用,变量来自之前的 `extract` 步骤(存于 ExecutionContext,可跨端传递,如小程序提取订单号 → Web 端断言)。
+- 断言必须对应真实业务预期(如订单号出现在 Web 后台),不写恒真断言。
+- 断言失败不一定是 Case 错误:先分析 Evidence(截图 / trace / log),判断是用例问题还是产品 bug,再决定修改 Case 还是上报问题。

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

@@ -0,0 +1,29 @@
+# Case 设计规范
+
+## Case 属于业务项目
+
+- Case 只存在于业务项目的 `tests/e2e/cases/`,永远不要写进 TestPilot 仓库的 `packages/`。
+- 一个 Case 描述一条完整的业务流程(如:创建订单、提交退款),不是单个页面操作。
+- `id` 使用 kebab-case,与文件名一致:`order-create.yaml` → `id: order-create`。
+
+## AI 不能凭空生成测试
+
+正确路径:
+
+```text
+用户需求 → 代码 / 页面 / 配置 → Evidence → 测试步骤 → Case
+```
+
+禁止路径:
+
+```text
+用户需求 → AI 猜 → Case
+```
+
+看到"测试登录"就直接写 `locator: { text: 登录 }` 是错误的。
+必须先阅读项目真实页面/代码,确认元素存在、文案准确,再生成步骤。
+
+## 业务数据
+
+- 不要把业务账号、密码硬编码进 Case。
+- 测试数据放业务项目 `tests/e2e/fixtures/` 或 `tests/e2e/data/`,Case 中通过变量引用。

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

@@ -0,0 +1,42 @@
+# DSL 规范
+
+Case 是 YAML 文件,V0.1 顶层结构:
+
+```yaml
+id: order-create      # kebab-case,与文件名一致
+name: 用户创建订单      # 人类可读名称
+steps:                # 有序步骤列表
+  - target: miniapp   # 执行端:miniapp | web
+    action: click     # 见下方 Action 表
+    locator:          # 定位器(见 rules/locator.md)
+      text: 提交订单
+```
+
+## V0.1 稳定 Action
+
+| action | 用途 | 关键字段 |
+| --- | --- | --- |
+| `launch` | 启动应用(miniapp) | — |
+| `navigate` | 打开页面(web) | `url` |
+| `click` | 点击 | `locator` |
+| `input` | 输入 | `locator`, `value` |
+| `select` | 选择 | `locator`, `value` |
+| `wait` | 等待 | 条件(以 @testpilot/dsl schema 为准) |
+| `assert` | 断言 | `locator`, `expected` |
+| `extract` | 提取内容为变量 | `locator`, 变量名(以 schema 为准) |
+| `screenshot` | 截图取证 | — |
+
+字段定义最终以 `packages/dsl` 的 zod schema 为准;不要使用表中之外的字段。
+
+## 原则:Action 是通用测试原语,不是业务能力
+
+```text
+login / order / payment   ❌ 业务动作不是 Action
+click / input / assert    ✓ 由基础 Action 组合表达业务流程
+```
+
+登录、下单等业务流程由多个基础 Action 组合而成,不要设计业务 Action。
+
+## 示例
+
+见仓库 `examples/cases/order-create.yaml`(小程序下单 → Web 后台验证的黄金路径)。

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

@@ -0,0 +1,14 @@
+# Locator 规范
+
+## V0.1 支持形式
+
+- `text:` 按可见文案匹配(仅 web,如 `text: 提交订单`)
+- `css:` 按 CSS 选择器匹配(web 与小程序均支持,如 `css: .order-id`;小程序匹配 WXML 的 class/id)
+
+## 铁律:不凭空发明 locator
+
+- locator 必须来自真实证据:页面源码、DOM、组件代码,或 screenshot / extract 的结果。
+- 禁止根据业务名词猜测文案或类名。
+- 文案类 locator 要与真实渲染完全一致,注意空格与标点。
+- 优先选择稳定且语义化的目标:自定义属性 > 语义类名 > 文案;避免依赖动态生成的类名和元素索引。
+- 小程序端只能用 css:从 WXML / WXSS 中确认 class 或 id 后再写步骤。

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

@@ -0,0 +1,12 @@
+# Workflow:分析测试结果
+
+1. 执行 `npx testpilot 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? }] }] } }`
+   - `report.html` —— 人类可读报告
+   - `screenshots/`、`traces/`、`logs/` —— 失败取证
+3. 失败分析顺序:report.json 中失败步骤的 `error` 信息 → 对应 `screenshot` → `logs/run.log` → `events.ndjson`。
+4. 得出结论:
+   - Case 问题(locator 过期、步骤错误)→ 修改 Case,重新 validate → run
+   - 产品 bug → 停止修改 Case,向用户报告证据与结论
+5. 不要在未分析 Evidence 的情况下盲目重跑或修改 Case。

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

@@ -0,0 +1,13 @@
+# Workflow:创建测试 Case
+
+输入:用户的一句业务需求(如"帮我测试用户下单")。
+
+1. 阅读本 Skill:`rules/dsl.md`、`rules/case-design.md`、`rules/locator.md`。
+2. 分析项目结构:确定被测端(miniapp / web)与业务入口页面。
+3. 找到业务路径上的真实页面与组件,收集证据(读代码 / DOM / 现有测试)。
+4. 确定测试路径:从入口到业务结果页的完整步骤。
+5. 按 DSL 规范生成 Case,写入 `tests/e2e/cases/<case-id>.yaml`。
+6. 执行 `npx testpilot validate tests/e2e/cases/<case-id>.yaml`。
+7. 校验失败则修复 Case 后重新 validate,直到通过。
+
+禁止:跳过第 2-3 步直接生成 Case(AI 不能凭空生成测试)。

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

@@ -0,0 +1,19 @@
+# Workflow:执行测试
+
+```bash
+npx testpilot run                  # 运行项目配置(testpilot.yaml)中的 Case
+npx testpilot run <file>           # 运行指定 Case
+npx testpilot run --tag smoke      # 按标签运行
+```
+
+执行链路:
+
+```text
+CLI → Case Loader → DSL Validator → Execution Engine → Adapter(Playwright / WeChatIDE)→ Evidence → Reporter
+```
+
+规则:
+
+- 只通过 testpilot CLI 执行测试,不要直接调用 playwright 或 wechat-devtools。
+- 被测服务需先就绪(如业务后端、本地页面服务),`navigate` 的相对 url 基于 testpilot.yaml 的 `web.baseUrl` 解析。
+- 运行产物写入 `.testpilot/artifacts/runs/<run-id>/`(screenshots / traces / logs)。

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

@@ -0,0 +1,21 @@
+# Workflow:校验 Case
+
+任何 Case 在 run 之前必须先 validate。
+
+```bash
+npx testpilot validate              # 全量
+npx testpilot validate <file>       # 指定文件
+```
+
+检查内容:
+
+- YAML 格式
+- DSL 结构
+- action 是否存在
+- target 是否存在
+- locator 是否合法
+- 必填字段
+- 变量引用
+- 当前 adapter 是否支持该 action
+
+输出 `ValidationResult`;有错误时修复 Case 后重新校验,全部通过才允许 run。

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "csspilot",
+  "version": "0.1.0",
+  "description": "TestPilot — AI Native 跨端业务测试基础设施 CLI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/3lin9/css-test-pilot.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "csspilot": "dist/bin.js"
+  },
+  "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/adapter-core": "workspace:^",
+    "@testpilot/adapter-playwright": "workspace:^",
+    "@testpilot/adapter-wechatide": "workspace:^",
+    "@testpilot/core": "workspace:^",
+    "@testpilot/dsl": "workspace:^",
+    "@testpilot/evidence": "workspace:^",
+    "@testpilot/execution-engine": "workspace:^",
+    "@testpilot/reporter": "workspace:^",
+    "@types/node": "^22.0.0",
+    "commander": "^12.0.0",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}