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

package/commands/dev-run-test.tmpl

@@ -1,15 +1,15 @@
-# /dev-run-test — Run Dev Self-Check Tests & Report Results
+# /dev-run-test — Chạy Dev Self-Check Tests & Report kết quả
 
-> **Scope — dev self-check (smoke), not the official test suite.** Runs the tests produced
-> by `/dev-gen-test` so the developer can confirm their own code works before review. This
-> is a developer self-check, **not** the QC/dev-team's authoritative test run (separate flow).
-> The pass/fail is published to Living Docs as a **dev self-test** signal — it tells QC the
-> dev ran their checks; it is NOT a statement of official test coverage.
+> **Scope — dev self-check (smoke), không phải bộ test chính thức.** Chạy các test do
+> `/dev-gen-test` sinh ra để dev xác nhận code mình chạy được trước khi review. Đây là một
+> self-check của dev, **không** phải lần chạy test authoritative của QC/dev-team (flow riêng).
+> Pass/fail được publish lên Living Docs như tín hiệu **dev self-test** — nó cho QC biết
+> dev đã chạy check của họ; KHÔNG phải tuyên bố về độ phủ test chính thức.
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a UC-ID or service name. Context loading provides `conventions.test_command` and `tech_stack.module`.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID hoặc tên service. Context loading cung cấp `conventions.test_command` và `tech_stack.module`.*
 
 ## Context
 {{include:steps/context-loader.md}}
@@ -18,20 +18,20 @@
 
 ## Service Detection
 
-Read `active_module` from context (resolved in context-loader Step 1).
-Use it to select the correct run command and error analysis table below.
+Đọc `active_module` từ context (đã phân giải ở context-loader Bước 1).
+Dùng nó để chọn đúng lệnh chạy và bảng phân tích lỗi bên dưới.
 
 ---
 
 ## Submodule Working Directory
 
-*Skip this section if `service_root` is not set (single-service mode).*
+*Bỏ qua section này nếu `service_root` chưa được set (single-service mode).*
 
-When running in **umbrella/submodule mode** (`service_root` was resolved in context-loader Step 1.6):
+Khi chạy ở **umbrella/submodule mode** (`service_root` được phân giải ở context-loader Bước 1.6):
 
-- All commands in the **Run** section below must execute from within `{service_root}/`
-- `conventions.test_command` was loaded from `{service_root}/.agent/project-context.yaml` — already service-specific
-- Prefix every shell command with `cd {service_root} &&`:
+- Mọi lệnh trong section **Run** bên dưới phải thực thi từ trong `{service_root}/`
+- `conventions.test_command` được nạp từ `{service_root}/.agent/project-context.yaml` — đã riêng theo service
+- Prefix mọi lệnh shell bằng `cd {service_root} &&`:
 
 ```bash
 cd {service_root}
@@ -44,13 +44,13 @@ npx vitest run src/...                 # web-frontend
 flutter test test/{domain}/...         # flutter
 ```
 
-> **Why cd?** Claude Code session is opened at umbrella root. Each service submodule has its own build tool, test runner, and dependency tree — tests must run from inside the service directory.
+> **Vì sao cd?** Session Claude Code mở ở umbrella root. Mỗi service submodule có build tool, test runner, và cây dependency riêng — test phải chạy từ trong thư mục service.
 
 ---
 
 ## Run
 
-### If `platform_type = backend`
+### Nếu `platform_type = backend`
 
 ```bash
 # Run all tests for this UC
@@ -71,7 +71,7 @@ pytest tests/{domain}/{test_file}.py::{TestClass}::{test_method} -v
 pytest tests/ --cov={source_dir} --cov-report=term-missing
 ```
 
-### If `platform_type = web-frontend`
+### Nếu `platform_type = web-frontend`
 
 ```bash
 # Run all tests
@@ -87,7 +87,7 @@ npx playwright test {UC-ID}
 npx cypress run --spec "cypress/e2e/{UC-ID}*"
 ```
 
-### If `platform_type = mobile`
+### Nếu `platform_type = mobile`
 
 ```bash
 # Flutter:
@@ -105,7 +105,7 @@ xcodebuild test -scheme {Scheme} -destination 'platform=iOS Simulator,name=iPhon
 ./gradlew connectedAndroidTest              # instrumented (device/emulator required)
 ```
 
-> **Note for Android instrumented tests:** a running emulator or connected device is required before running `connectedAndroidTest`. Start one via Android Studio or: `emulator -avd {AVD_NAME} &`
+> **Lưu ý cho Android instrumented test:** cần một emulator đang chạy hoặc device kết nối trước khi chạy `connectedAndroidTest`. Khởi động qua Android Studio hoặc: `emulator -avd {AVD_NAME} &`
 
 ---
 
@@ -115,86 +115,86 @@ xcodebuild test -scheme {Scheme} -destination 'platform=iOS Simulator,name=iPhon
 
 #### java-spring / golang / dotnet / php-laravel
 
-| Error Pattern | Common Cause | Suggested Fix |
+| Error Pattern | Nguyên nhân thường gặp | Suggested Fix |
 |---|---|---|
-| `NullPointerException` | Missing mock setup | Check `given(...)`/`coEvery`/`mockk` for null dependency |
-| `Bean not found` | Missing mock declaration | Add `@MockBean` / inject mock |
-| `Expected 200, got 401` | Missing auth setup | Add auth token/user to test context |
-| `Expected 200, got 400` | Request body fails validation | Check required fields in DTO |
-| `Expected 200, got 403` | Wrong role | Add correct role to test user |
-| `LazyInitializationException` | Lazy collection outside transaction | Add `@Transactional` or eager fetch |
-| `Mapper not found` | Code not compiled | Run build step before tests |
-| `DataIntegrityViolationException` | Duplicate key in DB setup | Use `@Transactional` + rollback, or clean DB between tests |
-| Assertion mismatch | Wrong mock return value | Re-read `given(...).willReturn(...)` setup |
+| `NullPointerException` | Thiếu setup mock | Kiểm tra `given(...)`/`coEvery`/`mockk` cho dependency null |
+| `Bean not found` | Thiếu khai báo mock | Thêm `@MockBean` / inject mock |
+| `Expected 200, got 401` | Thiếu setup auth | Thêm auth token/user vào test context |
+| `Expected 200, got 400` | Request body fail validation | Kiểm tra field bắt buộc trong DTO |
+| `Expected 200, got 403` | Sai role | Thêm đúng role cho test user |
+| `LazyInitializationException` | Lazy collection ngoài transaction | Thêm `@Transactional` hoặc eager fetch |
+| `Mapper not found` | Code chưa compile | Chạy build trước khi test |
+| `DataIntegrityViolationException` | Trùng key trong DB setup | Dùng `@Transactional` + rollback, hoặc clean DB giữa các test |
+| Assertion mismatch | Sai giá trị mock return | Đọc lại setup `given(...).willReturn(...)` |
 
 #### context-engineering (AI/LLM pipelines)
 
-| Error Pattern | Common Cause | Suggested Fix |
+| Error Pattern | Nguyên nhân thường gặp | Suggested Fix |
 |---|---|---|
-| `AssertionError` on LLM mock output | Mock return value not matching schema | Re-check `mock_llm.return_value` / `mock_llm.complete.return_value` setup |
-| `ValidationError` on response | LLM output structure doesn't match expected schema | Tighten schema check or add retry logic in test |
-| `ConnectionError` / `APIError` | Real LLM API being called in test | Ensure `patch('...')` mock is applied — never call real LLM in unit tests |
-| `TimeoutError` | Test calling live LLM endpoint | Add mock; check test fixtures |
-| Flaky / non-deterministic results | Real LLM response used in assertion | Replace with deterministic mock return value |
+| `AssertionError` trên output mock LLM | Giá trị mock return không khớp schema | Kiểm tra lại setup `mock_llm.return_value` / `mock_llm.complete.return_value` |
+| `ValidationError` trên response | Cấu trúc output LLM không khớp schema kỳ vọng | Siết schema check hoặc thêm retry logic trong test |
+| `ConnectionError` / `APIError` | LLM API thật bị gọi trong test | Đảm bảo mock `patch('...')` được áp dụng — không bao giờ gọi LLM thật trong unit test |
+| `TimeoutError` | Test gọi LLM endpoint live | Thêm mock; kiểm tra test fixture |
+| Kết quả flaky / non-deterministic | Response LLM thật dùng trong assertion | Thay bằng giá trị mock return tất định |
 
 ### Web frontend failure patterns
 
-| Error Pattern | Common Cause | Suggested Fix |
+| Error Pattern | Nguyên nhân thường gặp | Suggested Fix |
 |---|---|---|
-| `Unable to find role "..."` | Element not rendered yet | Wrap in `await waitFor(() => ...)` |
-| `TestingLibraryElementError: Found multiple elements` | Selector too broad | Use `getByRole(..., { name: '...' })` to narrow |
-| `Network request not intercepted` | Missing MSW handler / `cy.intercept` | Add handler for the endpoint |
-| `act(...)` warning | State update after test ended | Await async events / `await userEvent.click(...)` |
-| `Cannot read properties of undefined` | Component rendered before data loaded | Add loading state or mock resolved data |
-| Playwright timeout | Page not navigated / element hidden | Check route, add `waitForSelector` |
-| `expect(page.locator(...)).toBeVisible` fails | Wrong selector | Use Playwright Inspector to find correct locator |
+| `Unable to find role "..."` | Element chưa render | Bọc trong `await waitFor(() => ...)` |
+| `TestingLibraryElementError: Found multiple elements` | Selector quá rộng | Dùng `getByRole(..., { name: '...' })` để thu hẹp |
+| `Network request not intercepted` | Thiếu MSW handler / `cy.intercept` | Thêm handler cho endpoint |
+| `act(...)` warning | State update sau khi test kết thúc | Await async event / `await userEvent.click(...)` |
+| `Cannot read properties of undefined` | Component render trước khi data load | Thêm loading state hoặc mock data đã resolve |
+| Playwright timeout | Page chưa navigate / element ẩn | Kiểm tra route, thêm `waitForSelector` |
+| `expect(page.locator(...)).toBeVisible` fail | Sai selector | Dùng Playwright Inspector để tìm đúng locator |
 
 ### Mobile failure patterns
 
 #### Flutter
-| Error Pattern | Common Cause | Suggested Fix |
+| Error Pattern | Nguyên nhân thường gặp | Suggested Fix |
 |---|---|---|
-| `pumpAndSettle timed out` | Async operation not completing | Use `pump(Duration(...))` for specific delay |
-| `No widget found` | Widget not rendered / wrong finder | Check `find.byType`, `find.text`, `find.byKey` |
-| `setState called after dispose` | Widget disposed before async completes | Cancel async in `dispose()` |
-| BLoC state mismatch | Wrong event emitted | Verify `mockBloc` received correct event |
+| `pumpAndSettle timed out` | Async operation chưa hoàn thành | Dùng `pump(Duration(...))` cho delay cụ thể |
+| `No widget found` | Widget chưa render / sai finder | Kiểm tra `find.byType`, `find.text`, `find.byKey` |
+| `setState called after dispose` | Widget bị dispose trước khi async xong | Cancel async trong `dispose()` |
+| BLoC state mismatch | Sai event emit | Verify `mockBloc` nhận đúng event |
 
 #### React Native
-| Error Pattern | Common Cause | Suggested Fix |
+| Error Pattern | Nguyên nhân thường gặp | Suggested Fix |
 |---|---|---|
-| `Unable to find element` | Missing `testID` or wrong query | Add `accessibilityLabel` or `testID` to component |
-| `act(...)` warning | Async state updates | Wrap in `act(async () => { ... })` |
-| Navigation mock missing | `useNavigation` not mocked | Add jest mock for `@react-navigation/native` |
+| `Unable to find element` | Thiếu `testID` hoặc sai query | Thêm `accessibilityLabel` hoặc `testID` vào component |
+| `act(...)` warning | Async state update | Bọc trong `act(async () => { ... })` |
+| Thiếu navigation mock | `useNavigation` chưa mock | Thêm jest mock cho `@react-navigation/native` |
 
 #### iOS / Android
-| Error Pattern | Common Cause | Suggested Fix |
+| Error Pattern | Nguyên nhân thường gặp | Suggested Fix |
 |---|---|---|
-| `XCTAssertEqual failed` | Wrong expected value | Check ViewModel output for given mock |
-| `Compose node not found` | Wrong `contentDescription` / `testTag` | Add `Modifier.testTag(...)` to composable |
-| `Hilt injection failed` | Missing test module | Add `@UninstallModules` + `@BindValue` in test class |
-| Emulator not available | `connectedAndroidTest` without device | Start emulator first, wait for it to boot |
+| `XCTAssertEqual failed` | Sai giá trị kỳ vọng | Kiểm tra output ViewModel cho mock đã cho |
+| `Compose node not found` | Sai `contentDescription` / `testTag` | Thêm `Modifier.testTag(...)` vào composable |
+| `Hilt injection failed` | Thiếu test module | Thêm `@UninstallModules` + `@BindValue` trong test class |
+| Emulator not available | `connectedAndroidTest` không có device | Khởi động emulator trước, chờ nó boot |
 
 ---
 
 ## Write Trace State
 
-After the run, persist results to the **authoritative TSV** in the service so they reach
-the Living Docs report at the spec module (via `/sync` + `/validate-traces`). The test
-files themselves stay in the service — only the run *status* is reported.
+Sau khi chạy, lưu kết quả vào **TSV authoritative** trong service để chúng tới được
+report Living Docs ở spec module (qua `/sync` + `/validate-traces`). Các file test
+ở lại trong service — chỉ *status* của lần chạy được report.
 
-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
-test's `@trace.verifies={UC-ID}-SC{N}` tag). *(Umbrella + `spec_source`: `trace_dir` is `{spec_source}/.trace` — tests run from `service_root` but the `dev_selftest` update writes into the **spec repo**; commit/push the spec submodule for it.)*
+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` — test chạy từ `service_root` nhưng update `dev_selftest` ghi vào **spec repo**; commit/push spec submodule cho nó.)*
 
-| Column | Value |
+| Cột | Giá trị |
 |--------|-------|
-| `dev_selftest` | `pass` if all tests for this SC passed · `fail` if any failed · `not_run` if its tests were skipped/absent |
-| `dev_selftest_at` | today `YYYY-MM-DD` |
+| `dev_selftest` | `pass` nếu mọi test của SC này pass · `fail` nếu có cái fail · `not_run` nếu test của nó bị skip/vắng |
+| `dev_selftest_at` | hôm nay `YYYY-MM-DD` |
 
-Leave all other columns unchanged — in particular **never** touch `qc_status`/`qc_run_at`
-(the official QC automation result, owned by `/qc-run-test`). `dev_selftest` (dev smoke)
-and `qc_status` (official QC) are separate
-signals. `dev_selftest`/`dev_selftest_at` are also orthogonal to `status`
-(OK/GAP/DRIFT/UNTRACKED): `status` tracks *coverage*, `dev_selftest` tracks the dev's latest *run result*.
+Giữ nguyên mọi cột khác — đặc biệt **không bao giờ** đụng `qc_status`/`qc_run_at`
+(kết quả QC automation chính thức, do `/qc-run-test` sở hữu). `dev_selftest` (dev smoke)
+và `qc_status` (QC chính thức) là hai tín hiệu riêng. `dev_selftest`/`dev_selftest_at` cũng
+trực giao với `status` (OK/GAP/DRIFT/UNTRACKED): `status` theo dõi *coverage*, `dev_selftest`
+theo dõi *kết quả chạy* gần nhất của dev.
 
 ## Refresh Panel Mirror
 {{include:steps/trace-mirror.md}}
@@ -212,13 +212,13 @@ signals. `dev_selftest`/`dev_selftest_at` are also orthogonal to `status`
 |------|-------|------------|
 
 ## Recommendations
-{specific fix per failure}
+{fix cụ thể cho từng failure}
 
 Trace: {paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv updated (dev_selftest, dev_selftest_at)
 
 Next:
-  All tests pass → /review-code {UC-ID}
-  Tests fail     → /fix-bug {TICKET_ID} (real bug) or fix test (wrong expectation)
+  Mọi test pass → /review-code {UC-ID}
+  Test fail     → /fix-bug {TICKET_ID} (bug thật) hoặc fix test (sai expectation)
 
-📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
+📊 Living Docs: chạy /validate-traces (hoặc /sync) để push trace này lên dashboard spec-module.
 ```