Aside from doc blocks, one of the most useful ways to document your test is by using the PHPunits
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
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
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
If we run:
phpunit --testdox-text UserTest.txt UserTest:
We would end up with a text document like below.
– User cannot be under 16
– User must be male.
Alternatively we can replace
--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
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.
testUserCannotBeUnder16AndUserMustBeMale() should most likely be