What Is the Test Pyramid: QA Strategy Explained

A payments team depended almost entirely on end-to-end checks and had a green release pipeline. A change to currency rounding still reached production because every browser test used whole-number prices. When engineers added decimal cases, the suite became slower and failures scattered across checkout, receipts, and refunds. The defect was a pure calculation error, but the only available test surface was the entire deployed system.

That is the problem the test pyramid addresses. It is not a command to hit a particular percentage at each level. It is a way to place most behavioral evidence where feedback is fast, failures are specific, and setup is controlled, while keeping a smaller number of broad tests for risks that only appear across real boundaries.

Read the pyramid as an economic model

The classic shape has many small tests near the code, fewer tests across integrations, and a thin layer of end-to-end tests. Width represents relative quantity, but the more useful interpretation is cost. Tests near the base are usually cheaper to run and diagnose. Tests near the top usually require more components, data, infrastructure, and waiting.

A test belongs at the lowest layer that can faithfully expose the risk. “Lowest” does not mean “unit at any cost.” A mocked unit test cannot reveal an incompatible database migration. A direct API test cannot prove that a keyboard user can finish checkout. A browser test is appropriate when the browser is part of the behavior.

The pyramid also describes feedback ownership. A unit failure should guide the developer to a small piece of logic. A contract or integration failure should identify a broken boundary. An end-to-end failure should say which critical journey is unavailable. When every failure arrives as “checkout timed out,” the suite has lost this diagnostic structure.

Do not turn the shape into a compliance chart. A static website, an event-processing platform, and a mobile application have different risk profiles. Preserve the principle of cheaper, narrower evidence supporting a small number of broad confidence checks.

Define layers by boundaries, not tool names

Teams often argue about whether a test is “unit” or “integration” because they classify by library. Instead, state which real boundaries the test crosses.

A test using HTTP is not automatically end-to-end. If it starts one service in process and replaces dependencies, it is a component test. A “unit” test that boots an application, contacts a shared database, and needs credentials is integration work regardless of its filename.

Document the boundary in the test project README and CI job names. This makes failures easier to route. It also prevents a team from claiming a broad base of unit tests that quietly depend on shared infrastructure.

Put rule combinations in unit and component tests

Calculation rules, state transitions, authorization decisions, mapping logic, and validation boundaries usually belong near the base. These tests can cover combinations that would be expensive to construct through a user interface.

For the rounding failure, isolate the policy and make examples explicit:

import { describe, expect, test } from "vitest";
import { calculateTax } from "./tax";

describe("calculateTax", () => {
  test.each([
    { net: 10.01, rate: 0.2, expected: 2.0 },
    { net: 10.03, rate: 0.2, expected: 2.01 },
    { net: 0, rate: 0.2, expected: 0 },
  ])("$net at $rate returns $expected", ({ net, rate, expected }) => {
    expect(calculateTax(net, rate)).toBe(expected);
  });

  test("rejects a negative net amount", () => {
    expect(() => calculateTax(-1, 0.2)).toThrow("Net amount must not be negative");
  });
});

These checks fail close to the policy and run without accounts, browsers, or payment providers. They do not prove the deployed service uses the policy correctly, so add a component test through the service’s public API.

A component test should start the service with controlled dependencies, send a realistic request, and assert the public result. Avoid repeating every unit case. Select representative cases that prove routing, serialization, validation, and the connection to domain logic.

Mocks are useful for rare dependency responses and deterministic errors. They become harmful when they restate an external system’s behavior from memory. Keep mock contracts small, validate them against provider contracts where possible, and use real infrastructure for boundaries whose behavior matters.

Cover real integrations at their seams

Integration tests should focus on facts that cannot be established in memory: SQL constraints, transaction behavior, queue delivery, file encoding, identity claims, network serialization, or cache invalidation.

For a repository-backed order service, test its behavior against the same database engine used by the application. Create isolated data, exercise the repository, and verify persisted state. Running against a simpler substitute can miss engine-specific types, locking, and migration behavior.

Keep setup narrow. A database integration test does not need the entire frontend. Start the minimum application slice, apply migrations, generate a unique tenant or schema, and clean it without relying on test order. If isolation is expensive, use transaction rollback only when production code does not cross transaction boundaries that the test must observe.

Contract tests address a related but distinct risk. A consumer can publish the requests it sends and responses it requires. A provider verifies those expectations against its implementation. This catches interface drift earlier than a shared staging journey, but it does not prove that two deployed services can authenticate, route traffic, or process real data together.

When an integration test fails, retain structured logs, request identifiers, database error details, and the dependency version. A screenshot is rarely useful at this layer.

Keep end-to-end tests selective and meaningful

End-to-end tests earn their cost when they prove a high-value journey through production-like wiring. Suitable candidates include sign-in, placing an order, restoring access, or completing a required approval. The test should exercise a supported entry point and assert a meaningful outcome, not every intermediate implementation detail.

Choose cases using risk:

• business impact if the path fails;
• frequency and importance of the journey;
• amount of wiring not covered below;
• history of cross-component failures;
• need to prove accessibility or browser behavior.

One purchase journey can establish that routing, identity, inventory, payment sandbox, and confirmation work together. It should not carry all coupon, address, currency, and inventory permutations. Put those combinations in lower layers and keep only a few representative end-to-end variants.

Control data through APIs or setup services rather than long UI preconditions. Generate unique identifiers. Wait for observable business states instead of fixed delays. Assert the final persisted or displayed outcome, then clean up safely. If cleanup failure could hide the test result, report it separately.

Retries can distinguish transient environment problems from repeatable failures, but an automatic pass after retry is still evidence of instability. Record both attempts and assign the cause. A release gate that silently converts flakes to green cannot be trusted.

Design one feature across the pyramid

Consider adding account lockout after five failed sign-in attempts. Map risks before writing tests.

At the unit layer, cover the state transition from four failures to locked, reset after a successful sign-in, and time-window boundaries. These are deterministic rule combinations.

At the component layer, call the authentication service through its API. Verify that failed credentials increment the counter, a locked account receives the documented error, and a successful request issues a session only when permitted.

At the integration layer, use the real persistence mechanism to verify atomic increments under concurrent attempts and expiration of the lock record. If events notify a security service, verify the emitted schema and delivery interaction at the queue boundary.

At the end-to-end layer, retain one browser journey: a user reaches the lock threshold, sees a useful message, and cannot enter the protected area. Add an accessibility assertion for focus or announcement if that is part of the interface risk.

This distribution avoids repeating the same assertion four times. Each layer owns a different failure mode. A unit failure points to lockout policy. An integration failure points to persistence or concurrency. A browser failure points to wiring or user experience.

A coverage map can make that intent visible:

feature: account-lockout
risks:
  threshold-policy: unit
  concurrent-attempts: integration
  error-contract: component
  user-message-and-access: end-to-end
owners:
  policy: identity-team
  browser-journey: quality-platform

The file is not a test framework requirement. Its value is the conversation it forces about which evidence exists and who responds.

Adapt the pyramid when architecture changes

Distributed and event-driven systems may need more contract, component, and integration coverage than a monolith. The shape can look like a honeycomb, trophy, or layered portfolio depending on how a team draws it. The label matters less than preserving fast local feedback and explicit boundary checks.

Frontend-heavy products often add component tests that render a screen with controlled network responses. These can verify interactions, state, and accessibility faster than a deployed browser journey. Still retain a few real end-to-end checks because a stubbed component test cannot reveal broken routes, headers, authentication, or asset delivery.

Legacy systems may not have seams for unit tests. Do not pause all coverage until the code is redesigned. Add characterization tests around stable public behavior, create API-level checks, and introduce seams when changing risky areas. The portfolio can move downward over time.

For data pipelines, test transformations with small deterministic datasets, validate schemas at producer and consumer boundaries, run integration checks against the execution engine, and keep a limited set of full pipeline examples. Comparing an entire output file without explaining the changed field creates broad but poor diagnostics.

Put the pyramid into the delivery pipeline

Feedback order should match test cost. Run static checks and focused unit tests during local development and pull requests. Run component and contract suites after the relevant build artifacts exist. Run selected integration tests with isolated infrastructure. Gate deployment with a small, reliable smoke set, then execute broader non-blocking coverage on an appropriate schedule if needed.

Parallelism is not a substitute for test design. A badly isolated suite may finish sooner with more workers while creating more data collisions. First remove shared accounts, order dependencies, fixed ports, and mutable global fixtures.

Tag tests by purpose and boundary, not by arbitrary priority labels. unit, contract, db-integration, and deployment-smoke tell maintainers what environment is required and what a failure means. Keep the default local command fast, and make the full pipeline reproducible without hidden CI-only behavior.

Publish results by layer. A single total pass rate hides whether the product has a code regression, an interface break, or a damaged environment. Retain failure artifacts appropriate to each boundary.

Audit the portfolio using failure evidence

Count alone cannot tell whether the pyramid is healthy. Review what the suite catches, how long feedback takes, and how failures are diagnosed. Useful repository questions include:

• Which end-to-end cases repeat combinations already proved below?
• Which production defects lacked a test at the closest reliable layer?
• Which unit tests assert implementation details and block refactoring?
• Which mocks can drift from real provider behavior?
• Which integration tests share mutable state?
• Which broad tests are quarantined, and what is their exit condition?
• Can a pull request author identify the owning component from a failure?

When a broad test finds a rule defect, add the smallest regression test near that rule, then decide whether the broad test still protects unique wiring. When a production issue involves configuration or routing, a deployment smoke test may be the right regression home.

The pyramid is working when evidence arrives at the layer that best explains the risk. Its goal is not a perfect triangle. Its goal is a portfolio in which fast checks carry the combinations, boundary checks expose integration mistakes, and a disciplined set of journeys confirms that the assembled product works.