Unit testing part 2: Writing and running tests

Tags:

Continuing from the unit test introduction, we will now continue and take a look at how to write tests and ways to run the tests.

Setting up PHPUnit

Before we can write tests, we need a testing tool. We are going to use PHPUnit for our examples, so you will need to install it.

The easiest way to install it is through PEAR. Read the PHPUnit installation guide for information on how to do that.

You will also need to be able to run PHP on the command line, including the phpunit command-line script. If you’re on Linux, chances are you already have PHP available on the command line – if not, the package for installing command-line PHP is usually something like php5-cli or such.

I have previously written a post on setting up command-line PHP on windows, which you can read to make it work on Windows.

To confirm everything works as expected, run a shell or command prompt and type in:

phpunit --version

which should output something like this:

PHPUnit 3.3.17 by Sebastian Bergmann.

Using PHPUnit

Next, let’s take a look at how to use PHPUnit so that we know how to use it when we actually start writing some real tests.

Writing a testcase

PHPUnit tests are written as testcase classes, which extend PHPUnit_Framework_TestCase. Let’s take a simple example to show you how they work.
For this example, we will just write a quick test for PHP’s array and count function.

class ArrayTest extends PHPUnit_Framework_TestCase {
  public function testAddingItemsIncreasesLength() {
    $array = array();
    $expectedLength = count($array) + 1;
 
    $array[] = 'foo';
    $this->assertEquals($expectedLength, count($array), 'Length was not correct');
  }  
}

As you can see from the code here, our test class is called ArrayTest and it extends from the PHPUnit testcase class. The naming convention for classes such as this is usually ClassNameTest – for example, a testcase for Zend_Controller_Action would be called Zend_Controller_ActionTest.

The ArrayTest class contains one method: testAddingItemsIncreasesLength. This is a test method. The convention for PHPUnit is that test methods are named testDescriptionOfWhatIsTested, so since our test checks that when we add an item into the array, the count is increased by one, our test is called testAddingItemsIncreasesLength. You can write as many test methods in a testcase as you think is necessary.

The code in the test method should be quite easy to understand – we create an array, calculate what the expected length of the array should be, push an item into the array and finally we have an assertion that confirms the result is as we expected. You can find a list of assertions you can do in the PHPUnit manual.

Running tests

Now that we have a test, how do we run it? These are the usual ways to do it:

  1. The most straightforward way is to run a single testcase with phpunit, like this: phpunit NameOfTest, so to run our ArrayTest, we can do phpunit ArrayTest. Note that this assumes you are in the directory where the test is saved, and that the filename is ArrayTest.php.
  2. Writing a test suite. This is complex and annoying to maintain, so I won’t go into it any more. If you really want to know, there’s a chapter on it in the PHPUnit manual.
  3. Using an XML configuration file. This is the easiest way to run multiple tests, so we’ll take a look at writing this next.

Since most of the time you’ll want to run all of your tests, or you have more than one test that you want to run, doing it manually with phpunit SomeTest isn’t very feasible. Option #2 can be used to run multiple tests in one go, but as said, it’s not exactly a very good method.

So to run multiple tests, we’ll use method #3 – an XML configuration file. This file can be named whatever you want, but it’s probably a good idea to call it phpunit.xml because that means phpunit will detect it automatically.

Here’s an example phpunit.xml configuration file:

<phpunit>
	<testsuite name="Test suite name">
		<directory>path/to/tests</directory>
	</testsuite>
</phpunit>

This is the simplest possible xml configuration. All we define is a testsuite element with a name attribute, and a path to the tests.

The typical directory layout for tests is like this:

project/tests
project/tests/phpunit.xml
project/tests/App/SomeClassTest.php (this is a test for class App_SomeClass)

In this case, you would set the directory in the phpunit.xml file to . to tell it the tests are in the current dir, like this:

<phpunit>
	<testsuite name="My tests">
		<directory>.</directory>
	</testsuite>
</phpunit>

Using this kind of a configuration file, we can now easily run all our tests by just typing phpunit on the command-line, and phpunit will then read the config and execute all tests, providing us with feedback about the process.

The configuration file has other options you can add to it too. We won’t look at other properties in this post, but you can find a list of configuration options from the PHPUnit manual.

Next week’s post

Next week we will finally get to actually writing some tests for some example methods. We’ll take a look at a class or two, and look at how to write good tests for it: Unit testing 3: writing tests for existing code

I’d like to apologize to those of you who were waiting for that to show up in this week’s post – I kind of forgot that explaining how to run tests and all that would need it’s own post, and posting that before going any further made more sense.