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

--durations n

Show the N slowest tests after the run completes

--fail-fast

Stop scheduling new tests after the first failure.

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

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

Disable reading the karva cache for test duration history

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

When set, .gitignore files will not be respected

--no-parallel

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

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

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

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

--show-output, -s

Show Python stdout during test execution

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

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

--test-prefix test-prefix

The prefix of the test functions

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

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