# 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

```bash
[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):**

```bash
health_check_should_return_200
user_should_be_created
```

**Avoid (unnecessarily verbose):**

```bash
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):**

```bash
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.