Generate tests that do not exist yet. Analyzes coverage gaps, then writes and runs new test files across three tiers (unit, integration via testcontainers, Playwright E2E), one test-generator agent per tier, healing failures for up to 3 iterations. Use when code has no tests or when raising coverage after implementation. Do NOT use to grade tests that already exist (use /ork:verify) or to run a suite without writing anything new.
Instrucciones de origen · Vista previa de solo lectura
name
cover
license
MIT
compatibility
Claude Code 2.1.220+. Requires network access.
description
Generate tests that do not exist yet. Analyzes coverage gaps, then writes and runs new test files across three tiers (unit, integration via testcontainers, Playwright E2E), one test-generator agent per tier, healing failures for up to 3 iterations. Use when code has no tests or when raising coverage after implementation. Do NOT use to grade tests that already exist (use /ork:verify) or to run a suite without writing anything new.
{"keywords":["cover","generate tests","test suite","test coverage","write tests for","add tests","need tests"],"examples":["generate tests for the authentication service","cover the payment module with unit and integration tests","I just finished implementing checkout, now write tests"],"anti-triggers":["verify","run tests","npm test","fix","implement","review"]}
["command -v vitest >/dev/null 2>&1 || command -v jest >/dev/null 2>&1 || echo 'Warning: no test runner found — run npm install first'"]
Cover — Test Suite Generator
Generate comprehensive test suites for existing code with real-service integration testing and automated failure healing.
Note: If disableSkillShellExecution is enabled (CC 2.1.91), the precondition check for vitest/jest won't run. Verify a test runner is installed before proceeding: npx vitest --version or npx jest --version.
Quick Start
/ork:cover authentication flow
/ork:cover --model=opus payment processing
/ork:cover --tier=unit,integration user service
/ork:cover --real-services checkout pipeline
Step -0.5: Effort-Aware Coverage Scaling (CC 2.1.76, env var since 2.1.120)
Read $CLAUDE_EFFORT (CC 2.1.120+) first; explicit --effort= token wins as override. Default when CC < 2.1.120 and no flag. Pattern matches assess + explore (#1540). Scale test generation depth:
high
Effort Level
Tiers Generated
Agents
maxIterations to pass Phase 5
low
Unit only
1 agent
2 (1 repair + 1 verify)
medium
Unit + Integration
2 agents
2 (1 repair + 1 verify)
high (default)
Unit + Integration + E2E
3 agents
3 (2 repairs + 1 verify)
xhigh (Opus 4.8, CC 2.1.111+)
Unit + Integration + E2E
3 agents
3 (the ceiling; xhigh adds agents, not heal passes)
Values are what you pass as maxIterations in Phase 5. The script clamps to [2, 3]
(heal-loop.js), so anything outside that range is coerced, and the final iteration always
verifies rather than repairing. There is no 4-iteration mode.
Override: Explicit --tier= flag or user selection overrides /effort downscaling.
Step -1: MCP Probe + Resume Check
# Probe MCPs (parallel):# memory is alwaysLoad in .mcp.json (CC 2.1.121+, #1541) — probe below kept as fallback for older CC:
ToolSearch(query="select:mcp__memory__search_nodes")
ToolSearch(query="select:mcp__context7__resolve-library-id")
Write(".claude/chain/capabilities.json", {
"memory": <true if found>,
"context7": <true if found>,
"skill": "cover",
"timestamp": now()
})
# Resume check:
Read(".claude/chain/state.json")
# If exists and skill == "cover": resume from current_phase# Otherwise: initialize state
Step 0: Scope & Tier Selection
AskUserQuestion(
questions=[
{
"question": "What test tiers should I generate?",
"header": "Test Tiers",
"options": [
{"label": "Full coverage (Recommended)", "description": "Unit + Integration (real services) + E2E"},
{"label": "Unit + Integration", "description": "Skip E2E, focus on logic and service boundaries"},
{"label": "Unit only", "description": "Fast isolated tests for business logic"},
{"label": "E2E only", "description": "Playwright browser tests"}
],
"multiSelect": false
},
{
"question": "Healing strategy for failing tests?",
"header": "Failure Handling",
"options": [
{"label": "Auto-heal (Recommended)", "description": "Fix failing tests up to 3 iterations"},
{"label": "Generate only", "description": "Write tests, report failures, don't fix"},
{"label": "Strict", "description": "All tests must pass or abort"}
],
"multiSelect": false
}
]
)
Override TIERS based on selection. Skip this step if --tier= flag was provided.
Task Management (MANDATORY)
# 1. Create main task IMMEDIATELY
TaskCreate(subject=f"Cover: {SCOPE}", description="Generate comprehensive test suite with real-service testing", activeForm=f"Generating tests for {SCOPE}")
# 2. Create subtasks for each phase
TaskCreate(subject="Discover scope and detect frameworks", activeForm="Discovering test scope") # id=2
TaskCreate(subject="Analyze coverage gaps", activeForm="Analyzing coverage gaps") # id=3
TaskCreate(subject="Generate tests (parallel per tier)", activeForm="Generating tests") # id=4
TaskCreate(subject="Execute generated tests", activeForm="Running tests") # id=5
TaskCreate(subject="Heal failing tests", activeForm="Healing test failures") # id=6
TaskCreate(subject="Generate coverage report", activeForm="Generating report") # id=7# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"]) # Analysis needs discovery first
TaskUpdate(taskId="4", addBlockedBy=["3"]) # Generation needs gap map
TaskUpdate(taskId="5", addBlockedBy=["4"]) # Execution needs generated tests
TaskUpdate(taskId="6", addBlockedBy=["5"]) # Healing needs test results
TaskUpdate(taskId="7", addBlockedBy=["6"]) # Report needs healed suite# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress") # When starting
TaskUpdate(taskId="2", status="completed") # When done — repeat for each subtask
6-Phase Workflow
Phase
Activities
Output
1. Discovery
Detect frameworks, scan scope, find untested code
Framework map, file list
2. Coverage Analysis
Run existing tests, map gaps per tier
Coverage baseline, gap map
3. Generation
Parallel test-generator agents per tier
Test files created
4. Execution
Run all generated tests
Pass/fail results
5. Heal
Fix failures, re-run (max 3 iterations)
Green test suite
6. Report
Coverage delta, test count, summary
Coverage report
Phase Handoffs
After Phase
Handoff File
Key Outputs
1. Discovery
01-cover-discovery.json
Frameworks, scope files, tier plan
2. Analysis
02-cover-analysis.json
Baseline coverage, gap map
3. Generation
03-cover-generation.json
Files created, test count per tier
5. Heal
05-cover-healed.json
Final pass/fail, iterations used
Phase 1: Discovery
Detect the project's test infrastructure and scope the work.
# PARALLEL — all in ONE message:# 1. Framework detection (hook handles this, but also scan manually)
Grep(pattern="vitest|jest|mocha|playwright|cypress", glob="package.json", output_mode="content")
Grep(pattern="pytest|unittest|hypothesis", glob="pyproject.toml", output_mode="content")
Grep(pattern="pytest|unittest|hypothesis", glob="requirements*.txt", output_mode="content")
# 2. Real-service infrastructure
Glob(pattern="**/docker-compose*.yml")
Glob(pattern="**/testcontainers*")
Grep(pattern="testcontainers", glob="**/package.json", output_mode="content")
Grep(pattern="testcontainers", glob="**/requirements*.txt", output_mode="content")
# 3. Existing test structure
Glob(pattern="**/tests/**/*.test.*")
Glob(pattern="**/tests/**/*.spec.*")
Glob(pattern="**/__tests__/**/*")
Glob(pattern="**/test_*.py")
# 4. Scope files (what to test)# If SCOPE specified, find matching source files
Grep(pattern=SCOPE, output_mode="files_with_matches")
Real-service decision:
docker-compose*.yml found → integration tests use real services
testcontainers in deps → use testcontainers for isolated service instances
Neither found + --real-services flag → error: "No docker-compose or testcontainers found. Install testcontainers or remove --real-services flag."
Neither found, no flag → integration tests use mocks (MSW/VCR)
# Detect and run coverage command# TypeScript: npx vitest run --coverage --reporter=json# Python: pytest --cov=<scope> --cov-report=json# Go: go test -coverprofile=coverage.out ./...# Parse coverage output to identify:# 1. Files with 0% coverage (priority targets)# 2. Files below threshold (default 70%)# 3. Uncovered functions/methods# 4. Untested edge cases (error paths, boundary conditions)
Output coverage baseline to user immediately (progressive output).
Phase 3: Generation (Parallel Agents)
Spawn test-generator agents per tier. Launch ALL in ONE message with run_in_background=true.
Isolation: spawn each tier agent with Agent(isolation="worktree"), one
worktree per tier (unit / integration / e2e) so they don't conflict. The
subagent bypass of the worktree-isolation guard was fixed in CC 2.1.154 and
completed in 2.1.203; ork's floor is >= 2.1.220, so every supported session
gets real isolation. Do not create worktrees by hand before spawning.
The new branch's base comes from the worktree.baseRef setting, never from a
hardcoded branch name. ork does not set it — a plugin cannot, and no ork
settings file carries it. Unless the operator put "baseRef": "head" in
.claude/settings.json or ~/.claude/settings.json, CC's default "fresh"
applies: every tier agent branches from origin/<default>, unpushed local
commits are invisible to it, and tsc fails with "cannot find module" for
code you just wrote. Verify the setting before spawning. Full pattern:
Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/worktree-agent-pattern.md")
# Unit tests agent (worktree-isolated)if"unit"in TIERS:
Agent(
subagent_type="ork:test-generator",
isolation="worktree",
prompt=f"""Generate unit tests for: {SCOPE}
Coverage gaps: {gap_map.unit_gaps}
Framework: {detected_framework}
Existing tests: {existing_test_files}
Focus on:
- AAA pattern (Arrange-Act-Assert)
- Parametrized tests for multiple inputs
- MSW/VCR for HTTP mocking (never mock fetch directly)
- Factory-based test data (FactoryBoy/faker-js)
- Edge cases: empty input, errors, timeouts, boundary values
- Target: 90%+ business logic coverage""",
run_in_background=True,
max_turns=50,
model=MODEL_OVERRIDE
)
# Integration + E2E agents follow the same pattern:# - subagent_type="ork:test-generator", isolation="worktree", run_in_background=True# - Integration focus: API endpoints (Supertest/httpx), real DB, contract tests (Pact), Zod schema validation# - E2E focus: Playwright, semantic locators, Page Object Model, axe-core a11y, visual regression## Special case — emulate (Vercel Labs stateful API emulation):# When integration tests need GitHub/Stripe/Resend/Okta/etc. emulated# (HMAC webhooks, parallel port isolation, full config from scratch),# spawn emulate-engineer instead of test-generator for that tier:# - subagent_type="ork:emulate-engineer" (same isolation="worktree" form)# - Pairs with emulate-seed skill for seed YAML patterns
Output each agent's results as soon as it returns — don't wait for all agents.
Focus mode (CC 2.1.101): In focus mode, include the full coverage report (before/after delta, test count per tier, files created) in your final message.
Phase 4: Execution
Run all generated tests and collect results.
# Run test commands per tier (PARALLEL if independent):# Unit: npx vitest run tests/unit/ OR pytest tests/unit/# Integration: npx vitest run tests/integration/ OR pytest tests/integration/# E2E: npx playwright test# Collect: pass count, fail count, error details, coverage delta
Phase 5: Heal Loop
Do NOT hand-roll the loop. Run the real executor:
Workflow(
scriptPath="${CLAUDE_PLUGIN_ROOT}/skills/cover/workflows/heal-loop.js",
args={"testCommand": "<tier test command>", "tier": "unit", "testGlob": "tests/unit/",
"maxIterations": 3} # from the effort table above; omitted defaults to 3
)
# One invocation per tier that has failures.
The iteration bound is enforced by the script, not by instruction.heal-loop.js
runs a real counted loop clamped to [2, 3]: each iteration spawns a diagnose agent that
actually executes the test command and returns structured pass/fail plus the verbatim
failure output, then a repair agent that receives that failure text and edits test files
only. It exits early the moment the suite is green.
The final iteration diagnoses but does not repair - there would be no run left to verify
that repair. So maxIterations: N means N diagnose runs and N-1 repair passes, and the
default 3 means 2 repairs. A ceiling of 1 is coerced to 2, since 1 would mean zero repairs.
Every failure is classified into the taxonomy (assertion, import, setup, timeout,
stale-selector, type, flaky, plus source-bug), which selects the fix strategy.
The workflow returns status: "healed" or a structured failure (status: "failed",
healed: false) carrying remaining_failures, failure_categories, and the per-iteration
ledger. Never report a "failed" result as a success: surface the still-failing tests in
the Phase 6 report.
Full /ork:cover runs (unit + integration + E2E with heal loop) take 15–45 min. After the Phase 6 report is assembled, call PushNotification(message=f"ork:cover complete — {SCOPE}: {coverage_pct}% coverage · {tests_generated} tests · {heal_loops} heal iters", status="proactive"). Full rule: Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/rules/push-notification-on-completion.md").
# Guard: Skip cron in headless/CI (CLAUDE_CODE_DISABLE_CRON)# if env CLAUDE_CODE_DISABLE_CRON is set, run a single check instead
CronCreate(
schedule="0 2 * * 0",
prompt="Weekly coverage drift check for {SCOPE}: npm test -- --coverage.
If coverage >= baseline → CronDelete.
If coverage drops > 5% → alert with regression details and recommendation."
)
Key Principles
Output limits (CC 2.1.77+): Opus 4.8 defaults to 64k output tokens (128k upper bound). For large test suites, chunk generation across multiple agent turns if output approaches the limit.
Partial reads (CC 2.1.144+): Read returns a [PARTIAL view] first page (not an error) on oversized files — re-read with explicit offset/limit so coverage analysis sees the whole file.
Tests only — never modify production source code, only generate test files
Real services when available — prefer testcontainers/docker-compose over mocks for integration tests because mock/prod divergence causes silent failures in production
Parallel generation — spawn one test-generator agent per tier in ONE message
Heal, don't loop forever — max 3 iterations, then report remaining failures
Progressive output — show results as each agent completes
Factory over fixtures — use FactoryBoy/faker-js for test data, not hardcoded values
Mock at network level — MSW/VCR, never mock fetch/axios directly
Agent Coordination
Context Passing
Each test-generator agent receives: coverage gaps for its tier, test framework config, real-service infrastructure (testcontainers, docker-compose), and fixture patterns from the project.
Monitor + Partial Results (CC 2.1.98)
Use Monitor for streaming test execution output from background agents:
# Stream test suite output in real-time
Bash(command="npm test -- --coverage 2>&1", run_in_background=true)
Monitor(pid=test_task_id) # Each line → notification
Full pattern reference (until-condition gates, partial-result salvage, TaskOutput vs Monitor decision): Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/monitor-patterns.md").
Partial results (CC 2.1.98): If a test-generator crashes mid-generation, synthesize what it produced:
for agent_result in test_gen_results:
if"[PARTIAL RESULT]"in agent_result.output:
# Agent crashed — check if it wrote any test files before dying
partial_tests = Glob(pattern="**/tests/**/*.test.*", path=agent_result.worktree)
if partial_tests:
# 6 passing tests from a crashed agent > 0 tests# Copy partial tests to main worktree, run them in Phase 4for test_file in partial_tests:
Bash(command=f"cp {test_file}{main_worktree}/{test_file}")
# Flag as partial in report
SendMessage (Test Healing)
When a generated test fails, the healer agent can request context from the generator:
SendMessage(to="test-generator-unit", message="Test user_service_test.py:42 fails — TypeError on mock return. What's the expected shape?")
Skill Chain
Standard chain: implement → cover → verify → commit. Use addBlockedBy between each.
Verification Gate
Before claiming coverage is complete, apply: Read("${CLAUDE_PLUGIN_ROOT}/skills/shared/rules/verification-gate.md"). Run the coverage report fresh. "Should pass" is not evidence.
Agent Status Protocol
All test-generator agents report using: Read("${CLAUDE_PLUGIN_ROOT}/agents/shared/status-protocol.md"). BLOCKED if tests can't be written due to missing interfaces. NEEDS_CONTEXT if test expectations are unclear.
Quality Bar
Done means all of these hold:
coverage report shows the before→after delta from the actual coverage command output, not an estimate
every generated test file was executed; final pass/fail counts pasted from the runner
no production source modified — only test files created; a source bug is reported, never silently patched
failures healed within the iteration budget (≤3, effort-scaled) or reported explicitly with the remaining-failure count
each requested tier (unit/integration/e2e) either produced tests or has a stated reason it was skipped
Related Skills
ork:implement — generates tests during implementation (Phase 5); use /ork:cover after for deeper coverage
Session recovery (CC 2.1.108+): After idle periods or interruptions, use /recap to restore conversational context alongside checkpoint-resume state. Enabled by default since CC 2.1.110 (even with telemetry disabled).
References
Load on demand with Read("${CLAUDE_PLUGIN_ROOT}/skills/cover/references/<file>"):
File
Content
real-service-detection.md
Docker-compose/testcontainers detection, service startup, teardown
