Good tests should:
- Run quickly
- Fail meaningfully
- Document the system under test
- Explain themselves when they go wrong
Consider the following test:
You can follow the code of the above test, and you might have an idea of what the test is trying to prove.
If/when it fails, the error will be something like
assertion failure: 401 is not 200 which means what exactly?
But It’s Documented!
Yes. That’s the annoying thing. There’s a great big comment in the middle of the code saying what it’s testing… but that comment is never going to appear in the output of the test – the console log and the test report.
If only someone had named the test method
healthCheckEndpointReturnsOk or had added some additional reporting to the assertion explaining what it was asserting…
With a good assertion framework, you don’t really need to write too many messages explaining what the assertion means, though it can add value.
With a good test name, and tests that test simple single things, the fact that the test fails should document what went wrong.
Overall, though, hiding the why of a test inside a comment is neither use nor ornament. You want the context and meaning of a test to appear in the test report.