К основному содержанию
скилл CX Codex

test-file-split — скилл для Claude Code: делит тест-файлы по 500 строк

Скилл test-file-split разбивает разросшийся тест-файл на части по блокам describe(), когда тот подходит к лимиту в 500 строк или уже перевалил его.

MIT ★ 539 обновлён 2026-10-29

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a claude-code
Открыть на GitHub

Что делает test-file-split

Скилл включается, когда тест-файл подбирается к 500 строкам или уже перерос их. Порядок такой: посчитать строки через wc -l, найти блоки describe() и разложить их по новым файлам так, чтобы общие beforeEach/afterEach остались вместе. Суффикс нового файла выбирается по смыслу: -<area>.test.ts для функциональной части, .adversarial.test.ts для состязательных тестов.

Общие фикстуры и фабрики моков уезжают в tests/helpers/<module>-shared.ts. Если пересечение маленькое, проще продублировать импорты. Третий путь — вынести из исходного модуля чистые функции и тестировать их напрямую, без моков.

Проверка двойная: каждый файл отдельно, потом все вместе одной командой bun --smol test. Bun держит тесты в одном процессе, поэтому утечка mock.module() валит совместный прогон при зелёных одиночных. Проверку в CI можно ослабить переменной TEST_CAP_ENFORCE=0, тогда она только предупреждает. Скилл заточен под bun:test и скрипт scripts/check-test-file-cap.ts из репозитория opencode-swarm; в чужом проекте лимит в 500 строк ничем не подкреплён, и останется только памятка. Резать тот же файл третий раз не стоит: если он опять перерос лимит, тесты пора перегруппировать по модулям исходника.

Какие задачи решает

  • разрезать тест-файл на 500+ строк по блокам describe()
  • вынести общие фикстуры в tests/helpers/
  • поймать утечку mock.module() при совместном прогоне
  • вынести чистые функции из модуля ради тестов без моков
  • понять, когда дальнейшее деление файла только вредит

Примеры запросов агенту

  • Файл tests/unit/scripts/my-module.test.ts перевалил за 500 строк, раздели его по describe()-блокам.
  • Проверь новые тест-файлы вместе через bun --smol test, чтобы поймать утечку моков.
  • Вынеси общие фикстуры в tests/helpers/my-module-shared.ts и подключи из обоих файлов.

Как установить test-file-split

1Через Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a claude-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/test-file-split/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о test-file-split

Как установить test-file-split в Claude Code?

Выполните npx skills add ZaxbyHub/opencode-swarm --skill test-file-split -a claude-code. Файл скилла окажется по пути ~/.claude/skills/test-file-split/SKILL.md.

Что делает test-file-split?

Описывает порядок разделения тест-файла, который подошёл к 500 строкам: замер, границы блоков, общие хелперы, проверка изоляции моков.

Почему совместный прогон падает, если по отдельности тесты проходят?

Bun запускает файлы в одном процессе, и mock.module() из одного файла протекает в другой. Скилл требует гонять разбитые файлы вместе и смотреть на изоляцию.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Тесты и QA» →
bun-test-basics secondsky Скилл bun-test-basics подсказывает синтаксис bun:test: ассерты, describe/it, модификаторы skip, only, each и запуск тестов. CX Codex +1 481установок bun-test-mocking secondsky Скилл bun-test-mocking помогает писать моки и шпионы во встроенном раннере bun:test. Пригодится при изоляции сетевых вызовов и подмене модулей. CX Codex +1 427установок testrail-test-case-cursorrules-prompt-file PatrickJS Правило testrail-test-case-cursorrules-prompt-file задаёт роль QA-инженера для составления тест-кейсов TestRail по шагам или из автотестов. Помогает форматировать сценарии в таблицы и CSV для импорта. CX Codex +1 ★ 41 178звёзд репо test-file Anand Tyagi Плагин test-file для Claude Code генерирует подробные тесты для отдельного файла проекта. За один запуск обрабатывает один файл. ★ 1 013звёзд репо xray-test-case-cursorrules-prompt-file PatrickJS Правило xray-test-case-cursorrules-prompt-file для Cursor преобразует описания фич и код автотестов в структурированные тест-кейсы Xray для Jira. Включает поля, шаги и тестовые данные. CX Codex +1 ★ 41 178звёзд репо test-master https://github.com/Jeffallan Скилл test-master для Claude Code: пишет юнит-, интеграционные и E2E-тесты, разбирает покрытие и находит причины нестабильных тестов. CX Codex +1 5 800установок

Из того же набора121

Весь набор →
durable-session-state Скилл durable-session-state сохраняет планы, решения, результаты проверок и вердикты ревью в файлах проекта. Он помогает продолжить долгую задачу после сжатия контекста или передачи работы. CX Codex +1 ★ 539звёзд репо swarm-pr-feedback Скилл swarm-pr-feedback для Claude Code собирает известные замечания к PR в реестр, проверяет каждое по коду и только после этого вносит правки. Разбирает замечания ревью, сбои CI и конфликты. CX Codex +1 ★ 539звёзд репо swarm-pr-feedback Скилл swarm-pr-feedback для автоматической обработки замечаний к pull request, падений CI и конфликтов слияния перед публикацией правок. CX Codex +1 ★ 539звёзд репо commit-pr Скилл commit-pr проверяет код перед пушем, создаёт конвенциональные коммиты и оформляет PR-описание. Включается при подготовке изменений к отправке. CX Codex +1 ★ 539звёзд репо fork-pr-operations Скилл fork-pr-operations инструктирует агента по работе с пулл-реквестами из форков: одобрение воркфлоу в GitHub Actions, безопасный rebase и сверка актуальности проверок CI. CX Codex +1 ★ 539звёзд репо parallel-work-check Скилл parallel-work-check для Claude Code сравнивает локальное состояние существующей ветки с удалённым и проверяет новые коммиты. Помогает заметить параллельные изменения до начала правок. CX Codex +1 ★ 539звёзд репо design-docs Ведёт design-доки проекта: домен, техспеку, behavior-спеку, реестр section-ID и changelog. Запускается по заголовку [MODE: DESIGN_DOCS ...]. CX Codex +1 ★ 539звёзд репо orchestrating-subagents Скилл orchestrating-subagents для Claude Code задаёт правила декомпозиции задач: выбор моделей для ролей, параллельный запуск исследователей и независимую приёмку кода ревьюерами. CX Codex +1 ★ 539звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой