Dependencies in PHPUnit tests

PHPUnit 3.4 now supports dependencies between different test methods. It allows you to execute a particular test ONLY IF the test that it depends on executes successfully. Take the following example (Listing 1.) where we test a linked-list class I developed earlier.

A simple unit-test with PHPUnit

The test basically creates a link-list with 100 nodes, and tests a few class methods – reverseList, deleteFirstNode, deleteLastNode. As you can see the linklist creation part and method tests are combined in the single test method testLinkList().

The primary focus here is on testing the three class functions. There is nothing wrong with this. But what if the linklist creation part itself fails before the other tests are conducted? Of course we can add another test to check that the links are being created correctly, but that mixes up the two parts.

Listing 1.

<?php
 
require_once 'linklist.class.php';
require_once 'PHPUnit/Framework.php';
 
class LinkListTest extends PHPUnit_Framework_TestCase
{
    /* How many nodes to create */
    private $_nNodes = 100;
 
    public function testLinkList()
    {
        /* Linklist creation block */
        $theList = new LinkList();
 
        for($i=1; $i <= $this->_nNodes; $i++)  
        {
            $theList->insertLast($i);
        }
 
 
        /* 
            Linklist methods testing block :
 
            $theList->totalNodes() is a public function 
            in the 'linklist' class that returns the total
            number of nodes in the link-list.
        */
 
        $theList->reverseList();
        $this->assertEquals($this->_nNodes, $theList->totalNodes());
 
        $theList->deleteFirstNode();
        $this->assertEquals($this->_nNodes - 1, $theList->totalNodes());
 
        $theList->deleteLastNode();
        $this->assertEquals($this->_nNodes - 2, $theList->totalNodes());
    }
}
 
?>

Splitting up tests

A better way is to split the linklist creation part and class method testing part into two separate test functions as below (Listing 2). Here the linklist is created in the ‘testCreateList()’ method and the testing of the class methods is done in the ‘testLinkList()’ method. This allows us to keep the two testing blocks separate.

Listing 2.

<?php
 
require_once 'linklist.class.php';
require_once 'PHPUnit/Framework.php';
 
class LinkListTest extends PHPUnit_Framework_TestCase
{
    /* How many nodes to create */
    private $_nNodes = 100;
 
    public function testCreateList()
    {
        $theList = new LinkList();
 
        for($i=1; $i <= $this->_nNodes; $i++)
        {
            $theList->insertLast($i);
        }
        $this->assertTrue(!empty($theList));
 
        return $theList;
    }
 
    /**
     * @depends testCreateList
     */
    public function testLinkList($theList)
    {
        $theList->reverseList();
        $this->assertEquals($this->_nNodes, $theList->totalNodes());
 
        $theList->deleteFirstNode();
        $this->assertEquals($this->_nNodes - 1, $theList->totalNodes());
 
        $theList->deleteLastNode();
        $this->assertEquals($this->_nNodes - 2, $theList->totalNodes());
    }
}
 
?>

The important point to note here is that we have specified that the ‘testLinkList‘ method depends on the ‘testCreateList‘ method, with a @depends annotation. This tells PHPUnit that if the ‘testCreateList‘ test fails then the test dependent on it, ‘testLinkList‘, will have to be skipped, which is a logical way to go.

/**
 * @depends testCreateList
 */

Producers & Consumers in a Test

First some definitions:

a. A producer is a test method that yields its unit under test as return value.
b. A consumer is a test method that depends on one or more producers and their return values.

What it means is that a ‘Producer’ is a test method that returns some data that will be used by a ‘Consumer’ test method. In our example the ‘testCreateList‘ is a Producer and the ‘testLinkList‘ is the Consumer. The ‘testCreateList‘ method returns a linklist object which is then received by the dependent method ‘testLinkList‘. So if for some reason the ‘testCreateList‘ fails to return some data then the test that depends on it, ‘testLinkList‘, will have to be skipped, as it has nothing to work with.

Bear in mind that it does not mean that every test method that depends on some other method has to accept some arguments from the method it is dependent on. Lets breakup the above example further (Listing 3). Here we have added one more test method, ‘testNodesDefined‘, which makes sure that the ‘$_nNodes’ variable is not null. The ‘testCreateList‘ method is dependent on this method, so that if the ‘$_nNodes’ is null then the ‘testCreateList‘ is skipped, which causes the test ‘testLinkList‘ to be skipped.

Listing 3.

<?php
 
require_once 'linklist.class.php';
require_once 'PHPUnit/Framework.php';
 
class LinkListTest extends PHPUnit_Framework_TestCase
{
    /* How many nodes to create */
    private $_nNodes = 100;
 
    public function testNodesDefined()
    {
        $this->assertNotNull($this->_nNodes);
    }
 
    /**
     * @depends testNodesDefined
     */
    public function testCreateList()
    {
        $theList = new LinkList();
 
        for($i=1; $i <= $this->_nNodes; $i++)
        {
            $theList->insertLast($i);
        }
        $this->assertTrue(!empty($theList));
 
        return $theList;
    }
 
    /**
     * @depends testCreateList
     */
    public function testLinkList($theList)
    {
        $theList->reverseList();
        $this->assertEquals($this->_nNodes, $theList->totalNodes());
 
        $theList->deleteFirstNode();
        $this->assertEquals($this->_nNodes - 1, $theList->totalNodes());
 
        $theList->deleteLastNode();
        $this->assertEquals($this->_nNodes - 2, $theList->totalNodes());
    }
}
 
?>

A output from a failed test, when we set ‘$_nNodes’ to null, is shown below.
Listing 4.

D:\localhost\datastructures>phpunit --verbose LinkListTest
PHPUnit 3.4.2 by Sebastian Bergmann.
 
LinkListTest
FSS
 
Time: 0 seconds
 
There was 1 failure:
 
1) LinkListTest::testNodesDefined
Failed asserting that <null> is not null.
 
D:\localhost\test\datastructures\LinkListTest.php:13
 
There were 2 skipped tests:
 
1) LinkListTest::testCreateList
This test depends on "LinkListTest::testNodesDefined" to pass.
 
 
2) LinkListTest::testLinkList
This test depends on "LinkListTest::testCreateList" to pass.
 
 
FAILURES!
Tests: 1, Assertions: 2, Failures: 1, Skipped: 2.
 
D:\localhost\test\datastructures>

Note: The tests are executed in the sequence in which you wrote them. So take care while writing dependent tests. For example, sequencing test methods as below will not work.

    public function testNodesDefined()
    {
        $this->assertNotNull($this->_nNodes);
    }
 
    /**
     * @depends testCreateList
     */
    public function testLinkList($theList)
    {
        ..
    }
 
    /**
     * @depends testNodesDefined
     */
    public function testCreateList()
    {
        ..
    }

What all of this has brought us

Testing a complex class in a single humongous test method is not wrong, but can create a confusing mess of ‘asserts’. Splitting a single test method into multiple dependent tests can help you segregate your test methods by functionality which in turn will get you to quickly localize defects in your code.

1. Installing phpcpd
We will be using the PEAR installer for this purpose. First the PEAR channel that is used to distribute phpcpd needs to be registered with the local PEAR environment. This tells PEAR from where the install files should be downloaded.

c:\> pear channel-discover pear.phpunit.de
Adding Channel "pear.phpunit.de" succeeded
Discovery of channel "pear.phpunit.de" succeeded

After this is done the PEAR installer is ready to install phpcpd.

c:\> pear install phpunit/phpcpd
downloading phpcpd-1.1.1.tgz ...
Starting to download phpcpd-1.1.1.tgz (8,078 bytes)
.....done: 8,078 bytes
install ok: channel://pear.phpunit.de/phpcpd-1.1.1

Post installation you will find the PHPCPD source files in the PEAR directory.

2. Running your first check.
Here is our first check on the admin sub directory of a project with the results. You can check for duplicate code in a individual file or a directory.

c:\localhost\project> phpcpd ./admin
phpcpd 1.1.1 by Sebastian Bergmann.
 
Found 3 exact clones with 50 duplicated lines in 6 files:
 
  - .messages.php:95-105
    .messagesgroup.php:112-122
 
  - .viewschedules.php:14-23
    .tutorbookings.php:14-23
 
  - .ampieexport.php:4-35
    .amcolumnexport.php:4-35
 
0.35% duplicated lines out of 14456 total lines of code.

3. Options
By default phpcpd will search for a minimum of 5 identical lines and 70 identical tokens. So if there are less than 5 duplicate lines in the code or less than 70 identical tokens they will be ignored. To override this you can use the –min-lines and –min-tokens switch as below.

c:\localhost\project> phpcpd --min-lines 4 --min-tokens 40 ./admin
phpcpd 1.1.1 by Sebastian Bergmann.
 
Found 9 exact clones with 187 duplicated lines in 14 files:
 
  - .actionaction.updatestudent.php:15-27
    .actionaction.updatetutor.php:15-27
 
  - .adminFunctions.php:91-98
    .adminFunctions.php:124-131
 
  - .messages.php:95-118
    .messagesgroup.php:112-135
 
  - .viewschedules.php:14-84
    .tutorbookings.php:14-84
 
  - .viewschedules.php:167-185
    .tutorbookings.php:145-163
 
  - .tutors.php:14-20
    .dimdim.php:14-20
 
  - .ampieexport.php:4-44
    .amcolumnexport.php:4-44
 
  - .geoipgeoip.inc.php:236-241
    .geoipgeoip.inc.php:272-277
 
  - .studentschedule.php:14-20
    .Copy of onetomanyschedule.php:14-20
 
1.29% duplicated lines out of 14457 total lines of code.

The report generated by phpcpd can also be exported to a PMD-CPD xml format. The following scans the admin directory and saves the report in the projectPhpcpd.xml file.

c:\localhost\project> phpcpd --log-pmd projectPhpcpd.xml ./admin

Most of the php source files have the .php extension and phpcpd uses this by default when comparing files. To add other extensions to the list you can use the –suffixes option, which takes a comma separated list of extension names.

c:\localhost\project> phpcpd --suffixes php,php5 ./admin

Concluding thoughts
There is also a Java program called PMD which can detect duplicate code. But the main advantage of a PEAR package is that you can integrate it in your project itself or use it with phpUnderControl.

generatedata.com is one such tool. Generatedata lets you specify the database schema details and generates the dummy sql data for you, with table creation and complete inserts. The data can further be exported to html, excel, xml or csv formats. The tool is available online and there is also a downloadable version of the tool if you like to modify the code or need to install it on your server or development machine.

The tool also has an option to generate country specific data; currently limited to Canada,Netherlands,UK and the US. If you need to add other countries to the list, you have the option of modifying the code to suit your specific purpose. Even though there are many free tools available online with the same purpose, I find Generatedata to be simple to use.

In part 1 of this tutorial you have seen how to write a simple web test using Selenium. In this part we will see how to use the test generated using the IDE with Selenium RC and PHPUnit.

In this part we will use Delicious as our test target. I’ve already created a small Selenium test that you can use. You can download the HTML source from here.

Starting up.
Restart the Selenium IDE. In the source tab replace the default HTML with the one from the above file. Set the Base URL to http://delicious.com/. After doing this your IDE should like below.

If you are on a slow internet connection than it may help to slow the test speed.

So what exactly does this test do? Simple:

1. First it opens the delicious home page
2. Then it searches by the keyword ‘selenium’
3. Reads the total number of bookmarks from the results page as shown below

Now this may not look like a test for you , but it is just an exercise in using Selenium, you will surely apply it to a good test case. Onwards…

Before running this test make sure that you are logged out of Delicious.
Now run the selenium IDE test. After the test is successfully completed this is what you should see in the log pane.

Is that all?
If this was all there was I wouldn’t be really writing this post. The interesting part comes now – running the same test from PHP. From the file menu select ‘Export Test Case As…’ and as we are using PHP, select ‘PHP – Selenium RC’. Save the file by the name ‘Example.php’.

This is what we will get in the ‘Example.php’ file.

<?php
 
require_once 'PHPUnit/Extensions/SeleniumTestCase.php';
 
class Example extends PHPUnit_Extensions_SeleniumTestCase
{
  function setUp()
  {
    $this->setBrowser("*chrome");
    $this->setBrowserUrl("http://delicious.com/");
  }
 
  function testMyTestCase()
  {
    $this->open("/");
    $this->type("homepage-searchinput", "selenium");
    $this->click("homepage-searchsubmit");
    $this->waitForPageToLoad("30000");
    $this->getText("xpath=/html/body[@id='index']/div
                         [@id='doc3']/div[@id='bd']/div
                         [@id='yui-main']/div[@id='content']/h3/div/em");
  }
}
?>

A short notice.
Before we proceed a few points to consider. Make sure that the file name and the class name are the same, here ‘Example’. Say if you change the class name to ‘Delicious’ make sure that you also change the file name to ‘Delicious.php’.

What the code basically does is it initializes the browser to ‘chrome’ (you can set the browser to your preference by changing to ‘*iexplore’ or ‘*firefox’); sets the baseurl to ‘http://delicious.com/’ and runs the test.

Whats the complex looking line!?
Everything may look fine to you except maybe the last line – ‘$this->getText…’. The function ‘getText’ returns the text found at the element specified in the expression. The complex looking line is an xpath expression to the results element:

You don’t have to rake your brains to find an xpath to an element. An easy way is to use the XPather Firefox addon to get the xpath of any element on a page. After you download and install the addon, restart Firefox, right-click on any element and from the context menu select ‘Show in XPather’. XPather retrieves the xpath to the specified element, which you can than use in your test code.

Note: This site uses ‘delicious’ as an example, so even some minor changes made by them to their site will render the xpath invalid, throwing an ‘element not found’ error in selenium. If this happens please notify me or you can find the new xpath using the Xpather plugin.

Downloading and installing Selenium RC
Selenium RC is a Java based command line server that starts browsers and runs commands you pass from your tests.

1. First make sure you have a Java runtime installed on your machine.
2. Download Selenium RC from here.
3. After extracting the files from the archive copy the ‘selenium-server.jar’ file to any directory you feel appropriate. I copied it to my PHP installations bin directory.
4. Start the Selenium RC server from the command-line by issuing the following command:

java -jar selenium-server.jar

This will start the server on port 4444.
5. Now the server is ready to accept test commands from your PHP script. Make sure you keep this server running till you finish testing.

Installing PHPUnit
1. An easy way to install PHPUnit is to use the PEAR installer. The PEAR channel (pear.phpunit.de) is used to distribute PHPUnit so make sure that it is registered with your local PEAR environment:

pear channel-discover pear.phpunit.de

After the channel is registered install PHPUnit:

pear install phpunit/PHPUnit

Actual testing
Now that PHPUnit is installed and the Selenium RC server is up and running, its time to run our test we saved before in our ‘Example.php’ file. Type the following on your command-line:

phpunit Example

This will start the test. The PHPUnit Selenium driver will execute each test command from your file and send it to the Selenium server, which does the job of launching the appropriate browser, opening web pages, and performing various specified actions; and closing the browser after the test completes.

Now the above test does basically nothing important. So we will add some simple conditional statements to the code.

.
.
    $bookmarks = $this->getText("xpath=/html/body[@id='index']/div
                       [@id='doc3']/div[@id='bd']/div
                       [@id='yui-main']/div[@id='content']/h3/div/em");
 
    echo ($bookmarks > 3000)? "On the top" : "Still not there";
  }
}
 
?>

This is what PHPUnit has to say about the above test.

Or we can use an assertion as below, deliberately rigged to fail the test:

.
.
    $bookmarks = $this->getText("xpath=/html/body[@id='index']/div
                       [@id='doc3']/div[@id='bd']/div
                       [@id='yui-main']/div[@id='content']/h3/div/em");
 
    $this->assertGreaterThan(33000, $bookmarks);
 
 
 
 
 
    }
}
 
?>

Now PHPUnit will shout failure:

You can look at more functions to implement in your tests here and here.

This concludes the second part of the tutorial.