@educa-corp/sdd-framework 0.6.0 → 0.7.1

package/commands/dev-gen-test.tmpl

@@ -1,490 +0,0 @@
-# /dev-gen-test — Sinh Dev Self-Check Tests
-
-> **Scope — dev self-check (smoke), không phải bộ test chính thức.** Các test này để
-> dev nhanh chóng kiểm chứng code mình sinh ra so với các BDD scenario. Đây là một
-> self-check của dev, **không** phải bộ test authoritative của QC/dev-team (cái đó có
-> flow riêng, implement ở nơi khác). Kết quả hiện lên dashboard Living Docs như một tín hiệu
-> **dev self-test** để QC thấy dev đã tự chạy check của mình.
-
-## Gate
-{{include:steps/gate.md}}
-
-*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID hoặc path file `.feature`. Tìm file feature tại `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}-*.feature` (glob khớp xuyên các PRD — filename gồm hậu tố slug) và các file implementation gắn tag `@trace.implements={UC-ID}`.*
-
-## Context
-{{include:steps/context-loader.md}}
-
----
-
-## Service Detection
-
-Đọc `@trace.service` và `@trace.module` từ header file feature.
-
-| Điều kiện | Hành động |
-|---|---|
-| `@trace.module` có mặt | Dùng làm `active_module` |
-| `@trace.module` vắng | Dùng `tech_stack.module` từ project-context.yaml |
-| `@trace.service` có mặt | Lưu làm `active_service` |
-| `@trace.service` vắng | Dùng domain của `{UC-ID}` làm fallback |
-
-**Phân loại platform type:**
-
-| 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
-
-Trước khi sinh, quét file feature tìm scenario và các file implementation tìm class/function. Hiện:
-
-```
-Test Plan — {UC-ID} ({active_module})
-──────────────────────────────────────
-Platform   : {backend | web-frontend | mobile}
-Scenarios  : {N} scenario từ file .feature
-Impl files : {danh sách file gắn tag @trace.implements={UC-ID}}
-
-Test cần sinh:
-  {danh sách riêng theo platform — xem template bên dưới}
-
-Proceed? (Y/N)
-```
-
-Chờ "Y" rõ ràng trước khi sinh.
-
----
-
-## Generate
-
-### Nếu `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 test: mock ở layer Repository, test logic Service
-- Integration test: mock ở layer Facade/Service, chỉ test HTTP contract
-- Không bao giờ mock class đang được test
-- Theo naming: `methodName_whenCondition_shouldOutcome` (từ 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
-
-Kiểm tra `tech_stack.language` từ project-context.yaml để chọn đúng cú pháp test:
-
-**Nếu language = Python** (mặc định):
-
-```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)
-```
-
-**Nếu language = TypeScript / JavaScript** (Node.js LangChain.js, v.v.):
-
-```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}')
-  })
-})
-```
-
-**Nếu language = Java** (LangChain4j, v.v.): dùng JUnit 5 + Mockito, cùng pattern như unit test java-spring ở trên — mock interface `ChatLanguageModel`.
-
-Rules:
-- Mock LLM client ở boundary — không bao giờ gọi LLM thật trong unit test
-- Validate input schema và output schema riêng biệt
-- Mỗi scenario trong `.feature` map sang một test function
-- Dùng parameterized test cho nhiều biến thể input
-
----
-
-### Nếu `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:
-- Một file component test cho mỗi component liên quan tới UC
-- Một file E2E test cho mỗi UC, phủ happy path + các error scenario chính
-- Mock API call ở network layer (MSW hoặc cy.intercept), không phải ở component props
-- Dùng accessible query (`getByRole`, `getByLabelText`) — tránh `getByTestId` trừ khi cần
-- Mỗi test map đúng một scenario trong file `.feature`
-
----
-
-### Nếu `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
-
-**Mọi platform:**
-- [ ] `@trace.verifies` trên mỗi test class / test group
-- [ ] `@trace.service` trên mỗi test class / test group
-- [ ] Mỗi scenario trong file `.feature` có ≥ 1 test tương ứng
-- [ ] Phủ happy path
-- [ ] Phủ các scenario error / edge case chính
-
-**Chỉ backend:**
-- [ ] Mock đúng layer (Repository trong unit test, Facade/Service trong controller test)
-- [ ] Không gọi DB thật trong unit test
-- [ ] Test naming theo `methodName_whenCondition_shouldOutcome` (CLAUDE.md §6)
-
-**Chỉ Frontend / Mobile:**
-- [ ] Không hardcode delay (`sleep`, `setTimeout`) trong test — dùng `waitFor` / `pumpAndSettle`
-- [ ] Dùng accessible query (role, label) không phải selector phụ thuộc implementation
-- [ ] Mock API call ở network layer, không phải ở component level
-
----
-
-## Write Trace State
-
-Sau khi sinh tất cả file test, 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) — với mỗi scenario, tìm row có sẵn theo `sc_id` và cập nhật:
-
-| Cột | Giá trị |
-|--------|-------|
-| `test_count` | số test method phủ SC này |
-| `test_classes` | tên test class / describe-block, ngăn cách bởi dấu phẩy |
-| `dev_selftest` | `not_run` (test giờ đã tồn tại nhưng chưa chạy — `/dev-run-test` set pass/fail) |
-| `last_updated` | hôm nay `YYYY-MM-DD` |
-
-Giữ nguyên mọi cột khác (gồm `dev_selftest_at`, do `/dev-run-test` sở hữu, và `qc_status`/`qc_run_at`, do `/qc-run-test` sở hữu).
-
----
-
-## Refresh Panel Mirror
-{{include:steps/trace-mirror.md}}
-
----
-
-## Output
-
-{{include:steps/report-footer.md}}
-
-```
-/dev-gen-test Hoàn tất — {UC-ID} ({active_module})
-  ✅ {TestClass1} ({N} tests)
-  ✅ {TestClass2} ({N} tests)
-Trace: {paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv updated
-Next: /dev-run-test {UC-ID}
-
-📊 Living Docs: chạy /validate-traces (hoặc /sync) để push trace này lên dashboard spec-module.
-```