diff --git a/site/src/SUMMARY.md b/site/src/SUMMARY.md index 3f0715dfd1a..885d1343de4 100644 --- a/site/src/SUMMARY.md +++ b/site/src/SUMMARY.md @@ -25,6 +25,7 @@ - [Stability policy](book/stability.md) - [Experimental features](book/experimental-features.md) - [Reusing builds](book/reusing-builds.md) + - [Filtering expression](book/filtering-expression.md) --- - [How nextest works](book/how-it-works.md) - [Benchmarks](book/benchmarks.md) diff --git a/site/src/book/filtering-expression.md b/site/src/book/filtering-expression.md new file mode 100644 index 00000000000..b4231e07f2a --- /dev/null +++ b/site/src/book/filtering-expression.md @@ -0,0 +1,41 @@ +# Filtering expression + +* **Introduced in:** cargo-nextest 0.9.13 +* **Environment variable**: `NEXTEST_EXPERIMENTAL_EXPR_FILTER=1` +* **Tracking issue**: [] + +Tests to run can be filtered using filter expressions. + +## Filtering expression DSL + +A filtering expression define a set of tests, any test in the set will be run. + +Basic sets: +- `all()`: include everything +- `test(name-matcher)`: include all tests matching `name-matcher` +- `package(name-matcher)`: include all tests in packages matching `name-matcher` +- `deps(name-matcher)`: include all tests in packages depended by packages matching `name-matcher` +- `rdeps(name-matcher)`: include all tests in packages depending on packages matching `name-matcher` +- `none()`: include nothing + +Name matcher: +- `text`: match anything containing `text` +- `=text`: match anything equal to `text` +- `/reg/`: match anything matching the regex `reg` + +Operations: +- `set_1 & set_2` , `set_1 and set_2`: include everything in both `set_1` and `set_2` +- `set_1 | set_2`, `set_1 or set_2`, `set_1 + set_2`: include everything in either `set_1` or `set_2` +- `not set`: include everything not included in `set` +- `set_1 - set_2`: equivalent to `set_1 and not set_2` +- `(set)`: include everything in `set` + +Examples: +- `package(=serde) and test(deserialize)`: every tests containing `deserialize` in the package `serde` +- `not (test(parse) | test(run))`: every test not containing `parse` or `run` + +## Usage + +Multiple filter expressions can be pass to `cargo nextest`, if a test is include by one of the filtering expressions it will be run. + +- `cargo nextest run -E 'package(=crate_a)' -E 'test(parse)'`: will run every tests in the `crate_a` package and every test containing `parse`.