test-pyramid-design

Test Pyramid Design

When to Use This Skill

Use this skill when:

• Test Pyramid Design tasks - Working on design optimal test pyramids with unit/integration/e2e ratios. identify anti-patterns and recommend architecture-specific testing strategies
• Planning or design - Need guidance on Test Pyramid Design approaches
• Best practices - Want to follow established patterns and standards

Overview

The Test Pyramid, introduced by Mike Cohn, visualizes the ideal distribution of tests across different levels. More granular tests at the bottom (fast, cheap) and fewer broad tests at the top (slow, expensive).

The Classic Test Pyramid

                    ┌───────┐
                   /  E2E    \         ~10%
                  /   Tests   \        (UI, Acceptance)
                 /─────────────\
                /  Integration  \      ~20%
               /     Tests       \     (API, Component)
              /───────────────────\
             /      Unit Tests     \   ~70%
            /       (Fast, Cheap)   \  (Methods, Classes)
           └─────────────────────────┘

Test Level Characteristics

Level	Speed	Cost	Scope	Confidence	Maintenance
Unit	Fastest (ms)	Lowest	Single unit	Low	Low
Integration	Medium (s)	Medium	Components	Medium	Medium
E2E	Slowest (min)	Highest	Full system	High	High

Common Pyramid Shapes

Healthy Pyramid ✅

     /\          Unit: 70%+
    /  \         Integration: 20%
   /    \        E2E: 10%
  /      \
 /________\      Fast feedback, low maintenance

Characteristics:

• Fast CI/CD pipeline
• Quick feedback loop
• Low flakiness
• Easy maintenance

Ice Cream Cone ❌

   ██████████     E2E: 60%
    ████████      Integration: 30%
      ████        Unit: 10%

Problems:

• Slow pipelines (hours)
• Flaky tests
• Expensive maintenance
• Late feedback

Fix: Extract unit tests, reduce E2E scope

Cupcake ❌

   ██████████     E2E: 40%
   ██████████     Manual: 50%
      ████        Unit: 10%

Problems:

• High manual testing cost
• Inconsistent coverage
• Slow release cycles

Fix: Automate critical paths, add integration layer

Hourglass ❌

      ██          E2E: 10%
   ██████████     Integration: 70%
      ██          Unit: 20%

Problems:

• Slow integration tests
• Brittle test fixtures
• Missing unit test coverage

Fix: Push coverage down to unit level

Architecture-Specific Pyramids

Monolithic Application

     /\          Unit: 70%
    /  \         Integration: 20%
   /    \        E2E: 10%
  /______\

Focus on unit tests for business logic.

Microservices

     /\          E2E/Contract: 10%
    /  \         Integration: 30%
   /    \        Unit: 60%
  /______\

More integration tests for service boundaries. Add contract tests between services.

Event-Driven Architecture

     /\          E2E: 10%
    /  \         Integration: 35%
   /    \        Unit: 55%
  /______\

Integration tests for event handlers. Unit tests for event processing logic.

Frontend-Heavy (SPA)

     /\          E2E: 15%
    /  \         Integration: 25%
   /    \        Unit/Component: 60%
  /______\

Component tests replace some unit tests. Visual regression testing at integration level.

Testing Trophy (Kent C. Dodds)

Alternative for frontend applications:

                 ┌─────┐
                 │ E2E │              ~5%
              ┌──┴─────┴──┐
              │Integration│           ~50%
           ┌──┴───────────┴──┐
           │    Static        │       ~10%
        ┌──┴─────────────────┴──┐
        │        Unit            │    ~35%
        └────────────────────────┘

Designing Your Pyramid

Step 1: Assess Current State

Count tests by level:

Level        | Count | % Total | Time    | Pass Rate
-------------|-------|---------|---------|----------
E2E          | 150   | 45%     | 30 min  | 85%
Integration  | 100   | 30%     | 10 min  | 95%
Unit         | 80    | 25%     | 30 sec  | 99%

Step 2: Identify Anti-Pattern

If You Have...	Shape	Priority Fix
E2E > 30%	Ice Cream Cone	Extract to lower levels
Unit < 50%	Inverted	Add unit tests for logic
Integration > 50%	Hourglass	Push to unit level
Manual > 20%	Cupcake	Automate critical paths

Step 3: Set Target Ratios

Based on architecture:

Architecture	Unit	Integration	E2E
Monolith	70%	20%	10%
Microservices	60%	30%	10%
Serverless	50%	40%	10%
Frontend SPA	40%	45%	15%

Step 4: Migration Plan

Prioritize by ROI:

1. Quick wins: Convert flaky E2E to integration
2. Coverage gaps: Add unit tests for critical logic
3. Contract tests: Add for service boundaries
4. Remove duplicates: Consolidate redundant E2E tests

Test Level Guidelines

Unit Tests

Should test:

• Business logic
• Algorithms
• Data transformations
• Validation rules
• Edge cases

Should NOT test:

• External services
• Database queries
• File system operations
• Third-party libraries

Integration Tests

Should test:

• Database repository operations
• API endpoints
• Message handlers
• External service adapters
• Component interactions

Should NOT test:

• Pure business logic (use unit tests)
• Full user journeys (use E2E)

E2E Tests

Should test:

• Critical user journeys
• Happy paths
• Smoke tests
• Cross-system workflows

Should NOT test:

• Edge cases (use unit tests)
• API contracts (use integration tests)
• Everything (be selective)

.NET Example: Test Project Structure

src/
  MyApp.Domain/           # Business logic
  MyApp.Application/      # Use cases
  MyApp.Infrastructure/   # Data access
  MyApp.Api/              # HTTP endpoints

tests/
  MyApp.Domain.Tests/           # Unit tests (70%)
    Features/
      Orders/
        CreateOrderTests.cs
        OrderValidationTests.cs

  MyApp.Application.Tests/      # Integration tests (20%)
    Features/
      Orders/
        CreateOrderHandlerTests.cs

  MyApp.Api.Tests/              # E2E tests (10%)
    Features/
      Orders/
        OrdersEndpointTests.cs

Test Distribution Verification

// Build script or CI check
public class TestDistributionTests
{
    [Fact]
    public void TestPyramidRatiosAreHealthy()
    {
        var unitTests = CountTestsInAssembly("MyApp.Domain.Tests");
        var integrationTests = CountTestsInAssembly("MyApp.Application.Tests");
        var e2eTests = CountTestsInAssembly("MyApp.Api.Tests");

        var total = unitTests + integrationTests + e2eTests;

        Assert.True(unitTests / total >= 0.60, "Unit tests should be ≥60%");
        Assert.True(e2eTests / total <= 0.15, "E2E tests should be ≤15%");
    }
}

Metrics and Monitoring

Pipeline Health

Metric	Healthy	Warning	Critical
Unit test time	< 1 min	1-5 min	> 5 min
Integration time	< 5 min	5-15 min	> 15 min
E2E test time	< 10 min	10-30 min	> 30 min
Flaky test rate	< 1%	1-5%	> 5%

Coverage Balance

Track coverage by pyramid level:

• Unit coverage of business logic: ≥90%
• Integration coverage of APIs: ≥80%
• E2E coverage of critical paths: 100%

Integration Points

Inputs from:

• Architecture documents → Pyramid shape
• Risk assessment → E2E scope

Outputs to:

• test-strategy-planning skill → Strategy document
• CI/CD configuration → Pipeline stages
• automation-strategy skill → Automation scope