I'm a big fan of using PHPUnit's data providers feature because it allows you to easily run a lot of data through the same kinds of tests over and over again without having a bunch of duplicate code sitting around. But they aren't always the easiest thing to come back to an understand.

The data provider itself is a public function that returns an array of arrays containing the various pieces of data you want to pass to the test function.

public function dataProviderIndexOf()
{
    return array(
        array('haystack', 'needle', -1),
    );
}

When you declare the test function you need to declare the data provider using using the annotation below:

/**
* @dataProvider dataProviderIndexOf
*/
public function testIndexOf($input, $test, $expected)
{
    $string = new StringObject($input);

    $this->assertSame($expected, $string->indexOf($test));
}

When PHPUnit runs into this test with the @dataProvider annotation it loops through the data running the test with each array returned from the data provider.

The downside to running it the way I have it above is that when there's an error it's hard to tell why the test exists because the data passed to the function is referred to as data set #0 ('haystack', 'needle', -1) which is less than helpful if your trying to debug someone else's test.

PHPUnit 3.7.38 by Sebastian Bergmann.

Configuration read from /Users/scottkeckwarren/Projects/PHPO/tests/phpunit.xml

........F..........

Time: 40 ms, Memory: 3.00Mb

There was 1 failure:

1) ChainablePHP\StringObjectTest::testIndexOf with data set #0 ('haystack', 'needle', -1)
Failed asserting that 0 is identical to -1.

/Users/scottkeckwarren/Projects/PHPO/tests/Objects/StringObjectTest.php:30

It turns out there's already a solution for this. By using an associative array you can explain the test data.

public function dataProviderIndexOf()
{
    return array(
        'Search for needle in haystack' => array('haystack', 'needle', -1),
    );
}

Output:

1) ChainablePHP\StringObjectTest::testIndexOf with data set "Search for needle in haystack" ('haystack', 'needle', -1)
Failed asserting that 0 is identical to -1.

The nice thing about this is then you can filter based on the name when just that piece of data is failing.

phpunit --filter "Search for needle in haystack"

Like this post? Don't forget to follow us on Twitter and Facebook for updates.