agentvibes 2.13.7 → 2.13.9

package/.bmad/bmm/testarch/knowledge/test-levels-framework.md

@@ -1,473 +0,0 @@
-<!-- Powered by BMAD-CORE™ -->
-
-# Test Levels Framework
-
-Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios.
-
-## Test Level Decision Matrix
-
-### Unit Tests
-
-**When to use:**
-
-- Testing pure functions and business logic
-- Algorithm correctness
-- Input validation and data transformation
-- Error handling in isolated components
-- Complex calculations or state machines
-
-**Characteristics:**
-
-- Fast execution (immediate feedback)
-- No external dependencies (DB, API, file system)
-- Highly maintainable and stable
-- Easy to debug failures
-
-**Example scenarios:**
-
-```yaml
-unit_test:
-  component: 'PriceCalculator'
-  scenario: 'Calculate discount with multiple rules'
-  justification: 'Complex business logic with multiple branches'
-  mock_requirements: 'None - pure function'
-```
-
-### Integration Tests
-
-**When to use:**
-
-- Component interaction verification
-- Database operations and transactions
-- API endpoint contracts
-- Service-to-service communication
-- Middleware and interceptor behavior
-
-**Characteristics:**
-
-- Moderate execution time
-- Tests component boundaries
-- May use test databases or containers
-- Validates system integration points
-
-**Example scenarios:**
-
-```yaml
-integration_test:
-  components: ['UserService', 'AuthRepository']
-  scenario: 'Create user with role assignment'
-  justification: 'Critical data flow between service and persistence'
-  test_environment: 'In-memory database'
-```
-
-### End-to-End Tests
-
-**When to use:**
-
-- Critical user journeys
-- Cross-system workflows
-- Visual regression testing
-- Compliance and regulatory requirements
-- Final validation before release
-
-**Characteristics:**
-
-- Slower execution
-- Tests complete workflows
-- Requires full environment setup
-- Most realistic but most brittle
-
-**Example scenarios:**
-
-```yaml
-e2e_test:
-  journey: 'Complete checkout process'
-  scenario: 'User purchases with saved payment method'
-  justification: 'Revenue-critical path requiring full validation'
-  environment: 'Staging with test payment gateway'
-```
-
-## Test Level Selection Rules
-
-### Favor Unit Tests When:
-
-- Logic can be isolated
-- No side effects involved
-- Fast feedback needed
-- High cyclomatic complexity
-
-### Favor Integration Tests When:
-
-- Testing persistence layer
-- Validating service contracts
-- Testing middleware/interceptors
-- Component boundaries critical
-
-### Favor E2E Tests When:
-
-- User-facing critical paths
-- Multi-system interactions
-- Regulatory compliance scenarios
-- Visual regression important
-
-## Anti-patterns to Avoid
-
-- E2E testing for business logic validation
-- Unit testing framework behavior
-- Integration testing third-party libraries
-- Duplicate coverage across levels
-
-## Duplicate Coverage Guard
-
-**Before adding any test, check:**
-
-1. Is this already tested at a lower level?
-2. Can a unit test cover this instead of integration?
-3. Can an integration test cover this instead of E2E?
-
-**Coverage overlap is only acceptable when:**
-
-- Testing different aspects (unit: logic, integration: interaction, e2e: user experience)
-- Critical paths requiring defense in depth
-- Regression prevention for previously broken functionality
-
-## Test Naming Conventions
-
-- Unit: `test_{component}_{scenario}`
-- Integration: `test_{flow}_{interaction}`
-- E2E: `test_{journey}_{outcome}`
-
-## Test ID Format
-
-`{EPIC}.{STORY}-{LEVEL}-{SEQ}`
-
-Examples:
-
-- `1.3-UNIT-001`
-- `1.3-INT-002`
-- `1.3-E2E-001`
-
-## Real Code Examples
-
-### Example 1: E2E Test (Full User Journey)
-
-**Scenario**: User logs in, navigates to dashboard, and places an order.
-
-```typescript
-// tests/e2e/checkout-flow.spec.ts
-import { test, expect } from '@playwright/test';
-import { createUser, createProduct } from '../test-utils/factories';
-
-test.describe('Checkout Flow', () => {
-  test('user can complete purchase with saved payment method', async ({ page, apiRequest }) => {
-    // Setup: Seed data via API (fast!)
-    const user = createUser({ email: 'buyer@example.com', hasSavedCard: true });
-    const product = createProduct({ name: 'Widget', price: 29.99, stock: 10 });
-
-    await apiRequest.post('/api/users', { data: user });
-    await apiRequest.post('/api/products', { data: product });
-
-    // Network-first: Intercept BEFORE action
-    const loginPromise = page.waitForResponse('**/api/auth/login');
-    const cartPromise = page.waitForResponse('**/api/cart');
-    const orderPromise = page.waitForResponse('**/api/orders');
-
-    // Step 1: Login
-    await page.goto('/login');
-    await page.fill('[data-testid="email"]', user.email);
-    await page.fill('[data-testid="password"]', 'password123');
-    await page.click('[data-testid="login-button"]');
-    await loginPromise;
-
-    // Assert: Dashboard visible
-    await expect(page).toHaveURL('/dashboard');
-    await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
-
-    // Step 2: Add product to cart
-    await page.goto(`/products/${product.id}`);
-    await page.click('[data-testid="add-to-cart"]');
-    await cartPromise;
-    await expect(page.getByText('Added to cart')).toBeVisible();
-
-    // Step 3: Checkout with saved payment
-    await page.goto('/checkout');
-    await expect(page.getByText('Visa ending in 1234')).toBeVisible(); // Saved card
-    await page.click('[data-testid="use-saved-card"]');
-    await page.click('[data-testid="place-order"]');
-    await orderPromise;
-
-    // Assert: Order confirmation
-    await expect(page.getByText('Order Confirmed')).toBeVisible();
-    await expect(page.getByText(/Order #\d+/)).toBeVisible();
-    await expect(page.getByText('$29.99')).toBeVisible();
-  });
-});
-```
-
-**Key Points (E2E)**:
-
-- Tests complete user journey across multiple pages
-- API setup for data (fast), UI for assertions (user-centric)
-- Network-first interception to prevent flakiness
-- Validates critical revenue path end-to-end
-
-### Example 2: Integration Test (API/Service Layer)
-
-**Scenario**: UserService creates user and assigns role via AuthRepository.
-
-```typescript
-// tests/integration/user-service.spec.ts
-import { test, expect } from '@playwright/test';
-import { createUser } from '../test-utils/factories';
-
-test.describe('UserService Integration', () => {
-  test('should create user with admin role via API', async ({ request }) => {
-    const userData = createUser({ role: 'admin' });
-
-    // Direct API call (no UI)
-    const response = await request.post('/api/users', {
-      data: userData,
-    });
-
-    expect(response.status()).toBe(201);
-
-    const createdUser = await response.json();
-    expect(createdUser.id).toBeTruthy();
-    expect(createdUser.email).toBe(userData.email);
-    expect(createdUser.role).toBe('admin');
-
-    // Verify database state
-    const getResponse = await request.get(`/api/users/${createdUser.id}`);
-    expect(getResponse.status()).toBe(200);
-
-    const fetchedUser = await getResponse.json();
-    expect(fetchedUser.role).toBe('admin');
-    expect(fetchedUser.permissions).toContain('user:delete');
-    expect(fetchedUser.permissions).toContain('user:update');
-
-    // Cleanup
-    await request.delete(`/api/users/${createdUser.id}`);
-  });
-
-  test('should validate email uniqueness constraint', async ({ request }) => {
-    const userData = createUser({ email: 'duplicate@example.com' });
-
-    // Create first user
-    const response1 = await request.post('/api/users', { data: userData });
-    expect(response1.status()).toBe(201);
-
-    const user1 = await response1.json();
-
-    // Attempt duplicate email
-    const response2 = await request.post('/api/users', { data: userData });
-    expect(response2.status()).toBe(409); // Conflict
-    const error = await response2.json();
-    expect(error.message).toContain('Email already exists');
-
-    // Cleanup
-    await request.delete(`/api/users/${user1.id}`);
-  });
-});
-```
-
-**Key Points (Integration)**:
-
-- Tests service layer + database interaction
-- No UI involved—pure API validation
-- Business logic focus (role assignment, constraints)
-- Faster than E2E, more realistic than unit tests
-
-### Example 3: Component Test (Isolated UI Component)
-
-**Scenario**: Test button component in isolation with props and user interactions.
-
-```typescript
-// src/components/Button.cy.tsx (Cypress Component Test)
-import { Button } from './Button';
-
-describe('Button Component', () => {
-  it('should render with correct label', () => {
-    cy.mount(<Button label="Click Me" />);
-    cy.contains('Click Me').should('be.visible');
-  });
-
-  it('should call onClick handler when clicked', () => {
-    const onClickSpy = cy.stub().as('onClick');
-    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
-
-    cy.get('button').click();
-    cy.get('@onClick').should('have.been.calledOnce');
-  });
-
-  it('should be disabled when disabled prop is true', () => {
-    cy.mount(<Button label="Disabled" disabled={true} />);
-    cy.get('button').should('be.disabled');
-    cy.get('button').should('have.attr', 'aria-disabled', 'true');
-  });
-
-  it('should show loading spinner when loading', () => {
-    cy.mount(<Button label="Loading" loading={true} />);
-    cy.get('[data-testid="spinner"]').should('be.visible');
-    cy.get('button').should('be.disabled');
-  });
-
-  it('should apply variant styles correctly', () => {
-    cy.mount(<Button label="Primary" variant="primary" />);
-    cy.get('button').should('have.class', 'btn-primary');
-
-    cy.mount(<Button label="Secondary" variant="secondary" />);
-    cy.get('button').should('have.class', 'btn-secondary');
-  });
-});
-
-// Playwright Component Test equivalent
-import { test, expect } from '@playwright/experimental-ct-react';
-import { Button } from './Button';
-
-test.describe('Button Component', () => {
-  test('should call onClick handler when clicked', async ({ mount }) => {
-    let clicked = false;
-    const component = await mount(
-      <Button label="Submit" onClick={() => { clicked = true; }} />
-    );
-
-    await component.getByRole('button').click();
-    expect(clicked).toBe(true);
-  });
-
-  test('should be disabled when loading', async ({ mount }) => {
-    const component = await mount(<Button label="Loading" loading={true} />);
-    await expect(component.getByRole('button')).toBeDisabled();
-    await expect(component.getByTestId('spinner')).toBeVisible();
-  });
-});
-```
-
-**Key Points (Component)**:
-
-- Tests UI component in isolation (no full app)
-- Props + user interactions + visual states
-- Faster than E2E, more realistic than unit tests for UI
-- Great for design system components
-
-### Example 4: Unit Test (Pure Function)
-
-**Scenario**: Test pure business logic function without framework dependencies.
-
-```typescript
-// src/utils/price-calculator.test.ts (Jest/Vitest)
-import { calculateDiscount, applyTaxes, calculateTotal } from './price-calculator';
-
-describe('PriceCalculator', () => {
-  describe('calculateDiscount', () => {
-    it('should apply percentage discount correctly', () => {
-      const result = calculateDiscount(100, { type: 'percentage', value: 20 });
-      expect(result).toBe(80);
-    });
-
-    it('should apply fixed amount discount correctly', () => {
-      const result = calculateDiscount(100, { type: 'fixed', value: 15 });
-      expect(result).toBe(85);
-    });
-
-    it('should not apply discount below zero', () => {
-      const result = calculateDiscount(10, { type: 'fixed', value: 20 });
-      expect(result).toBe(0);
-    });
-
-    it('should handle no discount', () => {
-      const result = calculateDiscount(100, { type: 'none', value: 0 });
-      expect(result).toBe(100);
-    });
-  });
-
-  describe('applyTaxes', () => {
-    it('should calculate tax correctly for US', () => {
-      const result = applyTaxes(100, { country: 'US', rate: 0.08 });
-      expect(result).toBe(108);
-    });
-
-    it('should calculate tax correctly for EU (VAT)', () => {
-      const result = applyTaxes(100, { country: 'DE', rate: 0.19 });
-      expect(result).toBe(119);
-    });
-
-    it('should handle zero tax rate', () => {
-      const result = applyTaxes(100, { country: 'US', rate: 0 });
-      expect(result).toBe(100);
-    });
-  });
-
-  describe('calculateTotal', () => {
-    it('should calculate total with discount and taxes', () => {
-      const items = [
-        { price: 50, quantity: 2 }, // 100
-        { price: 30, quantity: 1 }, // 30
-      ];
-      const discount = { type: 'percentage', value: 10 }; // -13
-      const tax = { country: 'US', rate: 0.08 }; // +9.36
-
-      const result = calculateTotal(items, discount, tax);
-      expect(result).toBeCloseTo(126.36, 2);
-    });
-
-    it('should handle empty items array', () => {
-      const result = calculateTotal([], { type: 'none', value: 0 }, { country: 'US', rate: 0 });
-      expect(result).toBe(0);
-    });
-
-    it('should calculate correctly without discount or tax', () => {
-      const items = [{ price: 25, quantity: 4 }];
-      const result = calculateTotal(items, { type: 'none', value: 0 }, { country: 'US', rate: 0 });
-      expect(result).toBe(100);
-    });
-  });
-});
-```
-
-**Key Points (Unit)**:
-
-- Pure function testing—no framework dependencies
-- Fast execution (milliseconds)
-- Edge case coverage (zero, negative, empty inputs)
-- High cyclomatic complexity handled at unit level
-
-## When to Use Which Level
-
-| Scenario               | Unit          | Integration       | E2E           |
-| ---------------------- | ------------- | ----------------- | ------------- |
-| Pure business logic    | ✅ Primary    | ❌ Overkill       | ❌ Overkill   |
-| Database operations    | ❌ Can't test | ✅ Primary        | ❌ Overkill   |
-| API contracts          | ❌ Can't test | ✅ Primary        | ⚠️ Supplement |
-| User journeys          | ❌ Can't test | ❌ Can't test     | ✅ Primary    |
-| Component props/events | ✅ Partial    | ⚠️ Component test | ❌ Overkill   |
-| Visual regression      | ❌ Can't test | ⚠️ Component test | ✅ Primary    |
-| Error handling (logic) | ✅ Primary    | ⚠️ Integration    | ❌ Overkill   |
-| Error handling (UI)    | ❌ Partial    | ⚠️ Component test | ✅ Primary    |
-
-## Anti-Pattern Examples
-
-**❌ BAD: E2E test for business logic**
-
-```typescript
-// DON'T DO THIS
-test('calculate discount via UI', async ({ page }) => {
-  await page.goto('/calculator');
-  await page.fill('[data-testid="price"]', '100');
-  await page.fill('[data-testid="discount"]', '20');
-  await page.click('[data-testid="calculate"]');
-  await expect(page.getByText('$80')).toBeVisible();
-});
-// Problem: Slow, brittle, tests logic that should be unit tested
-```
-
-**✅ GOOD: Unit test for business logic**
-
-```typescript
-test('calculate discount', () => {
-  expect(calculateDiscount(100, 20)).toBe(80);
-});
-// Fast, reliable, isolated
-```
-
-_Source: Murat Testing Philosophy (test pyramid), existing test-levels-framework.md structure._