What to Put in Test Docblocks

There’s a great article on dockblocks in tests that has some really good advice. Sometimetimes a good test name isn’t enough and there should be some more context.

Here are some other things I like to put in PHPUnit test docblocks.

For Bugs & Bug Fixes

/**
 * @group https://github.com/owner/repo/issues/1111
 * @group regression
 */
public function testExample()
{
    // ...
}

In other words, I like to put the bug URL as well as a tag the test as a regression test — if it fails, something that was previously fixed got broken again.

The url @group means just the tests related to that bug can be run simply:

phpunit --group https://github.com/owner/repo/issues/1111

Database or Tests with a Network Required

This happens from time to time because we live in the real world where not all tests are 100% isolated. I don’t bother tagging tests that use SQLite as a database backend, but some tests will require an actually DBMS as a backing service.

/**
 * @group database
 */
public function testExample()
{
    // ...
}

Similarly if I have some tests that require network access I’ll tag them as such. A good example would be running an integration test on a HTTP client with something like httpbin.

/**
 * @group network
 * @group integration
 */
public function testExample()
{
    // ...
}

I may also tag tests like this with @group integration.

Database and networked backed tests tend to take longer, and the @group annotations make them easy to exclude if working on an unrelated part of the app.

phpunit --exclude-group database,network

Shouldn’t Tests be Fast Anyway?

Sure. But the real world sometimes place demands on applications and tests that prevents that. I find my most useful tests are fast, but that doesn’t mean that integration tests like the above are not useful or valuable.