Test naming convention consistent

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.

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.

// 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.

• ID: code-quality-essentials.organization.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:

  // 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 () => { ... })
  })