# The Test Pyramid ## Summary A strategic framework for building comprehensive automated test suites using a layered approach that prioritises fast, isolated tests at the foundation with fewer, broader tests at higher levels. Focuses on organising tests by execution speed and feedback quality rather than traditional categorisation, emphasising unit tests for business logic validation, targeted integration tests for complex external dependencies, feature tests for complete user workflows, and contract tests for service interface agreements. **Core Strategy:** - Foundation of comprehensive unit tests for rapid feedback - Feature tests validating complete user workflows end-to-end - Selective integration tests for complex external boundaries - Contract tests ensuring service interface agreements - Test organisation matching component architecture - Execution patterns optimised for development workflow ## Test Types & Implementation ### Unit Tests (Foundation - Primary Focus) **Purpose:** Validate individual components in isolation with maximum execution speed and comprehensive coverage. **Testing Scope:** - Business logic and algorithmic functions - Component methods and behavioural responses - Data processing and transformation logic - Input validation and error handling scenarios - Edge cases and boundary conditions **Implementation Strategy:** - Single test file per production component - External dependencies replaced with test doubles - Follow "arrange, act, assert" testing pattern - Focus on public interfaces, avoid testing private methods - Skip testing trivial code (simple getters, basic assignments) **Performance Expectation:** Thousands of tests executing in under 60 seconds **Example Structure:** ```text pkg/api/tests/unit/ ├── handlers/ ├── services/ ├── models/ └── utils/ ``` ### Feature Tests (Complete User Workflow Validation) **Purpose:** Verify end-to-end user scenarios work correctly with minimal but comprehensive coverage. **Testing Scope:** - Critical user interaction paths - Complete request/response cycles - Data flow through entire application stack - Authentication and authorisation workflows - User-facing error scenarios and edge cases **Implementation Strategy:** - Test from user perspective, not implementation details - Use realistic test data matching production scenarios - Execute through actual interfaces (HTTP APIs, web interfaces) - Maintain minimal scope - focus on core business value - Use descriptive test names reflecting user goals **Example Structure:** ```text pkg/api/tests/feature/ ├── user_registration_flow_test.go ├── content_processing_workflow_test.go └── api_error_handling_test.go ``` ### Integration Tests (Targeted Boundary Testing) **Purpose:** Validate complex integration points where unit and feature tests cannot provide adequate coverage. **When Integration Tests Add Value:** - Complex database operations with joins, transactions, or stored procedures - External API integration requiring authentication, retry logic, or rate limiting - File system operations with permissions, error handling, or concurrent access - Message queue operations with serialisation, routing, or delivery guarantees - Multi-step data processing pipelines with state management **When Integration Tests Are Unnecessary:** - Simple CRUD operations (adequately covered by unit tests) - Core business logic (belongs in unit test coverage) - Complete user workflows (covered by feature tests) - Basic external API calls (mock in unit tests for speed) **Implementation Strategy:** - Test single integration boundary per test - Use local instances of external dependencies when feasible - Validate data serialisation/deserialisation correctness - Verify error handling and retry mechanisms function properly **Example Structure:** ```text pkg/api/tests/integration/ ├── database_repository_test.go ├── external_payment_api_test.go └── file_upload_handler_test.go ``` ### Contract Tests (Service Interface Agreements) **Purpose:** Ensure API contracts between services remain stable and functional across changes. **When Contract Tests Are Essential:** - Multi-service architectures with team boundaries - External API dependencies with versioning requirements - Team coordination in larger development efforts - API versioning and backward compatibility scenarios **Implementation Strategy:** - Consumer-driven contract testing using tools like Pact - Provider tests validate contract compliance automatically - Consumer tests define explicit expectations - Automated contract sharing and validation between teams **Example Structure:** ```text pkg/api/tests/contract/ ├── user_service_consumer_test.go ├── payment_service_provider_test.go └── contracts/ # Generated contract files ``` ## Project Organisation Patterns ### Single Component Projects For applications with unified codebases: ```text frontend/src/tests/ ├── unit/ # Component logic, utilities, hooks ├── feature/ # Complete user workflows ├── integration/ # External API calls (if needed) ├── contract/ # API contracts (if consuming services) └── mocks/ # Test doubles and fixtures backend/tests/ ├── unit/ # Business logic, handlers ├── feature/ # Complete API workflows ├── integration/ # Database, external services (if needed) ├── contract/ # API contracts └── mocks/ # Test doubles and fixtures ``` ### Multi-Component Projects For complex applications with multiple independent components: ```text backend/pkg/ ├── api/ │ └── tests/ │ ├── unit/ # API handlers, business logic │ ├── integration/ # External services, database repos │ ├── feature/ # Complete API user journeys │ ├── contract/ # API provider/consumer contracts │ └── mocks/ # API-specific test doubles ├── content-pipeline/ │ └── tests/ │ ├── unit/ # Processing, transformations │ ├── integration/ # File systems, queues, database repos │ ├── feature/ # Complete pipeline workflows │ └── mocks/ # Pipeline-specific test doubles ├── database/ │ └── tests/ │ ├── unit/ # Query builders, models, validation │ ├── integration/ # Raw DB operations, migrations │ └── mocks/ # Database-specific test doubles └── shared/ └── tests/ ├── unit/ # Shared utility tests └── mocks/ # Truly shared test doubles ``` **Component Ownership:** - **Database component:** Raw database operations, schema management, migrations - **API/Pipeline components:** Repository patterns, business logic, external integrations - **Shared component:** Common utilities, configuration, cross-cutting concerns ## Test Execution & Pipeline Integration ### Development Workflow **Rapid Feedback (Unit Tests):** ```bash # Single component during development go test ./pkg/api/tests/unit/... # Specific functionality go test ./pkg/api/tests/unit/handlers/... # All unit tests across components go test ./pkg/*/tests/unit/... ``` **Component Validation:** ```bash # Complete component test suite go test ./pkg/api/tests/... # All tests of specific type go test ./pkg/*/tests/integration/... ``` **Full System Validation:** ```bash # Complete test suite go test ./pkg/*/tests/... ``` ### Pipeline Stages **Stage 1: Rapid Feedback (< 2 minutes)** - All unit tests across all components - Static analysis and linting validation - Build verification and compilation **Stage 2: Integration Validation (< 10 minutes)** - Integration tests by component (parallel execution) - Contract test validation and verification - Security scanning and vulnerability detection **Stage 3: System Confidence (< 30 minutes)** - Feature tests by component - Cross-component system tests (when necessary) - Performance regression testing ## Best Practices & Anti-Patterns ### Writing Effective Tests **Test Structure:** - Apply "arrange, act, assert" pattern consistently - Maintain single assertion per test for clarity - Use descriptive test names explaining the scenario - Create test data reflecting realistic usage patterns **Test Double Strategy:** - Mock external dependencies, preserve internal logic - Use test doubles to control test scenarios precisely - Keep test doubles simple and focused on behaviour - Store component-specific test doubles locally for maintainability **Maintainability:** - Apply same code quality standards to test code as production code - Avoid excessive DRY patterns - prioritise clarity over brevity - Remove tests that no longer provide value - Refactor tests when production code evolves ### Anti-Patterns to Avoid **Test Ice Cream Cone:** Excessive slow feature tests with insufficient fast unit tests **Test Duplication:** Identical scenarios tested across multiple pyramid levels **Integration Overuse:** Using integration tests for business logic validation **Mock Misuse:** Mocking internal components instead of external dependencies **Brittle Implementation Coupling:** Tests tied to implementation details rather than behaviour ### When to Add Different Test Types **Add Unit Tests When:** - Implementing any business logic or algorithms - Creating new components, functions, or classes - Refactoring existing code for maintainability - Fixing bugs (test-first approach for regression prevention) **Add Integration Tests When:** - Introducing new external dependencies with complex behaviour - Implementing complex data persistence scenarios - Building multi-step external API workflows - Adding authentication/authorisation integration points **Add Feature Tests When:** - Developing new user-facing features - Implementing critical business workflows - Making major API changes affecting user experience - Modifying system behaviour visible to users **Add Contract Tests When:** - Building multi-service system architectures - Consuming external APIs with evolving interfaces - Managing API versioning scenarios - Coordinating development across multiple teams ## 🔗 Related Resources - [The Practical Test Pyramid by Martin Fowler](https://martinfowler.com/articles/practical-test-pyramid.html) - [Consumer-Driven Contracts by Martin Fowler](https://martinfowler.com/articles/consumerDrivenContracts.html) - [Test-Driven Development practices](https://en.wikipedia.org/wiki/Test-driven_development) - [Microservices testing strategies](https://martinfowler.com/articles/microservice-testing/) - [Pact Contract Testing](https://docs.pact.io/)