PHPUnit Skeleton Classes

If you create classes in PHP then you should be unit testing them as much as you can. Setting up unit testing classes for your code can be time consuming and involve a bunch of copying and pasting. Thankfully, PHPUnit comes with a couple of helper functions that allow the creation of unit testing classes automatically, which can save a bit of copying and pasting.

As an example for this post I will use the following Spider class, which is part of some code I am working on at the moment to create a simple site spider in PHP.

<?php

class Spider {

    protected $queue = array();
    protected $urlLimit = 0;

    /**
     * Return a list of file types that are not to be downloaded.
     *
     * @return array The list of extensions to be excluded.
     */
    public function excludedFileExtensions() {
        $extensions = array('pdf', 'exe', 'zip', 'css', 'js', 'gz', 'tar', 'mp3', 'wav', 'flv', 'doc', 'docx', 'odp', 'psd', 'jpg', 'jpeg', 'png', 'gif');
        return $extensions;
    }

    /**
     * Set the hard limit on the number of links to find on a site. Once this
     * limit has been reached the loop will stop finding new pages.
     *
     * @param integer $limit The limit to be set.
     *
     * @return SitemapSpider The current object.
     */
    public function setUrlLimit($limit) {
        $this->urlLimit = $limit;
        return $this;
    }

    /**
     * Add an item to the queue.
     *
     * @param string $url The URL 
     */
    public function enqueue($url) {
        $this->queue[$url] = $url;
    }

    /**
     * Tests to see if a given string is a URL.
     *
     * @param string $url The string to test.
     *
     * @return boolean True if string is URL, otherwise false.
     */
    public function validUrl($url) {
        return preg_match('|^http(s)?://[a-z0-9-]+(.[a-z0-9-]+)*(:[0-9]+)?(/.*)?$|i', $url);
    }
}

Calling phpunit with the --skeleton-test flag will allow us to create unit testing classes for any class we stipulate. To do this with the above code, assuming that the class is in the file Spider.php, then we can run the following command.

phpunit --skeleton-test Spider Spider.php

The final parameter (Spider.php) is optional, but will only work if the file name is the same as the class name (with a .php extension at the end).

This creates a skeleton unit testing class ready for the actual unit tests to be implemented. Every method that was defined in the original class has its own test method in the unit testing class. Each test contains a call to markTestIncomplete(), which forces PHPUnit to skip the test and mark it as incomplete. When running the class through the command line this produces an "I" in the output. This class also includes the setUp() and tearDown() methods that are run before and after every test.

Here is the example unit testing class generated from the above command.

<?php

require_once 'C:\path\to\class\Spider.php';

/**
 * Test class for Spider.
 * Generated by PHPUnit on 2011-07-22 at 16:44:10.
 */
class SpiderTest extends PHPUnit_Framework_TestCase
{
    /**
     * @var Spider
     */
    protected $object;

    /**
     * Sets up the fixture, for example, opens a network connection.
     * This method is called before a test is executed.
     */
    protected function setUp()
    {
        $this->object = new Spider;
    }

    /**
     * Tears down the fixture, for example, closes a network connection.
     * This method is called after a test is executed.
     */
    protected function tearDown()
    {
    }

    /**
     * @todo Implement testExcludedFileExtensions().
     */
    public function testExcludedFileExtensions()
    {
        // Remove the following lines when you implement this test.
        $this->markTestIncomplete(
          'This test has not been implemented yet.'
        );
    }

    /**
     * @todo Implement testSetUrlLimit().
     */
    public function testSetUrlLimit()
    {
        // Remove the following lines when you implement this test.
        $this->markTestIncomplete(
          'This test has not been implemented yet.'
        );
    }

    /**
     * @todo Implement testEnqueue().
     */
    public function testEnqueue()
    {
        // Remove the following lines when you implement this test.
        $this->markTestIncomplete(
          'This test has not been implemented yet.'
        );
    }

    /**
     * @todo Implement testValidUrl().
     */
    public function testValidUrl()
    {
        // Remove the following lines when you implement this test.
        $this->markTestIncomplete(
          'This test has not been implemented yet.'
        );
    }
}

I should point out here that the unit testing class that is generated is enough to get you started in testing the class, but shouldn't be relied upon as a complete testing framework. There is a fine line between testing methods and testing functionality, which is probably the basis of a post all of its own. The final unit testing class should look very different from the file generated here, but this is a good way to get up and running quickly.

It is also possible to generate classes from existing unit testing classes by using the --skeleton-class flag. This is the exact opposite from the method described above and is used if you create your unit testing classes first. To create a simple class from the existing SpiderTest unit testing class that we created above we would do the following.

As before, the final parameter can be omitted here, but only if the filename matches the class name. This creates a simple skeleton class that can be used as a code template. Below is a typical example of the output from the above command.

<?php
/**
 * Generated by PHPUnit on 2011-07-22 at 17:10:51.
 */
class Spider
{}
?>

One important thing to note here is that this can delete your existing class files if you aren't careful. The generated file above always has the same structure as this so any code you already have will be overwritten by this action.