Drupal PHPUnit Integration Testing Framework

How to Install

You must execute the following in the directory above web. It will install this package in a directory called tests_integration.

mkdir -p tests_integration/src
cd tests_integration
echo "/vendor/\n*/.cache\n/reports/\n" > .gitignore
echo '{"autoload":{"psr-4":{"\\\\AKlump\\\\Drupal\\\\PHPUnit\\\\Integration\\\\":"src"}},"repositories":[{"type":"github","url":"https://github.com/aklump/drupal-phpunit-integration"}]}' > composer.json
composer require aklump/drupal-phpunit-integration:^0

This will create the file for running your tests:

mkdir -p ../bin
cp vendor/aklump/drupal-phpunit-integration/init/run_integration_tests.sh ../bin/

This will create phpunit.xml for configuring testing.

cp vendor/aklump/drupal-phpunit-integration/init/phpunit.xml.dist phpunit.xml

Test Class Namespace & File Structure

Before continuing please read the section Difference Between Integration Tests and Unit Tests so you create the tests appropriately.

Create your first integration test class:

web/modules/custom
└── alpha
    └── tests
        └── Integration
            └── FooTest.php

FooTest.php

namespace Drupal\Tests\alpha\Integration;

class FooTest extends \PHPUnit\Framework\TestCase {

Ensure your module's web/modules/custom/composer.json has the proper autoloading configuration:

{
  "autoload": {
    "psr-4": {
      "Drupal\\alpha\\": "src"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "Drupal\\Tests\\alpha\\": "./tests/"
    }
  }
}

Config File

Now open tests_integration/phpunit.xml and add one or more integration test directories:

<testsuites>
  <testsuite name="integration">
    <directory>../web/modules/custom/alpha/tests/Integration/</directory>
    <directory>../web/modules/custom/bravo/tests/Integration/</directory>
    <directory>../web/modules/custom/charlie/tests/Integration/</directory>
  </testsuite>
</testsuites>

Run Your Tests

1. cd into the directory above web root.
2. Run tests with bin/run_integration_tests.sh

The first time the tests are run, a cache is built that speeds up subsequent runs. To flush these caches, add the --flush parameter, e.g. bin/run_integration_tests.sh --flush.

Built-in Test Support Classes

Have a look in the following directories:

• tests_integration/vendor/aklump/drupal-phpunit-integration/src/Framework/MockObject

Custom Test Support Classes

• The directory tests_integration/src/ is namespaced to AKlump\Drupal\PHPUnit\Integration
• Place shared traits and other test support in src/ using said namespace.

Difference Between Integration Tests and Unit Tests

web/modules/custom
└── alpha
    ├── bin
    │   └── run_unit_tests.sh
    ├── src
    │   └── Foo.php
    └── tests
        ├── Integration
        │   └── FooTest.php
        └── Unit
            ├── FooTest.php
            └── phpunit.xml

Given the above module file structure, you can see two directories in tests. tests/Unit/FooTest.php can be run using alpha/bin/run_unit_tests.sh and has no Drupal dependencies. Therefore it's straight-up PHPUnit stuff. On the other hand, tests/Integration/FooTest.php cannot be run in the same manner as it has Drupal class dependencies, hence it "integrates" with Drupal. For that you must use tests_integration/bin/run_integration_tests.sh.

Use namespace Drupal\Tests\alpha\Unit; for unit test classes.

Unit tests are only mentioned here to distinguish the difference. This package concerns itself with Integration tests, with one caveat: it is convenient to add the Unit directory to tests_integration/phpunit.xml so that Unit tests are run at the same time as the Integration tests. This is a good idea and encouraged. In our example, it will look like this.

<testsuites>
  <testsuite name="unit">
    <directory>../web/modules/custom/alpha/tests/Unit/</directory>
  </testsuite>
  <testsuite name="integration">
    <directory>../web/modules/custom/alpha/tests/Integration/</directory>
  </testsuite>
</testsuites>

What About tests_integration/composer.lock?

It's up to you, but it seems like a good idea to source code commit this file as it will provide more stability to your app for tests passing if you have to reinstall dependencies.

How to Update this Package

To get the newest version of aklump/drupal-phpunit-integration:

cd tests_integration
composer update

This will only update the vendor/ directory so your changes and files in tests_integration are not affected.

You may want to diff run_integration_tests.sh and phpunit.xml from time to time and cherry pick as necessary, however, CHANGELOG.md should make note of any changes to these files.

cd tests_integration
diff vendor/aklump/drupal-phpunit-integration/init/run_integration_tests.sh ../bin/run_integration_tests.sh
diff vendor/aklump/drupal-phpunit-integration/init/phpunit.xml.dist phpunit.xml