Test Naming Guidelines

TLDR: Below are test naming guidelines that help me write consistent, clear test names.

This is quick post with the Test Naming Guidelines I have been using to make my test names consistent across multiple projects. I use also these with LLMs when writing tests or refactoring multiple tests to this style.

I used one of my personal projects as a basis to develop, refine and structure these guidelines with help from an LLM.

Below are the guidelines.

Format

[subject]_should_[expected_behavior]_[optional_when_condition]

Components

Subject: The component, feature, or system under test

• Examples: user, api, filter,time_report

Expected Behaviour: What should happen, described as an action or outcome

• Examples: return_success, validate_input, fail_with_error

Optional When Condition: Include only when necessary for clarity or disambiguation

• Format: when_[condition]

• Examples: when_input_valid, when_user_authenticated

Guidelines for When Conditions

Include when_[condition] if:

• Essential for understanding: The condition is crucial to know what's being tested

• Multiple variants exist: Similar tests with different conditions need distinction

• Specific circumstances: The behavior only occurs under particular conditions

Omit when_[condition] for:

• Basic/default behavior: Standard functionality that doesn't require special conditions

• Self-evident scenarios: Cases where the expected behavior already implies the context

• Overly obvious conditions: When the condition adds no meaningful information

Examples

Good (concise when appropriate):

health_check_should_return_200
user_should_be_created

Avoid (unnecessarily verbose):

health_check_should_return_200_when_request_valid  // "valid" is implied by 200 response
user_should_be_created_when_data_provided  // data is obviously needed

Good (meaningful distinctions):

user_should_login_successfully_when_credentials_valid
user_should_be_rejected_when_credentials_invalid

Principle

Keep test names as short as possible while maintaining clarity. The when_ clause is a tool for disambiguation, not a mandatory requirement.