@pzy560117/opentest 0.1.10 → 0.1.12

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

@@ -0,0 +1,44 @@
+# API Acceptance
+
+## ACC-API-001
+
+- execution surface: api
+- acceptance mode: n/a
+- tool route: project API command | pytest + httpx/requests | curl/httpie | Postman/Newman | contract tool
+- evidence layer: contract | integration | smoke | security-review
+- base URL:
+- auth/role:
+- fixture/seed:
+- teardown:
+- status: pending
+
+### Request
+
+- method:
+- path:
+- headers:
+- query:
+- body:
+
+### Expected Response
+
+- status code:
+- headers:
+- schema/source:
+- payload assertions:
+- error contract:
+
+### Read-Back Contract
+
+- API read endpoint:
+- DB/storage/log/event assertion:
+- idempotency/retry assertion:
+- cleanup assertion:
+
+### Evidence
+
+- status:
+- request/response record:
+- report path:
+- artifacts:
+- blockers:

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

@@ -0,0 +1,43 @@
+# Desktop GUI Acceptance
+
+## ACC-Desktop-001
+
+- execution surface: desktop-gui
+- acceptance mode: n/a
+- tool route: project GUI automation | @midscene/computer | accessibility/window metadata | scripted manual GUI acceptance
+- evidence layer: gui-acceptance | visual-acceptance | integration | smoke
+- target app/window:
+- launch command:
+- fixture/reset:
+- status: pending
+
+### Environment
+
+- OS/display/RDP:
+- model env status:
+- app version/build:
+- target process/window metadata:
+
+### Steps
+
+1.
+
+### Expected Outcome
+
+-
+
+### Read-Back Contract
+
+- persisted result surface:
+- reopen/restart check:
+- accessibility/window metadata assertion:
+- file/config/app-state assertion:
+
+### Evidence
+
+- status:
+- screenshots/recording:
+- GUI action log:
+- window/app metadata:
+- Midscene/computer report or log:
+- blockers:

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

@@ -1,13 +1,14 @@
 # Acceptance-to-Test Matrix
 
-| ID | Requirement source | Intent | Coverage dimension | Trigger/Input | Expected behavior | Risk | Evidence layer | Framework/command | Required evidence | Gap/blocker | Status |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| ACC-001 | REQ-001 / user story | create succeeds | create | valid fixture entity | entity is created and visible in list/detail | high | integration + acceptance | `python -m pytest` + real workflow | create evidence, UI/API/DB assertion, fixture used | none | pending |
-| ACC-002 | REQ-001 / design list view | read/list/detail succeeds | read/list/detail | seeded entity | list, search/filter, and detail show correct data | high | integration + acceptance | `python -m pytest` + real workflow | read/list/detail evidence and data consistency check | none | pending |
-| ACC-003 | REQ-002 / edit workflow | update succeeds | update | edited fixture entity | updated values persist after read back | high | integration + acceptance | `python -m pytest` + real workflow | update evidence and read-back assertion | none | pending |
-| ACC-004 | REQ-003 / delete rule | delete succeeds safely | delete | existing fixture entity | confirm/cancel behavior works; deleted item disappears after confirmation | high | integration + acceptance | `python -m pytest` + real workflow | delete evidence, cancel evidence, post-delete read check | none | pending |
-| ACC-005 | Risk: invalid and unauthorized input | failure and boundary paths are handled | failure/boundary | invalid, empty, duplicate, unauthorized, or stale fixture data | clear feedback without corrupting data | high | unit/integration/acceptance | `python -m pytest` + acceptance | validation, permission, duplicate, stale-state evidence | none | pending |
-| ACC-006 | Business rule: data consistency | data consistency holds | data consistency | create/update/delete flow | UI, API, database/storage, files, and logs agree | high | integration | project command or `python -m pytest` | consistency evidence across surfaces | none | pending |
-| ACC-007 | User workflow: full CRUD | end-to-end CRUD flow works | end-to-end CRUD | create -> list -> detail -> update -> read back -> delete | full user workflow completes and leaves clean state | high | E2E/acceptance | browser/API workflow | full-chain steps, screenshots/logs, cleanup evidence | none | pending |
-| ACC-008 | Quality gate requirement | smoke gate passes | smoke | app starts and core entry points open | core route/API/CRUD happy path does not crash | high | smoke | project smoke command or targeted workflow | smoke_report path | none | pending |
-| ACC-009 | Delivery gate requirement | pre-push gate passes | pre-push | staged change before push | format/lint/type/unit/integration/smoke/diff checks pass or block push | high | pre-push | project command sequence | pre_push_report path | none | pending |
+| ID | Requirement source | Intent | Execution surface | Acceptance mode | Coverage dimension | Trigger/Input | Expected behavior | Risk | Evidence layer | Framework/command | Required evidence | Gap/blocker | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| ACC-001 | REQ-001 / user story | create succeeds in web UI | web-browser | instant-acceptance | create | valid fixture entity | entity is created and visible in list/detail | high | browser-acceptance + integration | Playwright MCP / Playwright CLI + project command | create evidence, UI/API/DB assertion, fixture used | none | pending |
+| ACC-002 | REQ-WEB-REG-001 / regression need | web CRUD has durable regression | web-browser | durable-regression | read/list/detail + end-to-end CRUD | committed E2E test | create -> list -> detail -> update -> read back -> delete is repeatable | high | e2e | `npx playwright test` or project E2E command | test file, trace/report, stable locator assertions | none | pending |
+| ACC-003 | REQ-WEB-VIS-001 / visual risk | visual web state is verified | web-browser | visual-ai-assist | visual behavior | weak selector or canvas UI | Midscene helps locate UI and deterministic read-back proves result | medium | visual-acceptance | Midscene + Playwright route | Midscene report, screenshot, read/assert result | none | pending |
+| ACC-004 | REQ-ANDROID-001 / mobile flow | create succeeds in Android app | android-app | n/a | create | APK installed on emulator/device | task is created and visible after app refresh | high | visual-acceptance + e2e | `opentest-android-app` / `android-midscene-pytest` / `python -m pytest tests_py -v` | pytest report, ADB smoke, Midscene HTML report, screenshot, logcat, device/app metadata, `midscene_run` logs | missing ADB/APK/device/package/model env/result surface if unavailable | pending |
+| ACC-005 | REQ-DESKTOP-001 / settings workflow | desktop setting saves | desktop-gui | n/a | update | desktop app window is open | setting persists after save and reopen | high | gui-acceptance + integration | `opentest-desktop-gui` / project GUI automation / `@midscene/computer` | screenshot or recording, GUI action log, app/window metadata, deterministic read-back, Midscene/computer report when used | missing display/RDP/app launch/window identity/model env/result surface if unavailable | pending |
+| ACC-006 | REQ-API-001 / contract | API create succeeds | api | n/a | create | valid request payload | response status and payload confirm created entity | high | contract + integration | `opentest-api` / project API command / `python -m pytest tests/api -v` | request/response record, status code, payload/schema assertion, read-after-write, data consistency, cleanup/teardown | missing base URL/auth/fixture/seed/teardown/dependency/schema/result surface if unavailable | pending |
+| ACC-007 | Risk: invalid and unauthorized input | failure and boundary paths are handled | api | n/a | failure/boundary | invalid, empty, duplicate, unauthorized, expired, forbidden, or stale fixture data | clear error contract without corrupting data | high | contract + security-review | `opentest-api` / project command / `python -m pytest tests/api -v` | validation, auth/permission, duplicate/idempotency, stale-state, error schema, sensitive-field evidence | none | pending |
+| ACC-007A | Risk: list contract drift | API list/search behavior is stable | api | n/a | list/filter/sort/pagination | seeded collection and query params | pagination, filtering, sorting, and empty result follow contract | medium | contract + integration | `opentest-api` / project API command | request/response record, schema assertion, pagination metadata, fixture isolation | not applicable if no list endpoint changed | pending |
+| ACC-008 | Quality gate requirement | smoke gate passes | web-browser | instant-acceptance | smoke | app starts and core entry points open | core route/API/CRUD happy path does not crash | high | smoke | project smoke command or targeted workflow | smoke_report path | none | pending |
+| ACC-009 | Delivery gate requirement | pre-push gate passes | api | n/a | pre-push | staged change before push | format/lint/type/unit/integration/smoke/diff checks pass or block push | high | pre-push | project command sequence | pre_push_report path | none | pending |

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

@@ -24,5 +24,5 @@
 
 ## Evidence Plan
 
-| Evidence layer | Applicable scenario | Command or execution surface | Artifact path | Status |
-| --- | --- | --- | --- | --- |
+| Execution surface | Acceptance mode | Evidence layer | Applicable scenario | Command/tool | Artifact path | Status |
+| --- | --- | --- | --- | --- | --- | --- |

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

@@ -0,0 +1,27 @@
+# Web Browser Acceptance
+
+- ACC ID:
+- execution surface: web-browser
+- acceptance mode: instant-acceptance | durable-regression | visual-ai-assist
+- tool route: Playwright MCP | Playwright CLI | @playwright/test | Midscene
+- page/route:
+- actor/role:
+- fixture:
+
+## Steps
+
+1. open:
+2. snapshot:
+3. fill/input:
+4. submit/confirm:
+5. snapshot after submit:
+6. read/assert changed result:
+7. screenshot/report:
+
+## Evidence
+
+- status:
+- changed result asserted:
+- artifact paths:
+- console/network notes:
+- blocked reason:

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

@@ -1,23 +1,34 @@
 ---
 name: opentest-accept
-description: "OpenTest phase 4: execute natural language, MCP, or real workflow acceptance and write back evidence."
+description: "OpenTest phase 4: execute acceptance and write back evidence."
 ---
 
 # OpenTest Accept
 
-Execute required acceptance items and write PASS, FAIL, or blocked evidence back to cases and the matrix.
+Write PASS, FAIL, or blocked evidence to cases and matrix.
 
 ## Required references
 
 - `opentest/references/acceptance-evidence.md`
 - `opentest/references/complete-testing-workflow.md`
+- `opentest/references/test-surfaces.md`
+- `opentest/references/android-app-testing.md`
+- `opentest/references/web-browser-testing.md`
+- `opentest/references/desktop-gui-testing.md`
+- `opentest/references/api-testing.md`
 - `opentest/templates/acceptance-template.md`
+- `opentest/templates/android-app-acceptance-template.md`
+- `opentest/templates/desktop-gui-acceptance-template.md`
+- `opentest/templates/api-acceptance-template.md`
 
 ## Steps
 
 1. Read the matrix, fixtures, and `docs/opentest/acceptance/`.
-2. For frontend interactions, prefer Chrome DevTools MCP and observe the real rendered UI.
-3. For API/backend workflows, use project commands or direct API checks.
-4. For CRUD/data changes, execute the full chain from the workflow reference.
-5. Record feedback location/shape, artifacts, blocked evidence, and matching ACC IDs.
-6. Update acceptance records and run `bash "$OPENTEST_GUARD" accept --apply`.
+2. Select the acceptance tool from the matrix execution surface.
+3. For `web-browser`, use `opentest-web-browser`: Playwright MCP/CLI, `@playwright/test` for durable regression, Midscene only for visual assist.
+4. For `android-app`, use `opentest-android-app` and `android-midscene-pytest`: `python -m pytest tests_py -v`, ADB smoke, Midscene HTML, logcat, and `midscene_run`; block missing prerequisites.
+5. For `desktop-gui`, use `opentest-desktop-gui`: project GUI automation or `@midscene/computer`, screenshot/recording, metadata, and read-back.
+6. For `api`, use `opentest-api`: project API command or `pytest` with `httpx`/`requests`, schema checks, fixtures, read-after-write, and cleanup/teardown.
+7. For CRUD/data changes, execute the full chain from the workflow reference.
+8. Record feedback location/shape, artifacts, blocked evidence, and matching ACC IDs.
+9. Update acceptance records and run `bash "$OPENTEST_GUARD" accept --apply`.

package/assets/skills/opentest-android-app/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: opentest-android-app
+description: "OpenTest Android app execution surface adapter. Use when planning, authoring, running, or accepting Android APK/app GUI workflows through android-midscene-pytest, ADB, emulator/device setup, screenshots, logcat, and Midscene reports."
+---
+
+# OpenTest Android App
+
+Use this adapter for `android-app` matrix rows.
+
+## Required references
+
+- `opentest/references/android-app-testing.md`
+- `opentest/templates/android-app-acceptance-template.md`
+
+## Route
+
+1. Use `android-midscene-pytest` as the detailed Android execution skill when available.
+2. Keep durable Android assets in the fixed layout from `test-asset-layout.md`: `tests/android/tests_py/`, `tests/android/midscene/`, and `scripts/opentest-run-android.ps1` or an existing Android harness command.
+3. User-facing execution should enter through pytest, normally `python -m pytest tests_py -v` in an existing harness or the repository's Android test entry.
+4. Run `npm run test:android` only when model environment variables are ready or when debugging the Midscene layer.
+5. Mark blocked when ADB, emulator/device, APK path, package name, model credentials, fixture data, or stable result surface is missing.
+
+## Evidence Contract
+
+PASS requires pytest result, ADB smoke, Midscene HTML report when visual automation runs, screenshots, logcat, device/app metadata, and any available `midscene_run` logs. Static screenshots alone are not Android app acceptance.

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

@@ -0,0 +1,25 @@
+---
+name: opentest-api
+description: "OpenTest API execution surface adapter. Use when planning, authoring, running, or accepting HTTP API, RPC, backend workflow, contract, auth, data consistency, idempotency, and integration evidence."
+---
+
+# OpenTest API
+
+Use this adapter for `api` matrix rows.
+
+## Required references
+
+- `opentest/references/api-testing.md`
+- `opentest/templates/api-acceptance-template.md`
+
+## Route
+
+1. Prefer the repository's existing API/integration test command when it is explicit and repeatable.
+2. If no project command exists, default to `pytest` with `httpx` or `requests`, schema checks via `jsonschema` or existing Pydantic/DTO models, and fixtures for seed/teardown.
+3. Use OpenAPI, protobuf, or existing contract docs as the contract source when present; otherwise write the expected status, headers, response schema, and business payload in the acceptance case.
+4. Mock or stub third-party APIs unless the requirement explicitly needs a live external dependency.
+5. Mark blocked when base URL, auth token, fixture data, seed/teardown, dependency service, or stable read-back surface is missing.
+
+## Evidence Contract
+
+PASS requires request/response records, status code, response payload or schema assertion, auth/permission result when applicable, data consistency/read-after-write evidence, and cleanup or teardown proof. API smoke only proves liveness; it does not replace contract, boundary, permission, or data consistency evidence for high-risk changes.

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

@@ -11,6 +11,7 @@ Turn the matrix into executable tests, fixtures, seed/teardown notes, and accept
 
 - `opentest/references/opentest-driven-development.md`
 - `opentest/references/complete-testing-workflow.md`
+- `opentest/references/test-asset-layout.md`
 - `opentest/templates/fixtures-template.md`
 - `opentest/templates/acceptance-template.md`
 
@@ -18,7 +19,7 @@ Turn the matrix into executable tests, fixtures, seed/teardown notes, and accept
 
 1. Read `matrix` and `fixtures` from `.opentest.yaml`.
 2. Preserve each row's requirement source and expected behavior. Do not rewrite acceptance cases around current implementation names, component internals, or existing test files.
-3. For code evidence, use the project framework; if none exists, default to pytest with tests under `tests/` runnable by `python -m pytest`. Missing implementation means evidence stays pending; it does not remove the requirement acceptance case.
+3. Place assets in the fixed layout from `test-asset-layout.md`; default to pytest under `tests/` when no project framework exists. Missing implementation means evidence stays pending.
 4. Create/update fixtures, seed, teardown, users, roles, entities, files/images, and assertion surfaces.
 5. For CRUD/data changes, author the full acceptance flow: create -> list -> detail -> update -> read back -> delete -> confirm absence -> teardown.
 6. Record any gap/blocker with reason and risk.

package/assets/skills/opentest-desktop-gui/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: opentest-desktop-gui
+description: "OpenTest desktop GUI execution surface adapter. Use when planning, authoring, running, or accepting native desktop, Electron, Tauri, Windows, macOS, Linux, or RDP workflows and deciding between project GUI automation, @midscene/computer, accessibility metadata, screenshots, and scripted manual acceptance."
+---
+
+# OpenTest Desktop GUI
+
+Use this adapter for `desktop-gui` matrix rows.
+
+## Required references
+
+- `opentest/references/desktop-gui-testing.md`
+- `opentest/templates/desktop-gui-acceptance-template.md`
+
+## Route
+
+1. Prefer the repository's existing GUI automation command when it is explicit and repeatable.
+2. Use `@midscene/computer` for visual desktop automation, weak selectors, native controls, cross-window flows, or remote Windows RDP when deterministic project automation is unavailable.
+3. For Electron or Tauri apps that expose a browser context, prefer `web-browser` or Playwright routes for DOM-verifiable flows, and use `desktop-gui` only for native shell, tray, file picker, menu, OS dialog, or multi-window behavior.
+4. If model credentials, desktop access, display/RDP availability, app launch command, or stable result surface is missing, record `blocked` instead of PASS.
+
+## Evidence Contract
+
+PASS requires the executed steps, screenshot or screen recording, window/app metadata, GUI action log, and a deterministic read-back result after writes. `@midscene/computer` assertions are visual assistance; they must not replace persisted-result checks such as reopening a settings screen, reading a file/config value, querying an app state surface, or confirming the expected window state after restart.

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

@@ -1,27 +1,34 @@
 ---
 name: opentest-plan
-description: "OpenTest phase 1: analyze the change, risks, project facts, and create a test strategy plus acceptance-to-test matrix."
+description: "OpenTest phase 1: create test strategy and acceptance matrix."
 ---
 
 # OpenTest Plan
 
-Create `docs/opentest/plans/`, `docs/opentest/matrices/`, and a fixtures plan before implementation.
+Create plan, matrix, and fixtures before implementation.
 
 ## Required references
 
 - `opentest/references/codex-harness-coverage-heuristics.md`
 - `opentest/references/matrix-format.md`
 - `opentest/references/complete-testing-workflow.md`
+- `opentest/references/test-asset-layout.md`
+- `opentest/references/test-surfaces.md`
+- `opentest/references/android-app-testing.md`
+- `opentest/references/web-browser-testing.md`
+- `opentest/references/desktop-gui-testing.md`
+- `opentest/references/api-testing.md`
 
 ## Steps
 
-1. Read project rules, requirements/design/user request/diff, existing commands, and detection output.
-2. Treat requirements, design, user workflows, business rules, and risk notes as acceptance sources. Inspect current code only for project facts such as commands, routes, test framework, fixtures, or reusable helpers.
-3. Apply the CRUD baseline and test data requirements from the workflow reference for data-writing/API/form/file/stateful changes.
-4. Produce a requirement-first matrix with requirement source, user-observable expected behavior, coverage dimension, framework/command, required evidence, gap/blocker, and status.
-5. Write `.opentest.yaml` fields: `plan`, `matrix`, `fixtures`.
-6. Update handoff if present, then run `bash "$OPENTEST_GUARD" plan --apply`.
+1. Read rules, requirements/diff, commands, and detection output.
+2. Treat requirements and risks as sources; inspect current code only for project facts.
+3. Apply CRUD baseline and test data rules for data-writing/API/form/file/stateful changes.
+4. Classify execution surface and evidence layer separately: `web-browser`, `android-app`, `desktop-gui`, or `api`; use `opentest-android-app`, web modes, `opentest-desktop-gui`, and `opentest-api` where applicable.
+5. Produce a requirement-first matrix with source, behavior, surface, mode, evidence, command, gap/blocker, status, and fixed layout.
+6. Write `.opentest.yaml` fields: `plan`, `matrix`, `fixtures`.
+7. Update handoff if present, then run `bash "$OPENTEST_GUARD" plan --apply`.
 
 ## Gate
 
-Every applicable behavior, failure path, boundary, and risk surface needs evidence or a written gap/blocker. Every matrix row must cite a requirement source. Do not drop or narrow acceptance because current code has no matching function, component, API, or test file. CRUD baseline and test data are default requirements unless the matrix says why they are not applicable.
+Every behavior, failure path, boundary, and risk needs evidence or gap/blocker. Every row cites a source and includes surface plus evidence layer; web rows include acceptance mode. Do not use unit/component/integration/contract/smoke as the execution surface. Do not drop or narrow acceptance because current code has no matching file.

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

@@ -5,12 +5,18 @@ description: "OpenTest phase 3: run project verification commands in targeted, f
 
 # OpenTest Run
 
-Run matrix-driven commands and write evidence reports under `docs/opentest/runs/`.
+Run matrix-driven commands and write reports under `docs/opentest/runs/`.
 
 ## Required references
 
 - `opentest/references/command-routing.md`
 - `opentest/references/complete-testing-workflow.md`
+- `opentest/references/test-asset-layout.md`
+- `opentest/references/test-surfaces.md`
+- `opentest/references/android-app-testing.md`
+- `opentest/references/web-browser-testing.md`
+- `opentest/references/desktop-gui-testing.md`
+- `opentest/references/api-testing.md`
 
 ## Modes
 
@@ -22,10 +28,11 @@ Run matrix-driven commands and write evidence reports under `docs/opentest/runs/
 
 ## Steps
 
-1. Read `run_mode`, matrix, fixtures, and required evidence.
-2. Prefer explicit project commands; otherwise use `python -m pytest` for code-level tests.
-3. For coverage, prefer `python -m pytest --cov=. --cov-report=term-missing`.
-4. Smoke evidence is required unless the matrix says not applicable.
-5. For `pre-push`, run or record format/check, lint, type, unit, targeted integration, smoke, and `git diff --check`.
-6. Write `run_report`, plus `coverage_report`, `smoke_report`, or `pre_push_report` when produced/required.
-7. Run `bash "$OPENTEST_GUARD" run --apply`.
+1. Read `run_mode`, matrix, fixtures, required evidence, and fixed asset layout.
+2. Choose by matrix execution surface: MCP/CLI or `npx playwright test` for `web-browser`; `opentest-android-app` or `python -m pytest tests_py -v` for `android-app`, with `npm run test:android` only when model env is ready or debugging Midscene; `opentest-desktop-gui` for `desktop-gui`; `opentest-api` or `python -m pytest tests/api -v` for `api`.
+3. Prefer explicit project commands; otherwise use `python -m pytest` for code-level tests.
+4. For coverage, prefer `python -m pytest --cov=. --cov-report=term-missing`.
+5. Smoke evidence is required unless the matrix says not applicable.
+6. For `pre-push`, run or record format/check, lint, type, unit, targeted integration, smoke, and `git diff --check`.
+7. Write `run_report`, `coverage_report`, `smoke_report`, or `pre_push_report` when required.
+8. Run `bash "$OPENTEST_GUARD" run --apply`.

package/assets/skills/opentest-web-browser/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: opentest-web-browser
+description: "OpenTest web-browser execution surface adapter. Use when planning, authoring, running, or accepting browser-rendered web workflows and deciding between Playwright MCP, Playwright CLI, @playwright/test, and Midscene."
+---
+
+# OpenTest Web Browser
+
+Use this adapter for `web-browser` matrix rows.
+
+## Required references
+
+- `opentest/references/web-browser-testing.md`
+- `opentest/references/complete-testing-workflow.md`
+- `opentest/templates/web-acceptance-template.md`
+
+## Steps
+
+1. Decide `acceptance_mode`: `instant-acceptance`, `durable-regression`, or `visual-ai-assist`.
+2. For `instant-acceptance`, use Playwright MCP first; if browser MCP is unavailable or unstable, use Playwright CLI.
+3. For `durable-regression`, write or run `@playwright/test` or the repository's existing E2E framework.
+4. Use Midscene only for visual, weak-selector, canvas, cross-frame, or other UI surfaces selectors cannot prove well.
+5. For writes, run the full chain: open -> snapshot -> fill/input -> submit -> snapshot -> read/assert changed result -> screenshot -> PASS/FAIL.
+
+## Gate
+
+MCP or Playwright CLI evidence proves this acceptance run only. Do not count it as durable regression unless the repository has a committed repeatable test, command, and report path. Midscene must not replace read-after-write assertions.

package/assets/skills-zh/opentest/references/android-app-testing.md

@@ -0,0 +1,78 @@
+# Android App 测试
+
+用于 `android-app` 执行面的矩阵行。
+
+## 适配边界
+
+`opentest-android-app` 是 OpenTest 的执行面适配器。它让 Android App 测试在安装后的 OpenTest skills 中可见，并在可用时把详细执行路由到 `android-midscene-pytest`。
+
+这里不复制完整 Android Midscene SOP。本文只定义 OpenTest 矩阵、目录、证据和阻塞规则。
+
+## 默认目录
+
+稳定 Android 资产遵循 `opentest/references/test-asset-layout.md`：
+
+```text
+tests/android/
+  tests_py/
+  midscene/
+
+scripts/
+  opentest-run-android.ps1
+```
+
+如果仓库已有 Android harness，优先使用最接近的现有路径，但逻辑槽位必须保持一致：pytest wrapper、Midscene 脚本、设备准备和运行入口。
+
+标准 Midscene 槽位是 `tests/android/midscene/`。
+
+## 默认路线
+
+```text
+opentest-android-app
+  -> android-midscene-pytest
+  -> pytest wrapper
+  -> npm/Vitest wrapper
+  -> @midscene/android
+  -> ADB + Android emulator/device
+  -> screenshots + logcat + Midscene HTML report
+```
+
+面向用户的入口是 pytest。优先使用现有 Android harness 中的 `python -m pytest tests_py -v`，或仓库采用固定目录时的 `scripts/opentest-run-android.ps1`。
+
+只有 Midscene 模型环境变量齐全，或需要直接排查 Midscene 层时，才运行 `npm run test:android`。
+
+## 必需证据
+
+`android-app` 行需要：
+
+- pytest 报告或命令输出
+- ADB 冒烟结果
+- APK 路径、package name、模拟器/真机标识
+- 关键步骤后的截图
+- logcat 或定向 Android 日志
+- 执行视觉自动化时的 Midscene HTML 报告
+- 可用的 `midscene_run/log/ai-call.log`、`agent.log`、`android-device.log` 和 `midscene_run/report/*.html`
+- App 写数据时的写后读或持久化状态证明
+
+## 阻塞规则
+
+缺少任一必需前置条件时记录 `blocked`：
+
+- ADB
+- 模拟器或真机
+- APK 路径
+- package name 或 launch activity
+- 需要视觉自动化时的 Midscene 模型凭据
+- fixture 数据、reset 路径或稳定结果面
+
+不得只凭静态截图把 Android App 验收标为 PASS。
+
+## 矩阵要求
+
+`android-app` 行必须包含：
+
+- `执行面`：`android-app`
+- `验收模式`：`n/a`
+- `证据层级`：`visual-acceptance`、`e2e`、`integration` 或 `smoke`
+- `框架/命令`：`opentest-android-app`、`android-midscene-pytest`、`python -m pytest tests_py -v` 或 `scripts/opentest-run-android.ps1`
+- `必需证据`：pytest、ADB 冒烟、使用时的 Midscene HTML 报告、截图、logcat、设备/App 元数据、`midscene_run` 日志，以及不可用时的 blocked 前置条件

package/assets/skills-zh/opentest/references/api-testing.md

@@ -0,0 +1,77 @@
+# API 测试
+
+用于 `api` 执行面的矩阵行。
+
+## 默认架构
+
+优先使用仓库已有 API 测试框架。项目没有明确 API 测试命令时，默认采用：
+
+```text
+pytest
+  -> httpx 或 requests client
+  -> pytest fixtures 管 seed/teardown
+  -> jsonschema 或项目已有 Pydantic/DTO 模型做契约断言
+  -> 可选 DB/存储/日志回读
+  -> pytest report 或 JUnit XML
+```
+
+依赖需要隔离时，用 Docker Compose、testcontainers 或仓库已有本地服务启动方式。第三方 API 默认 mock/stub；打 live 外部服务必须有明确需求和记录的风险说明。
+
+稳定 API 资产放入 `opentest/references/test-asset-layout.md` 约定的 `tests/api/`：client 放 `tests/api/clients/`，fixtures 放 `tests/api/fixtures/`，schemas 放 `tests/api/schemas/`，可重复入口使用 `scripts/opentest-run-api.ps1` 或仓库等价命令。
+
+## 证据层级
+
+| 层级 | 证明内容 | 常见命令/工具 |
+| --- | --- | --- |
+| contract | 状态码、headers、响应字段、schema、错误形态 | 项目 contract tests、`pytest`、OpenAPI 检查 |
+| integration | API handler、service、数据库/存储、队列/日志副作用 | 项目 integration 命令、`pytest`、本地服务 |
+| smoke | base URL 和关键 endpoint 存活 | 项目 smoke 命令、小型 `pytest`/curl 脚本 |
+| security-review | 鉴权、授权、敏感字段泄漏、注入风险 | 定向测试 + review 记录 |
+
+## 必需 API 用例
+
+API 变更应按适用性写入矩阵：
+
+- 主路径：期望状态码、payload、headers 和业务状态
+- 校验失败：非法、空、边界、格式错误、不支持字段
+- 鉴权和权限：未登录、token 过期、角色错误、对象级授权
+- 未找到和过期状态：资源不存在、已删除资源、stale version
+- 冲突和幂等：重复创建、重复提交、带 idempotency key 的 retry、并发修改
+- 适用时的限流或节流
+- 列表 endpoint 变更时的分页、过滤、排序和空结果
+- 数据一致性：响应、DB/存储、事件、队列消息、文件或日志
+- teardown/cleanup：创建资源已删除，或隔离 fixture namespace 已重置
+
+## 契约来源
+
+契约来源优先级：
+
+1. 仓库提交的 OpenAPI/protobuf/schema 文件。
+2. 既有 request/response DTO、Pydantic model、serializer 或 typed client。
+3. 明确写出字段和错误的需求/设计文档。
+4. 验收用例中手写 schema。
+
+当当前实现行为与需求冲突时，不得只按实现反推契约。
+
+## 阻塞规则
+
+缺少任一必需前置条件时记录 `blocked`：
+
+- base URL 或服务启动命令
+- auth token、角色或测试用户
+- fixture seed/teardown 路径
+- 依赖服务、数据库、队列或 mock server
+- 稳定契约来源或期望 schema
+- 确定性写后读结果面
+
+不得只凭 2xx 响应把 API 验收标为 PASS。写操作必须包含可信结果面的写后读证据，例如 API 查询 endpoint、DB/存储记录、队列/事件/日志，或另一个项目自有状态面。
+
+## 矩阵要求
+
+`api` 行必须包含：
+
+- `执行面`：`api`
+- `验收模式`：`n/a`
+- `证据层级`：`contract`、`integration`、`smoke` 或 `security-review`
+- `框架/命令`：项目 API 命令、`python -m pytest tests/api -v`、curl/httpie 脚本、项目已使用时的 Postman/Newman，或契约工具
+- `必需证据`：请求/响应记录、状态码、payload/schema 断言、适用时的鉴权/权限断言、写后读/数据一致性，以及 cleanup/teardown 证明

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

@@ -13,6 +13,10 @@ OpenTest 应根据变更类型、风险和项目事实选择适用覆盖面。
 - `tdd-workflow`
 - `e2e-runner`
 - `browser-e2e-testing`
+- `opentest-android-app`
+- `android-midscene-pytest`
+- `opentest-desktop-gui`
+- `opentest-api`
 - `verification-loop`
 - `code-reviewer`
 - `speckit-checklist`
@@ -28,6 +32,19 @@ OpenTest 应根据变更类型、风险和项目事实选择适用覆盖面。
 | 权限、支付、安全、数据写入、跨页面闭环 | high-risk 验收或 E2E 证据 |
 | 文案、配置、小范围无行为变更 | targeted review 或轻量证据 |
 
+## 执行面选择
+
+执行面和证据层级必须分开选择：
+
+| 执行面 | 默认路由 |
+| --- | --- |
+| `web-browser` | Chrome DevTools MCP、Playwright CLI 或浏览器验收 |
+| `android-app` | `opentest-android-app`；已安装时路由到 `android-midscene-pytest`，由 `python -m pytest tests_py -v` 通过 ADB 驱动 Midscene Android |
+| `desktop-gui` | `opentest-desktop-gui`；优先项目 GUI 自动化，视觉/原生/RDP GUI 流程用 `@midscene/computer`，无自动化时才用脚本化人工 GUI 验收 |
+| `api` | `opentest-api`；优先项目 API/integration 命令，否则用 `pytest` + `httpx`/`requests`、schema 校验、fixtures、写后读和 cleanup/teardown |
+
+不得把 unit、component、integration、contract、smoke 或 security review 这类代码检查归类成执行面；它们只能作为证据层级。
+
 ## 前端验收维度
 
 前端或真实链路验收可从以下维度中选择适用项，不要求每次全部覆盖：
@@ -74,7 +91,7 @@ OpenTest plan 阶段默认检查以下问题；适用则进入矩阵，不适用
 | ACC-001 | 用户保存后看到成功反馈 | medium | UI 验收 | pending |
 ```
 
-只有当风险或变更类型需要时，才增加覆盖维度、命令、证据路径和阻塞原因列。
+当矩阵需要驱动验收执行或风险要求时，再增加执行面、证据层级、命令/工具、证据路径和阻塞原因列。
 
 ## 质量门启发