@pzy560117/opentest 0.1.1 → 0.1.2

package/README.md

@@ -2,6 +2,8 @@
 
 OpenTest is a Codex skill bundle for planning, running, verifying, and archiving quality evidence for code changes.
 
+It is intended for OpenTest-driven development: before implementation, it turns explicit requirements plus implicit product behavior into an acceptance-to-test matrix, then uses that matrix to drive unit, component, integration, contract, E2E, smoke, browser acceptance, and security evidence.
+
 It provides a small lifecycle:
 
 ```text
@@ -10,6 +12,18 @@ plan -> author -> run -> accept -> verify -> archive
 
 `heal` is a recovery phase for stale test assets and must not hide product behavior failures.
 
+Recommended placement in a development loop:
+
+```text
+requirement / design
+  -> opentest plan
+  -> opentest author
+  -> implementation
+  -> opentest run
+  -> opentest accept
+  -> opentest verify
+```
+
 ## Install
 
 Install into the current project:
@@ -48,4 +62,3 @@ Restart Codex or open a new session after installation so the new skills are loa
 - `assets/skills/`: Codex skill files
 - `assets/manifest.json`: published asset manifest
 - `bin/opentest.js`: installer CLI
-

package/assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.1",
+  "version": "0.1.2",
   "skills": [
     "opentest/SKILL.md",
     "opentest/scripts/opentest-state.sh",
@@ -11,6 +11,7 @@
     "opentest/references/acceptance-evidence.md",
     "opentest/references/command-routing.md",
     "opentest/references/codex-harness-coverage-heuristics.md",
+    "opentest/references/opentest-driven-development.md",
     "opentest/templates/plan-template.md",
     "opentest/templates/matrix-template.md",
     "opentest/templates/acceptance-template.md",

package/assets/skills/opentest/SKILL.md

@@ -5,6 +5,8 @@ description: "OpenTest 路由入口。自动检测 .opentest.yaml、初始化测
 
 # OpenTest 路由入口
 
+OpenTest 是面向 AI 编程变更的测试决策与质量证据生命周期。它不是单纯的 TDD 包装，也不是只在实现结束后跑命令；它应在实现前先把显性需求、隐性边界、失败路径、交互反馈和风险场景整理成测试矩阵，再用矩阵驱动代码、验收和质量门。
+
 ## 产出语言契约
 
 - 面向用户输出和生成文档默认使用中文。
@@ -58,3 +60,26 @@ bash "$OPENTEST_STATE" get phase
 - `phase: archive`：调用 `opentest-archive`。
 
 若状态与可验证文件冲突，以文件状态为准，并用 `opentest-state.sh set` 修正。
+
+## OpenTest-Driven Development 用法
+
+当用户想“以测试驱动开发”、需求包含前端交互、登录、表单、权限、API、数据写入、跨页面流程或高风险行为时，OpenTest 必须前置到 build 之前：
+
+```text
+需求 / OpenSuper design
+  -> opentest plan    # 隐性场景挖掘 + acceptance-to-test matrix
+  -> opentest author  # 测试资产 / 自然语言验收用例
+  -> build            # 按矩阵实现
+  -> opentest run     # unit / integration / smoke / e2e 命令
+  -> opentest accept  # 真实页面、API 或链路验收
+  -> opentest verify  # 质量门报告
+```
+
+`plan` 阶段不能只复述需求。它必须主动检查：
+
+- 主路径、失败路径、边界输入、空数据、权限、网络、重复提交、并发或过期状态。
+- 前端反馈位置：字段下方、表单顶部、toast、modal、inline status、页面错误态。
+- 证据分层：unit、component、integration、contract、E2E、smoke、visual/browser acceptance、security/review。
+- 哪些证据是必需，哪些是不适用，哪些是 gap 或 risk-accepted 候选。
+
+实现完成后，`OpenSuper verify` 可以引用 OpenTest 的 verification report，但不能替代 OpenTest 的矩阵、运行记录和验收证据。

package/assets/skills/opentest/references/acceptance-evidence.md

@@ -6,10 +6,13 @@ Natural language acceptance cases must include:
 - intent
 - context
 - actor or role
+- trigger or input
 - steps
 - expected outcome
+- expected feedback location when UI feedback is involved
 - execution surface
 - evidence status
+- artifacts or observation notes
 
 Allowed evidence status:
 
@@ -20,3 +23,5 @@ Allowed evidence status:
 - risk-accepted
 
 Blocked evidence must include a reason such as unavailable MCP, unavailable environment, missing seed data, auth requirement, or external service failure.
+
+UI feedback evidence should record the actual location and shape of feedback, for example field-level inline error, form-level alert, toast, modal, page-level error panel, disabled control, loading indicator, or retry action.

package/assets/skills/opentest/references/codex-harness-coverage-heuristics.md

@@ -45,6 +45,25 @@ OpenTest 应根据变更类型、风险和项目事实选择适用覆盖面。
 | D9 组件联动 | 筛选、tab、数量、级联变化 |
 | D10 边界情况 | 空数据、长文本、特殊输入、前置数据缺失 |
 
+## 隐性场景默认挖掘
+
+OpenTest plan 阶段默认检查以下问题；适用则进入矩阵，不适用则简短说明：
+
+| 类别 | 默认追问 |
+| --- | --- |
+| 输入为空 | 空字段是否阻止提交，错误显示在字段下方还是表单顶部 |
+| 输入非法 | 格式、长度、范围、重复值、依赖字段如何反馈 |
+| 网络失败 | 是否显示网络错误、重试入口，是否保留用户输入 |
+| 服务端失败 | 4xx/5xx 是否区分，是否避免泄露技术细节 |
+| 认证/会话 | token 过期、未登录、已登录访问登录页如何处理 |
+| 权限不足 | 操作隐藏、禁用还是显示权限说明 |
+| 重复提交 | 提交中按钮状态、防重复请求、幂等或冲突处理 |
+| 空数据 | 初始无数据和筛选无结果是否区分 |
+| 长内容/大数据 | 分页、截断、虚拟化、长文本和极端数量 |
+| 移动端 | 键盘遮挡、触控目标、窄屏布局和返回路径 |
+| 可访问性 | 键盘路径、焦点、错误关联、屏幕阅读器提示 |
+| 安全 | 敏感信息、越权、注入、CSRF/重复操作风险 |
+
 ## 输出约束
 
 `/opentest-plan` 应优先输出窄矩阵：

package/assets/skills/opentest/references/matrix-format.md

@@ -2,8 +2,8 @@
 
 ## Minimal Columns
 
-| ID | 意图 | 风险 | 必需证据 | 状态 |
-| --- | --- | --- | --- | --- |
+| ID | 意图 | 触发/输入 | 期望行为 | 风险 | 证据层级 | 必需证据 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
 
 ## Optional Columns
 
@@ -14,3 +14,14 @@
 - 风险接受说明
 
 Only add optional columns when risk or change type needs them.
+
+## Evidence Layers
+
+- `unit`：纯函数、校验规则、状态计算。
+- `component`：表单反馈、按钮状态、局部 UI 状态。
+- `integration`：模块协作、API client、状态管理、mock server。
+- `contract`：请求/响应字段、错误码、权限响应。
+- `e2e`：跨页面、登录、权限、关键业务闭环。
+- `smoke`：关键页面或主路径不崩。
+- `browser-acceptance`：真实浏览器交互、反馈位置、响应式和视觉状态。
+- `security-review`：权限、敏感信息、越权、重复提交、注入风险。

package/assets/skills/opentest/references/opentest-driven-development.md

@@ -0,0 +1,48 @@
+# OpenTest-Driven Development
+
+## 定位
+
+OpenTest-driven development 不是传统 TDD 的替代名词。它把 TDD 放进更大的质量证据链里：先做隐性场景挖掘和风险矩阵，再决定哪些用 unit/component/integration/contract/E2E/smoke/browser acceptance/security review 证明。
+
+## 为什么不是只写 TDD
+
+传统 TDD 容易只覆盖显性需求和 happy path。真实产品行为还包括：
+
+- 空输入、非法输入和字段依赖。
+- 网络失败、服务端失败、认证过期和权限不足。
+- 错误反馈到底显示在字段下方、表单顶部、toast、modal 还是页面错误区。
+- loading、empty、retry、disabled、submitting、long content、mobile。
+- 跨页面跳转、返回恢复、数据刷新和重复提交。
+
+这些场景需要先进入 acceptance-to-test matrix，再决定证据层级。
+
+## 推荐顺序
+
+```text
+需求 / OpenSuper design
+  -> OpenTest plan: 隐性场景 + 风险 + 证据层级
+  -> OpenTest author: 测试资产和自然语言验收
+  -> build: 按矩阵实现
+  -> OpenTest run: 跑项目命令
+  -> OpenTest accept: 真实验收
+  -> OpenTest verify: 质量门报告
+  -> OpenSuper verify/archive
+```
+
+## 登录示例
+
+| ID | 意图 | 触发/输入 | 期望行为 | 风险 | 证据层级 | 必需证据 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| ACC-001 | 正确账号登录成功 | 合法账号密码 | 跳转目标页并建立会话 | high | e2e | 登录流程验收 | pending |
+| ACC-002 | 用户名为空 | 空用户名 + 任意密码 | 用户名字段下方错误，不发请求 | medium | component | 表单测试或 UI 验收 | pending |
+| ACC-003 | 密码错误 | 正确用户名 + 错误密码 | 表单顶部或密码区域显示认证失败，保留用户名 | high | integration | API mock + UI 验收 | pending |
+| ACC-004 | 网络断开 | 登录请求网络失败 | 显示网络错误和重试，不误报密码错误 | high | e2e | 网络失败验收 | pending |
+| ACC-005 | 重复点击提交 | 请求中再次点击 | 按钮 loading 且不重复提交 | medium | component | UI 状态测试 | pending |
+| ACC-006 | token 过期 | 访问受保护页面 | 回登录页并保留来源路径 | high | e2e | 会话过期验收 | pending |
+
+## 输出要求
+
+- 每个 required 场景必须有证据层级和执行面。
+- blocked 不能直接等于 pass；必须写原因和恢复路径。
+- high-risk 场景缺证据默认 fail，除非用户明确接受风险并写明理由。
+- 产品行为失败不能通过 heal 掩盖，必须回到实现或需求修正。

package/assets/skills/opentest/references/quality-gate.md

@@ -8,12 +8,15 @@
 - required test failure
 - required acceptance failure
 - required evidence gap for high-risk behavior
+- required evidence marked blocked without a recovery path
+- product behavior failure hidden as a test asset issue
 
 ## Risk Accepted
 
 - non-critical evidence gap with written reason
 - unavailable optional tool with fallback evidence
 - low-risk behavior covered by review rather than execution
+- blocked evidence with explicit reason and owner, when behavior is not high-risk
 
 ## Non-Blocking Gap
 

package/assets/skills/opentest/scripts/opentest-guard.sh

@@ -58,12 +58,6 @@ result_is_archivable() {
   [ "$result" = "pass" ] || [ "$result" = "risk-accepted" ]
 }
 
-result_is_verify_exit() {
-  local result
-  result=$(yaml_field verification_result)
-  [ "$result" = "pass" ] || [ "$result" = "risk-accepted" ] || [ "$result" = "fail" ]
-}
-
 guard_plan() {
   check_path "plan exists" "$(yaml_field plan)"
   check_path "matrix exists" "$(yaml_field matrix)"
@@ -99,7 +93,7 @@ guard_accept() {
 
 guard_verify() {
   check_path "verification report exists" "$(yaml_field verification_report)"
-  check_result "verification result is pass, risk-accepted, or fail" result_is_verify_exit
+  check_result "verification result is archivable" result_is_archivable
 }
 
 guard_heal() {

package/assets/skills/opentest/templates/acceptance-template.md

@@ -6,6 +6,8 @@
 - context:
 - actor:
 - execution surface:
+- trigger/input:
+- expected feedback location:
 - status: pending
 
 ### Steps
@@ -14,7 +16,14 @@
 
 ### Expected Outcome
 
-- 
+-
+
+### Feedback Contract
+
+- location:
+- visual state:
+- retry/recovery:
+- data preservation:
 
 ### Evidence
 

package/assets/skills/opentest/templates/matrix-template.md

@@ -1,5 +1,6 @@
 # Acceptance-to-Test Matrix
 
-| ID | 意图 | 风险 | 必需证据 | 状态 |
-| --- | --- | --- | --- | --- |
-| ACC-001 |  | low | targeted review | pending |
+| ID | 意图 | 触发/输入 | 期望行为 | 风险 | 证据层级 | 必需证据 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| ACC-001 | 主路径成功 |  |  | low | smoke | targeted review | pending |
+| ACC-002 | 失败/边界路径 |  |  | medium | acceptance | UI/API 验收 | pending |

package/assets/skills/opentest/templates/plan-template.md

@@ -12,7 +12,17 @@
 - 不适用:
 - gap:
 
+## 隐性场景挖掘
+
+- 空输入/非法输入:
+- 网络/服务端失败:
+- 权限/会话:
+- 重复提交/并发/过期状态:
+- loading/empty/error/retry:
+- 移动端/可访问性:
+- 安全/敏感信息:
+
 ## 证据计划
 
-| 证据 | 命令或执行面 | 产物路径 | 状态 |
-| --- | --- | --- | --- |
+| 证据层级 | 适用场景 | 命令或执行面 | 产物路径 | 状态 |
+| --- | --- | --- | --- | --- |

package/assets/skills/opentest/templates/report-template.md

@@ -13,8 +13,13 @@
 
 ## Acceptance Evidence
 
-| ID | result | evidence | notes |
-| --- | --- | --- | --- |
+| ID | required | result | evidence | notes |
+| --- | --- | --- | --- | --- |
+
+## Matrix Coverage
+
+| ID | evidence layer | required evidence | result | gap/risk |
+| --- | --- | --- | --- | --- |
 
 ## Quality Gate
 

package/assets/skills/opentest-accept/SKILL.md

@@ -14,9 +14,10 @@ description: "OpenTest 阶段 4：执行自然语言验收、MCP 验收或真实
 1. 读取矩阵和 `docs/opentest/acceptance/`。
 2. 对前端交互，优先用 Chrome DevTools MCP 执行真实页面验收。
 3. 对 API 或后台链路，使用项目已有命令或直接 API 检查。
-4. 工具、环境或前置数据不可用时，记录 blocked evidence。
-5. 更新验收记录。
-6. 运行 `bash "$OPENTEST_GUARD" accept --apply`。
+4. 对反馈类场景，必须观察实际呈现位置和形态；例如字段错误不能只记录“失败”，要记录是否在字段下方、表单顶部、toast、modal 或页面错误区显示。
+5. 工具、环境或前置数据不可用时，记录 blocked evidence。
+6. 更新验收记录。
+7. 运行 `bash "$OPENTEST_GUARD" accept --apply`。
 
 ## Existing Skill Routing
 

package/assets/skills/opentest-author/SKILL.md

@@ -9,14 +9,17 @@ description: "OpenTest 阶段 2：根据矩阵补齐测试资产和自然语言
 
 根据 acceptance-to-test matrix 创建或更新测试资产。
 
+本阶段把矩阵变成可执行证据：能用项目测试框架证明的写测试；更适合真实链路、浏览器、API 或人工可复验步骤证明的，写自然语言验收用例。不要为了“像 TDD”而把所有交互反馈硬塞进 unit test。
+
 ## 步骤
 
 1. 读取 `.opentest.yaml` 中的 `matrix`。
-2. 对代码级证据，按项目已有测试框架创建或更新测试文件。
-3. 对真实链路证据，写入 `docs/opentest/acceptance/` 自然语言验收用例。
-4. 对不适用或当前无法补齐的证据，记录原因和风险。
-5. 写入 `.opentest.yaml` 的 `acceptance` 字段。
-6. 运行 `bash "$OPENTEST_GUARD" author --apply`。
+2. 对 unit/component/integration/contract 证据，按项目已有测试框架创建或更新测试文件。
+3. 对 E2E、smoke、browser acceptance、真实 API 或跨页面流程，写入 `docs/opentest/acceptance/` 自然语言验收用例。
+4. 对前端反馈类用例，写清反馈位置和形态，例如字段下方错误、表单顶部错误、toast、modal、inline status 或页面错误态。
+5. 对不适用或当前无法补齐的证据，记录原因和风险。
+6. 写入 `.opentest.yaml` 的 `acceptance` 字段。
+7. 运行 `bash "$OPENTEST_GUARD" author --apply`。
 
 ## Existing Skill Routing
 

package/assets/skills/opentest-plan/SKILL.md

@@ -9,15 +9,21 @@ description: "OpenTest 阶段 1：分析变更、风险和项目事实，生成
 
 生成 `docs/opentest/plans/` 下的测试策略和 `docs/opentest/matrices/` 下的矩阵。
 
+本阶段是 OpenTest-driven development 的入口。它必须在实现前把“需求没写但成熟产品默认应该处理”的场景显性化，避免只根据字面需求写少量 happy path 测试。
+
 ## 步骤
 
-1. 读取项目规则、需求、diff、现有测试命令和 `opentest/references/codex-harness-coverage-heuristics.md`。
-2. 判断变更类型、风险等级和适用覆盖面。
-3. 生成窄矩阵，至少包含 `ID`、`意图`、`风险`、`必需证据`、`状态`。
-4. 对适用但未覆盖的证据面标记 `gap`。
-5. 写入 `.opentest.yaml` 的 `plan` 和 `matrix` 字段。
-6. 运行 `bash "$OPENTEST_GUARD" plan --apply`。
+1. 读取项目规则、需求、设计、diff、现有测试命令和 `opentest/references/codex-harness-coverage-heuristics.md`。
+2. 如果存在前端、表单、导航、CRUD、状态反馈或动效，优先读取项目内 `docs/frontend/DESIGN.md` 和可用的 `harness-frontend-design` / `product-ui-defaults` 规则。
+3. 判断变更类型、风险等级和适用覆盖面。
+4. 做隐性场景挖掘：空输入、非法输入、网络失败、权限不足、重复提交、长内容、空数据、错误映射、移动端、可访问性、跨页面返回和状态恢复。
+5. 生成窄矩阵，至少包含 `ID`、`意图`、`触发/输入`、`期望行为`、`风险`、`证据层级`、`必需证据`、`状态`。
+6. 对适用但未覆盖的证据面标记 `gap`。
+7. 写入 `.opentest.yaml` 的 `plan` 和 `matrix` 字段。
+8. 运行 `bash "$OPENTEST_GUARD" plan --apply`。
 
 ## 约束
 
 不要把 Codex Harness 全量 checklist 展开成固定必需项。低风险变更保留轻量覆盖摘要，高风险闭环再展开详细验收维度。
+
+不要把所有证据都写成 unit test。矩阵要明确哪些用 unit/component/integration/contract/E2E/smoke/browser acceptance/security review 证明。

package/assets/skills/opentest-run/SKILL.md

@@ -16,10 +16,12 @@ description: "OpenTest 阶段 3：按 targeted、fast、full 或 ci-like 模式
 - `full`：运行项目完整测试命令。
 - `ci-like`：尽量复现 CI 验证顺序。
 
+证据层级由矩阵决定。不要因为存在 `npm test` 就只跑 unit test；如果矩阵要求 integration、contract、E2E、smoke 或安全检查，必须运行对应项目命令，或记录 missing command / blocked。
+
 ## 步骤
 
 1. 读取 `.opentest.yaml` 的 `run_mode` 和矩阵。
-2. 优先使用项目显式命令。
+2. 优先使用项目显式命令，按矩阵中的证据层级选择 targeted、fast、full 或 ci-like。
 3. 记录命令、退出码、摘要和日志路径到 `docs/opentest/runs/`。
 4. 写入 `.opentest.yaml` 的 `run_report` 字段。
 5. 运行 `bash "$OPENTEST_GUARD" run --apply`。

package/assets/skills/opentest-verify/SKILL.md

@@ -14,3 +14,10 @@ description: "OpenTest 阶段 5：应用质量门并生成验证报告。"
 验证报告按 build、type、lint、test、security、diff 组织。若项目没有某类命令，记录为 missing command 或 not applicable，不把未知状态写成 pass。
 
 按 build、type、lint、test、security、diff 的顺序组织证据。必需测试、必需验收、构建、类型或 lint 失败时标记 `fail`。非必需缺口可记录为 `risk-accepted`。写入 `docs/opentest/reports/` 和 `.opentest.yaml` 的 `verification_report`、`verification_result`。
+
+验证报告还必须回看矩阵，确认：
+
+- 每个 required evidence 都有 pass、fail、blocked 或 risk-accepted 结论。
+- 高风险行为不能因为没有工具、没有测试框架或没有 seed data 就直接通过。
+- blocked evidence 必须包含阻塞原因和后续恢复路径。
+- 若产品行为失败，不进入 `heal` 修测试资产；应返回实现或需求修正。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pzy560117/opentest",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "OpenTest quality evidence lifecycle skills for Codex",
   "keywords": [
     "opentest",