From 1dafb9385b2f2c5616e83c2c14fec1f938ac4dd3 Mon Sep 17 00:00:00 2001
From: devmobasa <4170275+devmobasa@users.noreply.github.com>
Date: Fri, 30 Oct 2026 19:25:15 +0100
Subject: [PATCH] docs: add nextest as the fast local test run

The local gate serializes tests because of a native font race. nextest
gives each test its own process, so the whole suite can run in parallel
while iterating. It is local only: it skips doctests and the isolated
render tests, so the gate stays as it is. Add it to the Nix shell.
---
 AGENTS.md       |  1 +
 CONTRIBUTING.md | 10 ++++++++++
 flake.nix       |  1 +
 3 files changed, 12 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index d0f4a16b..2f013d49 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -54,6 +54,7 @@
 - Dependency changes must satisfy `deny.toml`. A new license or duplicate version needs an entry there with its reason.
 
 ## Validation
+- For a fast full-suite run while iterating, use `cargo nextest run --workspace --all-features`. Each test gets its own process, so it runs in parallel despite the native-font race that keeps the gate serial. It skips doctests and the isolated render tests, so it does not replace the gate.
 - Full local CI is `./tools/lint-and-test.sh`. It needs the .NET SDK selected by `global.json`. Without it, `cargo test` still runs the Rust source guards in `tests/repository_guards` (process sites, config writers, shared dependencies, use statements, no Python), but not the C# checks, including the source-coverage check that finds `.rs` files Cargo never compiles.
 - That script runs the C# repository checks (assets, version, nixpkgs recipe, source coverage, legacy tools), the C# tool tests (which also run the packaging shell contracts), `cargo fmt --all -- --check`, clippy with all targets/features, all-feature tests, and no-default-feature tests.
 - Run `git diff --check` before handoff. When relevant files are untracked and the index must stay unchanged, check those files directly as well.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4407555b..700426fd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -125,6 +125,16 @@ cargo test session::
 cargo test -p wayscriber-configurator
 ```
 
+For a fast run of the whole suite, use [cargo-nextest](https://nexte.st/), which the Nix shell
+includes. It gives each test its own process, so it can run in parallel despite the native font
+race that keeps the local CI entry point serial:
+
+```bash
+cargo nextest run --workspace --all-features
+```
+
+It skips doctests and the isolated render tests, so it does not replace that entry point.
+
 Before submitting a broad or cross-package change, run the local CI entry point:
 
 ```bash
diff --git a/flake.nix b/flake.nix
index 46258f24..583af8f8 100644
--- a/flake.nix
+++ b/flake.nix
@@ -33,6 +33,7 @@
         developmentInputs = with pkgs; [
           rustToolchain
           cargo-deny
+          cargo-nextest
           util-linux
           pkg-config
           cairo