
Inside the Pyramid: The Ideal Shape for Drupal’s Test Suite

November 18, 2026
The Ideal Shape
As we touched on in Speed Up Your Testing with Deuteros, the Drupal test suite is not in an ideal shape. If we consider the distribution of tests among the various Drupal test types (UnitTestCase, KernelTestBase, BrowserTestBase, WebDriverTestBase, and BuildTestBase), we quickly realize that, instead of resembling the Test Pyramid, which relies on a wide majority of lightning-fast Unit tests, we are currently stuck with what I call the Test Spinning Birthday Cake:
Source: *Test.php files in core/tests and in core modules, profiles, themes and recipes; abstract classes left out. Nightwatch not included.
Running our test suite ended up being either slow or very expensive: as a matter of fact, a significant slice of the Drupal Association’s budget currently goes into running CI tests on drupal.org.
How Fast?
For anyone wondering how much faster
UnitTestCasetests are, here is how long it took 1,000 iterations of the same test code to complete, according to the Deuteros benchmarks:
UnitTestCase+ PHPUnit mocks: <1sUnitTestCase+ Prophecy API mocks: <0.5sKernelTestBase+ Entity objects: ~12 minutes
Redundant Redundancy
The main reason for this inefficiency is redundancy: many functional or kernel tests end up covering overlapping functionality, so we test the same code paths over and over.
To make matters worse, we are also dealing with inconsistent granularity: next to a functional test covering an entire form, you can find another functional test only checking that one option of a selector in that form behaves correctly: test coverage for a single bug fix next to that of an entire feature.
This is what I would call explicit redundancy.
However, we also have implicit redundancy, which may come in a few flavors:
- Testing at the wrong level, meaning much higher than the code we actually care about. Say we exercise our code path through a functional test, very far from the class we want to test: that implicitly tests every step between Drupal’s bootstrap and our code, that is, the entire stack.
- Enabling modules just to autoload classes. All Drupal tests use a bootstrap script that autoloads the classes of every module, so you can just use them in your test. Enabling a module just to autoload its code exercises the whole module installation pipeline, every time the test runs, for no reason, because that is not what your test is about.
- Needlessly relying on persistence. It is not uncommon to find tests where an entity is saved even though it is only being manipulated as a data object used to pass information around. That alone is a reason people pick kernel tests and, if you do not need persistence, there are much more performant options.
As a consequence, readability suffers as well, since the test’s assertions and expectations are often lost among several lines of setup code or other preliminary steps, as those kinds of tests usually require a more complex test environment.
The bottom line is that, speed and costs aside, DX and maintainability are not exactly ideal either.
How Did We Get Here?
Back when we added automated testing, we introduced a test gate mandating test coverage for any change landing in core. No matter whether you were dealing with a brand-new feature or a tiny bug fix, everything had to get test coverage. However, the guidelines stopped there: there was no clear direction about which kind of test to write each time. So people would either pick the route they were most familiar with or piggyback on an existing test.
That is not bad in itself, but it depends on which tests are available. By now we have a lot of tests inherited from the Drupal 7 days, hence an abundance of functional tests, which are among the slowest to run. And many new tests are functional tests as well, for similar reasons.
Right now, even our AI best practices will not encourage you to write Unit tests. Their claim:
“Unit tests, at least in Drupal, are the least useful kind of tests.”
Harsh, but that is our current reality, and it is going to be reinforced one AI-generated test at a time.
As far as I can tell, one of the main reasons Unit tests are seen as the least useful is that most Drupal code manipulates entities, and entities are very hard to Unit-test because they bring a lot of baggage. The moment you try to instantiate one in a UnitTestCase test, you find yourself setting up test doubles for half of the Entity system.
The Silver Bullet
I believe the Test Pyramid can help us address the Drupal test suite’s performance issues, by letting us implement most of the coverage via Unit tests, and only rely on kernel and functional tests for very narrow and specific use cases: for instance, to ensure subsystems are correctly wired and that critical scenarios are working properly.
Aside from Speed, if we adopt the Test Pyramid we get more:
- Breadth. If your class method has an if branch, you have two cases to test. Two class methods with an
ifeach, four cases, and so on. Test your classes individually and you are testing two cases at a time. Let them combine and the number of code paths explodes: by the time you get to the top, it is impossible to exercise them all. That is where we are now: there is no way to have exhaustive coverage through the current approach, while the Pyramid would give us much finer-grained coverage at the bottom. - Explicitness. Ever tried debugging a functional test? Most of the time you get an error that doesn’t tell you which line to look at. You navigate the codebase, exercise your intuition, maybe spin up a debugger and step through the test at hand, and after a while you may track the issue down to a class. If you were Unit-testing that class, its test would fail and you would know instantly where to look.
Push test coverage down whenever you can and you get all of these advantages, thus improving DX as well. Combine that with clear guidelines on how to shape your module’s test suite and Maintainability improves significantly.
To make a long story short, in my opinion this is the shape we should aspire to, the Test Squeezed Skyscraper:
We should aim for something with a very wide base and much thinner upper layers. How much we can actually squeeze remains to be seen, but that is the ideal goal.
The Trap
Did you notice any resemblance between the Pyramid and the Squeezed Skyscraper? They look very similar, but this similarity hides a trap: in practice there is no direct mapping between the layers of our Skyscraper, that is, Drupal’s test types, and the levels of the Pyramid. Sure, they are correlated, but there is no hard rule enforcing a mapping between them. In fact, you can:
- Unit-test an individual form builder class in
UnitTestCase, even if it is about the UI. - Write a database Integration test based on
UnitTestCase, not a kernel test. - Test a full request/response cycle End-To-End through a kernel test, not a functional test. This is a recent, very exciting addition.
- Unit-test an object through a functional test - joking, that would take us back to Drupal 7.
To sum up, test levels are not the same as test types. Test types are tools at our disposal for providing coverage. Test levels define the scope of a test:
- End-To-End tests exercise your codebase through its entire scope, which for Drupal means a request/response cycle. They should be the bare minimum needed to cover critical scenarios, like the login flow.
- Integration tests exercise subsystems together, often crossing the process boundary: think of database queries, file system access, API requests. You want as many of these tests as needed to ensure your code is wired together properly.
- Unit tests cover individual behaviors of your codebase, typically targeting a single class. If your code is object-oriented and organized properly, you can do a lot with Unit tests alone.
These days the default assumption is that when implementing an Integration test, we need a kernel test, and when testing something at the UI level, we need a functional test. In a way, I have been suggesting this myself. This doesn’t have to be the case.
I think the goal should be to widen the Skyscraper’s base: push down towards it as many tests as we can. If we can do an Integration test using UnitTestCase, great. That doesn’t mean breaking the rules and using a Unit test where an Integration test is called for. It means we can get a fast test while still getting the coverage we were aiming for.
Up Next
In the next post, I’ll cover how to get there and the principles behind the guidelines I’m proposing.
Want a faster, leaner test suite for your Drupal project? Talk to our team.