Running Simpletest and PHPUnit

4 min read

In this article by Matt Glaman, the author of the book Drupal 8 Development Cookbook. This article will kick off with an introduction to getting a Drupal 8 site installed and running.

(For more resources related to this topic, see here.)

Running 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. Read the change record here:

Getting ready

Currently core comes with Composer dependencies prepackaged and no extra steps need to be taken to run PHPUnit. This article will demonstrate how to run tests the same way that the QA testbot on does.

The process of managing Composer dependencies may change, but is currently postponed due to’s testing and packaging infrastructure. Read more here:

How to do it…

  1. First enable 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 and run the following to execute all available PHPUnit tests:
  3. php core/scripts/ PHPUnit
    Running Simpletest tests required executing the same script, however instead of passing PHPUnit as the argument, you must define the URL option and tests option:
  4. php core/scripts/ –url http://localhost –all
    Review the test output!

How it works…

The script has been shipped with Drupal since 2008, then named run-functional-tests.php. The command interacts with the test suites in Drupal to run all or specific tests and sets up other configuration items. We will highlight some of the useful options below:

  • –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 Simpletest without having to have Drupal installed
  • –concurrency: This allows you to define how many tests run in parallel

There’s more…

Is run-tests a shell script?

The 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 from 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 are issues with discovered PHP across platforms that prevent providing a shebang line to allow executing the file as a normal bash or bat script. For more info view this issue:

Running Simpletest without Drupal installed

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

Here is an example adapted from the DrupalCI test runner for Drupal core:

php core/scripts/ --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 Simpletest without a full-fledged environment.

Running specific tests

Each example thus 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 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 of 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.


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

The test bot utilizes Docker and can be downloaded locally to run tests. The project ships with a Vagrant file to allow it to be run within a virtual machine or locally. Learn more on the testbot’s project page:

See also

  • PHPUnit manual:
  • Drupal PHPUnit handbook:
  • Simpletest from the command line:

Resources for Article:

Further resources on this subject:


Please enter your comment!
Please enter your name here