Running PHPUnit with a specific data provider set

Recently when writing some tests using a data provider in PHPUnit, I wanted to be able to re-run a specific set, rather than the test with every single set in the data provider. I discovered the filtering options available in PHPUnit were a lot more powerful than I'd first thought.

Note: this blog post has an accompanying repository which can be found here - the code used in this post is all in that repository and you can clone / run it yourself to try it out.

Full suite

Running our full test suite gives us the following:

Command:

vendor/bin/phpunit

Output:

........                                                            8 / 8 (100%)

Time: 19 ms, Memory: 4.00MB

OK (8 tests, 8 assertions)

Filtering

You can filter PHPUnit to run a specific test method like so:

Command:

vendor/bin/phpunit --filter it_adds_two_numbers_together

Output:

....                                                                4 / 4 (100%)

Time: 35 ms, Memory: 4.00MB

OK (4 tests, 4 assertions)

You can even run all test methods within a test class using the filters too:

Command:

vendor/bin/phpunit --filter AdderTest

Output:

....                                                                4 / 4 (100%)

Time: 38 ms, Memory: 4.00MB

OK (4 tests, 4 assertions)

Filtering data providers

Our test for it_adds_two_numbers_together relies on a @dataProvider in PHPUnit:

public function number_provider(): array
{
    return [
        '2 plus 2'     => [2, 2, 4],
        '2 plus 3'     => [2, 3, 5],
        '1 plus 3'     => [1, 3, 4],
        '123 plus 123' => [123, 123, 246],
    ];
}

Filtering by the test runs all 4 sets in the data provider. I wanted to be able to run a specific set (for example, the set named 2 plus 3)

After checking the documentation for PHPUnit, I noticed that the filter option allows you to use some regex-y style strings to match certain sets within a data provider - so I tried that:

Command:

vendor/bin/phpunit --filter '/::it_adds_two_numbers_together .*"2 plus 3"$/' 

Output:

.                                                                   1 / 1 (100%)

Time: 18 ms, Memory: 4.00MB

OK (1 test, 1 assertion)

Success! But, the syntax for it seemed a bit fiddly - however, there’s some handy shortcuts for filters that can help us to reduce it down to something that seems much easier to remember:

Command:

vendor/bin/phpunit --filter 'it_adds_two_numbers_together@2 plus 3' 

Output:

.                                                                   1 / 1 (100%)

Time: 36 ms, Memory: 4.00MB

OK (1 test, 1 assertion)

Success once again! And we can still use regex-y style strings to match things. If I wanted to run anything with a data set that ended in plus 3 (which is 2 sets in our example) I could use:

Command:

vendor/bin/phpunit --filter 'it_adds_two_numbers_together@.*plus 3'  

Output:

..                                                                  2 / 2 (100%)

Time: 20 ms, Memory: 4.00MB

OK (2 tests, 2 assertions)

The documentation has all the filter options available to it, I really found these helpful when working with data sets (especially named data sets)