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 cache: Manage the karva cache
karva show-config: Print the resolved configuration karva would run with
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: 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 the given source path.

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

--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], and html[:DIR] write reports to disk.

--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

--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

--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-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 any of the [src], [terminal], and [test] settings. The selected profile is layered on top of any [profile.default] overrides, which themselves layer on top of the top-level options.

Defaults to default.

May also be set with the KARVA_PROFILE environment variable.

--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 events

--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

--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 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 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]