This is an excerpt from my book: Drupal 8 module development - second edition. Do check out the rest of the book/chapter to see how you can write automated tests in Drupal 8.

Automated testing is a process by which we rely on special software to continuously run pre-defined tests that verify the integrity of our application. To this end, automated tests are a collection of steps that cover the functionality of an application and compare triggered outcomes to expected ones.

Manual testing is a great way to ensure that a piece of written functionality works as expected. The main problem encountered by most adopters of this strategy, especially those who use it exclusively, is regression. Once a piece of functionality is tested, the only way they can guarantee regressions (or bugs) were not introduced by another piece of functionality is by retesting it. And as the application grows, this becomes impossible to handle. This is where automated tests come in.

Automated testing uses special software that has an API that allows us to automate the steps involved in testing the functionality. This means that we can rely on machines to run these tests as many times as we want, and the only thing stopping us from having a fully-working application is the lack of proper test coverage with well-defined tests.

There's a lot of different software available for performing such tests and it's usually geared toward specific types of testing. For example, Behat is a powerful PHP-based open source behavior testing framework that allows the scripting of tests that mirror quite closely what a manual tester would do—interact with the application through the browser and test its behavior. There are other testing frameworks that go much lower in the level of their testing target. For example, the PHP industry standard tool, PHPUnit, is widely used for performing unit tests. This type of testing focuses on the actual code at the lowest possible level; it tests that class methods work properly by verifying their output after providing them with different input. A strong argument in favor of this kind of testing is that it encourages better code architecture, which can be (partly) measured by the ease with which unit testing can be written for it.

We also have functional or integration tests which fall somewhere in between the two examples. These go higher than code level and enlist application subsystems in order to test more comprehensive sets of functionality, without necessarily considering browser behavior and user interaction.

It is not difficult to agree that a well-tested application features a combination of the different testing methodologies. For example, testing the individual architectural units of an application does not guarantee that the entire subsystem works, just as testing only the subsystem does not guarantee that its individual components will work properly under all circumstances. Also, the same is true for certain subsystems that depend on user interaction—these require test coverage as well.

Testing methodologies in Drupal 8

Like many other development aspects, automated testing has been greatly improved in Drupal 8. In the previous version, the testing framework was a custom one built specifically for testing Drupal applications—Simpletest. Its main testing capability focused on functional testing with a strong emphasis on user interaction with a pseudo-browser. However, it was quite strong and allowed a wide range of functionality to be tested.

Drupal 8 development started with Simpletest as well. However, with the adoption of PHPUnit, Drupal is moving away from it and is in the process of deprecating it. To replace it, there is a host of different types of tests—all run by PHPUnit—that can cover more testing methodologies. So let's see what these are.

Drupal 8 comes with the following types of testing:

• Simpletest: exists for legacy reasons but no longer used to create new tests. This will be removed in Drupal 9.
• Unit: low-level class testing with minimal dependencies (usually mocked).
• Kernel: functional testing with the kernel bootstrapped, access to the database and only a few loaded modules.
• Functional: functional testing with a bootstrapped Drupal instance, a few installed modules and using a Mink-based browser emulator (Goutte driver).
• FunctionalJavaScript: functional testing like the previous, using the Selenium driver for Mink that allows for testing JavaScript powered functionality.

Apart from Simpletest, all of these test suites are built on top of PHPUnit and are, consequently, run by it. Based on the namespace the test classes reside in, as well as the directory placement, Drupal can discover these tests and know what type they are.

PHPUnit

Drupal 8 uses PHPUnit as the testing framework for all types of tests. In this section, we will see how we can work with it to run tests.

On your development environment (or wherever you want to run the tests), make sure you have the composer dependencies installed with the --dev flag. This will include PHPUnit. Keep in mind not to ever do this on your production environment as you can compromise the security of your application.

Although Drupal has a UI for running tests, PHPUnit is not well integrated with this. So, it's recommended that we run them using the command line instead. Actually, it's very easy to do so. To run the entire test suite (of a certain type), we have to navigate to the Drupal core folder:

cd core

And run the following command:

../vendor/bin/phpunit --testsuite=unit

This command goes back a folder through the vendor directory and uses the installed phpunit executable (make sure the command finds its way to the vendor folder in your installation). As an option, in the previous example, we specified that we only want to run unit tests. Omitting that would run all types of tests. However, for most of the others, there will be some configuration needed, as we will see in the respective sections.

If we want to run a specific test, we can pass it as an argument to the phpunit command (the path to the file):

../vendor/bin/phpunit tests/Drupal/Tests/Core/Routing/UrlGeneratorTest.php

In this example, we run a Drupal core test that tests the UrlGenerator class.

Alternatively, we can run multiple tests that belong to the same group (we will see how tests are added to a group soon):

../vendor/bin/phpunit --group=Routing

This runs all the tests from the Routing group which actually contains the UrlGeneratorTest we saw earlier. We can run tests from multiple groups if we separate them by a comma.

Also, to check what the available groups are, we can run the following command:

../vendor/bin/phpunit --list-groups

This will list all the groups that have been registered with PHPUnit.

Finally, we can also run a specific method found inside a test by using the --filter argument:

../vendor/bin/phpunit --filter=testAliasGenerationUsingInterfaceConstants

This is one of the test methods from the same UrlGeneratorTest we saw before and is the only one that would run.

Registering tests

There are certain commonalities between the various test suite types regarding what we need to do in order for Drupal (and PHPUnit) to be able to discover and run them.

First, we have the directory placement where the test classes should go in. The pattern is this: tests/src/suite_type, where suite_type is a name of the test suite type this test should be. And it can be one of the following:

• Unit
• Kernel
• Functional
• FunctionalJavascript

So, for example, unit tests would go inside the tests/src/Unit folder of our module. Second, the test classes need to respect a namespace structure as well:

namespace Drupal\Tests\[module_name]\[suite_type]

This is also pretty straightforward to understand.

Third, there is a certain metadata that we need to have in the test class PHPDoc. Every class must have a summary line describing what the test class is for. Only classes that use the @coversDefaultClass attribute can omit the summary line. Moreover, all test classes must have the @group PHPDoc annotation indicating the group they are part of. This is how PHPUnit can run tests that belong to certain groups only.

So now that we know how to register and run tests, let's order the book and start by looking at unit tests first.