Test Naming Convention

There are only two hard things in Computer Science: cache invalidation and naming things. –Phil Karlton

There may be nothing as subjective as a good name. Luckily we're naming tests, not children, so we'll get by.

---

The Class Name

There are 2 parts to a test name: the class name and the method name. It's important to remember the significance of the former.

The class name should provide clarity to the logical grouping of tests it contains. Some examples:

• UsersApiTests
• FileUploadTests
• UserContractValidationTests

---

The Method Name

I've adapted 2 useful formats for the method name: the happy path, and the edge case.

These conventions are used above the unit test level in the testing pyramid, e.g. component, integration, e2e tests.

We'll cover unit test naming towards the end.

---

Format: Happy Path

A happy path test makes sure the functionality works as expected when given straightforward inputs.

 <Functionality>_VERIFY_<Result>

Note: Writing connectors, e.g. "verify", in all CAPS allows us to visually parse the components more easily.

Composition

 <Functionality>
  : The general functionality to be tested; more granular than the class name, adds clarity

 <Result>
  : The expected test outcome or behavior, e.g. return value, response code, state change, action taken

Examples

• FileUploadTests.DeviceUpload_VERIFY_PdfUploadToKindleSuccess
• FileUploadTests.DeviceUpload_VERIFY_TxtUploadToKindleFails
• FileUploadTests.CloudUpload_VERIFY_EpubUploadSuccess
• UsersApiTests.UsersPost_VERIFY_Response201Created

---

Format: Edge Case

An edge case test makes sure the functionality is working as expected when the inputs are not ideal, e.g. out of bounds, on the fringe, or otherwise.

 <Functionality>_WHEN_<Condition>_THEN_<Result>

Note: Including "when" and "then" clarifies the method name components for programmers and non-programmers alike.

Composition

 <Condition>
  : The condition, state, or branch of logic to be isolated

Examples

• FileUploadTests.CloudUpload_WHEN_UserNotPremiumMember_THEN_PDFUploadFails
• UsersApiTests.UsersPost_WHEN_InvalidRequestParams_THEN_Response400BadRequest
• UsersApiTests.UsersPost_WHEN_NameLengthBelowMin_THEN_Response400BadRequest

---

It's a good idea for the scope of a test name to reflect the target code's level of abstraction. Compare these to the above UserApiTests.

• UserCreationTests.ValidateContract_VERIFY_UserContractValidationSuccess
• UserCreationTests.ValidateContract_WHEN_EmailFormatNotValid_THEN_ReturnFalse
• UserCreationTests.ValidateContract_WHEN_PasswordHasNoSpecialChar_THEN_ThrowIllegalArgumentException
• UserCreationTests.ValidateContract_WHEN_NameLengthExceedsMax_THEN_ThrowIllegalArgumentException

Lastly, well-written edge case tests are a succinct representation of the conditions which are important for the happy path of that functionality.

---

Test Type: Unit

Aren't these conventions a little overkill for unit tests? Maybe so. I tend to use a simpler variant for low-level tests.

 <Method?>_<InputOrType>_<Output|PoD>

Composition

 <Method?> (Optional)
  : The purpose of the method being tested; it does NOT need to match the method name; not required if the test class name is clear about the target code

 <InputOrType>
  : Either the value of the input parameter OR type of input depending on input complexity

 <Output|PoD>
  : Either the expected output OR the point of difference (PoD) as compared to the happy path, i.e. what makes this edge case relevant

Examples

• RomanNumeralTests.RomanToInt_MMCDLXVIII_2468
• RomanNumeralTests.IntToRoman_1994_MCMXCIV
• ReverseIntegerTests.Positive_Overflow
• ReverseIntegerTests.Negative_DoubleOverflow

---

Quiz

Q: Which one is better?

1. DeviceUpload_VERIFY_TxtUploadToKindleFails
2. DeviceUpload_WHEN_TxtFile_THEN_UploadToKindleFails

A: Both are perfectly acceptable.

1. The happy path format is more concise and just as clear.
2. The edge case format is self-documenting; it tells us the file type is important to the happy path for device file upload.

There's a trade-off as with most things in CS and in life. The decision is up to you!

---

Final Thoughts

Remember that there's no silver bullet, nor do we need one. We have the power to use the right tool for the right job.

 

Until Next Time,
Ryo

---

TL;DR - Prefer verbose clarity over terse obscurity.

---

References:

1. GivenWhenThen | Martin Fowler
2. Unit test naming best practices | StackOverflow
3. 7 Popular Unit Test Naming Conventions | VitalFlux
4. Unit Test Naming Convention | Matheus.ro
5. You are naming your tests wrong! | Enterprise Craftsmanship

Further Reading:

1. Picking better names for variables, functions, and projects | Mac Wright
2. Practical Test Pyramid | Martin Fowler
3. Unit tests value proposition | Enterprise Craftsmanship
4. Software Testing Guide | MartinFowler