add documentation for filtering expressions

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)

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`.