@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/commands/dev-run-test.tmpl

@@ -1,225 +0,0 @@
-# /dev-run-test — Chạy Dev Self-Check Tests & Report kết quả
-
-> **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}}
-
-*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}}
-
----
-
-## Service Detection
-
-Đọ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
-
-*Bỏ qua section này nếu `service_root` chưa được set (single-service mode).*
-
-Khi chạy ở **umbrella/submodule mode** (`service_root` được phân giải ở context-loader Bước 1.6):
-
-- 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}
-
-# Then run any of the commands in the Run section below, e.g.:
-{conventions.test_command}
-mvn test -Dtest={ClassName}            # java-spring
-go test ./... -run Test{FunctionName}  # golang
-npx vitest run src/...                 # web-frontend
-flutter test test/{domain}/...         # flutter
-```
-
-> **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
-
-### Nếu `platform_type = backend`
-
-```bash
-# Run all tests for this UC
-{conventions.test_command}
-
-# Scoped to specific class (faster feedback)
-# java-spring:
-mvn test -Dtest={ClassName}
-# golang:
-go test ./... -run Test{FunctionName}
-# dotnet:
-dotnet test --filter "FullyQualifiedName~{ClassName}"
-# php-laravel:
-php artisan test --filter {ClassName}
-# context-engineering (pytest):
-pytest tests/{domain}/{test_file}.py -v
-pytest tests/{domain}/{test_file}.py::{TestClass}::{test_method} -v
-pytest tests/ --cov={source_dir} --cov-report=term-missing
-```
-
-### Nếu `platform_type = web-frontend`
-
-```bash
-# Run all tests
-{conventions.test_command}
-
-# Scoped (Vitest / Jest):
-npx vitest run src/features/{domain}/{Component}.test.tsx
-npx jest src/features/{domain}/{Component}.test.tsx
-
-# E2E (Playwright):
-npx playwright test {UC-ID}
-# E2E (Cypress):
-npx cypress run --spec "cypress/e2e/{UC-ID}*"
-```
-
-### Nếu `platform_type = mobile`
-
-```bash
-# Flutter:
-flutter test test/{domain}/{UC-ID}_test.dart
-flutter test integration_test/{UC-ID}_test.dart   # integration
-
-# React Native:
-npx jest {UC-ID}
-
-# iOS (Xcode command line):
-xcodebuild test -scheme {Scheme} -destination 'platform=iOS Simulator,name=iPhone 15'
-
-# Android:
-./gradlew test                              # unit tests
-./gradlew connectedAndroidTest              # instrumented (device/emulator required)
-```
-
-> **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} &`
-
----
-
-## Analyze Failures
-
-### Backend failure patterns
-
-#### java-spring / golang / dotnet / php-laravel
-
-| Error Pattern | Nguyên nhân thường gặp | Suggested Fix |
-|---|---|---|
-| `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 | Nguyên nhân thường gặp | Suggested Fix |
-|---|---|---|
-| `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 | Nguyên nhân thường gặp | Suggested Fix |
-|---|---|---|
-| `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 | Nguyên nhân thường gặp | Suggested Fix |
-|---|---|---|
-| `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 | Nguyên nhân thường gặp | Suggested Fix |
-|---|---|---|
-| `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 | Nguyên nhân thường gặp | Suggested Fix |
-|---|---|---|
-| `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
-
-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.
-
-Cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (`{platform}` = platform của code/`.feature` đang test — `system` cho backend, `web`/`app` cho FE/App; 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}-{platform}.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ó.)*
-
-| Cột | Giá trị |
-|--------|-------|
-| `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` |
-| `last_updated` | hôm nay `YYYY-MM-DD` |
-
-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/ORPHANED): `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}}
-
-## Output
-
-{{include:steps/report-footer.md}}
-
-```
-/dev-run-test Report — {UC-ID} ({active_module})
-✅ Passed: {N} | ❌ Failed: {M} | ⏭️ Skipped: {K} | Duration: {X}s
-
-## Failed Tests
-| Test | Error | Root Cause |
-|------|-------|------------|
-
-## Recommendations
-{fix cụ thể cho từng failure}
-
-Trace: {paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv updated (dev_selftest, dev_selftest_at)
-
-Next:
-  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: chạy /validate-traces (hoặc /sync) để push trace này lên dashboard spec-module.
-```