hone:test-naming-audit

Test Naming Audit

What This Skill Does

Scans test files across the codebase and evaluates whether each test method/function name communicates the behavior being verified. A good test name reads as a complete sentence: it states what is being tested, under what conditions, and what the expected outcome is.

Flags tests whose names are:

• Cryptic: test1, test2, testA, testIt, foo_test.
• Too short: Single-word names like testParse, testLogin, testSave

that omit conditions and expectations.

• Abbreviated: testUsrAuth, test_inv_req where abbreviations hurt

readability.

• Implementation-focused: Names that reference implementation details

rather than behavior (testCallsApi, testUsesCache).

• Numbered: Names using numeric suffixes to distinguish cases

(testParse1, testParse2).

Reports each finding with the test name, file:line, the issue category, and a suggested improvement pattern.

When To Use

• On every PR that touches test files.
• As a weekly sweep of the full test suite.
• When the user asks to "audit test names" or "check test naming".

Do Not Use

• For test coverage analysis or missing tests.
• For test structure, assertions, or setup/teardown patterns.
• For non-test code naming — use hone:intent-clarity-audit or

hone:naming-specificity-audit instead.

• To rename tests automatically. This skill reports findings only.

Inputs To Confirm

1. Scope: Which directories or file patterns to scan for tests (default:

auto-detect test directories and files matching common patterns like *_test.*, *.test.*, *.spec.*, test_*.*, *Test.*, *Spec.*).

1. Exclusions: Glob patterns for files to skip (e.g., test helpers,

fixtures, generated tests).

1. Strictness: standard (flag clearly bad names) or strict (also flag

names that are acceptable but could be more descriptive). Default: standard.

Instructions

1. Find test files. Walk the repository tree and identify test files using

common naming conventions:

• Files: *_test.go, *.test.ts, *.test.js, *.spec.ts, *.spec.js,

test_*.py, *_test.py, *_test.rb, *Test.java, *Test.kt, *Spec.java, *Spec.kt, *_spec.rb, *Tests.swift, *_tests.rs.

• Directories: test/, tests/, __tests__/, spec/.

Apply user exclusions.

1. Extract test names. For each test file, identify individual test

definitions using language-appropriate patterns:

• JavaScript/TypeScript: it("..."), test("..."), describe("...") blocks

with it/test inside.

• Python: def test_* methods, @pytest.mark.parametrize names.
• Go: func Test*(t *testing.T).
• Java/Kotlin: @Test annotated methods, JUnit 5 @DisplayName.
• Ruby: it "...", describe, context blocks.
• Rust: #[test] fn test_*.
• Swift: func test*().

Record the test name and file:line.

1. Evaluate each test name. Apply these checks in order:

a. Cryptic check: Flag if the name matches patterns like test\d+, testA, testIt, test_it, or is a single generic word after the test prefix.

b. Too-short check: Flag if the name (excluding framework prefix/wrapper) contains fewer than 3 words (using camelCase, snake_case, or string splitting for it("...") style names).

c. Abbreviation check: Flag if the name contains tokens of 3 or fewer characters that are not common words (the, for, and, is, to, it, a, an, of, in, on, or, no, not, be, by, if, at, do, up).

d. Implementation-focus check: Flag if the name references implementation verbs (calls, uses, invokes, creates, mocks, stubs, spies) without describing the behavior.

e. Numbered check: Flag if the name ends with a numeric suffix that distinguishes it from an otherwise identical sibling name.

f. Sentence check (strict mode only): Flag if the name, when expanded from camelCase/snake_case, does not form a readable sentence with a subject, condition, and expectation pattern (e.g., "returns error when input is empty").

1. Classify severity.

• High: Cryptic or numbered names.
• Medium: Too-short or implementation-focused names.
• Low: Abbreviation issues, or strict-mode sentence failures.

1. Suggest improvements. For each finding, suggest a name pattern (not a

specific rename) showing the expected structure:

• should <expected behavior> when <condition>
• <method under test> returns <expected> when <condition>
• <scenario> results in <outcome>

1. Produce the report per Output Requirements.

Output Requirements

Produce a Markdown report:

# Test Naming Audit

**Repo**: <repo name>
**Scope**: <N> test files, <M> test cases | **Findings**: <count>

## Findings

| # | Test Name | File | Line | Issue | Severity | Suggested Pattern |
|---|-----------|------|------|-------|----------|-------------------|
| 1 | `test1` | tests/auth.test.ts | 14 | Cryptic name | High | `should reject expired tokens` |
| 2 | `testParse` | parser_test.go | 42 | Too short — missing conditions | Medium | `TestParse_ReturnsErrorForMalformedInput` |

## Summary

- **By issue**: 3 cryptic, 5 too-short, 2 numbered, 1 abbreviated
- **By severity**: 5 high, 3 medium, 3 low
- **Hotspot files**: auth.test.ts (4 findings), parser_test.go (3 findings)
- **Overall**: <X>% of test names meet the sentence-style standard

Quality Bar

• Every finding must reference a real test name at the stated file:line.
• Do not flag describe/context block names — only leaf test cases.
• Do not flag test names that use @DisplayName or equivalent display-name

annotations if the display name itself reads as a sentence.

• Framework-idiomatic patterns are acceptable: Go's TestFoo_Bar_Baz style

is fine if each segment adds meaning.

• Suggested patterns must be relevant to the specific test, not generic.
• If all test names pass, state that explicitly with the total count checked.