Testing Code

Core Workflow

Test writing follows a systematic approach: determine scope, understand patterns, map to requirements, write tests, verify coverage.

1. Determine Test Scope

Read project documentation:

•docs/user-stories/US-###-*.md for acceptance criteria to test
•docs/feature-spec/F-##-*.md for technical requirements
•docs/api-contracts.yaml for API specifications
•Existing test files to understand patterns

Choose test types needed:

•Unit tests: Individual functions, pure logic, utilities
•Integration tests: Multiple components working together, API endpoints
•Component tests: UI components, user interactions
•E2E tests: Complete user flows, critical paths
•Contract tests: API request/response validation
•Performance tests: Load, stress, benchmark testing

2. Understand Existing Patterns

Investigate current test approach:

•Test framework (Jest, Vitest, Pytest, etc.)
•Mocking patterns and utilities
•Test data fixtures and setup/teardown
•Assertion styles

Use code-finder agents if unfamiliar with test structure.

3. Map Tests to Requirements

Convert 3-5 acceptance criteria to specific test cases across test types:

Example mapping:

markdown

## User Story: US-101 User Login

### Test Cases
1. **Unit: Authentication service**
   - validateCredentials() returns true for valid email/password
   - validateCredentials() returns false for invalid password
   - checkAccountStatus() detects locked accounts

2. **Integration: Login endpoint**
   - POST /api/login with valid creds returns 200 + token
   - POST /api/login with invalid creds returns 401 + error
   - POST /api/login with locked account returns 403

3. **Component: Login form**
   - Submitting form calls login API
   - Error message displays on 401 response
   - Success redirects to /dashboard

4. **E2E: Complete login flow**
   - User enters credentials → submits → sees dashboard
   - User enters wrong password → sees error → retries successfully

4. Write Tests

Unit Test Structure:

javascript

describe('AuthService', () => {
  describe('validateCredentials', () => {
    it('returns true for valid email and password', async () => {
      const result = await authService.validateCredentials(
        'user@example.com',
        'ValidPass123'
      );
      expect(result).toBe(true);
    });

    it('returns false for invalid password', async () => {
      const result = await authService.validateCredentials(
        'user@example.com',
        'WrongPassword'
      );
      expect(result).toBe(false);
    });
  });
});

Integration Test Structure:

javascript

describe('POST /api/auth/login', () => {
  beforeEach(async () => {
    await resetTestDatabase();
    await createTestUser({
      email: 'test@example.com',
      password: 'Test123!'
    });
  });

  it('returns 200 and token for valid credentials', async () => {
    const response = await request(app)
      .post('/api/auth/login')
      .send({ email: 'test@example.com', password: 'Test123!' });

    expect(response.status).toBe(200);
    expect(response.body).toHaveProperty('token');
    expect(response.body.token).toMatch(/^eyJ/); // JWT format
  });

  it('returns 401 for invalid password', async () => {
    const response = await request(app)
      .post('/api/auth/login')
      .send({ email: 'test@example.com', password: 'WrongPassword' });

    expect(response.status).toBe(401);
    expect(response.body.error).toBe('Invalid credentials');
  });
});

Component Test Structure:

javascript

describe('LoginForm', () => {
  it('submits form with valid data', async () => {
    const mockLogin = jest.fn().mockResolvedValue({ success: true });
    render(<LoginForm onLogin={mockLogin} />);

    await userEvent.type(screen.getByLabelText(/email/i), 'user@example.com');
    await userEvent.type(screen.getByLabelText(/password/i), 'Password123');
    await userEvent.click(screen.getByRole('button', { name: /log in/i }));

    expect(mockLogin).toHaveBeenCalledWith({
      email: 'user@example.com',
      password: 'Password123'
    });
  });

  it('displays error message on API failure', async () => {
    const mockLogin = jest.fn().mockRejectedValue(new Error('Invalid credentials'));
    render(<LoginForm onLogin={mockLogin} />);

    await userEvent.type(screen.getByLabelText(/email/i), 'user@example.com');
    await userEvent.type(screen.getByLabelText(/password/i), 'wrong');
    await userEvent.click(screen.getByRole('button', { name: /log in/i }));

    expect(await screen.findByText(/invalid credentials/i)).toBeInTheDocument();
  });
});

E2E Test Structure:

javascript

test('user can log in successfully', async ({ page }) => {
  await page.goto('/login');

  await page.fill('[name="email"]', 'test@example.com');
  await page.fill('[name="password"]', 'Test123!');
  await page.click('button:has-text("Log In")');

  await page.waitForURL('/dashboard');
  expect(page.url()).toContain('/dashboard');
});

5. Edge Cases & Error Scenarios

Include boundary conditions and error paths:

javascript

describe('Edge cases', () => {
  it('handles empty email gracefully', async () => {
    await expect(
      authService.validateCredentials('', 'password')
    ).rejects.toThrow('Email is required');
  });

  it('handles extremely long password', async () => {
    const longPassword = 'a'.repeat(10000);
    await expect(
      authService.validateCredentials('user@example.com', longPassword)
    ).rejects.toThrow('Password too long');
  });

  it('handles network timeout', async () => {
    jest.spyOn(global, 'fetch').mockImplementation(
      () => new Promise((resolve) => setTimeout(resolve, 10000))
    );

    await expect(
      authService.login('user@example.com', 'pass')
    ).rejects.toThrow('Request timeout');
  });
});

Edge cases to always include:

•Empty/null inputs
•Minimum/maximum values
•Invalid formats
•Network failures
•API errors (4xx, 5xx)
•Timeout conditions
•Concurrent operations

6. Test Data & Fixtures

Create reusable test fixtures:

javascript

// tests/fixtures/users.ts
export const validUser = {
  email: 'test@example.com',
  password: 'Test123!',
  name: 'Test User'
};

export const invalidUsers = {
  noEmail: { password: 'Test123!' },
  noPassword: { email: 'test@example.com' },
  invalidEmail: { email: 'not-an-email', password: 'Test123!' },
  weakPassword: { email: 'test@example.com', password: '123' }
};

// Use in tests
import { validUser, invalidUsers } from './fixtures/users';

it('validates user data', () => {
  expect(validate(validUser)).toBe(true);
  expect(validate(invalidUsers.noEmail)).toBe(false);
});

7. Parallel Test Implementation

When tests are independent (different modules, different test types), spawn parallel agents:

Pattern 1: Layer-based

•Agent 1: Unit tests for services/utilities
•Agent 2: Integration tests for API endpoints
•Agent 3: Component tests for UI
•Agent 4: E2E tests for critical flows

Pattern 2: Feature-based

•Agent 1: All tests for Feature A
•Agent 2: All tests for Feature B
•Agent 3: All tests for Feature C

Pattern 3: Type-based

•Agent 1: All unit tests
•Agent 2: All integration tests
•Agent 3: All E2E tests

8. Run & Verify Tests

Execute test suite:

bash

# Unit tests
npm test -- --coverage

# Integration tests
npm run test:integration

# E2E tests
npm run test:e2e

# All tests
npm run test:all

Verify coverage:

•Aim for >80% code coverage
•100% coverage of critical paths
•All acceptance criteria have tests
•All error scenarios tested

Quality Checklist

Coverage:

• All acceptance criteria from user stories tested
• Happy path covered
• Edge cases included
• Error scenarios tested
• Boundary conditions validated

Structure:

• Tests follow existing patterns
• Clear test descriptions
• Proper setup/teardown
• No flaky tests (consistent results)
• Tests are isolated (no interdependencies)

Data:

• Test fixtures reusable
• Database properly seeded/reset
• Mocks used appropriately
• No hardcoded test data in production

Integration:

• Tests run in CI/CD
• Coverage thresholds enforced
• Fast feedback (quick tests)
• Clear failure messages