CLI Reference

karva

A Python test runner.

Usage

1

karva <COMMAND>

Commands

karva test

Run tests

karva snapshot

Manage snapshots created by karva.assert_snapshot()

karva version

Display Karva's version

karva help

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

karva test

Run tests

Usage

1

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.

--dry-run

Print discovered tests without executing them

--fail-fast

When set, the test will fail immediately if any test fails.

This only works when running tests in parallel.

--help, -h

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

--match, -m name-patterns

Filter tests by name using a regular expression.

Only tests whose fully qualified name matches the pattern will run. Uses partial matching (the pattern can match anywhere in the name). When specified multiple times, a test runs if it matches any of the patterns.

Examples: -m auth, -m '^test::test_login', -m 'slow|fast'.

--no-cache

Disable reading the karva cache for test duration history

--no-ignore

When set, .gitignore files will not be respected

--no-parallel

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

--no-progress

When set, we will not show individual test case results during execution

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

--quiet, -q

Use quiet output (or -qq for silent output)

--retry retry

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

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

--tag, -t tag-expressions

Filter tests by tag expression. Only tests with matching custom tags will run.

Expressions support and, or, not, and parentheses for grouping. When specified multiple times, a test runs if it matches any of the expressions.

Examples: -t slow, -t 'not slow', -t 'slow and integration', -t 'slow or integration', -t '(slow or fast) and not flaky'.

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

1

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

1

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

1

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

1

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

1

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

1

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

1

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

1

karva snapshot help [COMMAND]

karva version

Display Karva's version

Usage

1

karva version

Options

--help, -h

Print help

karva help

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

Usage

1

karva help [COMMAND]