An Introduction to Unit Testing

To be successful, a unit testing framework needs to have certain properties, including the following:

• Automated The system should run all the tests necessary with no interaction from the programmer.

• Easy to write The system must be easy to use.

• Extensible To streamline efforts and minimize duplication of work, you should be able to reuse existing tests when creating new ones.

To actually benefit from unit testing, we need to make sure our tests have certain properties:

• Comprehensive Tests should completely test all function/class APIs. You should ensure not only that the function APIs work as expected, but also that they fail correctly when improper data is passed to them. Furthermore, you should write tests for any bugs discovered over the life of the library. Partial tests leave holes that can lead to errors when refactoring or to old bugs reappearing.

• Reusable Tests should be general enough to usefully test their targets again and again. The tests will be permanent fixtures that are maintained and used to verify the library over its entire life span.

Writing Unit Tests for Automated Unit Testing

For the testing framework discussed in this chapter, we will use PEAR's PHPUnit. PHPUnit, like most of the free unit testing frameworks, is based closely on JUnit, Erich Gamma and Kent Beck's excellent unit testing suite for Java.

Installing PHPUnit is just a matter of running the following (which most likely needs root access):

# pear install phpunit

Alternatively, you can download PHPUnit from http://pear.php.net/PHPUnit.

Writing Your First Unit Test

A unit test consists of a collection of test cases. A test case is designed to check the outcome of a particular scenario. The scenario can be something as simple as testing the result of a single function or testing the result of a set of complex operations.

A test case in PHPUnit is a subclass of the PHPUnit_Framework_TestCase class. An instance of PHPUnit_Framework_TestCase is one or several test cases, together with optional setup and tear-down code.

The simplest test case implements a single test. Let's write a test to validate the behavior of a simple email address parser. The parser will break an RFC 822 email address into its component parts.

class EmailAddress {
  public $localPart;
  public $domain;
  public $address;
  public function _ _construct($address = null) {
    if($address) {
      $this->address = $address;
      $this->extract();
    }
  }
  protected function extract() {
    list($this->localPart, $this->domain) = explode("@", $this->address);
  }
}

To create a test for this, you create a TestCase class that contains a method that tests that a known email address is correctly broken into its components:

require_once "EmailAddress.inc";
require_once 'PHPUnit/Framework/TestCase.php';

class EmailAddressTest extends PHPUnit_Framework_TestCase {
  public function _ _constructor($name) {
    parent::_ _constructor($name);
  }
  function testLocalPart() {
    $email = new EmailAddress("george@omniti.com");
    // check that the local part of the address is equal to 'george'
    $this->assertTrue($email->localPart == 'george');
  }
}

Then you need to register the test class. You instantiate a PHPUnit_Framework_TestSuite object and the test case to it:

require_once "PHPUnit/Framework/TestSuite.php";
$suite = new PHPUnit_Framework_TestSuite();
$suite->addTest(new EmailAddressTest('testLocalPart'));

After you have done this, you run the test:

require_once "PHPUnit/TextUI/TestRunner.php";
PHPUnit_TextUI_TestRunner::run($suite);

You get the following results, which you can print:

PHPUnit 1.0.0-dev by Sebastian Bergmann.

.

Time: 0.00156390666962

OK (1 test)

Adding Multiple Tests

When you have a number of small test cases (for example, when checking that both the local part and the domain are split out correctly), you can avoid having to create a huge number of TestCase classes. To aid in this, a TestCase class can support multiple tests:

class EmailAddressTestCase extends PHPUnit_Framework_TestCase{

  public function _ _constructor($name) {
    parent::_ _constructor($name);
  }
  public function testLocalPart() {
    $email = new EmailAddress("george@omniti.com");
    // check that the local part of the address is equal to 'george'
    $this->assertTrue($email->localPart == 'george');
  }
  public function testDomain() {
    $email = new EmailAddress("george@omniti.com");
    $this->assertEquals($email->domain, 'omniti.com');
  }
}

Multiple tests are registered the same way as a single one:

$suite = new PHPUnit_FrameWork_TestSuite();
$suite->addTest(new EmailAddressTestCase('testLocalPart'));
$suite->addTest(new EmailAddressTestCase('testDomain'));
PHPUnit_TextUI_TestRunner::run($suite);

As a convenience, if you instantiate the PHPUnit_Framework_TestSuite object with the name of the TestCase class, $suite automatically causes any methods whose names begin with test to automatically register:

$suite = new PHPUnit_Framework_TestSuite('EmailAddressTestCase');
// testLocalPart and testDomain are now auto-registered
PHPUnit_TextUI_TestRunner::run($suite);

Note that if you add multiple tests to a suite by using addTest, the tests will be run in the order in which they were added. If you autoregister the tests, they will be registered in the order returned by get_class_methods() (which is how TestSuite extracts the test methods automatically).