Hidden Meaning

Good tests should:

  • Run quickly
  • Fail meaningfully
  • Document the system under test
  • Explain themselves when they go wrong

Consider the following test:

public void restApi() {
    int response = client.get("/endpoint");

    // the status code returned from the get
    // should be OK, indicating
    // the endpoint is healthy
    assertEquals(200, response);

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…

In Summary

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.

One comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s