Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a claude-code
Open on GitHub

What 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.ts is past 500 lines, split it along describe() boundaries.
  • Run the new files together with bun --smol test to check for mock leakage.
  • Move the shared fixtures into tests/helpers/my-module-shared.ts and 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-code

2Manually: put the files in place

~/.claude/skills/test-file-split/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/test-file-split/

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

Similar skills

All skills for Testing and QA →

From the same set121

The whole set →
durable-session-state The durable-session-state skill keeps task plans, decisions, validation results, and review verdicts in project files. Use it to pick up long-running work after context compaction or a handoff. CX Codex +1 ★ 539repo stars swarm-pr-feedback swarm-pr-feedback — a skill that works through PR feedback you already have: review notes, GitHub threads, failing checks, conflicts. Everything is verified against the code before a single edit lands. CX Codex +1 ★ 539repo stars swarm-pr-feedback swarm-pr-feedback — a skill that resolves pull request review comments, CI failures, and branch conflicts through structured verification stages. CX Codex +1 ★ 539repo stars commit-pr commit-pr — a portable skill that verifies your code before push, writes conventional commits, and fills in a PR body. Guards against accidentally committing generated files or secrets. CX Codex +1 ★ 539repo stars fork-pr-operations fork-pr-operations guides agents through fork pull request workflows: GitHub Actions approval, safe rebasing with force-with-lease, and handling multi-round bot reviews. CX Codex +1 ★ 539repo stars parallel-work-check parallel-work-check is a Claude Code skill that compares local and remote commits on an existing branch and reviews new changes. It helps catch overlapping work before editing. CX Codex +1 ★ 539repo stars design-docs Writes and syncs a project's design docs: domain, technical spec, behavior spec, plus a traceability registry and changelog. CX Codex +1 ★ 539repo stars orchestrating-subagents orchestrating-subagents is a Claude Code skill for dividing project tasks among subagents, with parallel explorers and independent code review in isolated contexts. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open