testing-principles

Language-Agnostic Testing Principles

Test-Driven Development (TDD)

The RED-GREEN-REFACTOR Cycle

Always follow this cycle:

1. RED: Write a failing test first
2. Write the test before implementation
3. Ensure the test fails for the right reason
4. Verify test can actually fail

1. GREEN: Write minimal code to pass
2. Implement just enough to make the test pass
3. Focus on making it work

1. REFACTOR: Improve code structure
2. Clean up implementation
3. Eliminate duplication
4. Improve naming and clarity
5. Keep all tests passing

1. VERIFY: Ensure all tests still pass
2. Run full test suite
3. Check for regressions
4. Validate refactoring didn't break anything

Quality Requirements

Coverage

• Treat coverage as a diagnostic signal for finding untested areas, not a target — a target gets gamed into trivial tests (Goodhart's Law)
• Concentrate tests on critical paths, business logic, and behavior whose regression would matter
• Prioritize meaningful assertions over the coverage number; any CI threshold is the project's config, not a quality goal in itself

Test Characteristics

All tests must be:

• Independent: No dependencies between tests (see Test Independence Verification for detailed criteria)
• Reproducible: Same input always produces same output
• Fast: Unit tests < 100ms each, integration tests < 1s each, full suite < 10 minutes
• Self-checking: Clear pass/fail without manual verification
• Timely: Written close to the code they test

Test Types

Unit Tests

Purpose: Test individual components in isolation

Characteristics:

• Test single function, method, or class
• Fast execution (milliseconds)
• No external dependencies
• Mock external services
• Majority of your test suite

Integration Tests

Purpose: Test interactions between components

Characteristics:

• Test multiple components together
• May include database, file system, or APIs
• Slower than unit tests
• Verify contracts between modules
• Smaller portion of test suite

End-to-End (E2E) Tests

Purpose: Test complete workflows from user perspective

Characteristics:

• Test entire application stack
• Simulate real user interactions
• Slowest test type
• Fewest in number
• Highest confidence level

Test Design Principles

AAA Pattern (Arrange-Act-Assert)

Structure every test in three clear phases:

// Arrange: Setup test data and conditions
user = createTestUser()
validator = createValidator()

// Act: Execute the code under test
result = validator.validate(user)

// Assert: Verify expected outcome
assert(result.isValid == true)

Adaptation: Apply this structure using your language's idioms (methods, functions, procedures)

One Assertion Per Concept

• Test one behavior per test case
• Multiple assertions OK if testing single concept
• Split unrelated assertions into separate tests

Example: prefer returns error when email is invalid over validates user.

Descriptive Test Names

Test names should clearly describe:

• What is being tested
• Under what conditions
• What the expected outcome is

Recommended format: "should [expected behavior] when [condition]"

Examples:

test("should return error when email is invalid")
test("should calculate discount when user is premium")
test("should throw exception when file not found")

Adaptation: Follow your project's naming convention (camelCase, snake_case, describe/it blocks)

Test Independence

Setup and Teardown

• Use setup hooks to prepare test environment
• Use teardown hooks to clean up resources
• Keep setup minimal and focused
• Ensure teardown runs even if test fails

Mocking and Test Doubles

When to Use Mocks

• Mock external dependencies: APIs, databases, file systems
• Mock slow operations: Network calls, heavy computations
• Mock unpredictable behavior: Random values, current time
• Mock unavailable services: Third-party services

Mocking Principles

• Mock at boundaries, not internally
• Keep mocks simple and focused
• Verify mock expectations when relevant
• Wrap external libraries/frameworks behind adapters and mock the adapter

Data Layer Testing

Mock Limitations for Data Layer

Mocks validate call patterns but cannot verify data layer correctness. The following pass through undetected with mock-only testing:

• Schema mismatches (table names, column names, data types)
• Query correctness (joins, filters, aggregations, grouping)
• Database constraints (NOT NULL, UNIQUE, foreign keys)
• Migration drift (schema changes that make code out of sync)

When Mocks Are Appropriate for Data Access

• Testing business logic that receives data from the data layer (mock the repository, test the service)
• Testing error handling paths (simulating connection failures, timeouts)
• Unit tests where data access is a dependency, not the subject under test

When Mocks Are Insufficient for Data Access

• Testing repository or data access implementations themselves
• Verifying query correctness (joins, filters, aggregations, grouping)
• Testing data integrity constraints
• Testing migration compatibility

Real Database Testing (Environment-Dependent)

Options for verifying data layer correctness against a real database engine:

• Containerized databases for CI environments
• In-memory databases for fast feedback (note: dialect differences may mask issues)
• Dedicated test databases with seed data

The appropriate approach depends on project environment and CI/CD capabilities.

AI-Generated Code and Schema Awareness

• AI-generated data access code has heightened schema hallucination risk
• Generated queries may use correct syntax but reference nonexistent schema elements
• Mock-based tests pass regardless of schema accuracy
• Mitigation: Design Docs should include explicit schema references so that documented schemas can be cross-checked against data access code during review

Test Quality Practices

Keep Tests Active

• Fix or delete failing tests: Resolve failures immediately
• Remove commented-out tests: Fix them or delete entirely
• Keep tests running: Broken tests lose value quickly
• Maintain test suite: Refactor tests as needed

Test Helpers and Utilities

• Create reusable test data builders
• Extract common setup into helper functions
• Build test utilities for complex scenarios
• Share helpers across test files appropriately

What to Test

Focus on Behavior

Test observable behavior, not implementation:

✓ Good: Test that function returns expected output ✓ Good: Test that correct API endpoint is called ✗ Bad: Test that internal variable was set ✗ Bad: Test order of private method calls

Test Public APIs

• Test through public interfaces
• Avoid testing private methods directly
• Test return values, outputs, exceptions
• Test side effects (database, files, logs)

Test Edge Cases

Always test:

• Boundary conditions: Min/max values, empty collections
• Error cases: Invalid input, null values, missing data
• Edge cases: Special characters, extreme values
• Happy path: Normal, expected usage

Test Quality Criteria

These criteria ensure reliable, maintainable tests.

Literal Expected Values

• Use hardcoded literal values in assertions
• Calculate expected values independently from the implementation
• If the implementation has a bug, the test catches it through independent verification
• If expected value equals mock return value unchanged, the test verifies nothing (no transformation occurred)

Result-Based Verification

• Verify final results and observable outcomes
• Assert on return values, output data, or system state changes
• For mock verification, check that correct arguments were passed

Meaningful Assertions

• Every test must include at least one assertion
• Assertions must validate observable behav