[site] some updates

sunshowers · sunshowers · commit 6b33c62fa805 · 2025-11-16T08:18:46.000Z
`running.md` was becoming too unwieldy, so make a new page called `selecting.md`.
diff --git a/site/mkdocs.yml b/site/mkdocs.yml
@@ -83,6 +83,7 @@ nav:
           - docs/installation/release-urls.md
     - "Using nextest":
           - docs/running.md
+          - docs/selecting.md
           - docs/listing.md
           - docs/reporting.md
     - "Features":
diff --git a/site/src/changelog.md b/site/src/changelog.md
@@ -1,5 +1,6 @@
 ---
 icon: material/list-box
+description: Changelog for cargo-nextest.
 toc_depth: 1
 ---
 
@@ -8,6 +9,27 @@ toc_depth: 1
 This page documents new features and bugfixes for cargo-nextest. Please see the [stability
 policy](https://nexte.st/docs/stability/) for how versioning works with cargo-nextest.
 
+## Unreleased
+
+### Added
+
+- Nextest now supports running tests under a debugger! Use `--debugger` to run a single test under gdb, lldb, WinDbg, CodeLLDB in Visual Studio Code, and other debuggers. For more information, see [_Debugger integration_](https://nexte.st/docs/integrations/debuggers/).
+
+### Changed
+
+- Nextest now sets `NEXTEST_BIN_EXE_*` environment variables with hyphens in binary names replaced by underscores, in addition to the existing variables with hyphens. This works around some shells and debuggers that drop environment variables containing hyphens. ([#2777])
+
+### Fixed
+
+- Fixed a panic when attempting to display progress during retries. ([#2771])
+- With [stress tests](https://nexte.st/docs/features/stress-tests/), the progress bar no longer overwrites unrelated output. ([#2765])
+- During [the list phase](https://nexte.st/docs/listing/), invalid output lines with control characters in them are now properly escaped. ([#2772])
+
+[#2777]: https://github.com/nextest-rs/nextest/pull/2777
+[#2771]: https://github.com/nextest-rs/nextest/pull/2771
+[#2765]: https://github.com/nextest-rs/nextest/pull/2765
+[#2772]: https://github.com/nextest-rs/nextest/pull/2772
+
 ## [0.9.111] - 2025-11-04
 
 ### Added
diff --git a/site/src/docs/ci-features/archiving.md b/site/src/docs/ci-features/archiving.md
@@ -147,7 +147,7 @@ See [this working example](https://github.com/nextest-rs/reuse-build-partition-e
 
 ## Example: Cross-compilation
 
-While cross-compiling code, some tests may need to be run on the host platform. (See [_Filtering by build platform_](../running.md#filtering-by-build-platform) for more.)
+While cross-compiling code, some tests may need to be run on the host platform. (See [_Filtering by build platform_](../selecting.md#filtering-by-build-platform) for more.)
 
 ### On the build machine
 
diff --git a/site/src/docs/configuration/per-test-overrides.md b/site/src/docs/configuration/per-test-overrides.md
@@ -47,7 +47,7 @@ for more information.
 : In [JUnit reports](../machine-readable/junit.md), whether to store output for passing and failing tests, respectively.
 
 `default-filter` <!-- md:version 0.9.84 -->
-: The [default filter](../running.md#running-a-subset-of-tests-by-default) on this platform. Only supported for overrides that specify `platform` and not `filter`.
+: The [default filter](../selecting.md#running-a-subset-of-tests-by-default) on this platform. Only supported for overrides that specify `platform` and not `filter`.
 
 `run-extra-args` <!-- md:version 0.9.86 -->
 : [Extra arguments](extra-args.md) to pass to the test binary.
diff --git a/site/src/docs/configuration/reference.md b/site/src/docs/configuration/reference.md
@@ -75,7 +75,7 @@ Profiles are configured under `[profile.<name>]`. The default profile is called
 
 - **Type**: String (filterset expression)
 - **Description**: The default set of tests to run
-- **Documentation**: [_Running a subset of tests by default_](../running.md#running-a-subset-of-tests-by-default)
+- **Documentation**: [_Running a subset of tests by default_](../selecting.md#running-a-subset-of-tests-by-default)
 - **Default**: `all()`: all tests are run
 - **Example**: `default-filter = "not test(very_slow_tests)"`
 
@@ -326,7 +326,7 @@ At least one of these filters must be specified.
 
 - **Type**: String (filterset expression)
 - **Description**: Override the default filter for specific platforms
-- **Documentation**: [_Running a subset of tests by default_](../running.md#running-a-subset-of-tests-by-default)
+- **Documentation**: [_Running a subset of tests by default_](../selecting.md#running-a-subset-of-tests-by-default)
 - **Note**: Can only be used with `platform` specification
 
 #### `priority`
diff --git a/site/src/docs/configuration/specifying-platforms.md b/site/src/docs/configuration/specifying-platforms.md
@@ -59,7 +59,7 @@ With this configuration:
 
 ### Host tests
 
-While cross-compiling code, some tests may need to be run on the host platform. (See the note about [Filtering by build platform](../running.md#filtering-by-build-platform) for more.)
+While cross-compiling code, some tests may need to be run on the host platform. (See the note about [Filtering by build platform](../selecting.md#filtering-by-build-platform) for more.)
 
 For tests that run on the host platform, to figure out if an override applies nextest will compute the result of the _target_ filter against the _host_ platform. (If the `host` key is specified, it will be considered as well based on the AND semantics listed above.)
 
diff --git a/site/src/docs/features/target-runners.md b/site/src/docs/features/target-runners.md
@@ -40,7 +40,7 @@ cargo nextest run --target x86_64-pc-windows-msvc
 
 ## Cross-compiling
 
-While cross-compiling code, some tests may need to be run on the host platform. (See [_Filtering by build platform_](../running.md#filtering-by-build-platform) for more.)
+While cross-compiling code, some tests may need to be run on the host platform. (See [_Filtering by build platform_](../selecting.md#filtering-by-build-platform) for more.)
 
 For tests that run on the host platform, nextest uses the target runner defined for the host.
 
diff --git a/site/src/docs/filtersets/index.md b/site/src/docs/filtersets/index.md
@@ -7,7 +7,7 @@ icon: material/account-filter
 Nextest supports a domain-specific language (DSL) for choosing sets of tests called **filtersets** (formerly **filter expressions**). The DSL is inspired by [Bazel's query language](https://bazel.build/query/quickstart), and
 is most similar to _revsets_ as implemented in the [Jujutsu](https://martinvonz.github.io/jj/latest/revsets/) and [Mercurial](https://www.mercurial-scm.org/repo/hg/help/revsets) source control systems.
 
-Filtersets are specified on the command line with `-E`, or `--filterset` <!-- md:version 0.9.76 -->. (In prior versions of nextest, use `--filter-expr`.)
+Filtersets are specified on the command line with `-E` or `--filterset`.
 
 ## Example: Running all tests in a crate and its dependencies
 
@@ -58,7 +58,7 @@ cargo nextest run -E 'test(my_test) + package(my-crate)'
 
 <!-- md:version 0.9.77 -->
 
-If [a default filter](../running.md#running-a-subset-of-tests-by-default) for tests is configured,
+If [a default filter](../selecting.md#running-a-subset-of-tests-by-default) for tests is configured,
 filtersets on the command line are intersected with the default filter.
 
 To match against all tests, not just the default set, pass in `--ignore-default-filter`.
diff --git a/site/src/docs/filtersets/reference.md b/site/src/docs/filtersets/reference.md
@@ -36,10 +36,10 @@ This section contains the full set of operators supported by the filterset DSL.
 : Include all tests in binary names matching `name-matcher`. For unit tests, the binary name is the same as the name of the crate. Otherwise, it's the name of the integration test, benchmark, or binary target.
 
 `platform(host)` or `platform(target)`
-: Include all tests that are [built for the host or target platform](../running.md#filtering-by-build-platform), respectively.
+: Include all tests that are [built for the host or target platform](../selecting.md#filtering-by-build-platform), respectively.
 
 `default()` <!-- md:version 0.9.75 -->
-: The default set of tests to run; see [_Running a subset of tests by default_](../running.md#running-a-subset-of-tests-by-default) for more information.
+: The default set of tests to run; see [_Running a subset of tests by default_](../selecting.md#running-a-subset-of-tests-by-default) for more information.
 
 !!! tip "Binary exclusions"
 
diff --git a/site/src/docs/integrations/debuggers.md b/site/src/docs/integrations/debuggers.md
@@ -1,5 +1,6 @@
 ---
 icon: material/debug-step-over
+description: Integrating with gdb, lldb, Visual Studio Code, and other debuggers.
 ---
 
 # Debugger integration
@@ -8,8 +9,8 @@ icon: material/debug-step-over
 
 With nextest, you can run individual tests under a text-based or graphical debugger. Supported debuggers include:
 
-* [GDB](https://sourceware.org/gdb/)
-* [LLDB](https://lldb.llvm.org/)
+* [gdb](https://sourceware.org/gdb/)
+* [lldb](https://lldb.llvm.org/)
 * [WinDbg](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/)
 * [CodeLLDB](https://github.com/vadimcn/codelldb) in Visual Studio Code, via [`codelldb-launch`](https://github.com/vadimcn/codelldb/tree/master/src/codelldb-launch).
 
@@ -25,13 +26,13 @@ In debugger mode, nextest will:
 
 ## Examples
 
-Run the test matching `my_test` under [GDB](https://sourceware.org/gdb/), using `rust-gdb`:
+Run the test matching `my_test` under [gdb](https://sourceware.org/gdb/), using `rust-gdb`:
 
 ```sh
 cargo nextest run --debugger "rust-gdb --args" my_test
 ```
 
-Run the test matching `my_test` under [LLDB](https://lldb.llvm.org/), using `rust-lldb`:
+Run the test matching `my_test` under [lldb](https://lldb.llvm.org/), using `rust-lldb`:
 
 ```sh
 cargo nextest run --debugger "rust-lldb --" my_test
diff --git a/site/src/docs/listing.md b/site/src/docs/listing.md
@@ -47,7 +47,7 @@ cargo nextest list
 
 <!-- md:version 0.9.75 -->
 
-`cargo nextest list` has the same behavior as `run` with default sets; see [_Running a subset of tests by default_](running.md#running-a-subset-of-tests-by-default) for more information.
+`cargo nextest list` has the same behavior as `run` with default filters; see [_Running a subset of tests by default_](selecting.md#running-a-subset-of-tests-by-default) for more information.
 
 ## Options and arguments
 
diff --git a/site/src/docs/running.md b/site/src/docs/running.md
@@ -1,5 +1,6 @@
 ---
 icon: material/run-fast
+description: Running tests with cargo-nextest.
 ---
 
 # Running tests
@@ -50,135 +51,15 @@ A test binary can be any of:
 
 For more about unit and integration tests, see [the documentation for `cargo test`](https://doc.rust-lang.org/cargo/commands/cargo-test.html).
 
-## Filtering tests
+## Selecting tests
 
 To only run tests that match certain names:
 
 ```
 cargo nextest run <test-name1> <test-name2>...
 ```
 
-### Filtersets
-
-Tests can also be selected using the [filterset DSL]. See that page for more information.
-
-For example, to run all tests except those in the `very-slow-tests` crate:
-
-```
-cargo nextest run -E 'not package(very-slow-tests)'
-```
-
-### Running a subset of tests by default
-
-<!-- md:version 0.9.77 -->
-
-By default, all discovered, non-ignored tests are run. To only run some tests by default, set the
-`default-filter` configuration.
-
-For example, some tests might need access to special resources not available to developer
-workstations. To not run tests in the `special-tests` crate by default, but to run them with the
-`ci` profile:
-
-```toml title="Default filter configuration in <code>.config/nextest.toml</code>"
-[profile.default]
-default-filter = 'not package(special-tests)'
-
-[profile.ci]
-default-filter = 'all()'
-```
-
-The default filter is available in the filterset DSL via the `default()` predicate.
-
-!!! info "Overriding the default filter"
-
-    By default, command-line arguments are always interpreted with respect to the default filter. For example, `cargo nextest -E 'all()'` will run all tests that match the default filter.
-
-    To override the default filter on the command line, use `--ignore-default-filter`. For example, `cargo nextest -E 'all()' --ignore-default-filter` will run all tests, including those not in the default filter.
-
-Because skipping some tests can be surprising, nextest prints the number of tests and binaries
-skipped due to their presence in the default filter. For example:
-
-=== "Colorized"
-
-    ```bash exec="true" result="ansi"
-    cat src/outputs/default-filter-output.ansi
-    ```
-
-=== "Plaintext"
-
-    ```bash exec="true" result="text"
-    cat src/outputs/default-filter-output.ansi | ../scripts/strip-ansi.sh
-    ```
-
-!!! tip "Default filter vs ignored tests"
-
-    The default filter and `#[ignore]` can both be used to filter out some tests by default. However, there are key distinctions between the two:
-
-    1. The default filter is defined in nextest's configuration while ignored tests are annotated within Rust code.
-    2. Default filters can be separately configured per-profile. Ignored tests are global to the repository.
-    3. Default filters are a nextest feature, while ignored tests also work with `cargo test`.
-
-    In practice, `#[ignore]` is often used for failing tests, while the default filter is typically used to filter out tests that are very slow or require specific resources.
-
-#### Per-platform default filters
-
-<!-- md:version 0.9.84 -->
-
-Default filters can be set per-platform via [the `overrides` section](configuration/per-test-overrides.md).
-
-```toml title="Per-platform default filter configuration"
-[[profile.default.overrides]]
-platform = 'cfg(windows)'
-default-filter = 'not test()'
-```
-
-### `--skip` and `--exact`
-
-<!-- md:version 0.9.81 -->
-
-Nextest accepts the `--skip` and `--exact` arguments after `--`, emulating the corresponding
-arguments accepted by `cargo test`. The `--skip` and `--exact` arguments apply to test name filters
-passed in after `--`.
-
-For example, to run all tests matching the substring `test3`, but not including `skip1` or `skip2`:
-
-```
-cargo nextest run -- --skip skip1 --skip skip2 test3
-```
-
-To run all tests matching exactly the names `test1` and `test2`:
-
-```
-cargo nextest run -- test1 test2 --exact
-```
-
-To run all tests except those matching exactly `slow_module::my_test`:
-
-```
-cargo nextest run -- --exact --skip slow_module::my_test
-```
-
-Alternatively, and in prior versions of nextest, use a [filterset](filtersets/index.md). Some examples:
-
-|                `cargo test` command                 |                Nextest filterset command                |
-| :-------------------------------------------------: | :-----------------------------------------------------: |
-|   `cargo test -- --skip skip1 --skip skip2 test3`   | `cargo nextest run -E 'test(test3) - test(/skip[12]/)'` |
-|         `cargo test -- test1 test2 --exact`         |  `cargo nextest run -E 'test(=test1) + test(=test2)'`   |
-| `cargo test -- --exact --skip slow_module::my_test` | `cargo nextest run -E 'not test(=slow_module::my_test)` |
-
-### Filtering by build platform
-
-While cross-compiling code, some tests (e.g. proc-macro tests) may need to be run on the host platform. To filter tests based on the build platform they're for, nextest's filtersets accept the `platform()` set with values `target` and `host`.
-
-For example, to only run tests for the host platform:
-
-```
-
-cargo nextest run -E 'platform(host)'
-
-```
-
-[filterset DSL]: filtersets/index.md
+For more information, see [_Selecting tests_](selecting.md).
 
 [^doctest]: Doctests are currently [not supported](https://github.com/nextest-rs/nextest/issues/16) because of limitations in stable Rust. For now, run doctests in a separate step with `cargo test --doc`.
 
@@ -251,18 +132,21 @@ fail-fast = { max-fail = 5, terminate = "immediate" }  # Stop after 5 failures,
 
   Tests can be marked as taking up more than one available thread. For more, see [*Heavy tests and `threads-required`*](configuration/threads-required.md).
 
-`--run-ignored=only` <!-- md:version 0.9.76 -->
-: Run only ignored tests. (With prior nextest versions, use `--run-ignored=ignored-only`.)
+`--run-ignored=only`
+: Run only ignored tests.
 
 `--run-ignored=all`
 : Run both ignored and non-ignored tests.
 
-`--no-tests=fail|warn|pass` <!-- md:version 0.9.75 -->
+`--no-tests=fail|warn|pass`
 : Control behavior when no tests are run. In some cases, e.g. using nextest with [cargo-hack](https://github.com/taiki-e/cargo-hack) to test the powerset of features, it may be useful to set this to `warn` or `pass`.
 
     If set to `fail` and no tests are found, nextest exits with the advisory code 4 ([`NO_TESTS_RUN`](https://docs.rs/nextest-metadata/latest/nextest_metadata/enum.NextestExitCode.html#associatedconstant.NO_TESTS_RUN)).
 
     <!-- md:version 0.9.85 --> The default is `fail`. In prior versions, the default was `pass` or `warn`.
+    
+`--debugger=DEBUGGER` <!-- md:version 0.9.112 -->
+: Run an individual test with the specified debugger. For more, see [_Debugger integration_](integrations/debuggers.md).
 
 [available parallelism]: https://doc.rust-lang.org/std/thread/fn.available_parallelism.html
 
diff --git a/site/src/docs/selecting.md b/site/src/docs/selecting.md
