# Test naming convention consistent

- **Pattern:** `ab-002158` (`code-quality-essentials.organization.test-naming-convention`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002158
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002158)

## Why it matters

When a test fails, the first signal is the test name in the CI output. A name like `"test1"` or `"works"` tells an engineer nothing about what broke or what regression to investigate — they must open the test file, read the code, and reconstruct the intent. ISO 25010:2011 §6.5.5 classifies this as a maintainability defect: diagnostic value is a measurable property of a test suite. Poor naming also correlates with poor test structure — if a developer cannot name a test precisely, they often haven't defined precisely what they're testing.

## Severity rationale

Low because vague test names do not break functionality but make failing tests significantly harder to triage, slowing down diagnosis and increasing the time bugs spend in production.

## Remediation

Adopt the "should [verb] when [condition]" or "returns [result] given [input]" pattern. Update existing tests incrementally — start with the highest-churn files where test names are most frequently read.

```typescript
// Bad naming: opaque in CI output
describe('auth', () => {
  it('test1', () => { ... })
  it('works', () => { ... })
  it('login check', () => { ... })
})

// Good naming: self-explanatory on failure
describe('authenticateUser', () => {
  it('returns a session token when credentials are valid', async () => { ... })
  it('throws InvalidCredentialsError when password is wrong', async () => { ... })
  it('throws AccountLockedError after 5 failed attempts', async () => { ... })
})
```

Choose `it()` or `test()` consistently — mixing both in the same codebase is a minor but visible inconsistency.

## Detection

- **ID:** `test-naming-convention`
- **Severity:** `low`
- **What to look for:** Examine test file descriptions inside `describe()` and `it()`/`test()` blocks. Consistent naming makes test output readable and failures self-explanatory. Common patterns include: "should [action] when [condition]", "returns [result] given [input]", "throws [error] when [condition]". Inconsistent naming — "test 1", "works", "check", "it works fine", or one-word descriptions — makes it hard to identify what broke when a test fails. Also check whether `describe` blocks group related tests meaningfully (by function or component name, not arbitrary groupings). Check whether all tests use `it()` or all use `test()` — mixing both is a minor inconsistency.
- **Pass criteria:** Enumerate all relevant code locations. Tests follow a consistent naming pattern throughout the suite. `describe` blocks meaningfully group tests. Test names are descriptive enough to understand what failed without reading the test body with at least 1 verified location.
- **Fail criteria:** Test names are vague, inconsistent, or meaningless ("test 1", "works", "should work"). Mixed `it()` and `test()` without a clear convention.
- **Skip (N/A) when:** No test files exist.
- **Detail on fail:** `"Inconsistent test naming: some tests use 'should' pattern, others are vague ('works', 'test1'); failing tests will be hard to diagnose"`
- **Remediation:** Adopt the "should [verb] when [condition]" pattern. Update existing tests incrementally:

  ```typescript
  // Bad naming: hard to understand from the test output
  describe('auth', () => {
    it('test1', () => { ... })
    it('works', () => { ... })
    it('login check', () => { ... })
  })

  // Good naming: failure message is self-explanatory
  describe('authenticateUser', () => {
    it('returns a session token when credentials are valid', async () => { ... })
    it('throws InvalidCredentialsError when password is wrong', async () => { ... })
    it('throws AccountLockedError after 5 failed attempts', async () => { ... })
  })
  ```

## External references

- iso-25010 maintainability.testability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-002158