@edupia-tutor/spec-driven-docs 0.14.0

package/commands/dev-gen-test.tmpl

@@ -0,0 +1,490 @@
+# /dev-gen-test — Generate Dev Self-Check Tests
+
+> **Scope — dev self-check (smoke), not the official test suite.** These tests let the
+> developer quickly verify their own generated code against the BDD scenarios. They are a
+> developer self-check, **not** the QC/dev-team's authoritative test suite (that has its
+> own separate flow, implemented elsewhere). Results surface to the Living Docs dashboard
+> as a **dev self-test** signal so QC can see the dev already ran their own checks.
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target in Step 1 is a UC-ID or `.feature` file path. Find the feature file at `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}-*.feature` (glob match across PRDs — filename includes slug suffix) and the implementation files tagged `@trace.implements={UC-ID}`.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Service Detection
+
+Read `@trace.service` and `@trace.module` from the feature file header.
+
+| Condition | Action |
+|---|---|
+| `@trace.module` present | Use as `active_module` |
+| `@trace.module` absent | Use `tech_stack.module` from project-context.yaml |
+| `@trace.service` present | Store as `active_service` |
+| `@trace.service` absent | Use `{UC-ID}` domain as fallback |
+
+**Platform type classification:**
+
+| Platform | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+---
+
+## CHECKPOINT — Test Plan
+
+Before generating, scan the feature file for scenarios and the implementation files for classes/functions. Display:
+
+```
+Test Plan — {UC-ID} ({active_module})
+──────────────────────────────────────
+Platform   : {backend | web-frontend | mobile}
+Scenarios  : {N} scenarios from .feature file
+Impl files : {list of files tagged @trace.implements={UC-ID}}
+
+Tests to generate:
+  {platform-specific list — see templates below}
+
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" before generating.
+
+---
+
+## Generate
+
+### If `platform_type = backend`
+
+#### java-spring
+
+```java
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=unit
+class {Resource}ServiceImplTest {
+    @Mock {Repository} {repository};
+    @InjectMocks {Resource}ServiceImpl service;
+
+    // methodName_whenValid_shouldReturnExpected()
+    //   Given — mock repository returns data
+    //   When  — call service method
+    //   Then  — assert result matches expected
+
+    // methodName_whenNotFound_shouldThrowException()
+    //   Given — mock returns Optional.empty()
+    //   When & Then — assertThrows({NotFoundException}.class, ...)
+}
+
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=integration
+@WebMvcTest({Resource}Controller.class)
+class {Resource}ControllerTest {
+    @MockBean {Facade | Service} facade;
+
+    // endpoint_shouldReturn200WhenValid()
+    // endpoint_shouldReturn400WhenInvalid()
+    // endpoint_shouldReturn404WhenNotFound()
+    // endpoint_shouldReturn401WhenUnauthenticated()
+}
+```
+
+Rules:
+- Unit tests: mock at Repository layer, test Service logic
+- Integration tests: mock at Facade/Service layer, test HTTP contract only
+- Never mock the class under test
+- Follow naming: `methodName_whenCondition_shouldOutcome` (from CLAUDE.md §6)
+
+#### golang
+
+```go
+// @trace.verifies={UC-ID}
+// Unit: table-driven tests for service layer
+func Test{Resource}Service_{Method}(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   {InputType}
+        want    {OutputType}
+        wantErr bool
+    }{
+        {"valid input", ..., ..., false},
+        {"not found", ..., nil, true},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) { ... })
+    }
+}
+
+// @trace.verifies={UC-ID}
+// Integration: HTTP handler tests using httptest
+func Test{Resource}Handler_{Endpoint}(t *testing.T) {
+    // setup router, mock service, fire request
+    // assert status code and response body
+}
+```
+
+#### dotnet
+
+```csharp
+// @trace.verifies={UC-ID}
+// Unit: xUnit + Moq
+public class {Resource}ServiceTests {
+    private readonly Mock<I{Repository}> _repoMock = new();
+    private readonly {Resource}Service _sut;
+
+    [Fact]
+    public async Task {Method}_WhenValid_Returns{Expected}() { }
+
+    [Fact]
+    public async Task {Method}_WhenNotFound_ThrowsNotFoundException() { }
+}
+
+// @trace.verifies={UC-ID}
+// Integration: WebApplicationFactory
+public class {Resource}ControllerTests : IClassFixture<WebApplicationFactory<Program>> {
+    [Fact]
+    public async Task {Endpoint}_Returns200_WhenValid() { }
+
+    [Fact]
+    public async Task {Endpoint}_Returns400_WhenInvalid() { }
+}
+```
+
+#### php-laravel
+
+```php
+// @trace.verifies={UC-ID}
+// Unit: PHPUnit
+class {Resource}ServiceTest extends TestCase {
+    public function test_{method}_when_valid_should_return_expected(): void { }
+    public function test_{method}_when_not_found_should_throw(): void { }
+}
+
+// @trace.verifies={UC-ID}
+// Feature: Laravel HTTP tests
+class {Resource}ControllerTest extends TestCase {
+    use RefreshDatabase;
+    public function test_{endpoint}_returns_200_when_valid(): void {
+        $response = $this->getJson('/api/{resource}');
+        $response->assertStatus(200)->assertJsonStructure([...]);
+    }
+}
+```
+
+#### context-engineering
+
+Check `tech_stack.language` from project-context.yaml to select the correct test syntax:
+
+**If language = Python** (default):
+
+```python
+# @trace.verifies={UC-ID}
+# @trace.test_type=unit
+# Unit: test prompt orchestration functions
+
+import pytest
+from unittest.mock import patch, MagicMock
+
+class Test{Resource}Prompt:
+    # test_{function}_when_valid_input_should_return_expected_output()
+    #   Given — mock LLM client returns controlled response
+    #   When  — call prompt function with valid input
+    #   Then  — assert output matches expected structure/content
+
+    # test_{function}_when_llm_unavailable_should_raise()
+    #   Given — mock LLM client raises connection error
+    #   When & Then — assert specific exception is raised
+
+    # test_{function}_trace_assertions()
+    #   Given — run function with trace capture enabled
+    #   Then  — assert @trace.implements tag present in function definition
+    #           assert output conforms to expected schema
+
+    def test_{function}_when_valid_should_return_expected(self, mock_llm):
+        # Arrange
+        mock_llm.complete.return_value = "{expected response}"
+        # Act
+        result = {function}(input={test_input})
+        # Assert
+        assert result == {expected_output}
+        mock_llm.complete.assert_called_once_with(...)
+
+    def test_{function}_when_invalid_input_should_raise(self):
+        with pytest.raises({ExpectedError}):
+            {function}(input=None)
+```
+
+**If language = TypeScript / JavaScript** (Node.js LangChain.js, etc.):
+
+```typescript
+// @trace.verifies={UC-ID}
+// @trace.test_type=unit
+import { jest } from '@jest/globals'
+
+describe('{Resource}Prompt', () => {
+  const mockLlm = { complete: jest.fn() }
+
+  it('{scenario description}', async () => {
+    mockLlm.complete.mockResolvedValue('{expected response}')
+    const result = await {function}({ input: '{test_input}', llm: mockLlm })
+    expect(result).toEqual({expected_output})
+    expect(mockLlm.complete).toHaveBeenCalledWith(expect.objectContaining({ ... }))
+  })
+
+  it('throws when input is invalid', async () => {
+    await expect({function}({ input: null, llm: mockLlm })).rejects.toThrow('{ExpectedError}')
+  })
+})
+```
+
+**If language = Java** (LangChain4j, etc.): use JUnit 5 + Mockito, same patterns as java-spring unit tests above — mock the `ChatLanguageModel` interface.
+
+Rules:
+- Mock the LLM client at the boundary — never call real LLM in unit tests
+- Validate input schema and output schema separately
+- Each scenario in `.feature` maps to one test function
+- Use parameterized tests for multiple input variants
+
+---
+
+### If `platform_type = web-frontend`
+
+#### react / nextjs / vue / nuxt / angular
+
+```typescript
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=component
+
+// Component tests (Vitest + Testing Library)
+describe('{ComponentName}', () => {
+  it('renders correctly when data is loaded', () => {
+    render(<{ComponentName} {...props} />)
+    expect(screen.getByText('...')).toBeInTheDocument()
+  })
+
+  it('shows loading state while fetching', () => { })
+
+  it('shows error message on API failure', () => { })
+
+  it('calls handler when user interacts', async () => {
+    await userEvent.click(screen.getByRole('button', { name: '...' }))
+    expect(mockHandler).toHaveBeenCalledWith(...)
+  })
+})
+
+// @trace.verifies={UC-ID}
+// @trace.test_type=e2e
+
+// E2E tests (Playwright or Cypress — use whichever is in project)
+test('{scenario from .feature}', async ({ page }) => {
+  await page.goto('/{route}')
+  await page.getByRole('button', { name: '...' }).click()
+  await expect(page.getByText('...')).toBeVisible()
+})
+```
+
+Rules:
+- One component test file per component involved in the UC
+- One E2E test file per UC covering happy path + key error scenarios
+- Mock API calls at the network layer (MSW or cy.intercept), not at component props
+- Use accessible queries (`getByRole`, `getByLabelText`) — avoid `getByTestId` unless necessary
+- Each test maps to exactly one scenario in the `.feature` file
+
+---
+
+### If `platform_type = mobile`
+
+#### flutter
+
+```dart
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=widget
+
+// Widget tests
+group('{FeatureName} widget tests', () {
+  testWidgets('renders correctly when state is loaded', (tester) async {
+    await tester.pumpWidget(MaterialApp(home: {Widget}()));
+    await tester.pumpAndSettle();
+    expect(find.text('...'), findsOneWidget);
+  });
+
+  testWidgets('shows loading indicator while fetching', (tester) async { });
+  testWidgets('shows error widget on failure', (tester) async { });
+  testWidgets('calls handler on tap', (tester) async {
+    await tester.tap(find.byType(ElevatedButton));
+    await tester.pumpAndSettle();
+    verify(() => mockBloc.add({Event}())).called(1);
+  });
+});
+
+// @trace.verifies={UC-ID}
+// @trace.test_type=integration
+// Integration test (flutter_test / integration_test package)
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+  testWidgets('{scenario from .feature}', (tester) async {
+    app.main();
+    await tester.pumpAndSettle();
+    // Navigate, interact, assert
+  });
+}
+```
+
+#### react-native
+
+```typescript
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=component
+
+// Jest + React Native Testing Library
+describe('{ComponentName}', () => {
+  it('{scenario description}', () => {
+    const { getByText, getByRole } = render(<{ComponentName} {...props} />)
+    expect(getByText('...')).toBeTruthy()
+  })
+
+  it('calls navigation on button press', () => {
+    const mockNavigate = jest.fn()
+    const { getByRole } = render(<{ComponentName} navigation={{ navigate: mockNavigate }} />)
+    fireEvent.press(getByRole('button'))
+    expect(mockNavigate).toHaveBeenCalledWith('...')
+  })
+})
+```
+
+#### ios-swiftui
+
+```swift
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=unit
+
+// XCTest — ViewModel unit tests
+@MainActor
+final class {Feature}ViewModelTests: XCTestCase {
+    var sut: {Feature}ViewModel!
+    var mockRepo: Mock{Repository}!
+
+    override func setUp() async throws {
+        mockRepo = Mock{Repository}()
+        sut = {Feature}ViewModel(repository: mockRepo)
+    }
+
+    func test_{method}_whenValid_shouldUpdate{State}() async throws {
+        // Given
+        mockRepo.stub{Method}Result = {expected}
+        // When
+        await sut.{method}()
+        // Then
+        XCTAssertEqual(sut.{state}, {expected})
+    }
+
+    func test_{method}_whenError_shouldSetErrorState() async throws { }
+}
+```
+
+#### android-compose
+
+```kotlin
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=unit
+
+// Unit test — ViewModel
+class {Feature}ViewModelTest {
+    @get:Rule val mainDispatcherRule = MainDispatcherRule()
+    private val mockRepo: {Repository} = mockk()
+    private lateinit var sut: {Feature}ViewModel
+
+    @Before fun setup() { sut = {Feature}ViewModel(mockRepo) }
+
+    @Test fun `{method} when valid should emit success state`() = runTest {
+        coEvery { mockRepo.{method}(any()) } returns Result.success({data})
+        sut.{method}({input})
+        assertEquals(UiState.Success({data}), sut.uiState.value)
+    }
+}
+
+// @trace.verifies={UC-ID}
+// @trace.test_type=ui
+
+// UI test — Compose
+@HiltAndroidTest
+class {Feature}ScreenTest {
+    @get:Rule(order = 0) val hiltRule = HiltAndroidRule(this)
+    @get:Rule(order = 1) val composeRule = createAndroidComposeRule<MainActivity>()
+
+    @Test fun {scenario}_displaysExpectedUi() {
+        composeRule.onNodeWithText("...").assertIsDisplayed()
+        composeRule.onNodeWithContentDescription("...").performClick()
+        composeRule.onNodeWithText("...").assertIsDisplayed()
+    }
+}
+```
+
+---
+
+## Checklist
+
+**All platforms:**
+- [ ] `@trace.verifies` on every test class / test group
+- [ ] `@trace.service` on every test class / test group
+- [ ] Every scenario in `.feature` file has ≥ 1 corresponding test
+- [ ] Happy path covered
+- [ ] Key error / edge case scenarios covered
+
+**Backend only:**
+- [ ] Correct layer mocked (Repository in unit tests, Facade/Service in controller tests)
+- [ ] No real DB calls in unit tests
+- [ ] Test naming follows `methodName_whenCondition_shouldOutcome` (CLAUDE.md §6)
+
+**Frontend / Mobile only:**
+- [ ] No hardcoded delays (`sleep`, `setTimeout`) in tests — use `waitFor` / `pumpAndSettle`
+- [ ] Accessible queries used (role, label) not implementation-specific selectors
+- [ ] API calls mocked at network layer, not at component level
+
+---
+
+## Write Trace State
+
+After generating all test files, update `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` — for each scenario, find the existing row by `sc_id` and update:
+
+| Column | Value |
+|--------|-------|
+| `test_count` | number of test methods covering this SC |
+| `test_classes` | comma-separated test class / describe-block names |
+| `dev_selftest` | `not_run` (tests now exist but have not been executed — `/dev-run-test` sets pass/fail) |
+| `last_updated` | today `YYYY-MM-DD` |
+
+Leave all other columns unchanged (including `dev_selftest_at`, which `/dev-run-test` owns, and `qc_status`/`qc_run_at`, which `/qc-run-test` owns).
+
+---
+
+## Refresh Panel Mirror
+{{include:steps/trace-mirror.md}}
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/dev-gen-test Complete — {UC-ID} ({active_module})
+  ✅ {TestClass1} ({N} tests)
+  ✅ {TestClass2} ({N} tests)
+Trace: {paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv updated
+Next: /dev-run-test {UC-ID}
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
+```