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.
Top comments (0)