fromSeptember 2013

Testing, Testing, One... Two... Three...

Drupal Extension to Behat and Mink

Crash Test PeepsThe Drupal community's commitment to cooperation and sharing is one of its defining characteristics, and the Drupal Extension to Behat and Mink is a powerful example of that cooperation in action. It is not a Drupal module. Rather, it extends the functional testing framework of Behat and Mink in order to provide Drupal-specific functionality. You'll find its detailed documentation at Read the Docs.

The extension helps site builders automate tests for Drupal 6, 7, and 8 without having to write custom code for common Drupal features. It currently provides support in three major areas: setting up test data, mapping page regions, and auto-discovery of Behat tests provided by modules and themes.

Setting Up Test Data

To test any Drupal site, at some point you'll need to set up test data. You can do this in a blackbox fashion, using pre-built steps to create a user – and log in via the interface – then fill out the appropriate form. This approach takes time to write, time to run, and becomes tedious to read. Adding data in this detailed way is warranted at times, but you're typically better off inserting data as a single step in the Given section of your scenario. The Drupal extension provides a driver system to help you.


The default driver assumes you have no privileged access to the Drupal site. All your data setup has to take place through the normal user interface. The blackbox driver exists so you can benefit from other Drupal Extension features.

Drupal API

When your tests run on the same machine as your Drupal installation, you can use the Drupal API directly to create users, nodes, taxonomy vocabularies, and taxonomy terms, without writing any supporting PHP code and without the tedium of blackbox steps. To do so, you configure your testing instance to point at the local path to the Drupal site, tag the scenario with @api, and then use pre-built steps.

    Given I am viewing “article” node with the title “Drupal API”

This will:

  • create the article, entering random data for the body
  • delete the article on completion of the scenario


If you run your tests on a different machine than the Drupal site being tested, the Drush driver lets you use Drush to create users.

  Given I am logged in as a user with the “administrator” role

This single step:

  • creates a user with a random name
  • assigns a pre-existing role
  • logs the user in
  • deletes the user at the end of the scenario.

The Drush driver doesn't support as many options as the Drupal API because Drush itself doesn't support those options.

Map Drupal Regions

It's often helpful on a Drupal site to check that you're pressing a button or seeing text on a particular part of the page, such as when you have two buttons with the same label, or when CSS formatting is region-specific and you want to be sure a block has been placed in the right spot.

The Drupal Extension facilitates checking gracefully by allowing you to map readable region names to their CSS selectors in the behat.yml file, and then use steps like:

  When I press the “Search” button in the “header” region

This step is accessible via any of the three drivers.

Auto-discover Module and Theme Supplied Steps

The Drupal Extension offers a feature that isn't in wide-spread use yet, but which has terrific potential.

If a module or theme provides its own custom step definitions in a file named {filename}, the steps can be used not only by the module builder to test module functionality but also passed along to site builders.

To take advantage of such steps, you'll need to define one or more directories where such files can be found (often the sites/all folder). The Drupal Extension will search recursively and load all files ending in

To see this in action, take a look at

The Drupal Extension's ability to support functional testing for Drupal sites has plenty of room to grow. If you've addressed a Drupal-specific testing need in your own work, contribute it back. Solutions for more specific-use cases will join a growing list of recipes. Module-specific steps can supplied by the module itself, available when that module is installed. General solutions will be incorporated into the Extension itself, ready for you and others with each new installation of the Drupal Extension.

Image: "Peeps vs. LEGO: Crash Test Dummies" by wiredforleg is licensed under CC BY-SA 2.0