SimpleTest Tutorial (Drupal 7)

Last updated May 23, 2013. Created by puregin on August 23, 2010.
Edited by ressa, geerlingguy, wizonesolutions, alextataurov. Log in to edit this page.

Note: The code for this tutorial is maintained in the Examples for Developers module. This means:

• You can grab a copy there and fiddle with it, change it, experiment with it.
• If you find problems, file an issue there and get it fixed. Patches and improvements are welcome.

This tutorial will take you through the basics of testing in Drupal. By the end you should be able to write your first test! For this example we will create a dummy module called "simpletest_example", which provides a content type called "simpletest_example". This content type is exactly the same as any basic Drupal node type (e.g., 'page'). The tutorial will then explain how to test this simpletest_example content type to ensure it functions properly.

Setup for the tutorial

First, we will need to make sure that the Simpletest module is installed. In Drupal 7, Simpletest is part of the core and is called Testing. If you have not done so already, you will need to make sure the Simpletest module is enabled.

Simpletest verbose testing information is on by default in Drupal 7, but since you need it, you may want to check to make sure it's turned on. It gives you a screenshot of what the Drupal page looks like at every point in the test. Check it at admin/config/development/testing/settings.

This tutorial makes use of the Simpletest Example module from http://drupal.org/project/examples.

How Drupal's Simpletest works

Most of Drupal is web-oriented functionality, so it's important to have a way to exercise these functions. Simpletest creates a complete Drupal installation and a virtual web browser and then uses the virtual web browser to walk the Drupal install through a series of tests, just like you would do if you were doing it by hand. It's terribly important to realize that each test runs in a completely new Drupal instance, which is created from scratch for the test. In other words, none of your configuration and none of your users exists! None of your modules are enabled beyond the default Drupal core modules. If your test sequence requires a privileged user, you'll have to create one (just as you would if you were setting up a manual testing environment from scratch). If modules have to be enabled, you have to enable them. If something has to be configured, you'll have to use Simpletest to do it, because none of the configuration on your current site is in the magically created Drupal instance that we're testing. None of the files in your files directory are there, none of the optional modules are installed, none of the users are created. We have magic commands to do all this within the Simpletest world, and we'll get to that in a little bit.

About the Simpletest Example module

The Simpletest Example module provides a custom node type (like 'page' or 'story'). It has a title and a body. That's it. It gives us a chance to demonstrate testing of content creation. To implement the node, we have to provide the node type to Drupal with hook_node_info() and provide a form for the node type with hook_form(). We implement permissions for the module (so that you need "create simpletest_example content" permissions to create one, or "edit own simpletest_example content" permissions to edit one.) And of course we need a simpletest_example.info.

Note that our module has a bug in it: The permissions handling is not done correctly. So even though there's a permission string for 'edit own simpletest_example', it's not handled correctly by simpletest_example_access(), so when our properly privileged user tries to edit a node, it can't. Of course, the manual user tester was probably testing with user 1, so never saw this failure case. We'll get to this later.

This code is maintained in the Examples for Developers module. It really helps to try out the code, change it a bit, experiment with dummy code like this before trying to do something serious.
You're encouraged to grab it, enable the module, and work with the code.

Figuring out what we need to test

If you install simpletest_example, you can manually go through the steps and see what you think needs to be tested.

Visit Content > Add new content > Simpletest Example Node Type where you should see the following.

Look at the interface and identify the things that need to be tested in our node type.

Take a tour and make sure you are familiar with how the interface works and that it functions properly in a basic case where you are manipulating it instead of simpletest. If you don't understand what it's doing or why, you can't write a workable test. In this case fill in the title and body fields and click the save button. You should see something like the following.

Building a test for simpletest_example

Now it's time to create our tests, which we'll do in the simpletest_example.test file (which you have in the complete module download).

If you are adding a new .test file to a module for Drupal 7, you will have to add it to the files[] section of the module's .info file. In our example, there is an entry for simpletest_example.test in the files[] section of the simpletest_example.info file:

If you add a .test file to an existing module, you will probably need to rebuild Drupal's caches in order to notify Drupal of the new file. To rebuild all caches, you can go to admin/config/development/performance and click the "Clear all caches" button.

There are four basic steps involved in building a test:

• Creating the structure (just creating a class that inherits from DrupalWebTestCase)
• Initializing the test case with whatever user creation or configuration needs to be done
• Creating actual tests within the test case
• And, of course, trying desperately to figure out why our test doesn't work the way we expect, and debugging the test (and perhaps the module)

To start, we just need a bit of boilerplate extending DrupalWebTestCase.

To make the test available to the Simpletest testing interface, we implement getInfo(). This just provides the user interface information that will show up on the simpletest page after clearing the cache table.

Next comes the terribly important setUp(). Here is where we must do anything that needs to be done to make this Drupal instance work the way we want to. We have to think: "What did I have to do to get from a stock Drupal install to where I can run this test?". In our case, we know that we had to:

• Enable the Simpletest Example module
• Create a user with privileges to create a simpletest_example node
• Log in the user

This work is done by the setUp() method:

Note: In Drupal 6, we had to explicitly enable every dependency our module had. Drupal 7 automatically enables all dependencies.

Create specific test: Creating a node

Now we need to create specific tests to exercise the module. We just create member functions of our test class, each of which exercises a particular test. All member functions should start with 'test' in lower-case. Any function that starts this way will automatically be recognized by Simpletest and run when requested (Note: Although it is possible to put each assertion into a separate function, testing several different assertions at once is recommended instead).

Our first test will be to create a new simpletest_example node by using the form at node/add/simpletest-example:

drupalPost, drupalGet, and Assertions

The code above did a very simple form submission on the node/add/simpletest-example page. It prepares an array of fields (the $edit array, giving random values for the title and body) and then it POSTs the form and asserts that we find appropriate text on the page.

Most tests will follow this pattern:

1. Do a drupalGet() to go to a page or a drupalPost() to POST a form.
2. Do one or more assertions to check that what we see on the page is what we should see.

$this->drupalGet($path) is as easy as it can be: It just goes to the named page.

$this->drupalPost($path, $edit_fields, $submit_button_name) is only slightly more complex.

And then there are dozens of possible assertions. The easiest of these is $this->assertText($text_to_find_on_page). When you get beyond this tutorial, you'll want to read about more of them.

Users in test and the core environment

Tests run in a separate (sandbox) environment. Logging a user in with $this->drupalLogin($account) happens in the test environment. Test methods, like drupalGet and drupalPost also act in that sandbox. If you want to call core API functions (eg: user_access) it's highly recommended to assign the test user to the core environment:

Simpletest switches the user to uid 1 during testing and takes care of restoring the user so we can change the user without security concerns.

Running the Simpletest web interface

Next we need to run the test. Here we'll use the web interface to run the test.

Go to the Configuration > Development > Testing page and find the module that you created. On this page you will see two tabs, Settings and List. In the List tab, you will see a list with the available tests. Select the test you just created -- it will be in the "Examples" group -- and press the Run tests button. (You may need to clear Drupal's cache to see it in the list),

Once the test has run you should see the results, which for this test will pass.

You can also run tests from command line. More information about it can be found at Running Tests Through command-line.

A demonstration failing test

It really doesn't teach us much to just have a test that succeeds. Let's look at one that fails.

We'll work within the same class and this time try to test editing a node. Our module has a flaw in it - it doesn't handle the 'edit own simpletest_example' permission string correctly, so a user with only that permission will not be able to edit it. In this test we'll create a node and then try to edit it.

Run the test and see the result.

Unit Testing

Simpletest also provides a DrupalUnitTestCase as an alternative to the DrupalWebTestCase.

The database tables and files directory are not created for unit tests. This makes them much faster to initialize than functional tests but means that they cannot access the database or the files directory. Calling any Drupal function that needs the database will throw exceptions. These include routine functions like watchdog(), module_implements(), module_invoke_all() etc.

More information about writing unit tests for Drupal can be found at Unit Testing with Simpletest.

When to use t() in simpletests

Unlike most strings in Drupal, strings in simpletest should not always be enclosed in t(). This is for two reasons:

1. Most strings used in simpletest are for testing only and not used on any website, so they are not translated.
2. It is simpler to provide performant, robust test coverage when different components are decoupled as much as possible (which means not running code like t() from other subsystems when it is not needed).

When to use t()

Use t() in your test methods in the following cases:

• When you are specifically testing functionality related to translation and localization.
• When you are testing for the presence of a string that is already translated in the user interface. For example, to check for the presence of the "Access denied" message on a 403 page, use the following code:
  
  <?php
$this->assertText(t('Access denied'), 'Access denied message found on forbidden foo page.');
?>
  
  Note that the first string, 'Access denied', is provided by drupal_deliver_html_page() and translated there with t(). Therefore, we also use t() when checking for the presence of this message.

When not to use t()

Do not use t() in:

• Strings in getInfo().
• Test assertion messages. Repeating the example from above:
  
  <?php
$this->assertText(t('Access denied'), 'Access denied message found on forbidden foo page.');
?>
  
  The second string, 'Access denied message found on forbidden foo page.', is for the test runner's information only, and so it is not translated.
• Test module and theme output, unless the test module is intended to test translation functionality.

In all the cases above, you can use format_string() if you need to format and sanitize variables for output in the string.

Debugging Simpletests

In the testing settings (admin/config/development/testing/settings) there is an option "Provide verbose information when running tests ". If you turn this on, every drupalGet() and every drupalPost() will be captured as an HTML file, which will be available for you to view in the test results. This is a tremendously important tool.

You can also use $this->verbose("some message") and the message you provide will be shown when verbose information is being displayed.

More information on debug() and $this->verbose() can be found on Boombatower's blog about debugging in Drupal 7.

Where to go from here

• Several of the API functions and assertions are documented in this section.
• Reading through drupal_web_test_case.php is instructive

Note: A Google Docs presentation to go with this material is maintained by rfay.