@edupia-tutor/spec-driven-docs 0.14.0

package/commands/qc-run-test.tmpl

@@ -0,0 +1,84 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# /qc-run-test — QC Script Generation & Run (writes qc_status)
+
+> Stage 5 of the native QC automation pipeline (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Ported from the QC team's qa-runner. Generates & runs Python pytest-playwright from the reviewed `.Test.md`, then writes the **official** `qc_status` into the trace TSV.
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target in Step 1 is a UC-ID. Read the reviewed `.Test.md` from `{paths.qc_dir}/{UC-ID}/test-cases/`. This command uses the **qc-playwright** stack module (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — independent of the dev implementation module.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Role & stack (per qc-playwright module)
+
+You are the **QC Runner** — stage 5. Convert reviewed `.Test.md` into Python
+pytest-playwright scripts + Page Objects, run them, and report the result per scenario.
+
+Stack rules (MANDATORY — from `modules/qc-playwright/stack-profile.yaml`):
+- Markdown-first: never generate Python without a reviewed `.Test.md`.
+- Page Object extends slim `BasePage`, 3 layers: locators `_x()`, actions `verb_noun()`, assertions `assert_x()` using `expect()`.
+- **Locators from the test-id contract (no runtime scan).** Read the FE tech-design §2b *Test Selectors* table at `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` (if present) and build each Page Object locator from its stable test-id — web `get_by_test_id("...")`, RN `testID`, Flutter `Key`/`Semantics`, native `accessibilityIdentifier`. **Prefer the map; fall back** to role/label/text/CSS (the slower scan) only for an actionable element that has **no** test-id in §2b — and note it so the gap can be added to the tech-design.
+- pytest-playwright fixtures; each test independent; group by (role, account) so auth never interleaves.
+- No hard-coded URL/cred/timeout (use `Env.*` / `CONFIG[...]`); no `time.sleep()`; no Allure.
+- Cover **100%** of TCs in the file — every TC ends Pass/Fail/Skip (none left Draft).
+- Classify each FAIL: script-bug (fix selector/logic) vs product-gap (keep FAIL + evidence, never fake-pass).
+
+## Skills — pick the layer, load ONE file (`{paths.qc_skills_dir}/qa-runner/`)
+
+`functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
+`non-functional.md`, `exploratory/session.md`.
+
+## Trace tag (mandatory)
+
+Every generated pytest test carries the framework scenario it verifies, taken from the
+`.Test.md` Trace matrix:
+
+```python
+# @trace.verifies={UC-ID}-SC{N}
+def test_TC_<FEATURE>_001_...(...): ...
+```
+
+## Write Trace State — qc_status (OFFICIAL QC result)
+
+After the run, update `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` (if `domain`/`prd_slug` weren't resolved from a spec target, locate the TSV by globbing `{paths.trace_dir}/**/{UC-ID}.tsv` — it was created earlier by `/generate-bdd`) — for each scenario row (matched by
+`sc_id` via its tests' `@trace.verifies={UC-ID}-SC{N}` tag). *(Umbrella + `spec_source`: `trace_dir` is `{spec_source}/.trace` — write the `qc_status` update into the **spec repo** and commit/push the spec submodule, same as `feedback/`.)*
+
+| Column | Value |
+|--------|-------|
+| `qc_status` | `pass` if all QC tests for this SC passed · `fail` if any failed · `skip` if all skipped/xfail · `not_run` if no QC test covers it |
+| `qc_run_at` | today `YYYY-MM-DD` |
+| `qc_owner` | **who the SC is waiting on** (the PM/PO "pending" view): `dev` if FAIL = product-gap (real defect → dev fixes) · `po` if `skip`/`not_run` because an **open `DOC_GAPS` 🔴 Blocker** prevents testing (PO must clarify PRD/BDD) · `—` if `pass`, or FAIL = script-bug (QC's own to fix — transient) |
+| `qc_blocked_by` | linked artifact: `GAP-{id}` when blocked by a spec gap (set here) · `BUG-{id}` once `/report-bug` is filed for the product-gap (backfilled by `/report-bug`) · `—` otherwise |
+
+Set `qc_owner`/`qc_blocked_by` together with `qc_status`. On `pass`, **clear** both to `—`.
+For a product-gap FAIL, set `qc_owner=dev` now; the `BUG-{id}` is backfilled into `qc_blocked_by`
+when QC runs the `/report-bug` that `/qc-report` prompts.
+
+Leave all other columns unchanged — **never** touch `dev_selftest`/`dev_selftest_at`
+(owned by `/dev-run-test`). `qc_status` (official QC) and `dev_selftest` (dev smoke) are
+separate signals; both are orthogonal to `status` (OK/GAP/DRIFT/UNTRACKED = coverage).
+
+## Refresh Panel Mirror
+{{include:steps/trace-mirror.md}}
+
+## Report
+
+{{include:steps/report-footer.md}}
+
+```
+/qc-run-test Report — {UC-ID} ({qc-playwright})
+QC: ✅ {pass} pass | ❌ {fail} fail | ⏭️ {skip} skip   (TCs: {total})
+Trace: {paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv updated (qc_status, qc_run_at)
+Next: /qc-report {UC-ID}   ← generate report + evidence
+      /qc-review {UC-ID}   ← review the generated scripts before merge
+📊 Living Docs: run /validate-traces (or /sync) to push qc_status to the spec-module dashboard.
+```