Test Attribute #2: Readability

Code-Readability-Dec-2013_zpsddede0c3
This is the 2nd post on test attributes that were described in the now famous “How to test your tests” post.

We often forget the most of the value we get from tests come after we’ve written them. Sure, TDD helps design the code, but let’s face it, when everything works for the first time, our tests become the future guardians of our code. Once in place, we can change the code, hopefully for the better, knowing that everything still works.

But if (and when) something breaks, there’s work to be done. We need to understand what worked before that doesn’t now. We then need to analyze the situation: According to what we’re doing right now, should we fix this problem? Or is this new functionality that we now need to cover with new tests, throwing away the old one? Finally there’s coding and testing again, depending on the result of our analysis.

The more we move further in time, the tests and code get stale in our mind. Then we forget about them completely. The cost of the changes rises. The analysis phase becomes longer, because we need to reacquaint ourselves with the surroundings. We need to re-learn what still works, and what stopped working. Even if we knew, we don’t remember which  changes can cause side effects, and how those will work out.

Effective tests minimize this process. They need to be readable.

Readability is subjective.  What I find readable now (immediately after I wrote it), will not seem so in 6 months. Let alone to someone else.

So instead of trying to define test readability, let’s break it down to elements we care about, and can evaluate.

What A Name

The most important part of a test (apart from testing the right thing) is its name. The reason is simple: When a test breaks, the name is the first thing we see when the test fails. This is the first clue we get that something is wrong, and therefore, it needs to tell us as much as possible.

The name of a test should include (at least) the specific scenario and the expected result of our test. If we’re testing APIs, it should say that too.

For example:

@Test public void divideCounterBy5Is25() { ...

I can understand what the test does (a scenario about dividing Counter), the details (division by 5) and the expected result for this scenario (25).

If it sounds like a sentence – even better. Good names come from verbally describing them.

It doesn’t matter if you use capitalization, underscore, or whatever you choose. It is important that you use the same convention that your team agrees on.

Names should also be specific enough to mentally discern from other sibling tests. So, in our example:

@Test public void divideCounterBy0Throws() { ...

This test is similar enough to the first name to identify it as a “sibling” scenario, because of the resemblance in the prefix. The specific scenario and result are different. It is important, because when those two will appear together in the test runner, one fails and one doesn’t, it helps us locate the problem before even starting to debug. These are clues to resolve the problem.

What A Body

If our names don’t help locate the problem, the test body should fill the gaps. It should contain all the information needed to understand the scenarios.

Here are a few tips to make test code readable:

  • Tests should be short. About 10-15 lines short.
  • If the setup is long, extract it to functions with descriptive names.
  • Avoid using pre-test functions like JUnit’s @Before or MSTest [TestInitialize]. Instead use methods called directly from the test. When you look at the code, setup and tear down need to be visible, otherwise, you’ll need to search further, and assume even more. Debugging tests with setup methods is no fun either, because you enter the test in a certain context that may surprise you.
  • Avoid using base test classes.  They too hide information relevant for understanding the scenarios. Preferring composition over inheritance works here too.
  • Make the assert part stand out.
  • Make sure that body and name align.

Analysis takes time, and the worst kind (and slowest) requires debugging. Tests (and code) should be readable enough to help us bypass this wasteful process.

Better Readability In Minutes

We are biased and so think that we write code and tests that are so good, everyone can understand it. We’re often wrong.

In agile, feedback is the answer.

Use the “Law of the Third Ear”. Grab an unsuspecting colleague’s ear, and pull it close to your screen, and she can tell you if she understands what the test does.

Even better, pair while writing the tests. Feedback comes us a by product and you get better tests.

Whatever you do, don’t leave it for later. And don’t use violence if you don’t need to.

Make tests readable now, so you can read them later.

Reference: Test Attribute #2: Readability from our JCG partner Gil Zilberfeld at the Geek Out of Water blog.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you two of our best selling eBooks for FREE!

JPA Mini Book

Learn how to leverage the power of JPA in order to create robust and flexible Java applications. With this Mini Book, you will get introduced to JPA and smoothly transition to more advanced concepts.

JVM Troubleshooting Guide

The Java virtual machine is really the foundation of any Java EE platform. Learn how to master it with this advanced guide!

Given email address is already subscribed, thank you!
Oops. Something went wrong. Please try again later.
Please provide a valid email address.
Thank you, your sign-up request was successful! Please check your e-mail inbox.
Please complete the CAPTCHA.
Please fill in the required fields.

Leave a Reply


8 + = fourteen



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy | Contact
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.
Do you want to know how to develop your skillset and become a ...
Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you two of our best selling eBooks for FREE!

Get ready to Rock!
You can download the complementary eBooks using the links below:
Close