Using PHPUnit's dataProvider for comprehensive failure testing

Writing tests to make sure your application handles failure conditions appropriately is one of the more difficult things to do. It's much easier to write a unit test case to make sure a function or method works when correct parameters are passed. PHPUnit provides some features that will enable you to easily write robust tests to test those failure conditions. Today I'm going to talk about using PHPUnit's dataProvider functionality.

Suppose you had the following static method:

class Example
{

    /**
     * An example method
     *
     * @param   array  $data
     * @return  void
     */
    public static function one($data)
    {

        if (!is_array($data)) {
            throw new Exception('Array expected');
        }

        if (!array_key_exists('one', $data)) {
            throw new Exception('Key (one) is required');
        }

        if (!array_key_exists('two', $data)) {
            throw new Exception('Key (two) is required');
        }

        $data['one'] = true;
        $data['two'] = false;
        return $data;
    }
}

Let's use PHPUnit's dataProvider to test all the failure conditions of the method Example::one(). Data providers must return an array of arrays representing the parameter set of the test method. In this case we are going to have a test method that accepts 3 parameters; a data set, an exception type, and an exception message.

class ExampleTest extends PHPUnit_Framework_TestCase
{
    /**
     * Test failure
     *
     * @test
     * @dataProvider failureDataProvider
     * @return  void
     */
    public function failure($data, $exception, $message)
    {
        $this->setExpectedException($exception, $message);
        Example::one($data);
    }
}

As you will notice, the PHPDoc of the test method defines the data provider method name using the '@dataProvider' tag. Let's define the data provider.

    /**
     * Failure Data Provider
     * @return  array
     */
    public function failureDataProvider()
    {
        return array(
            array('', 'Exception', 'Array expected'),
            array(false, 'Exception', 'Array expected'),
            array('foo', 'Exception', 'Array expected'),
            array(new Example(), 'Exception', 'Array expected'),
            array(array(), 'Exception', 'Key (one) is required'),
            array(array('somekey' => 'somevalue'), 'Exception', 'Key (one) is required'),
            array(array('one' => 'somevalue'), 'Exception', 'Key (two) is required'),
        );
    }

In this data provider we test all the possible failure conditions for the method Example::one(). Using a data provider keeps your tests clear and concise and enables the addition of additional test parameters with ease. All you need to do is simply add another array to test a new value. Let's see the result of our test.

# phpunit --verbose ExampleTest.php
PHPUnit 3.3.9 by Sebastian Bergmann.

ExampleTest
 ExampleTest::failure
 .......

Time: 0 seconds

OK (7 tests, 14 assertions)

The data provider functionality makes it easy to test large combinations of parameters for any method. Read more about the data provider functionality in the PHPUnit documentation.