Drupal Unit Autoload

Have you ever wanted to add PHPUnit tests to your Drupal 7 module? Well, you should. This tool aims to help you to deal with autoloading the classes that you have in your Drupal installation.

The Problem

The main problem arises when the class -or code- that you are testing depends on classes declared in other modules, or Drupal core itself.

Imagine that you are testing your Car class. That class depends on \DrupalCacheInterface (you are using a mock cache provider that has to implement that interface), and also depends on several classes from the service container module. After all you are injecting services in your Car class to be able to mock them afterwards, and that may require to have the Drupal\service_container\ available to you during tests.

Since you are doing unit testing, you may not want to bootstrap Drupal to have the database available in order to be able to check in the registry to find all those classes.

At this point you can think I will just use Composer's autoloader and define where to find those classes and namespaces. This is when you realize that Drupal allows you to install contrib modules in many locations. That makes it impossible to ship your module with the relative paths that you need.

Imagine this possibility:

• Our custom module (the one that will have unit testing) is installed in sites/example.org/modules/contrib/racing_modules/car.
• The modules that the car module depends on are installed in:
  • sites/all/modules/essentials/service_container.
  • sites/default/modules/contrib/dependency.

It seems that if you wanted to provide the path to includes/cache.inc to make \DrupalCacheInterface available, then you would need to add a path like: ../../../../../../includes/cache.inc. But what if someone decides to install your car module in sites/all/modules/car? That path you provided in the module will not work in that situation. The correct one would be ../../../includes/cache.inc. Basically every site installation may need a different path.

The problem that this project aims to solve is to give you a way to provide a single path in your code that will work in all those scenarios.

The Solution

Meet the Drupal Unit Autoload. To include it, just add the following to your PHPUnit test class (change the path depending on the location of your test classes):

require_once __DIR__ . '/../../vendor/e0ipso/drupal-unit-autoload/autoload.php';

That will load Composer's autoloader + the Drupal capabilities.

The only thing that you need to do is add a new composer.json key with tokens in the path.

Inside the folder where you have your unit tests you will need to have a composer.json file that has:

{
  "require-dev": {
    "phpunit/phpunit": "4.7.*",
    "mockery/mockery": "0.9.*",
    "e0ipso/drupal-unit-autoload": "1.0.*"
  },
  "autoload": {
    "psr-0": {
      … This is usual Composer business …
    },
    "psr-4": {
      … This is usual Composer business …
      "Drupal\\service_container\\": "DRUPAL_CONTRIB<service_container>/src",
      "Drupal\\Core\\": [
        "DRUPAL_CONTRIB<service_container>/lib/Core",
        "DRUPAL_CONTRIB<contrib>/src/DrupalCore"
      ]
    },
    "class-location": {
      "\\DrupalCacheInterface": "DRUPAL_ROOT/includes/cache.inc",
      "\\ServiceContainer": "DRUPAL_CONTRIB<service_container>/lib/ServiceContainer.php",
      "\\Drupal": "DRUPAL_CONTRIB<service_container>/lib/Drupal.php"
    }
  }
}

Running composer install on that folder will download PHPUnit, Mockery -and all of the tools that you use for your tests-. Additionally it will download this project, that is what "e0ipso/drupal-unit-autoload": "0.1.*" is for.

At this point you only need is add the paths with DRUPAL_ROOT or DRUPAL_CONTRIB<modulename> in your composer file.

You have two options:

• Provide class names and the files where they are found using the new key inside of autoload called class-location.
• Provide psr-4 and psr-0 namespace prefixes and the path where they are mapped. This is very simmilar to what composer does, but with the magic that finds where the Drupal root is and where the contrib modules are installed.

In the paths that you provide, you will be able to include two tokens: DRUPAL_ROOT and DRUPAL_CONTRIB<modulename>. Those tokens will be expanded to the real paths that they represent. This way, providing DRUPAL_CONTRIB<ctools> can end up expanding in:

• /var/www/docroot/sites/all/modules/ctools in one Drupal installation.
• /User/Sites/drupal-site/sites/default/modules/contrib/ctools in another installation.

The important thing to note is that your code ships with the same tokenized path for everyone, without caring about where the dependencies are installed.