@edupia-tutor/spec-driven-docs 0.14.0

package/commands/dev-run-test.tmpl

@@ -0,0 +1,224 @@
+# /dev-run-test — Run Dev Self-Check Tests & Report Results
+
+> **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.
+
+## 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`.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## 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.
+
+---
+
+## Submodule Working Directory
+
+*Skip this section if `service_root` is not set (single-service mode).*
+
+When running in **umbrella/submodule mode** (`service_root` was resolved in context-loader Step 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} &&`:
+
+```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
+```
+
+> **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.
+
+---
+
+## Run
+
+### If `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
+```
+
+### If `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}*"
+```
+
+### If `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)
+```
+
+> **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} &`
+
+---
+
+## Analyze Failures
+
+### Backend failure patterns
+
+#### java-spring / golang / dotnet / php-laravel
+
+| Error Pattern | Common Cause | 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 |
+
+#### context-engineering (AI/LLM pipelines)
+
+| Error Pattern | Common Cause | 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 |
+
+### Web frontend failure patterns
+
+| Error Pattern | Common Cause | 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 |
+
+### Mobile failure patterns
+
+#### Flutter
+| Error Pattern | Common Cause | 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 |
+
+#### React Native
+| Error Pattern | Common Cause | 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` |
+
+#### iOS / Android
+| Error Pattern | Common Cause | 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 |
+
+---
+
+## 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.
+
+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.)*
+
+| Column | Value |
+|--------|-------|
+| `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` |
+
+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*.
+
+## 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
+{specific fix per 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)
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
+```