tomevault-io Test Review Skill
Trigger
- Keywords: test coverage, test review, are tests sufficient, generate tests, test gen, coverage
When NOT to Use
- Code review (use
codex-code-review) - Document review (use
doc-review) - Just want to run tests (use
/verify)
Commands
| Command | Description | Use Case |
|---|---|---|
/codex-test-review |
Review test sufficiency | Required |
/codex-test-gen |
Generate unit tests | Add missing tests |
/check-coverage |
Test coverage analysis | After feature dev |
Workflow: /codex-test-review
Smart detect target → Read test + source → Codex review (5 dimensions) → Coverage assessment + Gate → Loop if Needs additions
Step 1: Smart Detection
| Input | Behavior |
|---|---|
| File path | Review that file directly |
| Directory | Review all tests in directory |
| Description | Auto-find related test files |
| Module name | Search related test files |
| No parameter | Auto-detect from git diff |
Step 2: Read Test and Source
- Read test file (
TEST_FILE) - Read corresponding source (
SOURCE_FILE, inferred from test path)
Step 3: Codex Review
First review: mcp__codex__codex with test review prompt. See references/codex-prompt-test-review.md.
Loop review: mcp__codex__codex-reply with re-review template. See references/codex-prompt-test-review.md.
Config: sandbox: 'read-only', approval-policy: 'never'
Save the returned threadId.
Workflow: /codex-test-review --ac-trace
AC traceability mode — maps Acceptance Criteria from request docs to test evidence.
--ac-trace input → Read request doc → Parse ACs → Filter quality-gate → Search evidence → Codex verify → Matrix + Gate
Step 1: Input Resolution
| Input | Behavior |
|---|---|
--ac-trace <request-path> |
Read specified request doc |
--ac-trace (no path) |
Auto-detect from docs/features/*/requests/*.md via git diff context |
No --ac-trace |
Existing behavior (5-dimension coverage review) |
Step 2: Parse & Filter ACs
- Locate
## Acceptance Criteriasection in request doc - Parse
- [ ]/- [x]items - Filter out quality-gate ACs matching:
/codex-review-fast,/codex-review-doc,/codex-review,/precommit,/precommit-fast,/pr-review
Step 3: Search Evidence
For each non-quality-gate AC:
| Evidence Type | Priority | How to Find |
|---|---|---|
| Automated test | 1 (preferred) | Search Related Files test paths; match AC text → test assertions |
| Runtime verification | 2 | Search /feature-verify results at L3+ confidence |
| Manual exception | 3 (verified only) | Check AC annotation <!-- exception: REASON, expires: DATE --> |
Step 4: Codex Verify (independent)
Fresh thread (mcp__codex__codex). See references/codex-prompt-ac-trace.md.
| Rule | Detail |
|---|---|
| Cache | request-path + git diff hash key; same session reuse |
| Timeout | 30s → fallback to Claude-only + ⚠️ Inconclusive |
| Unavailable | All items ⚠️ Inconclusive; advisory → ⚠️ Adequate with exceptions; strict → ⚠️ Need Human |
Config: sandbox: 'read-only', approval-policy: 'never'
Save the returned threadId.
Step 5: Exception Validation (3-gate)
| Gate | Check |
|---|---|
| Reason class | Closed enum: ENV_UNAVAILABLE / UNSAFE_TO_AUTOMATE / ONE_TIME_MIGRATION |
| Codex verification | Must emit VALID_EXCEPTION |
| Expiry | ISO 8601; expired = ⛔ (strict) or ⚠️ (advisory) |
Exception caps (from @rules/testing.md): 1-8 AC = max 1; 9-12 = max 2; 13+ = hard cap 2. Prohibited domains: Security AC, Data-integrity AC, Regression AC = no exceptions allowed.
Step 6: Output + Gate
Gate sentinels (from @rules/testing.md):
| Sentinel | Meaning |
|---|---|
✅ Adequate |
All ACs covered by evidence |
⚠️ Adequate with exceptions |
Validated exceptions within cap |
⚠️ Need Human |
Codex unavailable or inconclusive |
⛔ Inadequate |
Unverified exception, cap breach, or prohibited domain |
Workflow: /codex-test-gen
Read source → Derive test path → Codex generate → Save test file → Suggest review
Steps
- Read source file
- Derive test path:
src/service/xxx.ts→test/unit/service/xxx.test.ts - Codex generates tests. See
references/codex-prompt-test-gen.md. - Save to target path
- Suggest: run tests then
/codex-test-review
Review Dimensions
| Dimension | Scoring Criteria | Weight |
|---|---|---|
| Happy path | All public methods, main flows | High |
| Error handling | try/catch, error callbacks | High |
| Edge cases | null/undefined, extremes, empty sets | Medium |
| Mock quality | Not excessive, not insufficient | Medium |
Three-Layer Tests
| Type | Directory | Mock | Focus |
|---|---|---|---|
| Unit | test/unit/ |
Full | Single function |
| Integration | test/integration/ |
Only external | Inter-module |
| E2E | test/e2e/ |
Prohibited | Complete flow |
Common Boundaries
| Type | Cases |
|---|---|
| String | "", " ", null, undefined, very long |
| Number | 0, -1, NaN, Infinity, MAX_SAFE_INTEGER |
| Array | [], [null], very large, nested |
| Object | {}, null, circular reference |
Review Loop
⚠️ @CLAUDE.md auto-loop: fix → re-review → ... → ✅ PASS ⚠️
⛔ Needs additions → add tests → /codex-test-review --continue <threadId> → repeat until ✅ Sufficient.
Max 3 rounds. Still failing → report blocker.
Output
## Test Coverage Review
| Dimension | Coverage | Rating |
|-----------|----------|--------|
| ... | ... | ⭐1-5 |
### Gate: ✅ Tests sufficient / ⛔ Needs additions
Verification
- Coverage assessment includes all dimensions
- Gate is clear (✅ Tests sufficient / ⛔ Needs additions)
- Missing tests have specific code suggestions
- Codex independently researched source code branches
References
- Test review prompt:
references/codex-prompt-test-review.md - Test gen prompt:
references/codex-prompt-test-gen.md - AC trace prompt:
references/codex-prompt-ac-trace.md - Standards: @rules/testing.md
Examples
Input: /codex-test-review test/unit/service/xxx.test.ts
Action: Read test + source → Codex review → Coverage assessment + Gate
Input: /codex-test-gen src/service/xxx.ts
Action: Read source → Codex generate → Save test → Suggest review
Input: Are this service's tests sufficient?
Action: /codex-test-review → Assess coverage → Output gaps + Gate
Input: /codex-test-review --ac-trace docs/features/auth/requests/2026-03-01-login.md
Action: Parse AC → Filter quality-gate → Search evidence → Codex verify → Matrix + Gate
Converted and distributed by TomeVault — claim your Tome and manage your conversions.