Data Provider Docstrings

For a tl;dr, skip to the final gist.

I'm a big believer in BDD-style testing. And by that I mean testing the behaviour of your code, and expressing your tests in those terms.

In PHPUnit, this tends to mean that instead of having a test outline like this:

  • EventMatcherTest
    • testConstructor
    • testSetEvents
    • testGetEvents
    • testMatchEvent
    • providerMatchEvent

You have something that looks more like this:

  • EventMatcherTest
    • test_matchEvent_does_exact_name_match
    • test_matchEvent_does_alias_name_match
    • test_matchEvent_does_shortname_match
    • test_matchEvent_falls_back_to_closest_match
    • test_matchEvent_ignores_different_dates
    • test_matchEvent_doesnt_match_wrong_way_around
    • test_matchEvent_doesnt_match_if_nothing_similar

However, this week I was editing a test someone else had written that used a dataProvider, I tend to stay away from these because it can often be a bit opaque as to what each data set is actually testing. However, I don't dislike them enough to merit completely re-writing someone else's reasonably good passing test.

I needed to add an additional case to this data provider, but it wasn't entirely clear which cases had already been covered. I went through adding a comment to each one, so they looked like this:

But then I realised that I could turn the comments into code, by setting the array keys!

The biggest benefit of this approach is that instead of getting test failure output like this:

1) EventMatcherTest::testMatchEventsSucceeds with data set #0 (array('Man Utd', 'Arsenal'), 'Man Utd vs Arsenal')

You get output like this:

1) EventMatcherTest::testMatchEventsSucceeds with data set "Exact match" (array('Man Utd', 'Arsenal'), 'Man Utd vs Arsenal')

These strings also appear in the TAP and junit formatter output, and can be used with the --filter switch.