Skip to content

Listing tests

To build and list all tests in a workspace1, cd into the workspace and run:

cargo nextest list

cargo nextest list takes most of the same options that cargo nextest run takes. For a full list of options accepted, see Options and arguments below, or cargo nextest list --help.

nextest-runner:
    config::nextest_version::tests::test_valid_nextest_version::basic
    config::nextest_version::tests::test_valid_nextest_version::basic_with_patch
    config::overrides::tests::test_overrides_basic
    config::scripts::tests::test_scripts_basic
    config::tool_config::tests::tool_config_basic
    reporter::tests::no_capture_settings
    reporter::tests::on_test_finished_dont_show_immediate
    reporter::tests::on_test_finished_dont_store_final
    reporter::tests::on_test_finished_dont_write_status_line
    reporter::tests::on_test_finished_show_immediate
    reporter::tests::on_test_finished_store_final_1
    reporter::tests::on_test_finished_store_final_2
    reporter::tests::on_test_finished_store_final_3
    reporter::tests::on_test_finished_store_final_4
    reporter::tests::on_test_finished_with_interrupt
    reporter::tests::on_test_finished_write_status_line
nextest-runner::integration:
    basic::test_filter_expr_with_string_filters
    basic::test_filter_expr_without_string_filters
    basic::test_list_binaries
    basic::test_list_tests
    basic::test_retries::retry_overrides_ignored
    basic::test_retries::retry_overrides_obeyed
    basic::test_run
    basic::test_run_ignored
    basic::test_string_filters_without_filter_expr
    basic::test_termination

nextest-runner:
    config::nextest_version::tests::test_valid_nextest_version::basic
    config::nextest_version::tests::test_valid_nextest_version::basic_with_patch
    config::overrides::tests::test_overrides_basic
    config::scripts::tests::test_scripts_basic
    config::tool_config::tests::tool_config_basic
    reporter::tests::no_capture_settings
    reporter::tests::on_test_finished_dont_show_immediate
    reporter::tests::on_test_finished_dont_store_final
    reporter::tests::on_test_finished_dont_write_status_line
    reporter::tests::on_test_finished_show_immediate
    reporter::tests::on_test_finished_store_final_1
    reporter::tests::on_test_finished_store_final_2
    reporter::tests::on_test_finished_store_final_3
    reporter::tests::on_test_finished_store_final_4
    reporter::tests::on_test_finished_with_interrupt
    reporter::tests::on_test_finished_write_status_line
nextest-runner::integration:
    basic::test_filter_expr_with_string_filters
    basic::test_filter_expr_without_string_filters
    basic::test_list_binaries
    basic::test_list_tests
    basic::test_retries::retry_overrides_ignored
    basic::test_retries::retry_overrides_obeyed
    basic::test_run
    basic::test_run_ignored
    basic::test_string_filters_without_filter_expr
    basic::test_termination

Verbose output

With --verbose, information about binary paths and skipped tests is also printed.

nextest-runner::integration:
  bin: /home/rain/dev/nextest-rs/nextest/target/debug/deps/integration-87720ee436469004
  cwd: /home/rain/dev/nextest-rs/nextest/nextest-runner
  build platform: target
    basic::test_filter_expr_with_string_filters
    basic::test_filter_expr_without_string_filters
    basic::test_list_binaries
    basic::test_list_tests
    basic::test_retries::retry_overrides_ignored
    basic::test_retries::retry_overrides_obeyed
    basic::test_run
    basic::test_run_ignored
    basic::test_string_filters_without_filter_expr
    basic::test_termination
    target_runner::disregards_non_matching (skipped)
    target_runner::falls_back_to_cargo_config (skipped)
    target_runner::parses_cargo_config_cfg (skipped)
    target_runner::parses_cargo_config_exact (skipped)
    target_runner::parses_cargo_env (skipped)
    target_runner::test_listing_with_target_runner (skipped)
    target_runner::test_run_with_target_runner (skipped)
    target_triple::parses_cargo_env (skipped)
    target_triple::parses_custom_target_cli (skipped)
    target_triple::parses_custom_target_cli_from_rust_target_path (skipped)
    target_triple::parses_custom_target_cli_heuristic (skipped)
    target_triple::parses_custom_target_env (skipped)
    target_triple::parses_custom_target_env_from_rust_target_path (skipped)
    target_triple::parses_target_cli_option (skipped)
nextest-runner::bin/passthrough:
  bin: /home/rain/dev/nextest-rs/nextest/target/debug/deps/passthrough-d0acaba9cef8de3b
  cwd: /home/rain/dev/nextest-rs/nextest/nextest-runner
  build platform: target
    (no tests)

nextest-runner::integration:
  bin: /home/rain/dev/nextest-rs/nextest/target/debug/deps/integration-87720ee436469004
  cwd: /home/rain/dev/nextest-rs/nextest/nextest-runner
  build platform: target
    basic::test_filter_expr_with_string_filters
    basic::test_filter_expr_without_string_filters
    basic::test_list_binaries
    basic::test_list_tests
    basic::test_retries::retry_overrides_ignored
    basic::test_retries::retry_overrides_obeyed
    basic::test_run
    basic::test_run_ignored
    basic::test_string_filters_without_filter_expr
    basic::test_termination
    target_runner::disregards_non_matching (skipped)
    target_runner::falls_back_to_cargo_config (skipped)
    target_runner::parses_cargo_config_cfg (skipped)
    target_runner::parses_cargo_config_exact (skipped)
    target_runner::parses_cargo_env (skipped)
    target_runner::test_listing_with_target_runner (skipped)
    target_runner::test_run_with_target_runner (skipped)
    target_triple::parses_cargo_env (skipped)
    target_triple::parses_custom_target_cli (skipped)
    target_triple::parses_custom_target_cli_from_rust_target_path (skipped)
    target_triple::parses_custom_target_cli_heuristic (skipped)
    target_triple::parses_custom_target_env (skipped)
    target_triple::parses_custom_target_env_from_rust_target_path (skipped)
    target_triple::parses_target_cli_option (skipped)
nextest-runner::bin/passthrough:
  bin: /home/rain/dev/nextest-rs/nextest/target/debug/deps/passthrough-d0acaba9cef8de3b
  cwd: /home/rain/dev/nextest-rs/nextest/nextest-runner
  build platform: target
    (no tests)

Options and arguments

The output of cargo nextest list -h:

List tests in workspace

Usage: cargo nextest list [OPTIONS] [FILTERS]... [-- <FILTERS_AND_ARGS>...]

Arguments:
  [FILTERS]...           Test name filters
  [FILTERS_AND_ARGS]...  Test name filters and emulated test binary arguments (partially supported)

Options:
  -v, --verbose       Verbose output [env: NEXTEST_VERBOSE=]
      --color <WHEN>  Produce color output: auto, always, never [env: CARGO_TERM_COLOR=always] [default: auto]
  -h, --help          Print help (see more with '--help')

Package selection:
  -p, --package <PACKAGES>  Package to test
      --workspace           Test all packages in the workspace
      --exclude <EXCLUDE>   Exclude packages from the test
      --all                 Alias for --workspace (deprecated)

Target selection:
      --lib                Test only this package's library unit tests
      --bin <BIN>          Test only the specified binary
      --bins               Test all binaries
      --example <EXAMPLE>  Test only the specified example
      --examples           Test all examples
      --test <TEST>        Test only the specified test target
      --tests              Test all targets
      --bench <BENCH>      Test only the specified bench target
      --benches            Test all benches
      --all-targets        Test all targets

Feature selection:
  -F, --features <FEATURES>  Space or comma separated list of features to activate
      --all-features         Activate all available features
      --no-default-features  Do not activate the `default` feature

Compilation options:
      --build-jobs <N>        Number of build jobs to run
  -r, --release               Build artifacts in release mode, with optimizations
      --cargo-profile <NAME>  Build artifacts with the specified Cargo profile
      --target <TRIPLE>       Build for the target triple
      --target-dir <DIR>      Directory for all generated artifacts
      --unit-graph            Output build graph in JSON (unstable)
      --timings[=<FMTS>]      Timing output formats (unstable) (comma separated): html, json

Manifest options:
      --manifest-path <PATH>  Path to Cargo.toml
      --frozen                Require Cargo.lock and cache are up to date
      --locked                Require Cargo.lock is up to date
      --offline               Run without accessing the network

Other Cargo options:
      --cargo-quiet...          Do not print cargo log messages (specify twice for no Cargo output at all)
      --cargo-verbose...        Use cargo verbose output (specify twice for very verbose/build.rs output)
      --ignore-rust-version     Ignore `rust-version` specification in packages
      --future-incompat-report  Outputs a future incompatibility report at the end of the build
      --config <KEY=VALUE>      Override a configuration value
  -Z <FLAG>                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details

Filter options:
      --run-ignored <WHICH>    Run ignored tests [possible values: default, ignored-only, all]
      --partition <PARTITION>  Test partition, e.g. hash:1/2 or count:2/3
  -E, --filter-expr <EXPR>     Test filter expression (see 
                               <https://nexte.st/book/filter-expressions>)

Output options:
  -T, --message-format <FMT>  Output format [default: human] [possible values: human, json, json-pretty]
      --list-type <TYPE>      Type of listing [default: full] [possible values: full, binaries-only]

Reuse build options:
      --archive-file <PATH>       Path to nextest archive
      --archive-format <FORMAT>   Archive format [default: auto] [possible values: auto, tar-zst]
      --extract-to <DIR>          Destination directory to extract archive to [default: temporary directory]
      --extract-overwrite         Overwrite files in destination directory while extracting archive
      --persist-extract-tempdir   Persist extracted temporary directory
      --cargo-metadata <PATH>     Path to cargo metadata JSON
      --workspace-remap <PATH>    Remapping for the workspace root
      --binaries-metadata <PATH>  Path to binaries-metadata JSON
      --target-dir-remap <PATH>   Remapping for the target directory

Config options:
      --config-file <PATH>
          Config file [default: workspace-root/.config/nextest.toml]
      --tool-config-file <TOOL:ABS_PATH>
          Tool-specific config files
      --override-version-check
          Override checks for the minimum version defined in nextest's config

List tests in workspace

Usage: cargo nextest list [OPTIONS] [FILTERS]... [-- <FILTERS_AND_ARGS>...]

Arguments:
  [FILTERS]...           Test name filters
  [FILTERS_AND_ARGS]...  Test name filters and emulated test binary arguments (partially supported)

Options:
  -v, --verbose       Verbose output [env: NEXTEST_VERBOSE=]
      --color <WHEN>  Produce color output: auto, always, never [env: CARGO_TERM_COLOR=always] [default: auto]
  -h, --help          Print help (see more with '--help')

Package selection:
  -p, --package <PACKAGES>  Package to test
      --workspace           Test all packages in the workspace
      --exclude <EXCLUDE>   Exclude packages from the test
      --all                 Alias for --workspace (deprecated)

Target selection:
      --lib                Test only this package's library unit tests
      --bin <BIN>          Test only the specified binary
      --bins               Test all binaries
      --example <EXAMPLE>  Test only the specified example
      --examples           Test all examples
      --test <TEST>        Test only the specified test target
      --tests              Test all targets
      --bench <BENCH>      Test only the specified bench target
      --benches            Test all benches
      --all-targets        Test all targets

Feature selection:
  -F, --features <FEATURES>  Space or comma separated list of features to activate
      --all-features         Activate all available features
      --no-default-features  Do not activate the `default` feature

Compilation options:
      --build-jobs <N>        Number of build jobs to run
  -r, --release               Build artifacts in release mode, with optimizations
      --cargo-profile <NAME>  Build artifacts with the specified Cargo profile
      --target <TRIPLE>       Build for the target triple
      --target-dir <DIR>      Directory for all generated artifacts
      --unit-graph            Output build graph in JSON (unstable)
      --timings[=<FMTS>]      Timing output formats (unstable) (comma separated): html, json

Manifest options:
      --manifest-path <PATH>  Path to Cargo.toml
      --frozen                Require Cargo.lock and cache are up to date
      --locked                Require Cargo.lock is up to date
      --offline               Run without accessing the network

Other Cargo options:
      --cargo-quiet...          Do not print cargo log messages (specify twice for no Cargo output at all)
      --cargo-verbose...        Use cargo verbose output (specify twice for very verbose/build.rs output)
      --ignore-rust-version     Ignore `rust-version` specification in packages
      --future-incompat-report  Outputs a future incompatibility report at the end of the build
      --config <KEY=VALUE>      Override a configuration value
  -Z <FLAG>                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details

Filter options:
      --run-ignored <WHICH>    Run ignored tests [possible values: default, ignored-only, all]
      --partition <PARTITION>  Test partition, e.g. hash:1/2 or count:2/3
  -E, --filter-expr <EXPR>     Test filter expression (see 
                               <https://nexte.st/book/filter-expressions>)

Output options:
  -T, --message-format <FMT>  Output format [default: human] [possible values: human, json, json-pretty]
      --list-type <TYPE>      Type of listing [default: full] [possible values: full, binaries-only]

Reuse build options:
      --archive-file <PATH>       Path to nextest archive
      --archive-format <FORMAT>   Archive format [default: auto] [possible values: auto, tar-zst]
      --extract-to <DIR>          Destination directory to extract archive to [default: temporary directory]
      --extract-overwrite         Overwrite files in destination directory while extracting archive
      --persist-extract-tempdir   Persist extracted temporary directory
      --cargo-metadata <PATH>     Path to cargo metadata JSON
      --workspace-remap <PATH>    Remapping for the workspace root
      --binaries-metadata <PATH>  Path to binaries-metadata JSON
      --target-dir-remap <PATH>   Remapping for the target directory

Config options:
      --config-file <PATH>
          Config file [default: workspace-root/.config/nextest.toml]
      --tool-config-file <TOOL:ABS_PATH>
          Tool-specific config files
      --override-version-check
          Override checks for the minimum version defined in nextest's config

The output of cargo nextest list --help:

List tests in workspace

This command builds test binaries and queries them for the tests they contain.

Use --verbose to get more information about tests, including test binary paths and skipped tests.

Use --message-format json to get machine-readable output.

For more information, see <https://nexte.st/book/listing>.

Usage: cargo nextest list [OPTIONS] [FILTERS]... [-- <FILTERS_AND_ARGS>...]

Arguments:
  [FILTERS]...
          Test name filters

  [FILTERS_AND_ARGS]...
          Test name filters and emulated test binary arguments (partially supported)

Options:
  -v, --verbose
          Verbose output

          [env: NEXTEST_VERBOSE=]

      --color <WHEN>
          Produce color output: auto, always, never

          [env: CARGO_TERM_COLOR=always]
          [default: auto]

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

Package selection:
  -p, --package <PACKAGES>
          Package to test

      --workspace
          Test all packages in the workspace

      --exclude <EXCLUDE>
          Exclude packages from the test

      --all
          Alias for --workspace (deprecated)

Target selection:
      --lib
          Test only this package's library unit tests

      --bin <BIN>
          Test only the specified binary

      --bins
          Test all binaries

      --example <EXAMPLE>
          Test only the specified example

      --examples
          Test all examples

      --test <TEST>
          Test only the specified test target

      --tests
          Test all targets

      --bench <BENCH>
          Test only the specified bench target

      --benches
          Test all benches

      --all-targets
          Test all targets

Feature selection:
  -F, --features <FEATURES>
          Space or comma separated list of features to activate

      --all-features
          Activate all available features

      --no-default-features
          Do not activate the `default` feature

Compilation options:
      --build-jobs <N>
          Number of build jobs to run

  -r, --release
          Build artifacts in release mode, with optimizations

      --cargo-profile <NAME>
          Build artifacts with the specified Cargo profile

      --target <TRIPLE>
          Build for the target triple

      --target-dir <DIR>
          Directory for all generated artifacts

      --unit-graph
          Output build graph in JSON (unstable)

      --timings[=<FMTS>]
          Timing output formats (unstable) (comma separated): html, json

Manifest options:
      --manifest-path <PATH>
          Path to Cargo.toml

      --frozen
          Require Cargo.lock and cache are up to date

      --locked
          Require Cargo.lock is up to date

      --offline
          Run without accessing the network

Other Cargo options:
      --cargo-quiet...
          Do not print cargo log messages (specify twice for no Cargo output at all)

      --cargo-verbose...
          Use cargo verbose output (specify twice for very verbose/build.rs output)

      --ignore-rust-version
          Ignore `rust-version` specification in packages

      --future-incompat-report
          Outputs a future incompatibility report at the end of the build

      --config <KEY=VALUE>
          Override a configuration value

  -Z <FLAG>
          Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details

Filter options:
      --run-ignored <WHICH>
          Run ignored tests

          [possible values: default, ignored-only, all]

      --partition <PARTITION>
          Test partition, e.g. hash:1/2 or count:2/3

      --platform-filter <PLATFORM>
          Filter test binaries by build platform (DEPRECATED)

          Instead, use -E with 'platform(host)' or 'platform(target)'.

          [default: any]
          [possible values: target, host, any]

  -E, --filter-expr <EXPR>
          Test filter expression (see 
          <https://nexte.st/book/filter-expressions>)

Output options:
  -T, --message-format <FMT>
          Output format

          [default: human]
          [possible values: human, json, json-pretty]

      --list-type <TYPE>
          Type of listing

          [default: full]
          [possible values: full, binaries-only]

Reuse build options:
      --archive-file <PATH>
          Path to nextest archive

      --archive-format <FORMAT>
          Archive format

          [default: auto]
          [possible values: auto, tar-zst]

      --extract-to <DIR>
          Destination directory to extract archive to [default: temporary directory]

      --extract-overwrite
          Overwrite files in destination directory while extracting archive

      --persist-extract-tempdir
          Persist extracted temporary directory

      --cargo-metadata <PATH>
          Path to cargo metadata JSON

      --workspace-remap <PATH>
          Remapping for the workspace root

      --binaries-metadata <PATH>
          Path to binaries-metadata JSON

      --target-dir-remap <PATH>
          Remapping for the target directory

Config options:
      --config-file <PATH>
          Config file [default: workspace-root/.config/nextest.toml]

      --tool-config-file <TOOL:ABS_PATH>
          Tool-specific config files

          Some tools on top of nextest may want to set up their own default configuration but prioritize user configuration on top. Use this argument to insert configuration that's lower than --config-file in priority but above the default config shipped with nextest.

          Arguments are specified in the format "tool:abs_path", for example "my-tool:/path/to/nextest.toml" (or "my-tool:C:\\path\\to\\nextest.toml" on Windows). Paths must be absolute.

          This argument may be specified multiple times. Files that come later are lower priority than those that come earlier.

      --override-version-check
          Override checks for the minimum version defined in nextest's config.

          Repository and tool-specific configuration files can specify minimum required and recommended versions of nextest. This option overrides those checks.

List tests in workspace

This command builds test binaries and queries them for the tests they contain.

Use --verbose to get more information about tests, including test binary paths and skipped tests.

Use --message-format json to get machine-readable output.

For more information, see <https://nexte.st/book/listing>.

Usage: cargo nextest list [OPTIONS] [FILTERS]... [-- <FILTERS_AND_ARGS>...]

Arguments:
  [FILTERS]...
          Test name filters

  [FILTERS_AND_ARGS]...
          Test name filters and emulated test binary arguments (partially supported)

Options:
  -v, --verbose
          Verbose output

          [env: NEXTEST_VERBOSE=]

      --color <WHEN>
          Produce color output: auto, always, never

          [env: CARGO_TERM_COLOR=always]
          [default: auto]

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

Package selection:
  -p, --package <PACKAGES>
          Package to test

      --workspace
          Test all packages in the workspace

      --exclude <EXCLUDE>
          Exclude packages from the test

      --all
          Alias for --workspace (deprecated)

Target selection:
      --lib
          Test only this package's library unit tests

      --bin <BIN>
          Test only the specified binary

      --bins
          Test all binaries

      --example <EXAMPLE>
          Test only the specified example

      --examples
          Test all examples

      --test <TEST>
          Test only the specified test target

      --tests
          Test all targets

      --bench <BENCH>
          Test only the specified bench target

      --benches
          Test all benches

      --all-targets
          Test all targets

Feature selection:
  -F, --features <FEATURES>
          Space or comma separated list of features to activate

      --all-features
          Activate all available features

      --no-default-features
          Do not activate the `default` feature

Compilation options:
      --build-jobs <N>
          Number of build jobs to run

  -r, --release
          Build artifacts in release mode, with optimizations

      --cargo-profile <NAME>
          Build artifacts with the specified Cargo profile

      --target <TRIPLE>
          Build for the target triple

      --target-dir <DIR>
          Directory for all generated artifacts

      --unit-graph
          Output build graph in JSON (unstable)

      --timings[=<FMTS>]
          Timing output formats (unstable) (comma separated): html, json

Manifest options:
      --manifest-path <PATH>
          Path to Cargo.toml

      --frozen
          Require Cargo.lock and cache are up to date

      --locked
          Require Cargo.lock is up to date

      --offline
          Run without accessing the network

Other Cargo options:
      --cargo-quiet...
          Do not print cargo log messages (specify twice for no Cargo output at all)

      --cargo-verbose...
          Use cargo verbose output (specify twice for very verbose/build.rs output)

      --ignore-rust-version
          Ignore `rust-version` specification in packages

      --future-incompat-report
          Outputs a future incompatibility report at the end of the build

      --config <KEY=VALUE>
          Override a configuration value

  -Z <FLAG>
          Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details

Filter options:
      --run-ignored <WHICH>
          Run ignored tests

          [possible values: default, ignored-only, all]

      --partition <PARTITION>
          Test partition, e.g. hash:1/2 or count:2/3

      --platform-filter <PLATFORM>
          Filter test binaries by build platform (DEPRECATED)

          Instead, use -E with 'platform(host)' or 'platform(target)'.

          [default: any]
          [possible values: target, host, any]

  -E, --filter-expr <EXPR>
          Test filter expression (see 
          <https://nexte.st/book/filter-expressions>)

Output options:
  -T, --message-format <FMT>
          Output format

          [default: human]
          [possible values: human, json, json-pretty]

      --list-type <TYPE>
          Type of listing

          [default: full]
          [possible values: full, binaries-only]

Reuse build options:
      --archive-file <PATH>
          Path to nextest archive

      --archive-format <FORMAT>
          Archive format

          [default: auto]
          [possible values: auto, tar-zst]

      --extract-to <DIR>
          Destination directory to extract archive to [default: temporary directory]

      --extract-overwrite
          Overwrite files in destination directory while extracting archive

      --persist-extract-tempdir
          Persist extracted temporary directory

      --cargo-metadata <PATH>
          Path to cargo metadata JSON

      --workspace-remap <PATH>
          Remapping for the workspace root

      --binaries-metadata <PATH>
          Path to binaries-metadata JSON

      --target-dir-remap <PATH>
          Remapping for the target directory

Config options:
      --config-file <PATH>
          Config file [default: workspace-root/.config/nextest.toml]

      --tool-config-file <TOOL:ABS_PATH>
          Tool-specific config files

          Some tools on top of nextest may want to set up their own default configuration but prioritize user configuration on top. Use this argument to insert configuration that's lower than --config-file in priority but above the default config shipped with nextest.

          Arguments are specified in the format "tool:abs_path", for example "my-tool:/path/to/nextest.toml" (or "my-tool:C:\\path\\to\\nextest.toml" on Windows). Paths must be absolute.

          This argument may be specified multiple times. Files that come later are lower priority than those that come earlier.

      --override-version-check
          Override checks for the minimum version defined in nextest's config.

          Repository and tool-specific configuration files can specify minimum required and recommended versions of nextest. This option overrides those checks.


  1. Doctests are currently not supported because of limitations in stable Rust. For now, run doctests in a separate step with cargo test --doc