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?
DeviceUpload_VERIFY_TxtUploadToKindleFails
DeviceUpload_WHEN_TxtFile_THEN_UploadToKindleFails
A: Both are perfectly acceptable.
- The happy path format is more concise and just as clear.
- 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:
- GivenWhenThen | Martin Fowler
- Unit test naming best practices | StackOverflow
- 7 Popular Unit Test Naming Conventions | VitalFlux
- Unit Test Naming Convention | Matheus.ro
- You are naming your tests wrong! | Enterprise Craftsmanship
Top comments (1)
What is your preferred way of naming tests? Start a conversation and let's make it better!