Automated tests

Overview of PHPUnit and Nightwatch automated tests.

The Drupal project has embraced a philosophy of using automated tests, consisting of both unit tests (which test the functionality of classes at a low level) and functional tests (which test the functionality of Drupal systems at a higher level, usually involving web output). The goal is to have test coverage for all or most of the components and features, and to run the automated tests before any code is changed or added, to make sure it doesn't break any existing functionality (regression testing).

In order to implement this philosophy, developers need to do the following:

• When making a patch to fix a bug, make sure that the bug fix patch includes a test that fails without the code change and passes with the code change. This helps reviewers understand what the bug is, demonstrates that the code actually fixes the bug, and ensures the bug will not reappear due to later code changes.
• When making a patch to implement a new feature, include new unit and/or functional tests in the patch. This serves to both demonstrate that the code actually works, and ensure that later changes do not break the new functionality.

Writing tests

All PHP-based tests for Drupal core are written using the industry-standard PHPUnit framework, with Drupal extensions. There are several categories of tests; each has its own purpose, base class, namespace, and directory:

• Unit tests:
  • Purpose: Test functionality of a class if the Drupal environment (database, settings, etc.) and web browser are not needed for the test, or if the Drupal environment can be replaced by a "mock" object.
  • Base class: \Drupal\Tests\UnitTestCase
  • Namespace: \Drupal\Tests\yourmodule\Unit (or a subdirectory)
  • Directory location: yourmodule/tests/src/Unit (or a subdirectory)
• Kernel tests:
  • Purpose: Test functionality of a class if the full Drupal environment and web browser are not needed for the test, but the functionality has significant Drupal dependencies that cannot easily be mocked. Kernel tests can access services, the database, and a minimal mocked file system, and they use an in-memory pseudo-installation. However, modules are only installed to the point of having services and hooks, unless you install them explicitly.
  • Base class: \Drupal\KernelTests\KernelTestBase
  • Namespace: \Drupal\Tests\yourmodule\Kernel (or a subdirectory)
  • Directory location: yourmodule/tests/src/Kernel (or a subdirectory)
• Browser tests:
  • Purpose: Test functionality with the full Drupal environment and an internal simulated web browser, if JavaScript is not needed.
  • Base class: \Drupal\Tests\BrowserTestBase
  • Namespace: \Drupal\Tests\yourmodule\Functional (or a subdirectory)
  • Directory location: yourmodule/tests/src/Functional (or a subdirectory)
• Browser tests with JavaScript:
  • Purpose: Test functionality with the full Drupal environment and an internal web browser that includes JavaScript execution.
  • Base class: \Drupal\FunctionalJavascriptTests\WebDriverTestBase
  • Namespace: \Drupal\Tests\yourmodule\FunctionalJavascript (or a subdirectory)
  • Directory location: yourmodule/tests/src/FunctionalJavascript (or a subdirectory)
• Build tests:
  • Purpose: Test building processes and their outcomes, such as whether a live update process actually works, or whether a Composer project template actually builds a working site. Provides a temporary build workspace and a PHP-native HTTP server to send requests to the site you've built.
  • Base class: \Drupal\BuildTests\Framework\BuildTestBase
  • Namespace: \Drupal\Tests\yourmodule\Build (or a subdirectory)
  • Directory location: yourmodule/tests/src/Build (or a subdirectory)

Some notes about writing PHP test classes:

• The class needs a phpDoc comment block with a description and @group annotation, which gives information about the test.
• For unit tests, this comment block should also have @coversDefaultClass annotation.
• When writing tests, put the test code into public methods, each covering a logical subset of the functionality that is being tested.
• The test methods must have names starting with 'test'. For unit tests, the test methods need to have a phpDoc block with @covers annotation telling which class method they are testing.
• In some cases, you may need to write a test module to support your test; put such modules under the yourmodule/tests/modules directory.

Besides the PHPUnit tests described above, Drupal Core also includes a few JavaScript-only tests, which use the Nightwatch.js framework to test JavaScript code using only JavaScript. These are located in core/tests/Drupal/Nightwatch.

For more details, see:

• core/tests/README.md for instructions on running tests
• https://www.drupal.org/phpunit for full documentation on how to write and run PHPUnit tests for Drupal.
• http://phpunit.de for general information on the PHPUnit framework.
• Object-oriented programming topic for more on PSR-4, namespaces, and where to place classes.
• http://nightwatchjs.org/ for information about Nightwatch testing for JavaScript

File

core/core.api.php, line 1073

Classes