coverctl check

The check command runs the project’s native coverage runner, evaluates coverage per domain, and enforces policy thresholds from .coverctl.yaml. It is governance over go test / pytest / npm test / … — not a replacement for go tool cover.

Usage

coverctl check [flags]

Alias: coverctl c

Flags

Configuration

Flag	Description	Default
-c, --config	Config file path	.coverctl.yaml
-p, --profile	Coverage profile output path	.cover/coverage.out
--from-profile	Use existing coverage profile instead of running tests	false
-d, --domain	Filter to specific domain (repeatable)	all domains
-o, --output	Output format: text, json, html	text

Policy Enforcement

Flag	Description
--fail-under N	Fail if overall coverage is below N percent
--ratchet	Fail if coverage decreases from previous recorded value
--validate	Validate config file without running tests
--show-delta	Show coverage change from previous run
--history	History file path for delta display

Build/Test Flags

Flag	Description
--tags	Build tags (e.g., integration,e2e)
--race	Enable race detector
--short	Skip long-running tests
-v	Verbose test output
--run	Run only tests matching pattern
--timeout	Test timeout (e.g., 10m, 1h)
--test-arg	Additional argument forwarded to the native test runner (repeatable)

Incremental Mode

Flag	Description	Default
--incremental	Only test packages with changed files	false
--incremental-ref	Git ref to compare against	HEAD~1

Incremental mode speeds up CI by only testing packages that have changed.

Examples

Basic Usage

# Run coverage check with default config
coverctl check

# Use custom config file
coverctl check -c my-config.yaml

# Check specific domains
coverctl check -d core -d api

CI Pipeline

# Fail if coverage below 80%
coverctl check --fail-under 80

# Prevent coverage regression
coverctl check --ratchet

# JSON output for parsing
coverctl check -o json --ci

Integration Tests

# Run with integration build tag
coverctl check --tags integration

# Extended timeout for slow tests
coverctl check --tags integration --timeout 30m

# With race detector
coverctl check --race --timeout 20m

Incremental Mode

# Only test changed packages (faster CI)
coverctl check --incremental

# Compare against specific branch
coverctl check --incremental --incremental-ref origin/main

# Combine with other flags
coverctl check --incremental --fail-under 80 --ci

Validation Only

# Check config syntax without running tests
coverctl check --validate

Use Existing Profile

# Evaluate an existing profile without running tests
coverctl check --from-profile --profile coverage.out

Note: --from-profile only skips running tests; policy evaluation still runs against every configured domain. If you re-use a profile that already falls below a domain’s min, the check will keep failing. To unblock, regenerate a fresh profile with coverctl run / coverctl check, lower the domain thresholds or remove/adjust the matching rules, or scope the evaluation via --domain so that the enforced domains actually meet your coverage targets.

Output

Text Output (default)

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

JSON Output

{
  "passed": true,
  "domains": [
    {
      "name": "core",
      "covered": 1234,
      "total": 1414,
      "percent": 87.3,
      "required": 85,
      "status": "pass"
    }
  ]
}

Troubleshooting

If coverctl check disagrees with previously recorded history, make sure the history profile was produced by coverctl run or coverctl check. On Go projects, profiles from plain go test -coverprofile can omit -coverpkg instrumentation and diverge from coverctl’s numbers — that is a Go-runner detail, not the product model.

Exit Codes

Code	Meaning
0	All policy checks passed
1	Policy violation (coverage below threshold)
2	Invalid configuration or arguments
3	Test execution failed

Next

suggestPropose thresholds after a check.

runProduce a profile without enforcing policy.

MCP check toolSame gate, agent-callable.