test

./pants test [args]

Run tests.

Backend: pants.core
Config section: [test]

Basic options

`debug`

--[no-]test-debug

PANTS_TEST_DEBUG

default: False

Run tests sequentially in an interactive process. This is necessary, for example, when you add breakpoints to your code.

`debug_adapter`

--[no-]test-debug-adapter

PANTS_TEST_DEBUG_ADAPTER

default: False

Run tests sequentially in an interactive process, using a Debug Adapter (https://microsoft.github.io/debug-adapter-protocol/) for the language if supported.

The interactive process used will be immediately blocked waiting for a client before continuing.

This option implies --debug.

`force`

--[no-]test-force

PANTS_TEST_FORCE

default: False

Force the tests to run, even if they could be satisfied from cache.

`output`

--test-output=<ShowOutput>

PANTS_TEST_OUTPUT

one of: all, failed, none
default: failed

Show stdout/stderr for these tests.

`use_coverage`

--[no-]test-use-coverage

PANTS_TEST_USE_COVERAGE

default: False

Generate a coverage report if the test runner supports it.

`open_coverage`

--[no-]test-open-coverage

PANTS_TEST_OPEN_COVERAGE

default: False

If a coverage report file is generated, open it on the local system if the system supports this.

`extra_env_vars`

--test-extra-env-vars="['<str>', '<str>', ...]"

PANTS_TEST_EXTRA_ENV_VARS

default: []

Additional environment variables to include in test processes. Entries are strings in the form ENV_VAR=value to use explicitly; or just ENV_VAR to copy the value of a variable in Pants's own environment.

`shard`

--test-shard=<str>

PANTS_TEST_SHARD

default:

A shard specification of the form "k/N", where N is a positive integer and k is a non-negative integer less than N.

If set, the request input targets will be deterministically partitioned into N disjoint subsets of roughly equal size, and only the k'th subset will be used, with all others discarded.

Useful for splitting large numbers of test files across multiple machines in CI. For example, you can run three shards with --shard=0/3, --shard=1/3, --shard=2/3.

Note that the shards are roughly equal in size as measured by number of files. No attempt is made to consider the size of different files, the time they have taken to run in the past, or other such sophisticated measures.

`timeouts`

--[no-]test-timeouts

PANTS_TEST_TIMEOUTS

default: True

Enable test target timeouts. If timeouts are enabled then test targets with a timeout= parameter set on their target will time out after the given number of seconds if not completed. If no timeout is set, then either the default timeout is used or no timeout is configured.

Advanced options

`report`

--[no-]test-report

PANTS_TEST_REPORT

default: False

Write test reports to --report-dir.

`report_dir`

--test-report-dir=<str>

PANTS_TEST_REPORT_DIR

default: {distdir}/test/reports

Path to write test reports to. Must be relative to the build root.

`timeout_default`

--test-timeout-default=<int>

PANTS_TEST_TIMEOUT_DEFAULT

default: None

The default timeout (in seconds) for a test target if the timeout field is not set on the target.

`timeout_maximum`

--test-timeout-maximum=<int>

PANTS_TEST_TIMEOUT_MAXIMUM

default: None

The maximum timeout (in seconds) that may be used on a test target.

Deprecated options

None

Related subsystems

debug-adapter, filter