Dries Buytaert

PHPUnit tests for Drupal

Writing tests can be hard. The key is to get started. When I start work on a new Drupal module, I like to start off by adding a very simple test and making it pass. Once I have one simple test passing, it becomes easy to add more. The key is get started with the simplest test possible. This page explains how I do that.

The most basic PHPUnit test for Drupal

The most basic test looks something like this:

<?php
namespace Drupal\Tests\my_module\Functional;

use Drupal\Tests\BrowserTestBase;

class MyModuleTest extends BrowserTestBase {

  /**
   * Modules to enable.
   *
   * @var array<string>
   */
  protected static $modules = ['my_module'];

  /**
   * Theme to enable. This field is mandatory.
   *
   * @var string
   */
  protected $defaultTheme = 'stark';

  /**
   * The simplest assert possible.
   */
  public function testOne() {
    $this->assertTrue(TRUE);
  }
}

Drupal uses PHPUnit for testing, and the test above is a PHPUnit test.

The test lives in docroot/modules/custom/my_module/tests/src/Functional/MyModuleTest.php.

Installing PHPUnit for Drupal

Drupal does not ship with PHPUnit out-of-the-box, so it needs to be installed.

The best way to install PHPUnit on a Drupal site is by installing the drupal/core-dev package. It can be installed using Composer:

$ composer require drupal/core-dev --dev --update-with-all-dependencies

The command above will download and configure PHPUnit, along with other development dependencies that are considered a best-practice for Drupal development (e.g. PHPStan).

Configuring PHPUnit for Drupal

Once installed, you still have to configure PHPUnit. All you need to do is set two variables:

• SIMPLETEST_BASE_URL should be the URL of your site (e.g. http://localhost/).
• SIMPLETEST_DB should be your database settings (e.g. mysql://username:password@localhost/database).

You can specify these directly in docroot/core/phpunit.xml.dist, or you can set them as environment variables in your shell.

Running a PHPUnit test for Drupal

With PHPUnit installed, let's run our basic test:

$ cd docroot/core
$ ../../vendor/bin/phpunit ../modules/custom/my_module/tests/src/Functional/MyModuleTest.php

We have to execute our test from inside the docroot/core/ directory so PHPUnit can find our test.

Using PHPUnit with Lando

I use Lando for my local development environment. There are a couple of things you can add to your .lando.yml configuration file to make using PHPUnit a bit easier:

services:
  appserver:
    overrides:
      environment:
        SIMPLETEST_BASE_URL: "http://localhost/"
        SIMPLETEST_DB: "mysql://username:password@localhost/database"
        BROWSERTEST_OUTPUT_DIRECTORY: "/app/phpunit-results"
tooling:
  test:
    service: appserver
    cmd: "php /app/vendor/bin/phpunit --verbose -c /app/docroot/core/phpunit.xml.dist"

The first 6 lines sets the variables and the last 4 lines create a new lando test command.

After changing my .lando.yml, I like to rebuild my Lando environment, though that might not be strictly necessary:

$ lando rebuild -y

Now, you can run the PHPUnit test as follows:

$ lando test modules/custom/my_module/tests/src/Functional/MyModuleTest.php