ma-agents 2.19.2 → 2.20.0

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-automate/steps-c/step-03b-subagent-backend.md

@@ -0,0 +1,246 @@
+---
+name: 'step-03b-subagent-backend'
+description: 'Subagent: Generate backend tests only (unit, integration, contract)'
+subagent: true
+outputFile: '/tmp/tea-automate-backend-tests-{{timestamp}}.json'
+---
+
+# Subagent 3B-backend: Generate Backend Tests
+
+## SUBAGENT CONTEXT
+
+This is an **isolated subagent** running in parallel with API test generation (and optionally E2E test generation for fullstack projects).
+
+**What you have from parent workflow:**
+
+- Target features/services identified in Step 2
+- Knowledge fragments loaded: test-levels-framework, test-priorities-matrix, data-factories
+- Config: test framework, detected stack type
+- Coverage plan: which services/modules need backend testing
+
+**Your task:** Generate backend tests ONLY (unit, integration, contract - not API endpoint tests, not E2E).
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- Read this entire subagent file before acting
+- Generate backend tests ONLY (unit, integration, contract)
+- Output structured JSON to temp file using the subagent output schema contract
+- Follow knowledge fragment patterns
+- Do NOT generate API endpoint tests (that's subagent 3A)
+- Do NOT generate E2E tests (that's subagent 3B-E2E)
+- Do NOT run tests (that's step 4)
+- Do NOT generate fixtures yet (that's step 3C aggregation)
+
+---
+
+## SUBAGENT TASK
+
+### 1. Identify Test Targets
+
+From the coverage plan (Step 2 output), identify:
+
+- Which services/modules need unit test coverage
+- Which integrations need integration test coverage (database, message queues, external services)
+- Which service contracts need contract test coverage (Pact, schema validation)
+- Business logic functions requiring edge case coverage
+
+### 2. Detect Framework & Language
+
+From `config.test_framework` and project manifests, determine:
+
+- **Python (pytest)**: Use `pytest` conventions, `conftest.py` fixtures, `@pytest.mark` decorators
+- **Java/Kotlin (JUnit)**: Use JUnit 5 annotations (`@Test`, `@BeforeEach`, `@Nested`), Mockito for mocking
+- **Go (go test)**: Use `*_test.go` files, `testing.T`, table-driven tests, `testify` assertions
+- **C#/.NET (xUnit)**: Use `[Fact]`, `[Theory]`, `[InlineData]`, `Moq` for mocking
+- **Ruby (RSpec)**: Use `describe`/`context`/`it` blocks, `let`/`before` helpers, `FactoryBot`
+
+### 3. Generate Unit Tests
+
+For each module/service, create test files following language-idiomatic patterns:
+
+**Python (pytest) example:**
+
+```python
+import pytest
+from unittest.mock import MagicMock, patch
+from myapp.services.user_service import UserService
+
+class TestUserService:
+    """[P0] Unit tests for UserService"""
+
+    def test_create_user_with_valid_data(self, user_factory):
+        """Should create user when data is valid"""
+        user_data = user_factory.build()
+        result = UserService.create(user_data)
+        assert result.email == user_data["email"]
+
+    def test_create_user_rejects_duplicate_email(self, user_factory):
+        """[P1] Should reject duplicate email"""
+        user_data = user_factory.build(email="existing@test.com")
+        with pytest.raises(DuplicateEmailError):
+            UserService.create(user_data)
+```
+
+**Go (go test) example:**
+
+```go
+func TestUserService_Create(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   CreateUserInput
+        wantErr bool
+    }{
+        {"valid user", validInput(), false},
+        {"duplicate email", duplicateInput(), true},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            svc := NewUserService(mockRepo)
+            _, err := svc.Create(tt.input)
+            if (err != nil) != tt.wantErr {
+                t.Errorf("Create() error = %v, wantErr %v", err, tt.wantErr)
+            }
+        })
+    }
+}
+```
+
+**Requirements:**
+
+- Follow the detected framework's idiomatic test patterns
+- Include priority tags [P0], [P1], [P2], [P3] in test descriptions
+- Use proper mocking for external dependencies (database, APIs, message queues)
+- Test both happy path and error cases
+- Use proper typing/type hints where applicable
+- No hard-coded test data; use factories or builders
+
+### 4. Generate Integration Tests
+
+For service integrations, create integration test files:
+
+- Database integration tests (with test database or in-memory alternatives)
+- Message queue consumer/producer tests
+- Cache integration tests
+- External service integration tests (with mocked HTTP clients)
+
+### 5. Generate Contract Tests (if applicable)
+
+If the project uses microservices or has defined API contracts:
+
+- Pact consumer/provider tests
+- Schema validation tests (JSON Schema, Protobuf)
+- OpenAPI spec compliance tests
+
+### 6. Track Fixture Needs
+
+Identify fixtures/helpers needed for backend tests:
+
+- Database fixtures (seed data, cleanup)
+- Factory functions (test data builders)
+- Mock services (HTTP mocks, message queue mocks)
+- Configuration fixtures (test environment config)
+
+**Do NOT create fixtures yet** - just track what's needed for aggregation step.
+
+---
+
+## OUTPUT FORMAT
+
+Write JSON to temp file: `/tmp/tea-automate-backend-tests-{{timestamp}}.json`
+
+```json
+{
+  "subagentType": "backend",
+  "testsGenerated": [
+    {
+      "file": "tests/unit/test_user_service.py",
+      "content": "[full test file content]",
+      "description": "Unit tests for UserService",
+      "priority_coverage": {
+        "P0": 3,
+        "P1": 2,
+        "P2": 1,
+        "P3": 0
+      }
+    },
+    {
+      "file": "tests/integration/test_user_repository.py",
+      "content": "[full test file content]",
+      "description": "Integration tests for user database operations",
+      "priority_coverage": {
+        "P0": 1,
+        "P1": 2,
+        "P2": 1,
+        "P3": 0
+      }
+    }
+  ],
+  "coverageSummary": {
+    "totalTests": 15,
+    "testLevels": ["unit", "integration", "contract"],
+    "fixtureNeeds": ["databaseFixture", "userFactory", "mockHttpClient"]
+  },
+  "status": "complete",
+  "success": true,
+  "subagent": "backend-tests",
+  "knowledge_fragments_used": ["test-levels-framework", "test-priorities-matrix", "data-factories"],
+  "summary": "Generated 15 backend test cases (10 unit, 4 integration, 1 contract)"
+}
+```
+
+**On Error:**
+
+```json
+{
+  "subagentType": "backend",
+  "testsGenerated": [],
+  "coverageSummary": {
+    "totalTests": 0,
+    "testLevels": [],
+    "fixtureNeeds": []
+  },
+  "status": "partial",
+  "success": false,
+  "subagent": "backend-tests",
+  "error": "Error message describing what went wrong",
+  "partial_output": {
+    /* any tests generated before error */
+  }
+}
+```
+
+---
+
+## EXIT CONDITION
+
+Subagent completes when:
+
+- All identified modules have backend test files generated
+- All tests follow language-idiomatic patterns
+- JSON output written to temp file using the subagent output schema contract
+- Fixture needs tracked
+
+**Subagent terminates here.** Parent workflow will read output and proceed to aggregation.
+
+---
+
+## SUBAGENT SUCCESS METRICS
+
+### SUCCESS:
+
+- All backend tests generated following idiomatic patterns
+- JSON output valid and complete, matches subagent output schema contract
+- No E2E or browser tests included (out of scope)
+- Proper mocking used for external dependencies
+- Priority tags assigned to all test cases
+
+### FAILURE:
+
+- Generated tests other than backend tests (unit/integration/contract)
+- Did not follow language-idiomatic patterns
+- Invalid or missing JSON output
+- Output schema does not match the contract
+- Ran tests (not subagent responsibility)
+- Used real external services instead of mocks

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-automate/steps-c/step-03b-subagent-e2e.md

@@ -0,0 +1,213 @@
+---
+name: 'step-03b-subagent-e2e'
+description: 'Subagent: Generate E2E tests only'
+subagent: true
+outputFile: '/tmp/tea-automate-e2e-tests-{{timestamp}}.json'
+---
+
+# Subagent 3B: Generate E2E Tests
+
+## SUBAGENT CONTEXT
+
+This is an **isolated subagent** running in parallel with API test generation.
+
+**What you have from parent workflow:**
+
+- Target features/user journeys identified in Step 2
+- Knowledge fragments loaded: fixture-architecture, network-first, selector-resilience
+- Config: test framework, Playwright Utils enabled/disabled
+- Coverage plan: which user journeys need E2E testing
+
+**Your task:** Generate E2E tests ONLY (not API, not fixtures, not other test types).
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire subagent file before acting
+- ✅ Generate E2E tests ONLY
+- ✅ Output structured JSON to temp file
+- ✅ Follow knowledge fragment patterns
+- ❌ Do NOT generate API tests (that's subagent 3A)
+- ❌ Do NOT run tests (that's step 4)
+- ❌ Do NOT generate fixtures yet (that's step 3C aggregation)
+
+---
+
+## SUBAGENT TASK
+
+### 1. Identify User Journeys
+
+From the coverage plan (Step 2 output), identify:
+
+- Which user journeys need E2E coverage
+- Critical user paths (authentication, checkout, profile, etc.)
+- UI interactions required
+- Expected visual states
+
+### 2. Browser Interaction (Selector Verification)
+
+**Automation mode:** `config.tea_browser_automation`
+
+If `auto` (fall back to MCP if CLI unavailable; if neither available, generate from best practices):
+
+- Open the target page first, then verify selectors with a snapshot:
+  `playwright-cli -s=tea-automate-{{timestamp}} open <target_url>`
+  `playwright-cli -s=tea-automate-{{timestamp}} snapshot` → map refs to Playwright locators
+  - ref `{role: "button", name: "Submit"}` → `page.getByRole('button', { name: 'Submit' })`
+  - ref `{role: "textbox", name: "Email"}` → `page.getByRole('textbox', { name: 'Email' })`
+- `playwright-cli -s=tea-automate-{{timestamp}} close` when done
+
+If `cli` (CLI only — do NOT fall back to MCP; generate from best practices if CLI unavailable):
+
+- Open the target page first, then verify selectors with a snapshot:
+  `playwright-cli -s=tea-automate-{{timestamp}} open <target_url>`
+  `playwright-cli -s=tea-automate-{{timestamp}} snapshot` → map refs to Playwright locators
+  - ref `{role: "button", name: "Submit"}` → `page.getByRole('button', { name: 'Submit' })`
+  - ref `{role: "textbox", name: "Email"}` → `page.getByRole('textbox', { name: 'Email' })`
+- `playwright-cli -s=tea-automate-{{timestamp}} close` when done
+
+> **Session Hygiene:** Always close sessions using `playwright-cli -s=tea-automate-{{timestamp}} close`. Do NOT use `close-all` — it kills every session on the machine and breaks parallel execution.
+
+If `mcp`:
+
+- Use MCP tools for selector verification (current behavior)
+
+If `none`:
+
+- Generate selectors from best practices without browser verification
+
+### 3. Generate E2E Test Files
+
+For each user journey, create test file in `tests/e2e/[feature].spec.ts`:
+
+**Test Structure:**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('[Feature] E2E User Journey', () => {
+  test('[P0] should complete [user journey]', async ({ page }) => {
+    // Navigate to starting point
+    await page.goto('/feature');
+
+    // Interact with UI
+    await page.getByRole('button', { name: 'Submit' }).click();
+
+    // Assert expected state
+    await expect(page.getByText('Success')).toBeVisible();
+  });
+
+  test('[P1] should handle [edge case]', async ({ page }) => {
+    // Test edge case scenario
+  });
+});
+```
+
+**Requirements:**
+
+- ✅ Follow fixture architecture patterns (from fixture-architecture fragment)
+- ✅ Use network-first patterns: intercept before navigate (from network-first fragment)
+- ✅ Use resilient selectors: getByRole, getByText, getByLabel (from selector-resilience fragment)
+- ✅ Include priority tags [P0], [P1], [P2], [P3]
+- ✅ Test complete user journeys (not isolated clicks)
+- ✅ Use proper TypeScript types
+- ✅ Deterministic waits (no hard sleeps, use expect().toBeVisible())
+
+### 4. Track Fixture Needs
+
+Identify fixtures needed for E2E tests:
+
+- Page object models (if complex)
+- Authentication fixtures (logged-in user state)
+- Network mocks/intercepts
+- Test data fixtures
+
+**Do NOT create fixtures yet** - just track what's needed for aggregation step.
+
+---
+
+## OUTPUT FORMAT
+
+Write JSON to temp file: `/tmp/tea-automate-e2e-tests-{{timestamp}}.json`
+
+```json
+{
+  "success": true,
+  "subagent": "e2e-tests",
+  "tests": [
+    {
+      "file": "tests/e2e/authentication.spec.ts",
+      "content": "[full TypeScript test file content]",
+      "description": "E2E tests for user authentication journey",
+      "priority_coverage": {
+        "P0": 2,
+        "P1": 3,
+        "P2": 2,
+        "P3": 0
+      }
+    },
+    {
+      "file": "tests/e2e/checkout.spec.ts",
+      "content": "[full TypeScript test file content]",
+      "description": "E2E tests for checkout journey",
+      "priority_coverage": {
+        "P0": 3,
+        "P1": 2,
+        "P2": 1,
+        "P3": 0
+      }
+    }
+  ],
+  "fixture_needs": ["authenticatedUserFixture", "paymentMockFixture", "checkoutDataFixture"],
+  "knowledge_fragments_used": ["fixture-architecture", "network-first", "selector-resilience"],
+  "test_count": 15,
+  "summary": "Generated 15 E2E test cases covering 5 user journeys"
+}
+```
+
+**On Error:**
+
+```json
+{
+  "success": false,
+  "subagent": "e2e-tests",
+  "error": "Error message describing what went wrong",
+  "partial_output": {
+    /* any tests generated before error */
+  }
+}
+```
+
+---
+
+## EXIT CONDITION
+
+Subagent completes when:
+
+- ✅ All user journeys have E2E test files generated
+- ✅ All tests follow knowledge fragment patterns
+- ✅ JSON output written to temp file
+- ✅ Fixture needs tracked
+
+**Subagent terminates here.** Parent workflow will read output and proceed to aggregation.
+
+---
+
+## 🚨 SUBAGENT SUCCESS METRICS
+
+### ✅ SUCCESS:
+
+- All E2E tests generated following patterns
+- JSON output valid and complete
+- No API/component/unit tests included (out of scope)
+- Resilient selectors used (getByRole, getByText)
+- Network-first patterns applied (intercept before navigate)
+
+### ❌ FAILURE:
+
+- Generated tests other than E2E tests
+- Did not follow knowledge fragment patterns
+- Invalid or missing JSON output
+- Ran tests (not subagent responsibility)
+- Used brittle selectors (CSS classes, XPath)