Speed up your testing with Deuteros

• Kernel tests run much faster, as they only require installing the subsystems needed to run the test code. These are ideal for Integration testing, as they allow you to pick and choose the parts of Drupal available to the test.

• Unit tests, lightning-fast and narrow-scoped, are what should be used to implement the large majority of the test coverage. By default, they do close to nothing in the setup phase, allowing to test individual codebase units in isolation, by providing test doubles of all the objects the test subject interacts with.

So we are good now, right? Well, not exactly. The entity subsystem – which powers users, nodes, media items, and taxonomy terms among others – has historically been problematic when it comes to unit testing, because instantiating an entity object involves instantiating a significant amount of dependencies. In most cases this meant that, to write an entity unit test, a Kernel test with all its baggage was needed. Since entities are very prevalent in any Drupal codebase, this meant that a wide range of test scenarios could not rely on fast unit tests.

Meet Deuteros

This issue has been bugging me for a long time now, so I decided to experiment with an AI-assisted solution since long and tedious tasks is something LLMs are supposed to be good at.

The result is Deuteros – Drupal Entity Unit Test Extensible Replacement Object Scaffolding – a PHP library allowing the use of fast unit tests (extending UnitTestCase, for those in the know) when interacting with entities. And, yes, Claude helped me come up with the name as well.

Deuteros is fully open source and available today. You can explore the project, file issues, or contribute improvements on GitHub. The repository includes examples, docs, and instructions to start using it right away.

This is achieved by:

• Allowing the creation of test doubles implementing various entity and field interfaces. These can be passed around in test code as if they were real entity objects.

use Deuteros\Double\EntityDoubleFactory;
use Deuteros\Double\EntityDoubleDefinitionBuilder;

class MyServiceTest extends TestCase {

  public function testMyService(): void {
    // Get a factory (auto-detects PHPUnit or Prophecy)
    $factory = EntityDoubleFactory::fromTest($this);

    // Create an entity double
    $entity = $factory->create(
      EntityDoubleDefinitionBuilder::create('node')
        ->bundle('article')
        ->id(42)
        ->label('Test Article')
        ->field('field_body', 'Article content here')
        ->build()
    );

    // Use it in your test
    $myService = new MyService();
    $myService->doStuff($entity);
    
    // These assertions would all pass
    $this->assertInstanceOf(EntityInterface::class, $entity);
    $this->assertSame('node', $entity->getEntityTypeId());
    $this->assertSame('article', $entity->bundle());
    $this->assertSame(42, $entity->id());
    $this->assertSame('Article content here', $entity->get('field_body')->value);
  }

}

• Allowing the instantiation of real entity objects while providing test doubles for dependencies such as field items and Entity Field API services. This allows unit testing of custom entity logic such as the one typically added to bundle classes.

class MyNodeTest extends TestCase {

  private SubjectEntityFactory $factory;

  protected function setUp(): void {
    $this->factory = SubjectEntityFactory::fromTest($this);
    $this->factory->installContainer();
  }

  protected function tearDown(): void {
    $this->factory->uninstallContainer();
  }

  public function testNodeCreation(): void {
    $node = $this->factory->create(Node::class, [
      'nid' => 42,
      'type' => 'article',
      'title' => 'Test Article',
      'body' => ['value' => 'Body text', 'format' => 'basic_html'],
      'status' => 1,
    ]);

    // Real Node instance with DEUTEROS field doubles.
    $this->assertInstanceOf(Node::class, $node);
    $this->assertSame('node', $node->getEntityTypeId());
    $this->assertSame('article', $node->bundle());
    $this->assertSame('Test Article', $node->get('title')->value);
    $this->assertSame('Body text', $node->get('body')->value);
  }

}

How AI Enabled a New, Faster Class of Drupal Tests

This sounds all good but does it actually work? Well, the library is already being adopted by some Tag1 client projects and it seems to be working nicely. To get an idea of the speed gains Deuteros allows, we implemented some benchmark tests: a simple test trait performing a few node manipulation operations was used to measure the performance of multiple test types: in my DDEV local environment, 1000 iterations of the test complete in less than 1 second with Unit tests while they take ~12 minutes with Kernel tests – details and replication steps available here. Of course, running tests in parallel could likely reduce the gap by a factor of ten, but I’ll still take the former, thanks.

What’s Next?

Complex projects very often require patches to implement new functionality not yet available in the Drupal codebase, or apply bug fixes before they are eventually released. Applying patches for all intents and purposes means running a fork of the original project, which means there is no guarantee that, even if individual patches don’t break tests, their combined behavior won’t introduce regressions. Ideally, to be fully confident about the codebase quality, one would need to run the entire Drupal core + contrib test suite and confirm that nothing breaks. Currently, even on the drupal.org infrastructure – which is fully optimized for the job – on average you need to wait for ~15 minutes to get test results: adding the test suites of a hundred modules increases that by a lot. Running this on every pull request or commit push does not seem viable at the moment.

Deuteros was written as a standalone PHP library, so that it could easily be adopted without having to make significant changes to the host project. If it were widely adopted both in Drupal core and in contrib-land, running all unit test suites could probably happen in less than one minute, increasing the confidence in our changes by a lot, and possibly reducing our energy footprint as a bonus. Should we try?

Image by Google DeepMind from pexels.