coverage-ratchet

Gate Xcode test coverage against a committed baseline that only rises.

696|66|Updated Oct 29, 2025
One-click install
npx skills add https://github.com/rshankras/claude-code-apple-skills --skill coverage-ratchet
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: coverage-ratchet
Source: https://github.com/rshankras/claude-code-apple-skills/tree/main/skills/testing/coverage-ratchet
Command: npx skills add https://github.com/rshankras/claude-code-apple-skills --skill coverage-ratchet

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Build and test gates prove existing tests pass but cannot prove tests were actually written, so agent-written or rushed code ships with zero new tests while everything stays green. This Skill closes that hole with a deterministic coverage ratchet: line coverage is measured on every run and may never drop below a committed baseline.

Core Features & Use Cases

  • Coverage Gate Script: An xccov-based bash script runs the test suite with coverage enabled, extracts the app target's line coverage, and fails the build if it drops below the committed .coverage-baseline (minus a small jitter epsilon).
  • Ratchet-Up Workflow: When coverage rises meaningfully, the script suggests raising the baseline in the same commit as the tests that earned it, so the floor only tightens over time.
  • Advisory CRAP Report: A second script combines SwiftLint cyclomatic complexity with per-function xccov coverage to compute CRAP scores, listing the top 20 functions where a new test buys the most risk reduction.
  • Use Case: An iOS project where AI agents generate features that pass builds but include no tests can adopt this gate so every verify step deterministically proves coverage never regressed.

Quick Start

Set up a coverage ratchet gate for my Xcode project by copying the coverage-gate script, initializing the baseline, and wiring it into my test workflow.

Frequently Asked Questions about coverage-ratchet

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enforce a test coverage threshold in Xcode?

Use the coverage-gate script: run it once with --init to measure the app target's line coverage via xccov and write a .coverage-baseline file, then commit both. Subsequent runs fail if coverage drops below the baseline minus a 0.0025 jitter epsilon.

Why use a coverage ratchet instead of a fixed coverage threshold?

A fixed threshold like 80% either fails immediately on an existing codebase and gets disabled, or is set below current reality and gates nothing. A ratchet starts from the project's measured coverage and only tightens, so it works on any codebase from day one.

How do I find which Swift functions most need tests?

Run the crap-report script with an xcresult bundle. It combines SwiftLint cyclomatic complexity with per-function xccov coverage into CRAP scores and prints the top 20 functions where complexity is high and coverage is low.

Does the coverage gate work with SwiftLint and CI pipelines?

The gate itself only needs xcodebuild and xccov, so it wires into any CI step that can run a bash script. SwiftLint is required only for the advisory CRAP report, never for the gate.

What happens when the coverage measurement tooling fails?

The script fails loudly with a nonzero exit if xccov returns an unexpected JSON shape or the target is missing from the report. A broken measurement never reads as a passing gate.

When should I lower the coverage baseline?

Lowering the baseline is allowed only with a written reason in the commit message, such as deleting a well-covered module. Raising it is routine and should happen in the same commit as the tests that earned the increase.