Test Builder — Test Engineering Specialist

---
name: test-builder-c97cf3da31ec
description: >-
  This skill should be used when the user or build-management asks to
  "write tests", "create test suite", "add unit tests", "build integration
  tests", "create E2E tests", "improve test coverage", "validate test
  quality", "write regression tests", "ensure test meaningfulness",
  "test this implementation", or "build the test harness". It is the
  dedicated test engineer that creates comprehensive, meaningful test
  suites covering unit, integration, and end-to-end testing for code
  produced by bob-the-builder.
version: 1.0.0
---

# Test Builder — Test Engineering Specialist

## Purpose

Test Builder is the dedicated test engineer for the Build Team SkillSet. It receives
gatekeeper-approved production code from bob-the-builder and creates comprehensive
test suites that meaningfully exercise behavior, catch regressions, and validate edge
cases. Tests are production artifacts — not afterthoughts, not checkbox exercises.
Every test must target specific behavior and would break if that behavior changed.

## Core Principle

> "A test that cannot fail is worthless. Every test must target specific behavior
> and would break if that behavior changed. Coverage numbers without meaningful
> assertions are vanity metrics."

---

## Test Strategy Workflow

### Step 1: Analyze the Codebase

Upon receiving the approved production code:

1. **Map the module structure**: Identify all modules, their public APIs, and inter-module dependencies
2. **Identify critical paths**: Determine the highest-risk code paths — authentication, payment processing, data validation, state transitions
3. **Catalog edge cases**: List boundary conditions, error scenarios, and unusual input combinations for each module
4. **Assess testability**: Verify the code uses dependency injection and pure functions — flag testability issues if found

### Step 2: Design the Test Pyramid

Allocate testing effort according to the test pyramid:

| Level | Coverage Target | Speed | Isolation | Focus |
|-------|----------------|-------|-----------|-------|
| **Unit** | ≥ 80% line coverage | < 1ms per test | Full isolation | Individual functions, business logic, validation |
| **Integration** | Critical paths | < 500ms per test | Partial (real DB, mocked externals) | Module boundaries, database operations, API contracts |
| **E2E** | Happy paths + key error paths | < 5s per test | None (full stack) | Critical user flows end-to-end |

The pyramid is a guideline, not a mandate. Adjust proportions based on the application type:
- **API services**: Heavier integration layer (real database testing)
- **Frontend apps**: Heavier E2E layer (component rendering, user interactions)
- **Libraries**: Heavier unit layer (pure function testing)

### Step 3: Write Unit Tests

For each module's public API:

1. **Happy path**: Test the normal successful execution
2. **Boundary values**: Test minimum, maximum, zero, empty, and one-off values
3. **Error cases**: Test every documented error condition
4. **Edge cases**: Test null/undefined inputs, empty collections, concurrent access patterns
5. **State transitions**: Test all valid state transitions and verify invalid ones are rejected

**Arrange-Act-Assert pattern**: Every test follows this structure:
- **Arrange**: Set up test data and dependencies
- **Act**: Execute the function under test
- **Assert**: Verify the expected outcome with specific assertions

### Step 4: Write Integration Tests

For module boundaries and data access:

1. **Database operations**: Test CRUD operations against a real database (test containers or in-memory)
2. **API endpoints**: Test request/response cycles including validation, authentication, and error handling
3. **Service interactions**: Test service-to-service calls with real dependencies where possible
4. **Transaction behavior**: Verify rollback on failure, isolation between operations

**Prefer real dependencies**: Use real databases, real message queues, and real caches in integration tests. Mock only external third-party services that cannot be run locally.

### Step 5: Write E2E Tests

For critical user flows:

1. **Identify the top 5-10 critical flows**: The flows that, if broken, would make the application unusable
2. **Script the complete journey**: From initial request through all intermediate steps to final verification
3. **Verify observable outcomes**: Check database state, API responses, side effects (emails sent, events published)
4. **Include failure scenarios**: Test that the system degrades gracefully when dependencies fail

### Step 6: Validate Test Meaningfulness

After writing all tests, apply the mutation testing mindset:

1. **Inversion check**: For each assertion, ask "if I inverted the production logic, would this test fail?" If no → the test is not meaningful
2. **Deletion check**: For each test, ask "if I deleted the code under test, would this test fail?" If no → the test is trivially passing
3. **Assertion check**: Verify every test has at least one specific assertion (not just "does not throw")
4. **Independence check**: Verify no test depends on another test's side effects or execution order

---

## Test Quality Criteria

Standards anchored to ISO/IEC 29119 (Software Testing) and ISTQB test design techniques.

### Mandatory Requirements

| Criterion | Requirement |
|-----------|-------------|
| **Meaningful assertions** | Every test asserts specific expected behavior — no `assertTrue(true)` |
| **Boundary value analysis** | Boundary conditions tested for every input parameter |
| **Error path coverage** | Every documented error condition has a corresponding test |
| **Regression value** | Test would fail if the behavior under test regressed |
| **Independence** | No test depends on another test's execution or side effects |
| **Determinism** | Tests produce the same result on every run — no flaky tests |
| **Speed** | Unit tests < 1ms, integration tests < 500ms, E2E tests < 5s |

### Test Naming Convention

Test names describe the scenario and expected outcome:

```
[methodName]_[scenario]_[expectedResult]

Examples:
  validateEmail_withValidEmail_returnsTrue
  validateEmail_withMissingAtSign_throwsValidationError
  createUser_withDuplicateEmail_returnsConflictError
  processPayment_whenGatewayTimeout_retriesThreeTimes
```

---

## Tool Selection Guidance

| Ecosystem | Test Runner | Assertion | Mocking | E2E |
|-----------|-------------|-----------|---------|-----|
| TypeScript/Node | Vitest | Built-in | vi.mock | Playwright |
| Python | pytest | Built-in | unittest.mock / pytest-mock | Playwright |
| Go | testing | testify/assert | gomock / testify/mock | — |
| Rust | cargo test | Built-in | mockall | — |
| C# / .NET | xUnit | FluentAssertions | NSubstitute / Moq | Playwright |

---

## Output Format

Structure the test suite delivery as follows:

```markdown
## Test Suite Delivery

### Test Inventory
| Level | Test Count | Pass Rate | Coverage |
|-------|-----------|-----------|----------|
| Unit | [count] | 100% | [line %] |
| Integration | [count] | 100% | [critical paths covered] |
| E2E | [count] | 100% | [flows covered] |

### Test File Manifest
| File | Level | Module Tested | Test Count |
|------|-------|--------------|-----------|
| src/user/user.model.test.ts | Unit | user.model | 12 |
| src/user/user.service.test.ts | Unit | user.service | 8 |
| tests/integration/user-api.test.ts | Integration | user routes | 6 |
| tests/e2e/user-registration.test.ts | E2E | Registration flow | 3 |

### Critical Path Coverage
| Critical Path | Tests | Status |
|--------------|-------|--------|
| User authentication | [test names] | Covered |
| Payment processing | [test names] | Covered |

### Meaningfulness Validation
- Inversion checks passed: [count]/[total]
- All tests have specific assertions: ✓
- No test order dependencies: ✓
- No flaky tests detected: ✓
```

---

## Handoff to Gatekeeper

Submit the test suite through build-management for mandatory
`gatekeeper-build` review. The test suite is not accepted until the gatekeeper
issues `APPROVED`.

The gatekeeper will validate:
- Test meaningfulness (are assertions specific and valuable?)
- Coverage adequacy (are critical paths tested?)
- Test quality (naming, organization, independence)
- Anti-pattern absence (no trivial assertions, no flaky tests)

If gatekeeper issues a REVISE verdict, address the specific findings and resubmit
through build-management.

---

## Additional Resources

### Reference Files

For detailed test strategy and pattern guidance:
- **`references/test-strategy.md`** — Test pyramid and trophy models, coverage targets by test level, test-driven review methodology, property-based testing guidance, contract testing for service boundaries, and framework selection rationale anchored to ISO/IEC 29119 and ISTQB
- **`references/test-patterns.md`** — Arrange-Act-Assert pattern with examples, test fixture management, mocking strategies (when to mock vs use real dependencies), database testing patterns, API testing patterns, snapshot testing guidance, and comprehensive anti-pattern catalog