CLI Reference

karva

A Python test runner.

Usage

Text Only
karva <COMMAND>

Commands

karva test: Run tests
karva snapshot: Manage snapshots created by karva.assert_snapshot()
karva coverage: Read and report native Karva coverage data
karva cache: Manage the karva cache
karva show-config: Print the resolved configuration karva would run with
karva server: Run the language server
karva version: Display Karva's version
karva help: Print this message or the help of the given subcommand(s)

karva test

Run tests

Usage

Text Only
karva test [OPTIONS] [PATH]...

Arguments

PATHS: List of files, directories, or test functions to test [default: tests if it exists, otherwise the project root]

Options

--color color

Control when colored output is used

Possible values:

auto: Display colors if the output goes to an interactive terminal
always: Always display colors
never: Never display colors

--config-file path

The path to a karva.toml file to use for configuration.

While karva configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the KARVA_CONFIG_FILE environment variable.

--cov source

Measure code coverage for a source path or importable Python name.

May be passed multiple times to measure several sources. Pass without a value (--cov) to measure the current working directory.

--cov-append cov-append

Add this run to compatible native coverage data instead of replacing it

Possible values:

true
false

--cov-branch

Measure branch coverage in addition to line coverage

--cov-context context

Record per-test coverage contexts.

Currently supports test, which records the qualified test name for each line executed while that test is running. Contexts are emitted in JSON coverage reports.

Possible values:

test: Record the current test name for each covered line

--cov-fail-under percent

Fail the run if total coverage is below the given percentage.

Accepts any value in 0..=100 (fractional values such as 90.5 are allowed). When the reported TOTAL percentage is below the threshold, the test command exits with a non-zero status even if every test passed. Has no effect when tests have already failed.

--cov-include glob

Include only coverage report files whose project-relative path matches this glob.

May be passed multiple times.

--cov-omit glob

Exclude coverage report files whose project-relative path matches this glob.

May be passed multiple times.

--cov-report type

Coverage report type.

term (default) prints a compact terminal table. term-missing extends it with a Missing column listing the uncovered line numbers per file. xml[:PATH], json[:PATH], html[:DIR], and lcov[:PATH] write reports to disk. May be passed multiple times to render several reports from one analysis. Pass an empty value (--cov-report=) to persist native data only.

--doctest-modules doctest-modules

Collect examples from module, class, function, and method docstrings

Possible values:

true
false

--durations n

Show the N slowest tests after the run completes

--fail-fast fail-fast

Stop scheduling new tests after the first failure.

Equivalent to --max-fail=1. Use --no-fail-fast to keep running after failures.

Possible values:

true
false

--fail-slow seconds

Duration budget, in seconds, for a test's full lifecycle.

Unlike --timeout, a test is always allowed to finish — including fixture teardown — before being reported as a failure if the total duration exceeded this budget. A test-level @karva.tags.fail_slow decorator overrides the default for that specific test.

Accepts fractional seconds such as --fail-slow=1 or --fail-slow=0.25.

--filter, -E filter-expressions

Filter tests using a filterset expression.

Predicates: test(<matcher>) matches the fully qualified test name; tag(<matcher>) matches any custom tag on the test.

Matchers: =exact, ~substring, /regex/, #glob. The default is substring for test() and exact for tag(). String bodies may be quoted ("...") to allow spaces or reserved characters.

Operators: & / and, | / or, not / !, and - as shorthand for "and not". Use parentheses for grouping. and binds tighter than or.

When specified multiple times, a test runs if it matches any of the expressions (OR semantics across flags).

Examples: -E 'tag(slow)', -E 'test(/^mod::test_login$/)', -E 'tag(slow) & test(~login)', -E '(tag(fast) | tag(unit)) - tag(flaky)'.

--final-status-level level

Test summary information to display at the end of the run [default: pass]

May also be set with the KARVA_FINAL_STATUS_LEVEL environment variable.

Possible values:

none: Don't display the summary line or any diagnostic blocks
fail: Only display the summary line and diagnostics on failure
retry: Display the summary line plus diagnostics on failure or when any test was retried. The summary line gains a N retried count whenever a retry happened
slow: Same as retry until a slow-test threshold is implemented
pass: Always display the summary line and diagnostics (default)
skip: Same as pass until skip-specific summary lines are emitted
all: Always display every summary status

--flaky-result action

Whether tests that pass only after a retry should pass or fail the run

May also be set with the KARVA_FLAKY_RESULT environment variable.

Possible values:

pass: A test that passes after retrying does not fail the run
fail: Any test requiring a retry fails the run

--help, -h

Print help (see a summary with '-h')

--last-failed, --lf

Re-run only the tests that failed in the previous run

--max-fail n

Stop scheduling new tests after this many failures.

Accepts a positive integer such as --max-fail=3. --max-fail=1 is equivalent to the legacy --fail-fast, and --no-fail-fast clears the limit. When --max-fail is provided alongside --fail-fast or --no-fail-fast, --max-fail takes precedence.

--no-cache no-cache

Disable reading the karva cache for test duration history

Possible values:

true
false

--no-capture

Disable output capture and run tests serially.

Lets stdout/stderr from tests flow directly to the terminal, useful when debugging with print statements or interactive debuggers. Implies --show-output and forces a single worker so output from concurrent tests cannot interleave.

--no-cov

Disable coverage measurement for this run.

Overrides any --cov flag and any [coverage] sources configured in karva.toml / pyproject.toml. Useful when iterating locally without editing config.

--no-cov-on-fail

Do not render coverage reports when tests fail.

Native coverage data is still persisted.

--no-fail-fast

Run every test regardless of how many fail.

Clears any fail-fast or max-fail value set in configuration. When --max-fail is provided alongside --no-fail-fast, --max-fail takes precedence.

--no-ignore no-ignore

When set, .gitignore files will not be respected

Possible values:

true
false

--no-parallel no-parallel

Disable parallel execution (equivalent to --num-workers 1)

Possible values:

true
false

--no-tests action

Behavior when no tests are found to run [default: auto]

May also be set with the KARVA_NO_TESTS environment variable.

Possible values:

auto: Automatically determine behavior: fail if no filter expressions were given, pass silently if filters were given
pass: Silently exit with code 0
warn: Produce a warning and exit with code 0
fail: Produce an error message and exit with a non-zero code

--num-workers, -n num-workers

Number of parallel workers (default: number of CPU cores)

--output-format output-format

The format to use for printing diagnostic messages

Possible values:

full: Print diagnostics verbosely, with context and helpful hints (default)
concise: Print diagnostics concisely, one per line

--partition strategy:m/n

Run only one partition of the collected tests.

Accepts slice:M/N where this run executes slice M of N total slices (1-indexed). Tests are sorted by qualified name and then distributed by cycling through slices: test 1 to slice 1, test 2 to slice 2, ..., test N+1 to slice 1, and so on. Running every slice:1/N through slice:N/N together covers every collected test exactly once.

Also accepts hash:M/N, which assigns each test to a stable bucket based on its qualified name. Hash partitioning is less balanced than slice, but adding or removing a test only changes that test's bucket.

--profile, -P name

Configuration profile to use.

Profiles are defined as [profile.<name>] sections in karva.toml (or [tool.karva.profile.<name>] in pyproject.toml) and may override env, src, terminal, test, coverage, junit, and overrides. The selected profile is layered on top of any [profile.default] overrides, which themselves layer on top of Karva's built-in defaults.

Defaults to default.

May also be set with the KARVA_PROFILE environment variable.

--random-seed seed

Seed used by --shuffle. Does not enable shuffling by itself.

Pass last to reuse the most recently generated seed.

--result-format format

Machine-readable test result format

Possible values:

json: Write one JSON document with the full run result
jsonl: Write newline-delimited JSON records

--result-output path

Write machine-readable test results to this path

--retry retry

When set, the test will retry failed tests up to this number of times

--run-ignored run-ignored

Run ignored tests

Possible values:

only: Run only ignored tests
all: Run both ignored and non-ignored tests

--run-timeout seconds

Wall-clock limit for the whole run, in seconds.

When the run takes longer than this duration, karva stops the remaining workers and exits with a failure status. Accepts fractional seconds such as --run-timeout=1800 or --run-timeout=0.5.

--show-output, -s show-output

Show Python stdout during test execution

Possible values:

true
false

--shuffle shuffle

Use seeded randomized ordering instead of duration-aware scheduling

Possible values:

true
false

--slow-timeout seconds

Threshold in seconds after which a test is flagged as slow.

When a test takes longer than this duration, it is reported with a SLOW status line (gated on --status-level=slow or higher) and counted in the run summary. Pass a positive number such as --slow-timeout=60 or --slow-timeout=0.5.

--snapshot-update snapshot-update

Update snapshots directly instead of creating pending .snap.new files.

When set, karva.assert_snapshot() will write directly to .snap files, accepting any changes automatically.

Possible values:

true
false

--status-level level

Test result statuses to display during the run [default: pass]

May also be set with the KARVA_STATUS_LEVEL environment variable.

Possible values:

none: Don't display any test result lines (or the "Starting" header)
fail: Only display failed test results
retry: Display failed test results plus a TRY N FAIL line for each failed attempt that was retried
slow: Display failed, retried, and slow test results. Karva does not yet have a slow-test threshold, so this currently behaves like retry
pass: Display failed, retried, slow, and passing test results (default)
skip: Additionally display skipped test results
all: Display all test result statuses

--termination-grace-period seconds

Grace period before force-killing workers during shutdown, in seconds.

When karva stops workers because of Ctrl+C, fail-fast, or --run-timeout, it first asks them to terminate gracefully. If they are still running after this period, karva force-kills them. Pass 0 to force-kill immediately after graceful termination.

--test-prefix test-prefix

The prefix of the test functions

--timeout seconds

Hard per-test timeout, in seconds.

Tests that run longer than this duration are killed and reported as failures. A test-level @karva.tags.timeout decorator overrides the default for that specific test.

Accepts fractional seconds such as --timeout=120 or --timeout=0.5.

--try-import-fixtures try-import-fixtures

When set, we will try to import functions in each test file as well as parsing the ast to find them.

This is often slower, so it is not recommended for most projects.

Possible values:

true
false

--verbose, -v

Use verbose output (or -vv and -vvv for more verbose output)

--watch

Re-run tests when Python source files change

karva snapshot

Manage snapshots created by karva.assert_snapshot()

Usage

Text Only
karva snapshot <COMMAND>

Commands

karva snapshot accept: Accept all (or filtered) pending snapshots
karva snapshot reject: Reject all (or filtered) pending snapshots
karva snapshot pending: List pending snapshots
karva snapshot review: Interactively review pending snapshots
karva snapshot prune: Remove snapshot files whose source test no longer exists
karva snapshot delete: Delete all (or filtered) snapshot files (.snap and .snap.new)
karva snapshot help: Print this message or the help of the given subcommand(s)

karva snapshot accept

Accept all (or filtered) pending snapshots

Usage

Text Only
karva snapshot accept [PATH]...

Arguments

PATHS: Optional paths to filter snapshots by directory or file

Options

--help, -h: Print help

karva snapshot reject

Reject all (or filtered) pending snapshots

Usage

Text Only
karva snapshot reject [PATH]...

Arguments

PATHS: Optional paths to filter snapshots by directory or file

Options

--help, -h: Print help

karva snapshot pending

List pending snapshots

Usage

Text Only
karva snapshot pending [PATH]...

Arguments

PATHS: Optional paths to filter snapshots by directory or file

Options

--help, -h: Print help

karva snapshot review

Interactively review pending snapshots

Usage

Text Only
karva snapshot review [PATH]...

Arguments

PATHS: Optional paths to filter snapshots by directory or file

Options

--help, -h: Print help

karva snapshot prune

Remove snapshot files whose source test no longer exists

Usage

Text Only
karva snapshot prune [OPTIONS] [PATH]...

Arguments

PATHS: Optional paths to filter snapshots by directory or file

Options

--dry-run: Show which snapshots would be removed without deleting them
--help, -h: Print help

karva snapshot delete

Delete all (or filtered) snapshot files (.snap and .snap.new)

Usage

Text Only
karva snapshot delete [OPTIONS] [PATH]...

Arguments

PATHS: Optional paths to filter which snapshot files are deleted

Options

--dry-run: Show which snapshot files would be deleted without removing them
--help, -h: Print help

karva snapshot help

Print this message or the help of the given subcommand(s)

Usage

Text Only
karva snapshot help [COMMAND]

karva coverage

Read and report native Karva coverage data

Usage

Text Only
karva coverage [OPTIONS] <COMMAND>

Commands

karva coverage report: Print the compact terminal coverage report
karva coverage html: Generate a navigable annotated HTML coverage report
karva coverage xml: Generate a Cobertura-compatible XML coverage report
karva coverage json: Export documented JSON coverage data
karva coverage lcov: Generate an LCOV tracefile
karva coverage combine: Combine native coverage artifacts
karva coverage erase: Delete native combined and shard coverage data
karva coverage help: Print this message or the help of the given subcommand(s)

karva coverage report

Print the compact terminal coverage report

Usage

Text Only
karva coverage report [OPTIONS] [SELECTOR]...

Arguments

SELECTORS: File paths, directories, or dotted module names to include

Options

--append append

Append to the output file instead of replacing it

Possible values:

true
false

--config-file path

The path to a karva.toml file to use for configuration

May also be set with the KARVA_CONFIG_FILE environment variable.

--contexts regex

Include execution attributed to a matching context regular expression

--data-file path

Native coverage artifact path, relative to the project root

--fail-under percent

Fail when total coverage is below this percentage

--format format

Report representation

[default: text]

Possible values:

text: Human-readable aligned table
markdown: GitHub-flavored Markdown table
total: Numeric total percentage only

--help, -h

Print help (see a summary with '-h')

--include glob

Include only report paths matching this glob

--omit glob

Exclude report paths matching this glob after inclusion

--output path

Write the report to this path instead of stdout

--precision n

Decimal places shown in coverage percentages

--profile, -P name

Configuration profile to resolve

May also be set with the KARVA_PROFILE environment variable.

--show-missing

Show missing line ranges and branch arcs

--skip-covered

Hide files with complete coverage without changing totals

--skip-empty

Hide files with no statements or branches without changing totals

--sort sort

Column used to order displayed files

[default: name]

Possible values:

name: Source path
statements: Statement count
misses: Missing statement count
branches: Branch count
partial-branches: Partial branch count
coverage: Coverage percentage

karva coverage html

Generate a navigable annotated HTML coverage report

Usage

Text Only
karva coverage html [OPTIONS]

Options

--config-file path

The path to a karva.toml file to use for configuration

May also be set with the KARVA_CONFIG_FILE environment variable.

--contexts regex

Include execution attributed to a matching context regular expression

--data-file path

Native coverage artifact path, relative to the project root

--directory path

Directory receiving the report files

[default: htmlcov]

--fail-under percent

Fail when total coverage is below this percentage

--help, -h

Print help

--include glob

Include only report paths matching this glob

--omit glob

Exclude report paths matching this glob after inclusion

--precision n

Decimal places shown in coverage percentages

--profile, -P name

Configuration profile to resolve

May also be set with the KARVA_PROFILE environment variable.

--show-contexts

Show execution contexts beside annotated source lines

--skip-covered

Omit fully covered source pages from the index

--skip-empty

Omit sources with no statements or branches from the index

--title title

Report title shown in the browser

[default: Coverage report]

karva coverage xml

Generate a Cobertura-compatible XML coverage report

Usage

Text Only
karva coverage xml [OPTIONS]

Options

--config-file path

The path to a karva.toml file to use for configuration

May also be set with the KARVA_CONFIG_FILE environment variable.

--contexts regex

Include execution attributed to a matching context regular expression

--data-file path

Native coverage artifact path, relative to the project root

--fail-under percent

Fail when total coverage is below this percentage

--help, -h

Print help

--include glob

Include only report paths matching this glob

--omit glob

Exclude report paths matching this glob after inclusion

--output path

Path receiving the XML report

[default: coverage.xml]

--precision n

Decimal places shown in coverage percentages

--profile, -P name

Configuration profile to resolve

May also be set with the KARVA_PROFILE environment variable.

karva coverage json

Export documented JSON coverage data

Usage

Text Only
karva coverage json [OPTIONS]

Options

--config-file path

The path to a karva.toml file to use for configuration

May also be set with the KARVA_CONFIG_FILE environment variable.

--contexts regex

Include execution attributed to a matching context regular expression

--data-file path

Native coverage artifact path, relative to the project root

--fail-under percent

Fail when total coverage is below this percentage

--help, -h

Print help

--include glob

Include only report paths matching this glob

--omit glob

Exclude report paths matching this glob after inclusion

--output path

Path receiving the JSON report

[default: coverage.json]

--precision n

Decimal places shown in coverage percentages

--pretty-print

Format output with indentation and line breaks

--profile, -P name

Configuration profile to resolve

May also be set with the KARVA_PROFILE environment variable.

--show-contexts

Include per-line execution contexts

karva coverage lcov

Generate an LCOV tracefile

Usage

Text Only
karva coverage lcov [OPTIONS]

Options

--config-file path

The path to a karva.toml file to use for configuration

May also be set with the KARVA_CONFIG_FILE environment variable.

--contexts regex

Include execution attributed to a matching context regular expression

--data-file path

Native coverage artifact path, relative to the project root

--fail-under percent

Fail when total coverage is below this percentage

--help, -h

Print help

--include glob

Include only report paths matching this glob

--omit glob

Exclude report paths matching this glob after inclusion

--output path

Path receiving the LCOV tracefile

[default: coverage.lcov]

--precision n

Decimal places shown in coverage percentages

--profile, -P name

Configuration profile to resolve

May also be set with the KARVA_PROFILE environment variable.

karva coverage combine

Combine native coverage artifacts

Usage

Text Only
karva coverage combine [OPTIONS] [PATH]...

Arguments

INPUTS: Native coverage files or directories containing them

Options

--append

Include an existing combined artifact in the result

--config-file path

The path to a karva.toml file to use for configuration

May also be set with the KARVA_CONFIG_FILE environment variable.

--contexts regex

Include execution attributed to a matching context regular expression

--data-file path

Native coverage artifact path, relative to the project root

--fail-under percent

Fail when total coverage is below this percentage

--help, -h

Print help

--include glob

Include only report paths matching this glob

--keep

Keep input artifacts after a successful combination

--omit glob

Exclude report paths matching this glob after inclusion

--precision n

Decimal places shown in coverage percentages

--profile, -P name

Configuration profile to resolve

May also be set with the KARVA_PROFILE environment variable.

karva coverage erase

Delete native combined and shard coverage data

Usage

Text Only
karva coverage erase [OPTIONS]

Options

--config-file path

The path to a karva.toml file to use for configuration

May also be set with the KARVA_CONFIG_FILE environment variable.

--contexts regex

Include execution attributed to a matching context regular expression

--data-file path

Native coverage artifact path, relative to the project root

--fail-under percent

Fail when total coverage is below this percentage

--help, -h

Print help

--include glob

Include only report paths matching this glob

--omit glob

Exclude report paths matching this glob after inclusion

--precision n

Decimal places shown in coverage percentages

--profile, -P name

Configuration profile to resolve

May also be set with the KARVA_PROFILE environment variable.

karva coverage help

Print this message or the help of the given subcommand(s)

Usage

Text Only
karva coverage help [COMMAND]

karva cache

Manage the karva cache

Usage

Text Only
karva cache <COMMAND>

Commands

karva cache prune: Remove all but the most recent test run from the cache
karva cache clean: Remove the entire cache directory
karva cache help: Print this message or the help of the given subcommand(s)

karva cache prune

Remove all but the most recent test run from the cache

Usage

Text Only
karva cache prune

Options

--help, -h: Print help

karva cache clean

Remove the entire cache directory

Usage

Text Only
karva cache clean

Options

--help, -h: Print help

karva cache help

Print this message or the help of the given subcommand(s)

Usage

Text Only
karva cache help [COMMAND]

karva show-config

Print the resolved configuration karva would run with

Usage

Text Only
karva show-config [OPTIONS]

Options

--config-file path

The path to a karva.toml file to use for configuration

May also be set with the KARVA_CONFIG_FILE environment variable.

--help, -h

Print help (see a summary with '-h')

--profile, -P name

Configuration profile to resolve.

Defaults to default.

May also be set with the KARVA_PROFILE environment variable.

karva server

Run the language server

Usage

Text Only
karva server

Options

--help, -h: Print help

karva generate-shell-completion

Generate shell completion

Usage

Text Only
karva generate-shell-completion <SHELL>

Arguments

SHELL: The shell to generate the completion script for

Options

--help, -h: Print help

karva version

Display Karva's version

Usage

Text Only
karva version

Options

--help, -h: Print help

karva help

Print this message or the help of the given subcommand(s)

Usage

Text Only
karva help [COMMAND]