Skip to content
coverctl

Quick start (terminal)

This guide sets up coverctl from your terminal and runs your first coverage check from the command line. The same .coverctl.yaml works whether you call coverctl from a terminal or from an AI agent later.

Prerequisites

Section titled “Prerequisites”
  • A project with tests in any supported language
  • For Go projects: Go 1.25 or later installed (other languages use their native test runners)
  • coverctl installed (Installation Guide)

Where coverctl works best (and where it may need adjustments)

Section titled “Where coverctl works best (and where it may need adjustments)”

Calibrate expectations before you start.

Works best

  • Standard Go, Python, TypeScript/JavaScript, Java, Rust projects with a conventional layout (one language per repo or clearly separated per-package).
  • Repos with an existing test suite that produces coverage output (go test -cover, pytest --cov, nyc/c8, cargo tarpaulin, JaCoCo).
  • Domain-level enforcement (internal/payments, src/api, …) — this is the differentiated capability.

May need adjustments

  • Mock-heavy codebases. Line coverage measures execution, not quality; in repos where most logic lives behind mocks, thresholds alone can be misleading. Pair with coverctl debt and code-review judgment.
  • Exotic or mixed monorepos (matrix builds, multiple workspaces in one Cargo project, mixed Bazel + npm). The monorepo guide covers the supported shapes; one-off layouts may need an explicit domains block.
  • Smaller-ecosystem languages (Shell, Dart, Scala, Elixir). Parsing and runner support are real but less battle-tested than Go/Python/JS. File issues with a sample profile if something looks off.

Setup

Section titled “Setup”

  1. Navigate to your project

    Terminal window
    cd your-project

  2. Initialize coverctl

    Run the interactive setup wizard:

    Terminal window
    coverctl init

    The wizard will:

    • Auto-detect domains from your project structure
    • Let you adjust coverage thresholds with arrow keys
    • Create .coverctl.yaml configuration

  3. Run coverage check

    Terminal window
    coverctl check

    This will:

    • Run your language’s test runner with coverage instrumentation
    • Evaluate coverage per domain
    • Report pass/fail status for each domain

  4. Review results

    On a real first run with thresholds set near current coverage, expect a mix of PASS and FAIL. A failing domain is normal — coverctl tells you exactly what to do next:

    Domain  Coverage  Required  Status
    core    87.3%     85.0%     PASS
    api     72.1%     80.0%     FAIL (-7.9%)
    cli     76.4%     75.0%     PASS
    

    ✗ 1 of 3 domains below threshold.
      → coverctl suggest api    show uncovered files in failing domain
      → coverctl debt           list smallest tests to add

    When every domain passes, the footer points at the next step:

    Domain  Coverage  Required  Status
    core    87.3%     85.0%     PASS
    api     81.2%     80.0%     PASS
    cli     76.4%     75.0%     PASS
    

    ✓ All 3 domain(s) pass.
      → coverctl record         save coverage baseline for next run

Example Configurations

Section titled “Example Configurations”

After running coverctl init, you’ll have a .coverctl.yaml file tailored to your language. Here are examples for different project types:

Go Project

Section titled “Go Project”
version: 1
policy:
  default:
    min: 75
  domains:
    - name: core
      match: ["./internal/core/..."]
      min: 85
    - name: api
      match: ["./internal/api/..."]
      min: 80
    - name: cli
      match: ["./cmd/..."]
      min: 75
exclude:
  - "**/generated/**"
  - "**/mocks/**"

Python Project

Section titled “Python Project”
version: 1
language: python
profile: coverage.xml
policy:
  default:
    min: 75
  domains:
    - name: core
      match: ["src/core/**"]
      min: 85
    - name: api
      match: ["src/api/**"]
      min: 80
exclude:
  - "**/migrations/**"

TypeScript Project

Section titled “TypeScript Project”
version: 1
language: javascript
profile: coverage/lcov.info
policy:
  default:
    min: 75
  domains:
    - name: components
      match: ["src/components/**"]
      min: 80
    - name: services
      match: ["src/services/**"]
      min: 85
exclude:
  - "**/*.test.ts"
  - "**/__mocks__/**"

Rust Project

Section titled “Rust Project”
version: 1
language: rust
profile: coverage.lcov
policy:
  default:
    min: 75
  domains:
    - name: core
      match: ["src/core/**"]
      min: 85
    - name: api
      match: ["src/api/**"]
      min: 80
exclude:
  - "tests/**"
  - "benches/**"

Generate the LCOV profile coverctl reads:

Terminal window
cargo install cargo-llvm-cov          # one-time
cargo llvm-cov --lcov --output-path coverage.lcov
coverctl check

cargo-llvm-cov is the standard Rust coverage tool; coverctl reads its LCOV output by default. For Cargo workspaces, run cargo llvm-cov from the workspace root and point profile: at the generated file.

Common Workflows

Section titled “Common Workflows”

Development Mode

Section titled “Development Mode”

Use watch mode for continuous feedback while developing:

Terminal window
coverctl watch

CI Pipeline

Section titled “CI Pipeline”

Run with JSON output and strict thresholds:

Terminal window
coverctl check -o json --fail-under 80

Generate HTML Report

Section titled “Generate HTML Report”

Create a visual coverage report:

Terminal window
coverctl report -o html > coverage.html

Next Steps

Section titled “Next Steps”