Test-Driven Drupal

If you don’t have one, you’ll need a new Drupal project to work on.

You’ll need PHP and Composer. For Drupal 11, you’ll need PHP 8.3.0 or newer.

First, run composer create-project drupal/recommended-project atdc-project followed by cd atdc-project && composer require --dev drupal/core-dev to add the development dependencies, including PHPUnit.

At this point, you should have a web directory and a phpunit file within vendor/bin.

Finally, run php -S localhost:8000 -t web to start a local web server.

You don’t need to install Drupal - as long as you see the installation page, that’s fine.

Before adding tests, you must create a module to place them in.

Run mkdir -p web/modules/custom/atdc to create an empty module directory and create an atdc.info.yml file within it with this content:

To make your module compatible with Drupal 10, add ^10 instead of ^11.

This is the minimum content needed for a module to be installable.

On the command line, run vendor/bin/phpunit web/modules/custom, and you’ll get an error like:

This isn’t an assertion failure, but PHPUnit needs help finding the files it needs to run.

To fix this, let’s configure PHPUnit.

Create a new phpunit.xml.dist file at the root of your project with this content:

This is based on web/core/phpunit.xml.dist with project-specific changes.

Namely, setting the bootstrap value to include the web/core path, fixing the error, and populating the SIMPLETEST_BASE_URL and SIMPLETEST_DB environment variables.

PHPUnit now knows where the files are, to connect to Drupal at http://localhost:8000 (matching the PHP web server address) and an SQLite database.

I’ve also added a testsuite that declares where any test classes will be located so the path doesn’t need to be specified on the command line.

Re-running the tests will give the expected error about a failing assertion:

Fix the assertion in the test by changing FALSE to TRUE, run vendor/bin/phpunit again, and you should see a passing test.

Now you have as passing test and know PHPUnit is working, let’s improve it.

Instead of the basic check, let’s check whether certain pages exist and are accessible.

To keep things simple and focused on writing and running tests, let’s use some standard Drupal pages - the front and administration pages instead of writing your own.

As you’re writing functional tests by extending BrowserTestBase, you can make HTTP requests to the web server and make assertions on the responses.

Replace the testBasic test method with the following:

These tests will make HTTP requests to the specified paths and assert the status code on the response matches the expected values.

I’m using the constants on the Response class, but you can also use the status code numbers - e.g. 200 and 403.

Running vendor/bin/phpunit, you should get two errors:

The responses are not returning the expected status codes, so the tests are failing.

Reviewing them, the front page should return a 200 response code (HTTP_OK) as it’s accessible to all users, including anonymous users.

As you’re logged out, the administration page should return a 403 (HTTP_FORBIDDEN).

Swapping the assertions should get the tests to pass.

Now, running vendor/bin/phpunit returns no errors or failures.

Congratulations!

In this chapter, you created a new Drupal 10 project, configured PHPUnit and created a custom module with your first passing browser tests.

From this, you can hopefully see that automated testing doesn’t need to be difficult, and the configuration you’ve done here will work for the upcoming chapters, where you’ll expand on what you’ve done and explore more that Drupal and PHPUnit have to offer.

In the current tests, we’re testing the responses as an anonymous user.

So, how do we test as an authenticated user?

For example, how do we test the administration pages to see if they work for a user who’s logged in?

Let’s start with a new test:

This is the same test as before, only with a different expected status code. This time, we want a 200 status code, but as we’re still anonymous, this test will fail.

The same as users, we need to create any content we need in each test.

Let’s create a page and test we can view it.

Firstly, let’s ensure the page is not found:

Similar to $this→createUser(), there are similar methods to create content types and nodes.

Again, as there are no existing content or content types, we need to create them and add the follow-up assertions:

Here’s a tip for today: if you’re getting an unexpected status code or another error that you want to debug, you’ll need to output the page content to see the error.

To do that, add this to your test, and it will output the page content:

In this chapter, you expanded your test suite to test as an authenticated user, and that content exists by creating a content type and node.

Next, we’ll start building a new module from scratch.

First, let’s create a page that will list the posts. This will be similar to our first tests for Drupal’s front and admin pages.

Create a new BlogPageTest and have it extend BrowserTestBase.

Let’s assert that a page should exist at /blog by returning a 200 status code, as this should be accessible by anonymous users.

As you haven’t created it, the status code should be a 404 - causing the test to fail.

Whilst you could create the page using the Views module, let’s create a custom route.

Create an atdc.routing.yml file:

With this added, the status code doesn’t change and is a 404.

Like in the previous chapter, you need to enable the atdc module by setting $modules in your test:

You’ll also need to create an atdc.info.yml file so the module can be installed:

This should change the status code to a 403, as you also need the node module for the access content permission:

This should cause the status code to change again - this time to a 500.

This is progress.

The atdc module is being installed and enabled, and its routing file is being loaded. But, it references a Controller class that doesn’t exist yet.

Let’s do that next.

Create the expected Controller class within a src/Controller directory:

Note the namespace is different from the one within the test classes and we don’t need to extend any other classes.

For this step, the simplest thing you can do to get a passing test is to return an empty render array.

As long as it’s an array, even an empty one, the test should pass:

As a rule, you want the tests to pass as often and quickly as possible by doing the simplest thing to achieve it - even returning a hard-coded value or an empty array.

Now the test passes, you can add to it and drive out the next piece of functionality.

This is also a good time to do a git commit.

Again, let’s start with a new test:

As we’re returning an empty array within BlogPageController, the page will have no content and this test will fail with a message like:

Start by extending the ControllerBase base class within your Controller:

Now, within the __invoke method, add this to return a list of each node title:

As the node titles are within the page content, the test should pass.

To be confident, try returning an empty array again or removing the foreach loop, seeing the test fail, and reverting the change.

Confidence comes from tests that pass and fail when expected, so you’re sure the correct behaviour is being tested, and the tests aren’t passing accidentally.

You can add further tests, such as checking that only nodes of a specified node type are returned. Currently, all nodes would be listed, even if they aren’t posts.

We have a list of post titles on a page and a test to prove it, but what if we want to ensure the posts are shown in a specified order?

That’s harder to do with a functional test, so in the next chapter, we’ll refactor the code and look at Kernel tests.

I like the Repository design pattern.

It’s much better to have all logic to find and load nodes in one place instead of duplicating them across an application.

It also makes it easier to test.

To start, within your atdc module, create an src/Repository directory and a PostNodeRepository.php file inside it.

This will contain the PostNodeRepository class that will be responsible for loading the post nodes from the database instead of within BlogPageController.

Add this as the initial content:

I like to make my classes final, but this is optional and, by adding this docblock, we can specify the findAll() method should return an array of NodeInterface objects - making the code easier to read and providing better completion.

So far, you haven’t changed BlogPageController, so the tests should still pass.

Next, let’s move the logic for loading nodes into the Repository.

Remove these lines from BlogPageController:

Add them to the findAll() method, alter the first line that gets the EntityTypeManager (we’ll refactor this later) and return the loaded nodes:

Within the BlogPageController, create a constructor method and inject the Repository using constructor property promotion:

Add use Drupal\atdc\Repository\PostNodeRepository; if needed, and use it to load the post nodes:

We’re almost back to a passing test, but there’s more to do.

Currently, the test is failing, as the response code is a 500 status because the PostNodeRepository isn’t being injected into the Controller.

It’s expected within the constructor, but you must add a create method to inject it.

You may also need to add use Symfony\Component\DependencyInjection\ContainerInterface; at the top of the file for the correct ContainerInterface to be used.

$container→get() uses a service’s ID to retrieve it from the container, but PostNodeRepository isn’t in the service container.

To do this, create an atdc.services.yml file within your module.

Add PostNodeRepository using the fully-qualified class name as the service name:

For now, include no arguments.

This should be enough to get the tests passing and back to green.

Before moving on, let’s refactor the PostNodeRepository and inject the EntityTypeManager as a dependency.

The same as the BlogPageController, create a constructor method and inject the EntityTypeManagerInterface:

Add the use Drupal\Core\Entity\EntityTypeManagerInterface; if needed, and specify it as an argument so it’s injected into the constructor:

Finally, update the code in the findAll() method:

If this refactor is successful, the test will still pass.

Whilst we haven’t added any new tests in this lesson, we’ve been able to use the existing tests to ensure that the functionality still works.

If you make a mistake, the tests will fail, and you can revert the changes and try again.

If they pass, the functionality still works as expected.

Now that the PostNodeRepository is in place, it’ll be easier for us to test the order in which the posts are returned tomorrow.

So far, we’ve been using Functional (or Browser) tests to ensure the blog page exists and that the correct posts are displayed.

It’s easy to assert the correct posts are shown on the page, but it’s much harder to assert they’re shown in the right order.

This is much easier to do with a Kernel test (aka. an integration test).

Instead of making HTTP requests and checking the responses, we can test the results from the repository and ensure it returns the results in the correct order.

Let’s create a new test that uses the PostNodeRepository to find the nodes and assert we get an expected number returned.

As with the Functional test, the file and class name must have a Test suffix, and test methods should have a test prefix. As we’re testing the PostNodeRepository class, the convention is to name the test PostNodeRepositoryTest.

As this is a Kernel test, it should be placed within the tests/src/Kernel directory and extend the EntityKernelTestBase class.

We could extend others, such as the regular KernelTestBase, but as we’ll be working with nodes, EntityKernelTestBase is the better option.

Instead of making assertions based on the HTTP response, we’re testing what’s returned from the findAll() method.

Currently, the 'Arrange' step within the test is empty, and whilst we’re asserting there should be three posts returned, none are.

We need to create some posts within the test.

To access the createNode() method we’ve used in previous lessons within a Kernel test, you must use the NodeCreationTrait.

Add use NodeCreationTrait within the test class and use Drupal\Tests\node\Traits\NodeCreationTrait; as an import if needed.

Within the test, you can use $this→createNode() to create posts.

Create the three posts the test is expecting:

This should be enough for the test to pass.

Next, let’s assert they’re returned in a specific order.

Update the posts to have a specific title and created date so we can specify which order we expect them to be returned in and which titles they should have:

Note we’re intentionally setting them to be in an incorrect order, to begin with, so the test doesn’t pass accidentally. This way, we can see it fail and know the task is complete once it passes.

Next, assert that the titles are returned in the correct order.

For each node in $nodes, get its label (title) and compare them with the titles in the order we want.

As expected, the test fails:

We want Post two to be returned first, followed by Post one and Post three.

We need to update the code within PostNodeRepository to fix the ordering.

After loading the nodes, we need to sort them.

This sorts the nodes based on their created time in the desired order and returns them.

This gets us further, but the test is still failing.

Whilst the order is correct, the array keys don’t match what we expect:

Finally, replace return $nodes; with return array_values($nodes) to reset the keys before returning them.

This should give us a passing test:

And, because the correct titles are still being shown, our original Functional tests still pass, too:

Tip: to see the names of the tests in your output, add the --testdox flag to the phpunit command:

In today’s lesson, you learned about Kernel tests and wrote one to test the ordering of the posts returned from the PostNodeRepository.

Tomorrow, we’ll refactor PostNodeRepositoryTest to use a Builder class and a custom assertion method.

This is how I’d like to create a post using a PostBuilder:

This makes it easier to do by creating named methods for each value we want to set and not relying on array keys whilst also moving implementation details like using DrupalDateTime to set the created date.

To do this, create a new class at src/Builder/PostBuilder.php:

It should be within the Drupal\atdc\Builder namespace and has a static create method that works as a named constructor and makes PostBuilder::create() work.

As it returns a new version of self, you can also chain methods onto it.

Add the additional methods and properties:

Again, by returning $this, we can keep chaining methods.

Finally, create the getPost() method that creates the node based on the property values, saves it, and returns it.

Now, refactor the test to use the PostBuilder:

Doing this simplifies the test and makes it easier to extend in the future by adding more methods to PostBuilder.

Finally, for today, let’s refactor the assertion that verifies the titles are returned in the correct order.

This is the current assertion:

We create an array of expected titles and compare that to an array created from array_map.

We can make this more reusable and readable by extracting this into a new custom assertion, which is just another static method.

Create a new static function at the bottom of the class with a name that describes what it’s asserting:

We can add arguments for the arrays of titles and nodes, and be explicit about what they contain by adding a docblock.

In this method, we can do the same logic and use array_map to create a list of node titles and compare them to the expected titles.

The benefits are that this now has a name that describes what we’re asserting, and because it’s a separate method, it can be reused in the same test or moved to a base class and used elsewhere.

Finally, refactor the test to use the new assertion:

In my opinion, this is a lot better.

In tomorrow’s lesson, let’s add some more tests to the PostNodeRepository that we skipped in previous lessons.

First, let’s ensure that only published nodes are returned and displayed on the page.

We can do this easily with a functional test, so add a new test method to BlogPostTest:

Import the PostBuilder by adding use Drupal\atdc\Builder\PostBuilder; if needed, and run the test to see the first error:

In this test, we want to create some published and unpublished posts and assert only the published ones are shown, but we don’t have this functionality on the PostBuilder.

To fix the error, add this function so it exists:

We’ll revisit this later once we have a failing test that requires further changes.

Running the tests again, you should get this unexpected error:

When using PostBuilder in the previous lesson, we were always providing a created date, but, as we’re not doing that in this test, the created date is NULL, causing this error.

Update the getPost() method to only set the created time if the created property has a value.

Now, we can see a similar error to the one before for isNotPublished().

Again, create the simplest version of the method so the test can progress:

Now, you should get the error you were likely expecting:

As we’ve set post two to be unpublished, we don’t want it to be displayed.

However, we have no logic for that.

Within PostBuilder, we need to use the isPublished and isNotPublished methods to set the status of the node that’s building built.

First, add an isPublished property to the class and set it to be TRUE by default:

Next, update the isPublished() and isNotPublished() methods to set the value appropriately:

Even though isPublished is already true by default, doing this makes it explicit and makes what’s being tested clearer.

Finally, within getPost(), update the code that creates the node to set the status property accordingly.

With these changes, the nodes have the correct status, but the test is still failing.

We also need to update the PostNodeRepository as that is responsible for loading and returning the relevant nodes from the database.

Currently, all we’re doing is this:

This will load all nodes, regardless of their type or status.

To fix this, change this to use loadByProperties() instead:

loadByProperties() allows you to pass an array of properties and values to filter the results.

Note: you can also use →getQuery() if you prefer and write the query yourself.

For this case, let’s add a property for status and its value to be TRUE:

This ensures that only published nodes are returned, so the unpublished nodes are no longer shown, and the tests pass.

The other issue is all published nodes are returned, even if they aren’t posts.

Before adding this to PostNodeRepository, create a new failing test for it:

Use PostBuilder to create two posts and $this→createNode() to create a post of a different type.

In this test, we want the two post titles to be shown but not the page’s title.

If you run the test, it should fail as expected:

Now we have a failing test, let’s add the extra condition to PostNodeRepository:

With both conditions, both tests should now pass, and you should only see published node articles on your blog page.

With these changes, the PostNodeRepository is more robust and fully featured.

While we could also write new Kernel tests for this functionality, it’s already covered in the Functional tests. If you write accompanying Kernel tests, you wouldn’t be able to make them fail without also making the Functional tests fail.

If you want to add them, you can.

It’s up to you and your project team.

Instead of writing test methods starting with test, you can also use an @test annotation or, in more recent versions of PHPUnit, a #[Test] attribute. This, with snake-case method names, is a popular approach as it can be easier to read.

Just be aware that if you write tests this way and don’t add the annotation or attribute, the test won’t be executed.

Let’s start by testing the existing functionality within PostBuilder by verifying it returns published and unpublished posts.

Create these tests, which should pass by default as the code is already written:

In both tests, we create a new post node with PostBuilder, set a title and the appropriate status, get the post and assert it’s in the correct state.

To verify the tests are working correctly, try changing some values in it and PostBuilder to see if it fails when expected.

Next, create a test for adding tags to a post.

It should be mostly the same as the others, but instead of an assertion for the published status, try to use var_dump() to see the value of field_tags:

You should see an error message like this:

Why is this if field_tags is a default field that’s created when Drupal is installed?

The same as users and content, the new Drupal instance is created for each test, which won’t have your existing fields, so, in the test, you need to install the required configuration.

To have the required configuration available, it can be added to the atdc module.

Any configuration files within a config/install directory can be installed, although if a site already has field_tags defined, we don’t want to cause a conflict.

The convention is to create a test module that will only be required within the appropriate tests and to place the configuration there.

To do this, create a web/modules/custom/atdc/modules/atdc_test directory and an atdc_test.info.yml file with this content:

Because of adding hidden: true, it won’t appear in the modules list in Drupal’s admin UI and avoid it being installed outside of the test environment.

Within the module, create a config/install directory, which is where the configuration files will be placed.

But how do you know what to name the configuration files and what content to put in them?

Rather than trying to write them by hand, I create the configuration I need, such as fields, within a Drupal site and then export and edit the files I need.

To do that for this project, as I’m using the PHP built-in web server, I can use Drush to install Drupal using an SQLite database:

Note: if you need Drush, run composer require drush/drush to install it via Composer.

If you have a database available, you can use that, too.

Once Drupal is installed and the configuration has been created, you can go to - /admin/config/development/configuration/single/export and select the configuration type and name.

The filename is shown at the bottom of the page, and you can copy the content into files within your module.

The uuid and _core values are site-specific, so they can be removed.

To add field_tags, you’ll need both the field and field storage configuration.

These are the files that I created in my module based on the field I created.

field.field.node.post.field_tags.yml:

field.storage.node.field_tags.yml:

Then, enable the module within PostBuilderTest:

Finally, install the configuration to create the field. Add this within the test:

After adding this and attempting to install the configuration to add the field, you’ll get an error:

The test is trying to install the field_tags, but it’s missing a dependency. Tags reference a taxonomy term, but we haven’t enabled the Taxonomy module within the test.

Enable the taxonomy module by adding it to the $modules array, and the error should change:

As well as the field configuration, we also need to create the Post content type.

This can be done by creating a node.type.post.yml file:

With this configuration, field_tags should be created on the Post content type, which is enough for the current test to pass.

Let’s update the test and add assertions about the tags being saved and returned.

Get the tags from the post and assert that three tags are returned:

As none have been added, this would fail the test.

Update the test to use a setTags() method that you haven’t created yet:

You should get an error confirming the method is undefined:

To fix this, add the tags property and setTags() method to PostBuilder:

Tags will be an array of strings, and setTags() should set the tags to the tags property.

Next, add the logic to getPost() to create a taxonomy term for each tag name.

If $this→tags is not empty, create a new taxonomy term for each one and save it to the post.

When running the test, you may see an error similar to this:

Or:

The error may depend on the Drupal version or database type used, but is because the table doesn’t exist within the test database.

Because this is a Kernel test, we need to be explicit about which tables are installed.

To install the table add this line to the top of the test method:

This will install the table and ensure it’s present to save data to.

As well as asserting we have the correct number of tags, let’s also assert that the correct tag names are returned and that they are the correct type of term.

To assert the tags array only includes taxonomy terms, use self::assertContainsOnlyInstancesOf(), and to check each term has the correct term type, loop over each term and use self::assertSame().

Next, add some new assertions to the test to check the tag names match the specified tags.

These should pass as we already have code for them, but to see them fail, try changing a term type or tag name in the assertion or when creating the post to ensure the test works as expected.

In this lesson, you learned how to add the configuration required for tests by creating a custom test module with the required configuration and how to install it within the test so configuration, such as fields, are available.

You created PostBuilderTest - a Kernel test for testing PostBuilder.

In the next lesson, we’ll look at unit testing and start to wrap up this course.

Based on what you’ve learned so far, let’s write a Unit test that we’d expect to pass:

This test is within the tests/src/Unit directory and the equivalent namespace and extends the UnitTestCase class.

However, when you run the test, you’ll get an error:

In a Unit test, there is no database or service container, so you need to use mocks instead.

Update the test to create a mock version of NodeInterface instead.

As the mock an instance of NodeInterface, it satisfies the assertion and the test passes.

Next, add an assertion to ensure the bundle is correct:

This will fail with this error:

Because you’re using a mock, all methods will return NULL.

To get this to pass, you need to define what $this→bundle() will return:

However, this leads us to the situation I described, where you’re only testing what’s defined in the mock and not any valuable logic.

Let’s improve this by introducing a PostWrapper.

Let’s create a PostWrapper class that wraps a post node and has some methods that return specific values from it.

Within the test, instantiate a new Postwrapper class that takes the node as an argument.

Then, add an assertion that a getType() method should return post.

Next, create a PostWrapper class with the getType() method:

Now the test isn’t testing the mock data directly, but the mock data is used within the PostWrapper to assert it is returning the expected value.

We’ve tested that the PostWrapper works with post nodes, but let’s also ensure it won’t work with other node types.

Create a new test that creates a mock node and returns page as the bundle:

Before creating a new PostWrapper, assert that an InvalidArgumentException should be thrown. As no assertion is thrown, this test should fail:

To fix it, within the constructor for PostWrapper, check the bundle and throw the expected Exception if the bundle is not post:

Again, instead of making assertions against the mock data directly, it’s used to provide known data to the classes that need it.

In this lesson, I introduced unit testing and mocking.

In tomorrow’s lesson, the final one in this course, I’ll show you an example of how to use mocks with Service classes.

Create a new test, PostNodeRepositoryUnitTest and, for now, just create a new PostNodeRepository:

Running the test will give this error:

This is expected as PostNodeRepository has a dependency - the EntityTypeManager.

But, as this is a unit test, you can’t get the Repository from the service container, and you need to instantiate it as well as any dependencies.

Try to fix this by creating a new EntityTypeManager and injecting it into the constructor:

Running the tests again will give you a similar error:

EntityTypeManager also has dependencies that need to be injected, and they may have dependencies.

Instead of doing this manually, let’s start using mocks.

Add use Drupal\Core\Entity\EntityTypeManagerInterface; and create a mock to use instead of the manually created version.

As the mock implements EntityTypeManagerInterface, this will fix the failure, and the test will continue.

Next, try to get the posts from the Repository:

Instead of returning a result, this also results in an error:

Within PostNodeRepository, we use the getStorage() on EntityTypeManager to get the node storage, which is an instance of EntityStorageInterface.

For the test to work, this needs to be mocked too and returned from the getStorage() method.

Create a mock of EntityStorageInterface, which will be used as the node storage:

Next, this needs to be returns from the mock EntityTypeManager.

To do this, specify that the getStorage() method when called with the value node, will return the mocked node storage:

This will then be returned instead of NULL and fix the error.

Next, let’s create and return the nodes we need and add the assertions.

You’ll need to use a mock for each node and set what each method needs to return.

The same as the Kernel test, set a title for each post with different created times.

Then, specify the loadByProperties method should return the posts.

Finally, add some assertions that the nodes returned are the correct ones and in the correct order:

As the assertions should match the returned values, this test should now pass.

This is testing the same thing as the kernel test, but it’s your preference which way you prefer.

Hopefully, if you run your whole testsuite, you should see output like this:

Or, if you use --testdox, output like this:

Everything should be passing, and your testsuite should have a combination of different types of tests.

In this course, you’ve learned:

I couldn’t cover everything in a short email course, but I hope it was useful.