Skip to content
coverctl

Quick Start

This guide will help you set up coverctl in your project and run your first coverage check.

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)

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

    Domain     Coverage  Required  Status
    ─────────────────────────────────────
    core         87.3%      85%    PASS
    api          81.2%      80%    PASS
    cli          76.4%      75%    PASS
    ─────────────────────────────────────
    Overall      82.1%      75%    PASS

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__/**"

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”