---
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. The extraction pattern: move the inline predicate or validator into an exported pure function and import it from both test files.
   Before renaming or moving shared code as part of the split, size the blast
   radius with the repo_map tool: run `repo_map` with action `importers` on the
   target file to find every consumer, `repo_map` (action: `dependencies`) to
   see what the target itself needs, and `repo_map` with action `blast_radius`
   to enumerate transitive dependents before you move anything.

## 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.