Software Development

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.

Published on Java Code Geeks with permission by Ashley Frieze, partner at our JCG program. See the original article here: Hidden Meaning

Opinions expressed by Java Code Geeks contributors are their own.

Ashley Frieze

Software developer, stand-up comedian, musician, writer, jolly big cheer-monkey, skeptical thinker, Doctor Who fan, lover of fine sounds
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button