Test Patterns

Test Patterns

A technology-agnostic skill for writing test code following established patterns.

Test Structure

Arrange-Act-Assert (AAA)

pattern:
  arrange: "Set up test data and preconditions"
  act: "Execute the code under test"
  assert: "Verify the expected outcome"

rules:
  - "Each test has exactly one Act step"
  - "Assert only what the test name promises"
  - "Arrange should use fixtures or factories, not inline data"

Test Naming

naming_convention:
  pattern: "test<Action><ExpectedBehavior>"
  examples:
    - "testLoginWithValidCredentialsReturnsToken"
    - "testCreateUserWithDuplicateEmailThrowsError"
    - "testCalculateTotalAppliesDiscount"

rules:
  - "Name describes the scenario and expected outcome"
  - "No generic names like testMethod1, testHappyPath"
  - "Read the name alone to understand what is being verified"

Test Isolation

isolation_principles:
  no_shared_state:
    description: "Each test runs independently"
    rules:
      - "No dependency on test execution order"
      - "No shared mutable state between tests"
      - "setUp/tearDown restore clean state"

  no_external_dependencies:
    description: "Tests don't rely on external systems"
    rules:
      - "Mock external APIs and services"
      - "Use in-memory or test databases"
      - "No network calls in unit tests"

  deterministic:
    description: "Same input always produces same result"
    rules:
      - "No reliance on current time (inject clock)"
      - "No random values without seeding"
      - "No filesystem side effects"

Fixture Patterns

fixture_patterns:
  factory:
    description: "Generate test data with defaults and overrides"
    use_when: "Need multiple variations of same entity"
    benefit: "Readable, maintainable test data"

  fixture_files:
    description: "Predefined data loaded before tests"
    use_when: "Database state needed for integration tests"
    benefit: "Consistent starting state"

  builder:
    description: "Fluent API for constructing test objects"
    use_when: "Complex objects with many optional fields"
    benefit: "Only specify what matters for each test"

Assertion Patterns

assertion_rules:
  one_concept_per_test:
    description: "Each test verifies one behavior"
    anti_pattern: "Multiple unrelated assertions in one test"

  specific_assertions:
    description: "Use the most specific assertion available"
    examples:
      - "assertEquals over assertTrue(a == b)"
      - "assertContains over assertTrue(str.includes(x))"
      - "assertThrows over try-catch with fail()"

  meaningful_messages:
    description: "Include context in assertion failures"
    rule: "Failure message should explain what went wrong without reading the code"

Mocking Guidelines

mocking_rules:
  mock_boundaries_only:
    description: "Only mock at system boundaries"
    mock: "External APIs, databases, file systems, time"
    dont_mock: "Internal classes, business logic, value objects"

  verify_interactions:
    description: "When mocking, verify the interaction matters"
    rule: "Mock verification should prove a business requirement"

  prefer_fakes:
    description: "Use fakes over mocks when possible"
    benefit: "Fakes exercise more real code, catch more bugs"

Test Categories

categories:
  unit:
    scope: "Single function or class"
    speed: "Milliseconds"
    isolation: "Full - no external dependencies"
    when: "Every code change"

  integration:
    scope: "Multiple components working together"
    speed: "Seconds"
    isolation: "Partial - may use test database"
    when: "After unit tests pass"

  e2e:
    scope: "Full user workflow"
    speed: "Seconds to minutes"
    isolation: "Minimal - uses real services"
    when: "Pre-merge, pre-release"

Used By Agents

primary_users:
  - test-developer: "Test code implementation"