| name | test-review |
| description | Test coverage review via Codex MCP. Use when: reviewing test sufficiency, identifying coverage gaps, test quality audit. Not for: generating tests (use codex-test-gen), code review (use codex-code-review). Output: coverage analysis + gap report. |
| allowed-tools | mcp__codex__codex, mcp__codex__codex-reply, Bash(git:*), Read, Grep, Glob, Write |
| context | fork |
| agent | Explore |
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 Criteria section 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
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
