Documenting your PHP unit test

Like many other cool things writing methods in sentence format can make your life that little bit easier when doing TDD

Aside from doc blocks, one of the most useful ways to document your test is by using the PHPunits --testdox-test flag.

One of the wonderful things about this approach is that it allows you to easily keep your documentation up to date in a project where changes to the design and code are frequent.

It can also make your unit test more accessible to other memebers in your team who are not developers and also to new developers picking up your code. It also allows you to take advantage of the high level language approach used by behaviour based testing frameworks such as Behat.

Test method names as senetces

Dan North describes one of his first “Aha” moments when doing test-driven development was the fact that method names should be sentences. Likewise, in order to take full advantage of this feature you will need to write your test method names as senetences.

For example where you might have a method name like testUserAge() you will need to rename it into something more useful like testUserCannotBeUnder16().

PHPunit TestDox functionality will strip the word “test” from the method name and will replace the camel cased words into a senetence. So, the example above will read;

User cannot be under 16

Using TestDox

A general example will look like this;
phpunit –testdox-[format] [Name to give to produced file] [name of test class]

So, given we have a test class named UserTest and a test method named testUserCannotBeUnder16() and another named testUserMustBeMale().

If we run:
phpunit --testdox-text UserTest.txt UserTest:

We would end up with a text document like below.

User
– User cannot be under 16
– User must be male.

Alternatively we can replace --testdox-text with --testdox-html if we prefer the output in html.

Sentences make life easier

Writing unit test is often very challenging, being discplined enough to write your method names in the form of sentences will make life just that little bit easier.

If we look at the difference between the method named testUserAge() and testUserCannotBeUnder16(). The latter removes any ambguity with regards to exactly what you are trying to test.

This approach should also help improve the quality of your test. For example, if you name a method as a sentence that contains the word “and” or just reads like it is doing more than one thing, this should be an indication that you are trying to do to much in one method and you should probably break it up into two seperate methods.
For example, testUserCannotBeUnder16AndUserMustBeMale() should most likely be testUserCannotBeUnder16() and testUserMustBeMale().

Further reading

1. http://phpunit.de/manual/current/en/other-uses-for-tests.html#other-uses-for-tests.agile-documentation

2. http://dannorth.net/introducing-bdd/