Skip to content

A Full Guide to PHPUnit in Drupal 8

PHPUnit Testing Drupal 8

Like many open-source projects, Drupal comes with automated tests that help prevent breaking changes while promoting code quality. Drupal 8 has changed its testing framework for unit and functional tests from its own Simpletest framework to PHPUnit, following Drupal 8’s strategy of using more third-party libraries in core. All Simpletests have been moved to PHPUnit as of Drupal 8.7.x.

PHPUnit can handle different types of tests in Drupal core: unit tests, kernel tests, and functional tests. With these three tests, you can confirm the quality and reaction of code on edge cases in different layers.

Unit tests test functions, methods, and classes without requiring a database connection to run. On the other hand, kernel tests test the integration of module APIs and require a database connection to be configured to run. Functional tests test the entire system and require more setup than the others. Within the functional tests, there are both browser and JavaScript tests. In addition to these PHP-based tests, you may also run core JavaScript tests using the Nightwatch framework.

Unit Tests

Your unit tests won’t be found unless they follow specific file structure, namespace, and metadata requirements. Drupal Console can generate a stub test when generating a module.

When writing custom code, be sure to use dependency injection to make mocking easier. You can find detailed information in this blog post, or see the examples module.

Unit test mocks are created using Prophecy.

Case Study Architecting a Drupal 8 Platform for the City of Raleigh

Kernel Tests

Per the documentation of the KernelTestBase class, kernel tests are “useful for testing some types of integrations which don’t require the overhead of a fully-installed Drupal instance, but which have many dependencies on parts of Drupal which can’t or shouldn’t be mocked.” The class partially boots Drupal, and can load the services and hooks of other modules. The documentation says that the configuration, database schema, and entity schema could be installed for some modules, but it’s not clear which modules support this.

Functional/UI Tests

Browser Tests

PHPUnit browser functional tests are run against a fresh Drupal installation so each test requires set up like installing modules, creating users, etc. This can be done in the BrowserTestBase::setUp() method (which is run before each test method in the class) or by writing an abstract base class (that extends BrowserTestBase) to be extended by additional test classes. You could also simply run a previous test at the beginning of the test you are writing. The results of the browser tests are saved to a directory, which can be configured in the phpunit.xml file. See PHPUnit Browser test tutorial in the Drupal documentation.

JavaScript Tests

PHPUnit Javascript functional tests are run against a fresh Drupal installation in an actual browser window, in order to test Javascript and AJAX functionality. They can extend JavascriptTestBase (deprecated) or WebDriverTestBase. Running them requires setting up PhantomJS (for JavascriptTestBase) or Chromedriver and Chrome/Chromium (for WebDriverTestBase). See PHPUnit Javascript test writing tutorial in the Drupal documentation.

Behat Tests

While not part of Drupal core, some contributed modules also include tests using the Behat framework. Behat uses the Gherkin syntax to describe features, which are then translated to functional and UI tests.

Behat tests would be used to test site-specific functionality and uses the site’s database, rather than a clean installation of Drupal. The Behat Drupal Extension is an open-source project that provides drivers and useful step definitions for Drupal. Tests are organized into features, scenarios, and steps. Features and scenarios can be tagged to be run in groups, or to let Behat know to use a certain driver.

While this Gist offers a helpful list of step definitions provided by the Behat Drupal Extension, users can also run the command “behat -dl” for a list of steps defined for a system.

Each of these steps uses a different driver, which provides a different layer of integration with Drupal.

Blackbox Driver

The blackbox driver operates similarly to both the PHPUnit Browser and JavaScript functional tests. If the feature or scenario isn’t tagged, it will be run in a headless browser. If the test is tagged with @javascript, Behat can use Selenium to open a browser window and run the test. Selenium can then be set up to run the tests in several different browsers.

Drush Driver

The Drush driver uses the Drush command line tool to complete steps. In order to use the Drush driver, the feature or scenario must be tagged with @api. The Drush driver allows tests to use all the blackbox steps, plus a few more steps like logging in and creating users. The Drush driver can be run on multiple sites via Drush aliases.

Drupal API Driver

The Drupal API driver provides more complex steps, but can only be run on one site at a time. Behat can be configured to use this driver when features or scenarios are tagged with @api. Behat can be configured to run either the Drush driver OR the API driver at one time.

Custom Step Definitions

Custom step definitions would be added to the FeatureContext.php file that gets created when Behat is initialized for a project. The step text and any arguments are set up in annotations to functions in the FeatureContext class. See the Behat documentation for details.

Next Steps

Unit and functional tests are a great way to help improve your code quality. Drupal core supports many different kinds of tests that focus on different parts of the system, and some tests may be better for testing different things. Look for a future blog post on how to run these tests, and incorporate automated testing into your workflow.

Atlantic BT is well-versed in Drupal architecture, development, and testing. Learn more about our development services, or contact us to chat with an expert.

capabilities covered
By Platform – Drupal

The Atlantic BT Manifesto

The Ultimate Guide To Planning A Complex Web Project


Atlantic BT's Insights

We’re sharing the latest concepts in tech, design, and software development. Learn more about our findings.

Questions & Answers

What is the best web development framework?
Many people commonly ask “what is a framework in web development?” Web development frameworks can easily be confused with web development tools, languages, or parts of the web development stack (like PHP, Ruby, or Javascript).
Learn More about What is the best web development framework?
What is the best programming language for web development?
If there was one “best” programming language, then everything else would be obsolete. The reality is that there are so many different programming languages because there is no “best” language for any situation.
Learn More about What is the best programming language for web development?
How much does web development cost?
Web development can vary from a few hundred to millions of dollars depending on what is needed. You may simply need some changes to something that already exists, or you'd like to build a large or complex application.
Learn More about How much does web development cost?
What is web design and development?
People often lump web design and development together, so what's the difference? As the Internet has evolved, the skills required to produce a high quality website or web application have changed.
Learn More about What is web design and development?
What is React web development?
React is a popular JavaScript library. It is primarily used for building interactive user interfaces (UI).
Learn More about What is React web development?
What is PHP web development?
PHP is a back end language primarily used for custom applications, content management systems (such as Wordpress), eCommerce engines (such as Magento), or even massive sites like Facebook.
Learn More about What is PHP web development?
What is bootstrap in web development?
Bootstrap is a framework used in front-end development to save time, specifically for mobile-first development. It combines CSS and Javascript templates and libraries to speed up the development process.
Learn More about What is bootstrap in web development?