HomeDocs
DocsCommunityTestimonialsUsersGitHubTwitterBlogJobsTermsPrivacyCookies
TermsPrivacyCookies
Hey! These docs are for version 2.13, which is no longer officially supported. Click here for the latest version, 2.17!




Run tests.

Backend: <span style="color: purple"><code>pants.core</code></span> Config section: <span style="color: purple"><code>[test]</code></span>

## Basic options

<div style="color: purple">

### `debug`

<code>--[no-]test-debug</code><br> <code>PANTS_TEST_DEBUG</code><br>

</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>

<br>

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

</div> <br>

<div style="color: purple">

### `debug_adapter`

<code>--[no-]test-debug-adapter</code><br> <code>PANTS_TEST_DEBUG_ADAPTER</code><br>

</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>

<br>

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.

</div> <br>

<div style="color: purple">

### `force`

<code>--[no-]test-force</code><br> <code>PANTS_TEST_FORCE</code><br>

</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>

<br>

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

</div> <br>

<div style="color: purple">

### `output`

<code>--test-output=<ShowOutput></code><br> <code>PANTS_TEST_OUTPUT</code><br>

</div> <div style="padding-left: 2em;"> <span style="color: green">one of: <code>all, failed, none</code></span><br> <span style="color: green">default: <code>failed</code></span>

<br>

Show stdout/stderr for these tests.

</div> <br>

<div style="color: purple">

### `use_coverage`

<code>--[no-]test-use-coverage</code><br> <code>PANTS_TEST_USE_COVERAGE</code><br>

</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>

<br>

Generate a coverage report if the test runner supports it.

</div> <br>

<div style="color: purple">

### `open_coverage`

<code>--[no-]test-open-coverage</code><br> <code>PANTS_TEST_OPEN_COVERAGE</code><br>

</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>

<br>

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

</div> <br>

<div style="color: purple">

### `extra_env_vars`

<code>--test-extra-env-vars="['&lt;str&gt;', '&lt;str&gt;', ...]"</code><br> <code>PANTS_TEST_EXTRA_ENV_VARS</code><br>

</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>

<br>

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.

</div> <br>

<div style="color: purple">

### `shard`

<code>--test-shard=<str></code><br> <code>PANTS_TEST_SHARD</code><br>

</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code></code></span>

<br>

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.

</div> <br>

## Advanced options

<div style="color: purple">

### `report`

<code>--[no-]test-report</code><br> <code>PANTS_TEST_REPORT</code><br>

</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>

<br>

Write test reports to --report-dir.

</div> <br>

<div style="color: purple">

### `report_dir`

<code>--test-report-dir=<str></code><br> <code>PANTS_TEST_REPORT_DIR</code><br>

</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>{distdir}/test/reports</code></span>

<br>

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

</div> <br>

## Deprecated options

None

## Related subsystems

[debug-adapter](🔗), [filter](🔗)