# Test names are descriptive

- **Pattern:** `ab-000295` (`ai-slop-test-theater.assertion-quality.descriptive-test-names`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000295
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000295)

## Why it matters

When a test fails in CI, the first signal is the test name. A name like `test 1` or `should work` tells the developer nothing: which behavior failed, which input triggered it, which component is broken. AI-generated test scaffolding frequently produces placeholder names that were never replaced. The result is a test suite where CI failure messages require reading test bodies to understand what broke — slowing down incident response and increasing the chance a developer ignores the failure. ISO-25010:2011 maintainability requires that tests communicate intent clearly.

## Severity rationale

Low because placeholder names don't affect whether tests catch bugs, but they degrade the team's ability to act quickly on CI failures.

## Remediation

Replace any test name under 5 characters or matching patterns like `test 1`, `foo`, `should work`, or empty strings with a name that describes the specific behavior and expected outcome. The name should complete the sentence "It...":

```ts
// Before: meaningless in CI output
it('test 1', () => { ... })
it('test 2', () => { ... })

// After: CI failure message is self-explanatory
it('rejects signup with duplicate email', () => { ... })
it('returns 404 when user does not exist', () => { ... })
```

## Detection

- **ID:** `descriptive-test-names`
- **Severity:** `low`
- **What to look for:** Walk all test files for `it(`/`test(`/`describe(` calls. Before evaluating, extract and quote the first-argument string of each call. Count all test names matching these patterns: a single number (`'1'`, `'2'`), `'test'`, `'test 1'`, `'test 2'`, `'it works'`, `'should work'`, `'foo'`, `'bar'`, `'todo'`, an empty string, or fewer than 5 characters total.
- **Pass criteria:** Fewer than 10% of test names match the placeholder patterns. Report: "X test names inspected, Y placeholder names (Z%)."
- **Fail criteria:** 10% or more of test names match the placeholder patterns.
- **Skip (N/A) when:** Project has 0 test files.
- **Detail on fail:** `"4 of 30 test names are placeholders (13%): 'test 1', 'test 2', 'foo', 'should work'. Use descriptive names like 'creates a user with valid email'"`
- **Remediation:** Placeholder test names like `test 1` make CI failure messages useless. Use descriptive names that match the assertion:

  ```ts
  // Bad: placeholder names
  it('test 1', () => { ... })
  it('test 2', () => { ... })

  // Good: descriptive
  it('creates a user with valid email', () => { ... })
  it('rejects users with invalid email format', () => { ... })
  ```

---

## External references

- iso-25010 maintainability.analysability

Taxons: code-quality

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