Why you should take more time to write good test names

We all know writing good tests is important. We all know having high test coverage is important. Sometimes we can forget that writing good test names is important too.

Imagine we are building out a form to submit a user’s account settings. This form includes contact information, branding colours, and a logo image.

Let’s use this simple example to highlight three reasons why we should all take more time to write thoughtful test names:

1. Help reviewers provide better feedback

Meaningful test names help others better understand the intention behind the code. Reviewers can then provide possible alternatives to achieve that intention. They can also ensure you consider appropriate edge cases.

In our form we want to allow users to customize their account by selecting from a list of colours. To make it simple we decide to use all the default css colours in the select list. We created a helper method to turn them into correctly formatted words.

 PASS  src/util/convertToSpaceCase.test.js
  convertToSpaceCase helper
    ✓ converts camel case string to space case string

The initial description of the test describes what is expected to happen but not necessarily the intention of this utility function. The feedback we might receive:

• Should this helper method also be able to handle other use cases? Kebab case, pascal case, snake case, etc?

This is a good question, but it doesn’t help us build a better form for our users. This could lead to wasted time and effort. If the test highlighted the intention, this could generate other questions.

 PASS  src/util/convertCssColorToDisplayString.test.js
  convertCssColorToDisplayString helper
    when provided a css color
      ✓ generates a displayable color name

The feedback we might now receive:

• Should we use this well maintained external library for displaying css colours?
• Are we following our content style guide with the outputted colour names?

The review is now more focused on the intention of what we are building. This should lead to a better experience for our users. The feedback could still request this become a re-usable generic utility component. But we do know the reviewer understands the intent.

2. Allow non-engineers to provide feedback

Next we want to build a phone number input component for our form. The requirements for this input include:

• If a valid phone number is entered it should display the number in a phone number format (ex: +X (XXX) XXX-XXXX)
• If not a valid phone number is entered we display an error message.

The tests we write for this component, keeping them as readable as possible, may look like this:

 PASS  src/components/PhoneNumberInput.test.js
  PhoneNumberInput component
    when provided string with phone number
      ✓ displays properly formatted phone number
    when provided string without phone number
      ✓ displays an error message

Our Product Manager can easily align our work with their acceptance criteria. Our Designer can see considered edge cases. This could spark discussion:

• What happens if the phone number is valid but missing a country code?
• What happens if the phone number copied-pasted into the input and includes special characters?

The resulting conversations help ensure your team is building a good solution. We can improve our phone number input component and update our tests.

PASS  src/components/PhoneNumberInput.test.js
  PhoneNumberInput component
    when provided string with phone number
      with just numbers
        ✓ displays properly formatted phone number
      with special characters
        ✓ displays properly formatted phone number
      without a country code
        ✓ displays properly formatted phone number with North American country code
    when provided string without phone number
      ✓ displays an error message

3. Save other’s time

Lastly we want to ensure that only administrators can access this account settings form.

PASS  src/features/AccountSettingsForm.test.js
  AccountSettingsForm page
    when user is an admin
      ✓ form is displayed
    when user is not an admin
      ✓ user is redirected and shown an error message

This is extremely simple example. But this test (and all the tests above) will provide a lot of information for our fellow engineers. Engineers working in this code in the future can quickly learn how this feature should work. They may even share with their PM or Designer. For example:

• “Ah! To test out this form, first I’ll need to make sure I am logged into my test account as an Admin.”
• “We are opening up accounts to European countries. I’ll let my Product Manager know we currently default our phone number country code to North America.”

Conclusion

I hope these examples have highlighted the extra value our tests can provide. Clear and descriptive test names are a great resource for both developers and non-developers alike. We can:

• better focus on the value we are trying to provide our users
• collaborate with our whole team to improve the experience for our users
• help others quickly understand the expected user experience

I hope this article encourages you to take an extra few minutes to re-review your test names the next time you write a test.