The test pyramid in practice: how two ADRs standardized quality

Tests only protect you when everyone follows the same rules. When I helped standardize testing at the company, the answer was to write that decision down in two ADRs (Architecture Decision Records), one for backend and one for frontend, and to use the test pyramid as the reference for how much to test at each level.

Why standardize

Without a standard, every project picks its own way, and the costs are well known:

• Reviews that debate test format instead of behavior.
• Unpredictable quality: you cannot trust that a new project starts with a safety net.
• Slower onboarding: newcomers must discover each repository's conventions.

In a previous context I saw the other side: several applications with zero test coverage that I brought above 80%. What was missing now was preventing projects from starting without that foundation.

What the ADRs define

Instead of a generic guide, the ADRs are focused and define:

• The three test levels: unit, integration, and end-to-end, all present in new projects.
• The AAA pattern (Arrange, Act, Assert): every test follows the same structure, making reading predictable.
• Jest as the standard tool, in backend and frontend, so configuration and vocabulary are the same.
• Playwright for frontend end-to-end tests: this is a key difference between the two ADRs. Playwright opens the application in a real browser, navigates the pages, clicks elements, and validates features the way a user would, automating end-to-end testing. This is defined exclusively in the frontend ADR.
• Execution on GitHub Actions: how to run unit and integration tests in the pipeline in a standardized way.
• Folder structure: where each type of test lives, so anyone can find what they need in any project.

The test pyramid as a guide to quantity

Where the concept comes from

The test pyramid (the test automation pyramid) was popularized by Mike Cohn in the book Succeeding with Agile (2009). In the original version the layers were Unit, Service, and UI; today they are commonly mapped to unit, integration, and end-to-end (e2e) tests. The core idea has two rules:

1. Write tests at different levels of granularity.
2. The higher the level, the fewer tests you should have.

The reasoning is practical: high-level tests (going through the UI or several services) are slower, more expensive to maintain, and more brittle (flaky), while unit tests give feedback in milliseconds and point to exactly where the problem is. The Google Testing Blog's guidance goes the same way: keep the pyramid shape, with few e2e tests, and let each team tune the exact proportion.

The proportions

A widely cited rule of thumb in the industry is the 70/20/10 split: about 70% unit tests, 20% integration tests, and 10% end-to-end tests. It is not a law: Martin Fowler himself treats the pyramid as a heuristic, noting that if high-level tests are fast, reliable, and cheap to change, the math can change. But as a starting point the proportion is useful, and it is what we adopted as a reference.

The insight came after a few months of watching the suite grow: the pyramid is not theory, it describes reality. We write many unit tests naturally, because they are fast and cheap. As we move up, each test already integrates everything below it, so we need fewer. The quantity shrinks organically.

That is why I brought the pyramid into the ADRs: not as a rigid rule, but as a way of telling people the expected proportion at each level, so nobody has to guess how many tests of each type to write.

"But what is the value of unit tests?"

A colleague asked me exactly that. In their experience, the value was in integration and end-to-end tests, because they had never really worked with unit tests. It is a fair question, and the conversation did more than any document could:

• They are the cheapest tests to write, run, and maintain, whether the code is written by a person or with the help of AI.
• They give the fastest feedback: you find the problem in seconds, while still developing, not after spinning up a whole environment.
• They protect business rules: changing one part of the code can silently break a rule that seemed unrelated. A unit test points exactly to where it happened.
• They sustain code quality over time, because they give you the safety to refactor and evolve.

Over time, and with that shift in mindset, my colleague came to see their value. Integration and e2e tests remain essential, but they rest on the base: the more confidence we have in unit tests, the less we depend on the expensive tests at the top.

What changed in practice

Today, the company's new projects start with unit, integration, and end-to-end tests following this standard:

• More confidence in deliveries, because code is validated against the expected functionality.
• More focused reviews, since test format is no longer up for debate.
• More precise agentic development: with clear conventions and reliable tests, AI agents can follow the pattern and validate what they generate. The same applies to manual changes, which now have a safety net.

Lessons

1. Standardize the decision, not just the tool. Jest and Playwright help, but what aligns the team is the ADR.
2. Use the pyramid to indicate proportion, not just to teach theory.
3. Folder structure and pipeline are part of quality, not a detail.
4. Good tests serve people and agents. Explicit conventions reduce mistakes on both sides.

Frequently asked questions

What is the ideal test pyramid proportion?

A widely cited rule of thumb is 70% unit tests, 20% integration tests, and 10% end-to-end tests. It is not a law: use it as a starting point and keep the pyramid shape, with fewer tests at each level up.

Why are unit tests the base of the pyramid?

Because they are the cheapest to write, run, and maintain, give the fastest feedback, and protect business rules whenever code changes, whether the change comes from a person or an AI.

Which tools do the testing ADRs define?

Jest as the standard tool in backend and frontend, the AAA pattern (Arrange, Act, Assert), unit and integration tests running on GitHub Actions, and Playwright for frontend end-to-end tests.

Why use an ADR to standardize testing?

Because an ADR records the decision, its context, and its consequences in the repository itself. That reduces repeated debates and gives a clear starting point to evolve the standard.

References

• TestPyramid, Martin Fowler
• The Practical Test Pyramid, martinfowler.com
• Just Say No to More End-to-End Tests, Google Testing Blog