test-file-split — Claude Code skill: splitting test files at 500 lines
test-file-split breaks an oversized test file into parts along describe() boundaries when it nears the 500-line cap or blows past it.
MIT ★ 539 updated 2026-10-29
npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a claude-codeWhat test-file-split does
The skill applies to test files that reach the 500-line mark. It walks through measuring the file with wc -l, finding the natural describe() groupings, and moving whole blocks into new files while keeping shared beforeEach/afterEach hooks together. Naming follows the content: -<area>.test.ts for a functional slice, .adversarial.test.ts when adversarial cases get their own home.
Shared fixtures and mock factories go to tests/helpers/<module>-shared.ts. Small overlap is cheaper to duplicate. The third route is pulling pure functions out of the source module so tests can hit them without mocks.
Verification runs twice: each new file alone, then all of them in one bun --smol test pass. Bun keeps test files in a single process, so a leaked mock.module() breaks the combined run while solo runs stay green. Setting TEST_CAP_ENFORCE=0 softens the CI check into a warning. The whole protocol assumes bun:test and the repo's scripts/check-test-file-cap.ts; drop it into a project without that gate and the 500-line rule has nothing behind it. A file that outgrows the cap a second time should be reorganised by source module rather than cut again.
What it helps with
- split a test file that passed 500 lines by
describe()blocks - move shared fixtures into
tests/helpers/ - catch a
mock.module()leak in a combined test run - extract pure functions so tests skip mocks
- decide when further splitting makes a suite worse
Example prompts for the agent
tests/unit/scripts/my-module.test.tsis past 500 lines, split it alongdescribe()boundaries.- Run the new files together with
bun --smol testto check for mock leakage. - Move the shared fixtures into
tests/helpers/my-module-shared.tsand import them from both files.
How to install test-file-split
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a claude-code2Manually: put the files in place
~/.claude/skills/test-file-split/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/test-file-split/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a codex2Manually: put the files in place
.agents/skills/test-file-split/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a cursor2Manually: put the files in place
.cursor/skills/test-file-split/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ZaxbyHub/opencode-swarm .agents/skills/test-file-split2Manually: put the files in place
.github/skills/test-file-split/SKILL.md1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a gemini-cli2Platform CLI
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .agents/skills/test-file-splitManually: put the files in place
.devin/skills/test-file-split/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about test-file-split
How do I install test-file-split in Claude Code?
Run npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a claude-code. The skill file lands at ~/.claude/skills/test-file-split/SKILL.md.
What does test-file-split do?
It lays out the steps for breaking up a test file that hit the 500-line cap: measuring, finding block boundaries, sharing helpers, checking mock isolation.
Why does a combined run fail when each file passes alone?
Bun runs test files in one process, so mock.module() set up in one file can bleed into another. The skill has you run the split files together and inspect isolation.
Source text
SKILL.md · MIT
---
name: test-file-split
description: Protocol for splitting test files that approach or exceed the FR-006 500-line limit (enforced in CI by scripts/check-test-file-cap.ts as a diff-scoped ratchet). Covers describe-block extraction, shared helper management, pure-function extraction, mock isolation verification, and cascading-split detection. Load when a test file approaches or exceeds 500 lines.
metadata:
audience: swarm-plugin
---
# 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
```bash
# 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.
3. **Extract pure functions from source (for testability):**
If the source module has inline validation logic, extract them as exported pure functions (e.g., `isValidPrNumber`, `resolveAllCandidates`) so both test files can target them independently. See the PR #1762 example below. See `.opencode/skills/generated/safe-extraction/SKILL.md` for the source extraction pattern.
## Step 4 — Extract and move describe blocks
1. Cut the selected `describe()` blocks from the original file.
2. Paste them into the new file.
3. Add all necessary imports to the new file.
4. Remove now-unused imports from the original file.
## Step 5 — Verify both files
### Line count check
```bash
wc -l tests/unit/scripts/my-module.test.ts tests/unit/scripts/my-module-sha.test.ts
# Both must be under 500 lines
```
### Isolated run
```bash
bun --smol test tests/unit/scripts/my-module.test.ts --timeout 60000
bun --smol test tests/unit/scripts/my-module-sha.test.ts --timeout 60000
```
### Co-run (mock isolation verification)
```bash
# Critical: Bun shares a single process across test files.
# mock.module leaks can cause co-run failures even when isolated runs pass.
bun --smol test tests/unit/scripts/my-module*.test.ts --timeout 60000
```
If the co-run fails but isolated runs pass, check for `mock.module()` leakage. See `.opencode/skills/writing-tests/SKILL.md` → "Mock Isolation Rules" and the `_internals` DI seam pattern.
## Step 6 — Evaluate `_test_exports` opportunity
After splitting, evaluate whether internal utility functions in the source module can be exported via `_test_exports` for zero-mock testing. This is a natural cleanup moment — the split already forces you to review test coverage boundaries.
## Cascading split warning
If a previously split file exceeds 500 lines **again**, the test suite is structurally too large for a single module. Do not split a third time — reorganize the tests by source module boundaries instead. Repeated splitting produces fragmented test suites that are hard to navigate and maintain.
## Real-world example (PR #1762)
`tests/unit/scripts/release-notes-fragments.test.ts` exceeded 500 lines. It was split into:
| File | Lines | Content |
|------|-------|---------|
| `release-notes-fragments.test.ts` | 379 | Fragment collection, deduplication, output formatting |
| `release-notes-fragments-sha.test.ts` | 261 | `extractCommitShasFromBody`, `mergeCandidateLists`, `resolveAllCandidates`, `isValidPrNumber`, `stripCustomReleaseNotesBlock` |
The split also extracted `isValidPrNumber` and `resolveAllCandidates` as pure exported functions from the source module, enabling independent testing.
© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm