How to make your test case easy to understand by using test naming conventions
Published: 2023-12-29 23:04:34


# Introduction

A common problem developers have is how to write the test name. Most projects don’t follow a convention, making the test cases a real mess!

Every developer chooses a different approach because there are no set rules.

Having a standard test naming convention will help you end this problem!

When you write meaningful tests, your tests should follow a naming convention. That naming convention has to be insightful and easy to understand.

By following a convention you can make it easier for the developers to:

- read the test.
- understand the behavior.
- understand the expectations.
- understand business rules.
- come up with new ideas for test scenarios
- understand faster what was already tested and what is not

Don’t worry about the length of the name. You should worry only if it’s not following the defined convention. And if it’s describing the behavior and results properly.

# Why having a test name convention is important?

Having a convention makes it easier for you to see what the test case is about. It’s the first thing that a developer reads in a test scenario!

By following the convention you can make the code more readable and easy to maintain.

Also, tests can be sort of a documentation of the behavior of the application you are working on. By making them meaningful you can make your tests be a guide for system business rules. It will help a lot of new developers that are arriving in the team.

# What convention should I follow?

So, how can I name my tests, so they become more readable, easy to understand, and help us as documentation? Here are some conventions that you can follow:

### **Method_Scenario_Behavior:**

This is a popular naming pattern it consists of the:

- **Method:** This part represents the method that is being tested.
- **Scenario:** represents the scenario that is being tested.
- **Behavior:** This represents the expected outcome for the test.

Pay attention when using this convention! Because if you refactor the code and change the name of the method tested.

You also have to remember to rename your test case, to keep it concise and avoid confusion at a later time.

Here are some examples of this pattern:

- emailValidator_whenEmailFollowValidPattern_returnThatIsValidEmail
- shoppingCart_whenAddProduct_ProductIsAddedToCart

### **Method_Behavior_Scenario:**

This is like the above-mentioned convention. But in the inverse order, putting the expected behavior before the test scenario.

It has the same disadvantage as the previous one since they are almost the same.

Here are some examples of this pattern:

- emailValidator_returnThatIsValidEmail_whenEmailFollowValidPattern
- shoppingCart_productIsAddedToCart_whenProductIsAdded

### **Should Standard:**

By using this convention, every test must start with the word “should”.

This method does not depend on the name of the method that is being tested. It depends only on the behavior and expectations.

A common way to use is: should_expectedBehavior_when_stateUnderTest

Here are some examples:

- should_throwInvalidPaymentMethodException_when_paymentMethodIsInvalid
- should_addProductToCart_when_ProductIsAddedToTheCart

### **Test Feature:**

In this convention, the method should start with the word “test”.

The convention is:

- testFeature.

Some people might affirm that the “test” word is redundant. Others can say that it is more natural to use the “test” word. It's up to you!

Here are some examples:

- testIsValidPasswordIfLenghtIsHigherThan7
- testIsValidPaymentMethodIfTheMethodIsCreditCard

A variation of this convention can use the snake case and the word when to represent the scenario.

Examples:

- test_IsValidPassword_when_lenghtIsHigherThan7
- test_IsValidPaymentMethod_when_IsCreditCard

### **Feature Only:**

This convention is almost the same as the previous one. It removes the word “test” from the naming convention, avoiding redundancy. By only writing the feature, the test is closer to being a sort of documentation.

Here are some examples:

- isValidPassowrdWhenLenghtIsBiggertThan7
- isValidPaymentMethodIfTheMethodIsCreditCard

You are free to use the snake case, if you believe that is gonna be easier to read. Like this:

- isValidPassowrd_when_lenghtIsBiggertThan7

### **When_Scenario_Expect_Outcome**

This convention starts with the word “when” and the test scenario. Followed by the word “expected” with the expected outcome.

Example:

- when_validPassowrd_expect_isPasswordValidTrue
- when_paymentMethodIsInvalid_expect_throwInvalidPaymentMethodException

### **Given_When_Then:**

This convention resembles the BDD process. You can break the test name into three parts:

- **Given:** Preconditions
- **When:** The scenario under test
- **Then:** The expected outcome.

Examples:

- given_formIsValid_when_submitButtonIsClicked_then_dataIsSaved
- given_databaseConnectionIsOpen_when_queryIsExecuted_then_resultsAreReturned

# Mistakes to avoid

You should avoid test names! They are not very descriptive and will make you waste time by reading all the test cases to find out what are about.

Some examples that I’ve seen:

- testNN
- test1
- test2
- test3
- testCreateSuccess
- testUpdateFailed
- test
- test_method

None of these test names tells much about what is being tested, so watch out to avoid this mistake

# Conclusion

The convention that is the best, is the one that works better for you. Choose the one that makes more sense for your project and your team (you can survey with the team if you want it to).

Some are easier to follow but can make your test dependent on the production code. (because of the method name)

Others can be harder to follow (not having a precise structure), making it tougher to choose a good name. But can be easy to main because less coupled with production code.

Choose wisely, start applying in your project, and see the benefits!

Next week we're talking about the pitfalls of test coverage, and how to use coverage effectively.