Data-driven testing with PHPUnit

Testing your code is an essential part of the development process, but sometimes it could also be expensive when you try to emulate many uses cases based on a set of different input data.

In many cases, you could end up with a massive directory of tests repeating the same block of code over and over for each possible user interaction.

Take for example this case:
Let’s say you are writing an application to transform markdown documents into HTML, so you probably need to handle at least the following methods:

- Transform h1 tags
- Transform code
- Transform links
- ...

Just to mention some of them.

One solution to add tests to each case would be having a method for each one of the Transformers:

class ExampleTest extends TestCase
{
  /** @test */
  public function transform_title()
  {
      //
  }
 
  /** @test */
  public function transform_code()
  {
      //
  }
 
  /** @test */
  public function transform_links()
  {
      //
  }
}

What’s the problem with that?

In the previous example, it is more likely that all the methods would share the same structure: a given input, the transform method or class, and the expected output.

Now imagine if you have 50 different transformers in your application, this test file is going to be huge.

Introducing data-driven testing

TL;DR
Data-driven testing (DDT) is a term used in the testing of computer software to describe testing done using a table of conditions directly as test inputs and verifiable outputs as well as the process where test environment settings and control are not hard-coded.

On this approach, you define a set of data that will drive your tests for each of the possible combinations.

$dataSet = [
    ['some A', TransformerA::class, 'expected output A'],
    ['some B', TransformerA::class, 'expected output B'],
    ['some C', TransformerA::class, 'expected output C'],
]

Then in your tests, you can use something like the following:

class ExampleTest extends TestCase
{
    /** @test */
    public function transform_content()
    {
        $dataSet = $this->dataSet();
 
        foreach($dataSet as $data) {
            $value = $data[0]
            $class = new $data[1];
            $expected = $data[2]
            $this->assertEquals($expected, $class->process($value));
        }
    }
 
    public function dataSet()
    {
        return [
            ['# Title #', TitleTransformer::class, '<h1>Title</h1>'],
            ['`$var`', CodeTransformer::class, '$var'],
            ['[Link](http://laravel-news.com)', LinkTransformer::class, '<a href="http://laravel-news.com">Link</a>']
        ]
    }
}

Here we are assuming that all the transformers class share the same interface or contract, with a process() method to handle the given input.

Data-driven testing an PHPUnit

Although this seems to be a good solution, PHPUnit has a more elegant way to work with this pattern.

PHPUnit uses some useful Annotations that you can use to simplify your code, for example instead of:

public function test_some_method_name()
{
 
}

PHPUnit uses the test prefix to identify which methods of a test class are test methods.

You can use:

/** @test **/
public function some_method_name()
{
 
}

In this case, you can remove the test_ prefix by adding a comment with the text @text to identify the testing method.

Now let’s use the @dataProvider Annotation in the previous example:

class ExampleTest extends TestCase
{
    /*
     * @test
     * @dataprovider dataSet
     */
    public function transform_content($input, $class, $expected)
    {
        $class = new $class;
        $this->assertEquals($expected, $class->process($value));
    }
 
    public function dataSet()
    {
        return [
            ['# Title #', TitleTransformer::class, '<h1>Title</h1>'],
            ['`$var`', CodeTransformer::class, '$var'],
            ['[Link](http://laravel-news.com)', LinkTransformer::class, '<a href="http://laravel-news.com">Link</a>']
        ]
    }
}

What’s happening here is that internally, PHPUnit is iterating over each set of data defined in the dataSet method, and passing each argument to the transform_content() method.

Now, if you receive a failure on any set of data, you’ll see something like this:

There was 1 failure:
 
1) TestsUnitExampleTest::transform_content with data set #1 ('# Title #', TitleTransformer::class, '<h1>Title</h1>')
...

As you can see, this can be very confusing, but we can improve it by adding a key name to each dataset like so:

public function dataSet()
{
    return [
        'Transform titles' =&gt; ['# Title #', TitleTransformer::class, '<h1>Title</h1>'],
        'Transform code text' =&gt; ['`$var`', CodeTransformer::class, '$var'],
        'Transform links' =&gt; ['[Link](http://laravel-news.com)', LinkTransformer::class, '<a href="https://laravel-news.com">Link</a>']
    ]
}

Then you can see something like the following in case of failure:

There was 1 failure:
 
1) TestsUnitExampleTest::transform_content with data set "Transform titles" ('# Title #', TitleTransformer::class, '<h1>Title</h1>')
...

Extra tip

You can even have a custom iterator by writing a class that implements the Iterator interface

use PHPUnitFrameworkTestCase;
 
class CustomIterator implements Iterator {
    protected $key = 0;
    protected $current;
 
    public function __construct()
    {
        //
    }
 
    public function __destruct()
    {
        //
    }
 
    public function rewind()
    {
        //
    }
 
    public function valid() {
        //
    }
 
    public function key()
    {
        //
    }
 
    public function current()
    {
        //
    }
 
    public function next()
    {
        //
    }
}

Here you can learn more about how to use a data provider that returns an Iterator object.

This article was inspired by Paul Redmond and some of his work on this HTML to AMP package.