Running tests - Simpletest and PHPUnit

Drupal 8 ships with two testing suites. Previously, Drupal only supported Simpletest. Now, there are PHPUnit tests as well. In the official change record, PHPUnit was added to provide testing without requiring a full Drupal Bootstrap, which occurs with each Simpletest test. You can read the change record at https://www.drupal.org/node/2012184.

There is currently a PHPUnit initiative active in Drupal core development. The goal is to fully remove the Simpletest framework by Drupal 9. No new Simpletest tests are being written, at least since 8.2. All current tests are currently being converted by contributors. More about the initiative can be found in this issue, https://www.drupal.org/node/2807237, where it is being coordinated.

We will be running tests using the run-tests.sh test runner. This is a test runner provided by Drupal that supports concurrency and running all of the various test suites. Running tests directly with PHPUnit will be covered in the following There's more... section.

Getting ready

Drupal 8.1.0 introduced the ability to perform JavaScript browser tests. This is powered using PhantomJS (http://phantomjs.org/), which uses a browser emulator powered by the Mink PHP library (http://mink.behat.org/). In order to run the FunctionalJavascript test suite, you must have PhantomJS running.

To install PhantomJS, refer to the official installation instructions at http://phantomjs.org/download.html.

How to do it...

1. First, install the Simpletest module. Even though you might only want to run PHPUnit, this is a soft dependency for running the test runner script.
2. Open a command-line terminal and navigate to your Drupal installation directory.
3. Next, we will run the test runner script. We will pass it a url option so that the Functional tests can run the browser emulator properly. We will also specify the test suites to run. This allows us to skip FunctionalJavascript tests due to PhantomJS not handling concurrency properly in the test runner:

$ php core/scripts/run-tests.sh --url http://localhost--types Simpletest,PHPUnit-Unit,PHPUnit-Kernel,PHPUnit-Functional --concurrency 20 --all

4. Running FunctionalJavascripts tests require PhantomJS to be running. Since PhantomJS prints output to the terminal, open a new tab or terminal and run the following command:

phantomjs --ssl-protocol=any --ignore-ssl-errors=true vendor/jcalderonzumba/gastonjs/src/Client/main.js 8510 1024 768 

5. With PhantomJS running, we can now execute the FunctionalJavascript test suite:

php core/scripts/run-tests.sh --url http://localhost--types PHPUnit-FunctionalJavascript --concurrency 1 --all

6. Review test output from each test suite run.

How it works...

The run-tests.sh script has been shipped with Drupal since 2008, then named
run-functional-tests.php. This command interacts with the test suites in Drupal to run all or specific tests and sets up other configuration items.

There are several different test suites that operate in specific ways:

• Simpletest: The deprecated test system, full bootstraps and installs Drupal and uses its own browser emulator pattern using curl and XPath.
• PHPUnit-Unit: Unit tests backed by PHPUnit. These are intended to test specific classes and not interact with the database.
• PHPUnit-Kernel: Integration-level tests backed by PHPUnit. It is a test that has the ability to install schema and configuration to the database, minimally bootstrapping Drupal for basic integration testing.
• PHPUnit-Functional: Functional tests are tests that require a fully bootstrapped Drupal and provide browser emulation via Mink. These can be considered a direct replacement of Simpletest tests but leveraging third-party testing libraries.
• PHPUnit-FunctionalJavascript: Functional tests that have the ability to interact with PhantomJS in order to test JavaScript, such as AJAX operations and specific user interface interactions.

The following are some of the useful options:

• --help: This displays the items covered in the following bullets
• --list: This displays the available test groups that can be run
• --url: This is required unless the Drupal site is accessible through http://localhost:80
• --sqlite: This allows you to run tests without having Drupal installed
• --concurrency: This allows you to define how many tests run in parallel

There's more...

We will now discuss more techniques and information for running Drupal's test suites.

Is run-tests a shell script?

The run-tests.sh isn't actually a shell script. It is a PHP script--which is why you must execute it with PHP. In fact, within core/scripts, each file is a PHP script file meant to be executed using the command line. These scripts are not intended to be run through a web server, which is one of the reasons for the .sh extension.

There can be issues with PHP across platforms that prevent providing a shebang line to allow executing the file as a normal bash or bat script. For more information, refer to this Drupal.org issue at https://www.drupal.org/node/655178.

Running tests without Drupal installed

With Drupal 8, tests can also be run from SQLlite and no longer requires an installed database. This can be accomplished by passing the sqlite and dburl options to the
run-tests.sh script. This requires the PHP SQLite extension to be installed.

Here is an example adapted from the DrupalCI test runner for Drupal core. DrupalCI is the continuous integration service, which runs on Drupal.org for all submitted patches and commits:

php core/scripts/run-tests.sh --sqlite /tmp/.ht.sqlite --die-on-fail --dburl sqlite://tmp/.ht.sqlite --all
  

Combined with the built-in PHP web server for debugging, you can run test suites without a full-fledged environment.

Running specific tests

Each example so far has used the all option to run every Simpletest available. There are various ways to run specific tests:

• --module: This allows you to run all the tests of a specific module
• --class: This runs a specific path, identified by a full namespace path
• --file: This runs tests from a specified file
• --directory: This run tests within a specified directory

Previously in Drupal, tests were grouped inside the module.test files, which is where the file option derives from. Drupal 8 utilizes the PSR-4 autoloading method and requires one class per file.

PhpStorm - Drupal Test Runner

Drupal 8 has seen a surge in test coverage for both Drupal core and contributed projects, most likely due to PHPUnit adoption. In response to this, the author has written a PhpStorm plugin called Drupal Test Runner that simplifies executing the run-tests.sh script runner.

The plugin's page can be found at https://plugins.jetbrains.com/plugin/8384-drupal-test-runner, and it's public source code can be found at https://github.com/mglaman/intellij-drupal-run-tests.

DrupalCI

With Drupal 8 came a new initiative to upgrade the testing infrastructure on Drupal.org. The outcome was DrupalCI. DrupalCI is open source and can be downloaded and run locally. The project page for DrupalCI is https://www.drupal.org/project/drupalci.

The test bot utilizes Docker and can be downloaded locally to run tests. The project ships with a Vagrant file that allows it to be run within a virtual machine or locally. Learn more on the testbot's project page at https://www.drupal.org/project/drupalci_testbot.

See also...

• Refer to the PHPUnit manual at https://phpunit.de/manual/4.8/en/writing-tests-for-phpunit.html.
• Refer to the Drupal PHPUnit handbook at https://drupal.org/phpunit.
• Refer to Running tests from the command line at https://www.drupal.org/node/645286.

• Refer to Commerce 2.x: Unit, Kernel, and Functional Tests Oh My! Authors blog post and tutorial for running tests in Drupal 8 for Drupal Commerce at https://drupalcommerce.org/blog/45322/commerce-2x-unit-kernel-and-functional-tests-oh-my.