test-file-split

Test File Split Protocol (FR-006)

scripts/check-test-file-cap.ts enforces the 500-line cap per test file (FR-006 / SC-006.1) as a diff-scoped ratchet: new test files over 500 lines and existing over-cap files that grew fail the quality gate and block PR merge. Pre-existing over-cap files not touched by the PR are non-blocking. Escape hatch: TEST_CAP_ENFORCE=0 soft-warns. This skill covers the complete splitting protocol.

Read first: .opencode/skills/writing-tests/SKILL.md (or .claude/skills/writing-tests/SKILL.md) for bun:test framework rules, mock isolation patterns, and file placement conventions.

When to use this skill

• A test file exceeds or approaches 500 lines
• CI fails with an FR-006 file-size violation
• You are adding tests to a file that is already above 400 lines (proactive split)

Step 1 — Measure and identify split boundaries

# Check the file
wc -l tests/unit/scripts/my-module.test.ts

# Find all test files exceeding 400 lines (early warning)
find tests/ -name "*.test.ts" -exec wc -l {} \; | sort -rn | awk '$1 > 400'

Identify natural describe() block boundaries. Group blocks by functional area:

• Each describe() block should belong to exactly one split file
• Shared beforeEach/afterEach hooks determine which blocks must stay together

Step 2 — Choose a suffix for the new file

Pattern	Example	When to use
<module>-<area>.test.ts	release-notes-fragments-sha.test.ts	Split by functional area (SHA resolution, validation, merge logic)
<module>-<area>.adversarial.test.ts	auth-login.adversarial.test.ts	Split adversarial tests into their own file

Step 3 — Manage shared imports and helpers

Three options, in order of preference:

1. Extract to shared utility (preferred for complex shared setup): Create tests/helpers/<module>-shared.ts with shared fixtures, mock factories, and setup functions. Import from both split files.

2. Duplicate simple imports (for small overlap): If only bun:test imports and 1-2 source imports are shared, duplicate them in both files. Simpler than a utility module for trivial cases.