@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.2

package/commands/qc-run-test.tmpl

@@ -4,68 +4,68 @@ updated: 2026-06-11
 ported_from: ai-automation-qc-base
 ---
 
-# /qc-run-test — QC Script Generation & Run (writes qc_status)
+# /qc-run-test — QC Script Generation & Run (ghi 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.
+> Stage 5 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-runner của team QC. Sinh & chạy Python pytest-playwright từ `.Test.md` đã review, rồi ghi `qc_status` **chính thức** vào 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.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Đọc `.Test.md` đã review từ `{paths.qc_dir}/{UC-ID}/test-cases/`. Lệnh này dùng stack module **qc-playwright** (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — độc lập với module implementation của dev.*
 
 ## Context
 {{include:steps/context-loader.md}}
 
 ---
 
-## Role & stack (per qc-playwright module)
+## Role & stack (theo module qc-playwright)
 
-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.
+Bạn là **QC Runner** — stage 5. Chuyển `.Test.md` đã review thành Python
+pytest-playwright script + Page Object, chạy chúng, và report kết quả theo từng 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).
+Quy tắc stack (BẮT BUỘC — từ `modules/qc-playwright/stack-profile.yaml`):
+- Markdown-first: không bao giờ sinh Python khi chưa có `.Test.md` đã review.
+- Page Object extends `BasePage` gọn, 3 lớp: locator `_x()`, action `verb_noun()`, assertion `assert_x()` dùng `expect()`.
+- **Locator từ test-id contract (không scan runtime).** Đọc bảng *Test Selectors* §2b của FE tech-design tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` (nếu có) và dựng mỗi Page Object locator từ test-id ổn định của nó — web `get_by_test_id("...")`, RN `testID`, Flutter `Key`/`Semantics`, native `accessibilityIdentifier`. **Ưu tiên map; fallback** về role/label/text/CSS (scan chậm hơn) chỉ cho một element có action mà **không** có test-id trong §2b — và ghi chú để gap được thêm vào tech-design.
+- pytest-playwright fixture; mỗi test độc lập; gom theo (role, account) để auth không bao giờ xen kẽ.
+- Không hard-code URL/cred/timeout (dùng `Env.*` / `CONFIG[...]`); không `time.sleep()`; không Allure.
+- Phủ **100%** TC trong file — mỗi TC kết thúc Pass/Fail/Skip (không còn Draft).
+- Phân loại mỗi FAIL: script-bug (fix selector/logic) vs product-gap (giữ FAIL + evidence, không bao giờ fake-pass).
 
-## Skills — pick the layer, load ONE file (`{paths.qc_skills_dir}/qa-runner/`)
+## Skills — chọn layer, nạp MỘT 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)
+## Trace tag (bắt buộc)
 
-Every generated pytest test carries the framework scenario it verifies, taken from the
-`.Test.md` Trace matrix:
+Mỗi pytest test được sinh ra mang scenario framework mà nó verify, lấy từ
+Trace matrix của `.Test.md`:
 
 ```python
 # @trace.verifies={UC-ID}-SC{N}
 def test_TC_<FEATURE>_001_...(...): ...
 ```
 
-## Write Trace State — qc_status (OFFICIAL QC result)
+## Write Trace State — qc_status (kết quả QC CHÍNH THỨC)
 
-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/`.)*
+Sau khi chạy, cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` (nếu `domain`/`prd_slug` không phân giải được từ spec target, định vị TSV bằng cách glob `{paths.trace_dir}/**/{UC-ID}.tsv` — nó được tạo trước đó bởi `/generate-bdd`) — cho mỗi scenario row (khớp
+`sc_id` qua tag `@trace.verifies={UC-ID}-SC{N}` của test). *(Umbrella + `spec_source`: `trace_dir` là `{spec_source}/.trace` — ghi update `qc_status` vào **spec repo** và commit/push spec submodule, giống `feedback/`.)*
 
-| Column | Value |
+| Cột | Giá trị |
 |--------|-------|
-| `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 |
+| `qc_status` | `pass` nếu mọi QC test của SC này pass · `fail` nếu có cái fail · `skip` nếu tất cả skip/xfail · `not_run` nếu không QC test nào phủ nó |
+| `qc_run_at` | hôm nay `YYYY-MM-DD` |
+| `qc_owner` | **SC đang chờ ai** (view "pending" của PM/PO): `dev` nếu FAIL = product-gap (defect thật → dev fix) · `po` nếu `skip`/`not_run` vì một **`DOC_GAPS` 🔴 Blocker đang open** chặn test (PO phải làm rõ PRD/BDD) · `—` nếu `pass`, hoặc FAIL = script-bug (QC tự fix — tạm thời) |
+| `qc_blocked_by` | artifact liên kết: `GAP-{id}` khi bị chặn bởi spec gap (set ở đây) · `BUG-{id}` khi `/report-bug` đã được file cho product-gap (backfill bởi `/report-bug`) · `—` ngược lại |
 
-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.
+Set `qc_owner`/`qc_blocked_by` cùng với `qc_status`. Khi `pass`, **clear** cả hai về `—`.
+Với FAIL product-gap, set `qc_owner=dev` ngay; `BUG-{id}` được backfill vào `qc_blocked_by`
+khi QC chạy `/report-bug` mà `/qc-report` nhắc.
 
-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).
+Giữ nguyên mọi cột khác — **không bao giờ** đụng `dev_selftest`/`dev_selftest_at`
+(do `/dev-run-test` sở hữu). `qc_status` (QC chính thức) và `dev_selftest` (dev smoke) là
+hai tín hiệu riêng; cả hai trực giao với `status` (OK/GAP/DRIFT/UNTRACKED = coverage).
 
 ## Refresh Panel Mirror
 {{include:steps/trace-mirror.md}}
@@ -78,7 +78,7 @@ separate signals; both are orthogonal to `status` (OK/GAP/DRIFT/UNTRACKED = cove
 /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.
+Next: /qc-report {UC-ID}   ← sinh report + evidence
+      /qc-review {UC-ID}   ← review script đã sinh trước khi merge
+📊 Living Docs: chạy /validate-traces (hoặc /sync) để push qc_status lên dashboard spec-module.
 ```