ktstr/test_support/dispatch.rs
1//! Process-level dispatch and nextest protocol handling.
2//!
3//! This module owns every code path that runs before (or in lieu of)
4//! the user's `main()`:
5//!
6//! - [`ktstr_test_early_dispatch`]: the `#[ctor]` that fires in every
7//! ktstr-linked binary. Routes the process to guest init, host-side
8//! VM launch, guest-side test execution, or nextest protocol handling.
9//! - [`ktstr_main`]: the nextest protocol handler — `--list` returns
10//! `ktstr/`, `gauntlet/`, and `host/` test names, `--exact` runs a single
11//! test. The prefix is also a resource-admission identity: `ktstr/` and
12//! `gauntlet/` boot VMs, while `host/` entries are ordinary host work.
13//! - [`run_ktstr_test`]: programmatic entry point used by library
14//! consumers and the macro-generated `#[test]` wrappers.
15//! - [`analyze_sidecars`]: collects sidecar JSON from a run directory
16//! and renders the full gauntlet analysis (rows + verifier + callback
17//! profile + KVM stats) into a string.
18//!
19//! The heavy lifting lives in sibling submodules: `eval` (host-side
20//! result judgment — `run_ktstr_test_inner` and `evaluate_vm_result`),
21//! `sidecar` (per-run JSON), `probe` (auto-repro + BPF probe pipeline),
22//! `args` (CLI extraction), and the [`crate::vmm`] VM launcher.
23
24use std::path::PathBuf;
25
26use anyhow::{Context, Result};
27
28use crate::assert::AssertResult;
29
30#[cfg(feature = "export")]
31use super::extract_export_output_arg;
32use super::{
33 HostClass, KTSTR_TESTS, KtstrTestEntry, TopoOverride, classify_host_error, collect_sidecars,
34 extract_export_check_test_arg, extract_export_test_arg, extract_shell_test_arg,
35 extract_test_fn_arg, extract_topo_arg, find_test, format_callback_profile, format_kvm_stats,
36 format_verifier_stats, maybe_dispatch_vm_test, parse_topo_string,
37 propagate_rust_env_from_cmdline, record_skip_sidecar, resolve_test_kernel,
38 run_ktstr_test_inner, sidecar_dir, try_flush_profraw,
39};
40
41/// Check if an error is a host topology mismatch (e.g. test requests
42/// 2 LLCs but host has 1, or more CPUs than the host carries).
43///
44/// Walks the FULL error chain via `e.chain().any(...)` so a
45/// [`TopologyInsufficient`] wrapped in `.context(...)` (the
46/// `crate::test_support::eval` `"build ktstr_test VM"` / `"run
47/// ktstr_test VM"` wrappers) is still recognised — mirrors
48/// [`is_resource_contention`]. Replaced a fragile message string-match
49/// (`"need"` + `"LLC"`/`"CPU"`) that would misclassify any unrelated
50/// error happening to contain those words as a topology skip.
51///
52/// [`TopologyInsufficient`]: crate::vmm::host_topology::TopologyInsufficient
53#[doc(hidden)]
54pub fn is_topology_insufficient(e: &anyhow::Error) -> bool {
55 e.chain().any(|cause| {
56 cause
57 .downcast_ref::<crate::vmm::host_topology::TopologyInsufficient>()
58 .is_some()
59 })
60}
61
62/// Check if an `anyhow::Error` carries a [`ResourceContention`].
63///
64/// Walks the FULL error chain via `e.chain().any(...)` so a
65/// `ResourceContention` wrapped in `.context(...)` (e.g. the
66/// `crate::test_support::eval` `"build ktstr_test VM"` and `"run ktstr_test VM"`
67/// wrappers) is still recognised — the macro's match arm depends on
68/// this.
69///
70/// Used by the `#[ktstr_test]` macro expansion to short-circuit on
71/// host-resource contention (LLC slots / CPUs unavailable, KVM fd
72/// budget exhausted, ENOMEM): the macro emits the canonical
73/// `ktstr: SKIP: resource contention: ...` banner and early-returns
74/// so libtest sees pass. The skip sidecar is recorded at every
75/// contention site inside `run_ktstr_test_inner`, so stats tooling
76/// still sees the skip without a panic-driven nextest retry. `pub`
77/// because the macro-generated `#[test]` body in `ktstr-macros`
78/// references it by absolute path; `#[doc(hidden)]` keeps it out
79/// of rustdoc's public surface — it is plumbing, not user API.
80///
81/// [`ResourceContention`]: crate::vmm::host_topology::ResourceContention
82#[doc(hidden)]
83pub fn is_resource_contention(e: &anyhow::Error) -> bool {
84 e.chain().any(|cause| {
85 cause
86 .downcast_ref::<crate::vmm::host_topology::ResourceContention>()
87 .is_some()
88 })
89}
90
91/// Check if an `anyhow::Error` carries a [`PerfModeUnavailable`].
92///
93/// Chain-aware (walks `e.chain()`), like [`is_topology_insufficient`].
94/// A `PerfModeUnavailable` is a HOST-INSUFFICIENCY skip, like RC/TI: the
95/// host fundamentally cannot honor an explicitly-requested perf-mode
96/// guarantee (too few CPUs for an exclusive host LLC + a service CPU).
97/// The VM is never run unisolated (it errors at build), so
98/// `result_to_exit_code` and the macro body route it to a VISIBLE skip
99/// by default, promoted to a FAIL banner under `KTSTR_NO_SKIP_MODE`.
100///
101/// [`PerfModeUnavailable`]: crate::vmm::host_topology::PerfModeUnavailable
102#[doc(hidden)]
103pub fn is_perf_mode_unavailable(e: &anyhow::Error) -> bool {
104 e.chain().any(|cause| {
105 cause
106 .downcast_ref::<crate::vmm::host_topology::PerfModeUnavailable>()
107 .is_some()
108 })
109}
110
111/// Check if an `anyhow::Error` carries a [`CpuBudgetUnsatisfiable`].
112///
113/// Chain-aware. A `CpuBudgetUnsatisfiable` is a HARD ERROR (an operator
114/// `--cpu-cap` number the host cannot satisfy), NOT a skip. (An author's
115/// per-test `cpu_budget` over the allowance skips via `TopologyInsufficient`
116/// instead — see `resolve_cpu_budget` — so it never carries this type.)
117///
118/// [`CpuBudgetUnsatisfiable`]: crate::vmm::host_topology::CpuBudgetUnsatisfiable
119#[doc(hidden)]
120pub fn is_cpu_budget_unsatisfiable(e: &anyhow::Error) -> bool {
121 e.chain().any(|cause| {
122 cause
123 .downcast_ref::<crate::vmm::host_topology::CpuBudgetUnsatisfiable>()
124 .is_some()
125 })
126}
127
128/// Check if an `anyhow::Error` carries a [`TopologyUnrepresentable`].
129///
130/// Chain-aware. A `TopologyUnrepresentable` is a HARD ERROR (a topology no
131/// host can represent under this VMM's static device layout — the aarch64
132/// over-`MAX_VCPUS` GICv3-redistributor case), NOT a skip.
133/// `classify_host_error` classifies it as `HostClass::Fail`, checked above
134/// the RC/TI skip types and handled above the `expect_err` inversion in
135/// both `err_to_exit_code` and the macro body, so a too-wide aarch64
136/// topology can neither masquerade as the expected failure nor be turned
137/// into a silent skip. Distinct from [`is_topology_insufficient`], which
138/// matches the host-DEPENDENT skip type.
139///
140/// [`TopologyUnrepresentable`]: crate::vmm::host_topology::TopologyUnrepresentable
141#[doc(hidden)]
142pub fn is_topology_unrepresentable(e: &anyhow::Error) -> bool {
143 e.chain().any(|cause| {
144 cause
145 .downcast_ref::<crate::vmm::host_topology::TopologyUnrepresentable>()
146 .is_some()
147 })
148}
149
150/// Predicate: walks the [`anyhow::Error`] chain looking for a
151/// [`KernelUnavailable`] cause. Used by `classify_host_error` to classify
152/// a no-kernel host as a skip-class host-insufficiency.
153///
154/// The harness signals "I have no kernel to boot, the binary was
155/// likely invoked outside `cargo ktstr test`" by surfacing
156/// [`KernelUnavailable`] rather than a generic `anyhow::bail!`.
157/// `classify_host_error` maps it to `HostClass::Skip` (the canonical
158/// `ktstr: SKIP: harness not configured: ...` banner), promoted to a FAIL
159/// under `KTSTR_NO_SKIP_MODE` — same shape as the resource-contention skip.
160/// `pub` + `#[doc(hidden)]`: plumbing re-exported from `test_support`
161/// alongside the sibling `is_*` predicates, not user API.
162///
163/// Both consumers route a `KernelUnavailable` through the shared
164/// [`classify_host_error`] (a no-kernel host is a skip-class
165/// host-insufficiency): `err_to_exit_code` and the `#[ktstr_test]` macro
166/// body both SKIP it by default, promoted to a FAIL under
167/// `KTSTR_NO_SKIP_MODE`. Under nextest the plain `#[test]` wrapper is
168/// suppressed, so a VM entry dispatches as `ktstr/{name}` (and a host-only
169/// entry as `host/{name}`) via `run_named_test` → `err_to_exit_code` —
170/// meaning a developer running `cargo nextest run`,
171/// or `cargo ktstr test` without `--kernel`, on a kernel-less host gets a
172/// clean skip rather than a hard fail on every entry. This cannot mask a CI
173/// kernel-build failure: a requested `--kernel` that fails to build bails in
174/// cargo-ktstr (`resolve_kernel_set`) before nextest is spawned, so a
175/// `KernelUnavailable` here only ever means "no kernel was requested".
176/// Pinned by `result_to_exit_code_kernel_unavailable_skips_on_dispatch_path`.
177///
178/// [`classify_host_error`]: crate::test_support::classify_host_error
179///
180/// [`KernelUnavailable`]: crate::test_support::eval::KernelUnavailable
181#[doc(hidden)]
182pub fn is_kernel_unavailable(e: &anyhow::Error) -> bool {
183 e.chain().any(|cause| {
184 cause
185 .downcast_ref::<crate::test_support::eval::KernelUnavailable>()
186 .is_some()
187 })
188}
189
190/// A nextest-safe kernel identifier whose construction is gated
191/// through [`sanitize_kernel_label`] — once a value of this type
192/// exists, the contained string is GUARANTEED to match the
193/// `kernel_[a-z0-9_]+` shape that nextest's test-name parsing
194/// accepts. The wrapped `String` is private so a future caller
195/// cannot bypass [`Self::new`] and stuff a raw label into the
196/// invariant.
197///
198/// Constructed by [`Self::new`] (which always calls
199/// [`sanitize_kernel_label`]). Read access is via
200/// [`Self::as_str`] / `Display` / `AsRef<str>` — both of which
201/// expose the sanitized form unchanged.
202///
203/// `pub(crate)` because every consumer (this module, the
204/// production parser at [`parse_kernel_list`], and the encoder
205/// helpers in `cargo-ktstr` that emit the wire format
206/// `parse_kernel_list` decodes) lives inside the workspace; no external
207/// surface is needed today. If a future external consumer needs
208/// to construct a `SanitizedKernelLabel` directly, expose
209/// `Self::new` as `pub` then — but the private inner stays a
210/// private invariant either way.
211#[derive(Clone, Debug, PartialEq, Eq, Hash)]
212pub(crate) struct SanitizedKernelLabel(String);
213
214impl SanitizedKernelLabel {
215 /// Sanitize `raw` via [`sanitize_kernel_label`] and wrap the
216 /// result in the invariant-preserving newtype. The only path
217 /// that produces a `SanitizedKernelLabel`; bypassing it is
218 /// impossible because the inner field is private to this
219 /// module.
220 pub(crate) fn new(raw: &str) -> Self {
221 Self(sanitize_kernel_label(raw))
222 }
223
224 /// Read access to the sanitized identifier. Returns `&str`
225 /// rather than `&String` so callers can compose with
226 /// `format!` / `starts_with` / `strip_suffix` without
227 /// chaining `.as_str().as_str()`.
228 pub(crate) fn as_str(&self) -> &str {
229 &self.0
230 }
231}
232
233impl std::fmt::Display for SanitizedKernelLabel {
234 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
235 f.write_str(&self.0)
236 }
237}
238
239impl AsRef<str> for SanitizedKernelLabel {
240 fn as_ref(&self) -> &str {
241 &self.0
242 }
243}
244
245// `PartialEq<&str>` and `PartialEq<str>` impls let `assert_eq!`
246// against a string literal stay readable in tests
247// (`assert_eq!(entries[0].sanitized, "kernel_6_14_2")`) without
248// forcing every consumer to chain `.as_str()`. The wrapped
249// `String` is private to this module, so impls comparing
250// against external `&str` values cannot break the
251// "constructor enforces sanitization" invariant — the
252// invariant attaches to value PRODUCTION, not to value
253// COMPARISON.
254impl PartialEq<&str> for SanitizedKernelLabel {
255 fn eq(&self, other: &&str) -> bool {
256 self.0 == *other
257 }
258}
259
260impl PartialEq<str> for SanitizedKernelLabel {
261 fn eq(&self, other: &str) -> bool {
262 self.0 == other
263 }
264}
265
266#[cfg(test)]
267impl SanitizedKernelLabel {
268 /// Test-only escape hatch: wrap a string that's ALREADY in
269 /// the sanitized shape (`kernel_[a-z0-9_]+`) without running
270 /// the sanitizer. Used by unit-test fixtures that hand-roll
271 /// `KernelEntry` values whose `sanitized` field is meant to
272 /// be a literal — running [`Self::new`] on `"kernel_6_14_2"`
273 /// would double-prefix to `"kernel_kernel_6_14_2"`.
274 ///
275 /// Production code must NEVER call this — invariant
276 /// violation here means callers can stuff arbitrary strings
277 /// into the field, defeating the point of the newtype.
278 /// `#[cfg(test)]` enforces that at compile time.
279 pub(crate) fn from_pre_sanitized_for_test(s: &str) -> Self {
280 Self(s.to_string())
281 }
282}
283
284/// One resolved kernel entry from `KTSTR_KERNEL_LIST` (the multi-
285/// kernel fan-out wire format that `cargo ktstr test --kernel A
286/// --kernel B` or `cargo ktstr verifier --kernel A --kernel B`
287/// exports before exec'ing into `cargo nextest`).
288///
289/// `label` is the producer-side label string before
290/// sanitization — e.g. `"6.14.2"` for Version, `"git_tj_sched_ext_for-next"`
291/// for Git, `"6.14.2-tarball-x86_64-kc..."` for CacheKey,
292/// `"path_linux_a3f2b1"` for Path. Preserved so the
293/// [`crate::test_support::dispatch`] verifier sweep filter can
294/// compare against `declare_scheduler!`'s `kernels = [...]`
295/// declarations — specifically, range membership
296/// (`"6.14..6.16"` vs `"6.14.2"`) needs the raw version string
297/// to feed into [`crate::kernel_path::decompose_version_for_compare`],
298/// which the sanitized form has lost (slashes / dots → underscores).
299///
300/// `sanitized` is the nextest-safe identifier appended to test names
301/// so `cargo nextest run -E 'test(kernel_6_14_2)'` filters work
302/// natively. The producer-side encoder in `cargo-ktstr` emits a
303/// semantic, operator-readable label per kernel:
304/// - Version / Range expansion: the version string verbatim
305/// (`6.14.2`, `6.15-rc3`).
306/// - CacheKey: the version prefix for tarballs, a compact
307/// `git_{kind}_{refhash6}` label for content-addressed git entries,
308/// or the legacy ref prefix for older `-git-` keys.
309/// - Git: `git_{owner}_{repo}_{kind}_{ref}` extracted from the URL
310/// (kind = tag/branch/sha).
311/// - Path: `path_{basename}_{hash6}` — basename + 6-char crc32 of
312/// the canonical path, disambiguating two `linux` directories
313/// under different parents.
314///
315/// [`SanitizedKernelLabel::new`] (which calls [`sanitize_kernel_label`])
316/// applies the `kernel_` prefix and `[a-z0-9_]+` normalization
317/// downstream. The newtype on this field makes the invariant
318/// compile-checked: a future caller cannot construct a
319/// `KernelEntry` whose `sanitized` field skipped sanitization.
320///
321/// `kernel_dir` is the canonical absolute path to the kernel-build
322/// directory the per-variant subprocess re-exports as
323/// `KTSTR_KERNEL`.
324#[derive(Clone, Debug)]
325pub(crate) struct KernelEntry {
326 pub(crate) label: String,
327 pub(crate) sanitized: SanitizedKernelLabel,
328 pub(crate) kernel_dir: PathBuf,
329}
330
331/// Parse the multi-kernel wire format `KTSTR_KERNEL_LIST` into a
332/// `Vec<KernelEntry>`. Format: `label1=path1;label2=path2;...`,
333/// semicolon-separated entries, `=` separating label from path. Empty
334/// / unset env returns an empty vec — callers treat that as
335/// "single-kernel mode" and fall through to `KTSTR_KERNEL`.
336///
337/// Malformed entries (missing `=`, empty label, empty path) are
338/// dropped silently — the producer is `cargo ktstr` which encodes
339/// the format under our control, so a malformed entry indicates a
340/// regression in the producer rather than operator input that
341/// deserves a clear error. Silent drop preserves the `len() <= 1` →
342/// "treat as single-kernel" invariant in the readers downstream.
343pub(crate) fn parse_kernel_list(raw: &str) -> Vec<KernelEntry> {
344 raw.split(';')
345 .filter_map(|seg| {
346 let seg = seg.trim();
347 if seg.is_empty() {
348 return None;
349 }
350 let (label, path) = seg.split_once('=')?;
351 let label = label.trim();
352 let path = path.trim();
353 if label.is_empty() || path.is_empty() {
354 return None;
355 }
356 Some(KernelEntry {
357 label: label.to_string(),
358 sanitized: SanitizedKernelLabel::new(label),
359 kernel_dir: PathBuf::from(path),
360 })
361 })
362 .collect()
363}
364
365/// Read [`crate::KTSTR_KERNEL_LIST_ENV`] and parse it into a
366/// `Vec<KernelEntry>`. Empty / unset / malformed → empty vec
367/// (single-kernel mode at the call site).
368pub(crate) fn read_kernel_list() -> Vec<KernelEntry> {
369 std::env::var(crate::KTSTR_KERNEL_LIST_ENV)
370 .ok()
371 .map(|v| parse_kernel_list(&v))
372 .unwrap_or_default()
373}
374
375/// Sanitise a kernel label (the producer-side identity emitted by
376/// `cargo ktstr`'s resolver) into a nextest-safe identifier of the
377/// shape `kernel_[a-z0-9_]+`.
378///
379/// Replaces every `[^A-Za-z0-9]` byte with `_`, lowercases, collapses
380/// runs of `_`, and prefixes with `kernel_`. Empty / pathologically-
381/// short input collapses to `kernel_` alone, which the parser
382/// downstream still recognises as a valid suffix (the empty
383/// `sanitized` marker just won't disambiguate two kernels — but the
384/// producer side guarantees non-empty labels, so the empty case is
385/// defensive only).
386///
387/// Example mappings:
388/// - `6.14.2` → `kernel_6_14_2`
389/// - `6.15-rc3` → `kernel_6_15_rc3`
390/// - `git_tj_sched_ext_for-next` → `kernel_git_tj_sched_ext_for_next`
391/// - `path_linux_a3f2b1` → `kernel_path_linux_a3f2b1`
392pub fn sanitize_kernel_label(raw: &str) -> String {
393 let mut out = String::with_capacity(raw.len() + 7);
394 out.push_str("kernel_");
395 let mut last_underscore = true; // suppress leading `_` after `kernel_`
396 for ch in raw.chars() {
397 let c = ch.to_ascii_lowercase();
398 if c.is_ascii_alphanumeric() {
399 out.push(c);
400 last_underscore = false;
401 } else if !last_underscore {
402 out.push('_');
403 last_underscore = true;
404 }
405 }
406 // Strip a trailing `_` so a label like `for-next-` doesn't
407 // produce a dangling separator.
408 if out.ends_with('_') && out.len() > "kernel_".len() {
409 out.pop();
410 }
411 out
412}
413
414ctor::declarative::ctor! {
415/// Early dispatch for `#[ktstr_test]` test execution.
416///
417/// Runs before `main()` in any binary that links against ktstr.
418///
419/// When running as PID 1 (the binary is `/init` in the VM), calls
420/// `ktstr_guest_init()` which handles the full init lifecycle and never
421/// returns.
422///
423/// - `--ktstr-test-fn=NAME --ktstr-topo=NnNlNcNt`: host-side dispatch —
424/// boots a VM with the specified topology and runs the test inside it.
425/// - `--ktstr-test-fn=NAME` (without `--ktstr-topo`): guest-side dispatch —
426/// runs the test function directly (inside a VM that was already booted).
427/// - nextest protocol (`--list`/`--exact`): intercepted when running
428/// under nextest (`NEXTEST` env var set), delegates to [`ktstr_main`].
429/// - Otherwise: no-op (falls through to the standard test harness).
430///
431/// ctor 1.0 ships both `#[ctor::ctor(...)]` (proc-macro attribute) and
432/// `ctor::declarative::ctor! { ... }` (declarative block). This site
433/// uses the declarative form because it sidesteps the TT-muncher
434/// recursion-limit cost the proc-macro form would impose on the
435/// ktstr_test expansion. The proc-macro form stays reachable via
436/// `crate::__private::ctor::ctor` for downstream consumers that prefer
437/// the attribute-on-fn shape; see `tests/private_module_paths.rs` for
438/// the re-export contract.
439#[doc(hidden)]
440#[ctor(unsafe)]
441pub fn ktstr_test_early_dispatch() {
442 // PID 1: the binary is /init in the VM. Perform full init lifecycle
443 // (mounts, scheduler, test dispatch, reboot). Never returns.
444 if unsafe { libc::getpid() } == 1 {
445 crate::vmm::rust_init::ktstr_guest_init();
446 }
447
448 // Export-self dispatch runs BEFORE host/guest test dispatch.
449 // `cargo ktstr export` is a router that exec's the test binary
450 // with `--ktstr-export-test=NAME`; the binary reads its own
451 // `KTSTR_TESTS` registry, embeds itself via `current_exe`, and
452 // writes the .run file. Running this check first means the
453 // export path never accidentally triggers VM boot if the
454 // operator simultaneously passes `--ktstr-test-fn` (the export
455 // arg wins because export is a one-shot tool, not a test
456 // execution).
457 if let Some(code) = maybe_dispatch_export() {
458 std::process::exit(code);
459 }
460 if let Some(code) = maybe_dispatch_shell_test() {
461 std::process::exit(code);
462 }
463 if let Some(code) = maybe_dispatch_host_test() {
464 std::process::exit(code);
465 }
466 // Propagate RUST_BACKTRACE / RUST_LOG from /proc/cmdline before
467 // `maybe_dispatch_vm_test` runs: ctor context is single-threaded
468 // (`.init_array` runs before any user thread exists), so this
469 // `set_var` is sound and the later guest-side code that spawns
470 // the probe thread observes the correct env.
471 propagate_rust_env_from_cmdline();
472 if let Some(code) = maybe_dispatch_vm_test() {
473 // The LLVM profiling runtime registers its atexit handler via a
474 // .init_array entry (C++ global initializer). Our ctor also lives
475 // in .init_array, and the execution order between them is
476 // non-deterministic. If our ctor runs first, the atexit handler
477 // was never registered, so std::process::exit() won't write the
478 // profraw. Serialize profraw to a buffer and write it to the SHM
479 // ring for host-side extraction.
480 try_flush_profraw();
481 std::process::exit(code);
482 }
483
484 // nextest protocol: intercept --list and --exact when running under
485 // nextest. Under cargo test, fall through to the standard harness
486 // which runs the #[test] wrappers generated by #[ktstr_test].
487 //
488 // Binaries with real #[ktstr_test] entries need the ctor to handle
489 // listing (gauntlet expansion) and dispatch (VM booting). The lib
490 // test binary has only the dummy entry and no gauntlet variants —
491 // skip interception so the standard harness discovers #[cfg(test)]
492 // module #[test] functions (unit tests).
493 //
494 // For `--list`, ktstr_main prints the gauntlet/ktstr names and
495 // RETURNS so the standard libtest harness can print its own list
496 // of `#[test]` items afterward. This makes plain `#[test]`
497 // functions inside a ktstr_test integration-test binary visible
498 // to nextest — without the fall-through, libtest never runs and
499 // those test names are silently dropped from the listing.
500 //
501 // For `--exact`, ktstr_main runs only when the test name starts
502 // with `ktstr/`, `gauntlet/`, or `host/` — names ktstr owns. Other names
503 // (libtest #[test] items, including the per-entry wrappers
504 // emitted by `#[ktstr_test]` itself) fall through to libtest's
505 // dispatch. Without this guard, run_named_test would fail
506 // `find_test` for a plain `#[test]` name and exit 1, blocking
507 // nextest from running it.
508 if std::env::var_os("NEXTEST").is_some() {
509 let has_real_tests = KTSTR_TESTS.iter().any(|e| !is_test_sentinel(e.name));
510 // A binary may carry only `declare_scheduler!` declarations
511 // (no `#[ktstr_test]` entries) — pure verifier-only test
512 // binaries. Without the scheduler check below the listing
513 // branch would never fire for such a binary and the
514 // verifier cells would silently fail to emit under nextest.
515 let has_schedulers = !super::KTSTR_SCHEDULERS.is_empty();
516 if has_real_tests || has_schedulers {
517 let args: Vec<String> = std::env::args().collect();
518 if args.iter().any(|a| a == "--list") {
519 ktstr_list_only();
520 list_verifier_cells_all();
521 list_plain_tests(args.iter().any(|a| a == "--ignored"));
522 std::process::exit(0);
523 } else if let Some(pos) = args.iter().position(|a| a == "--exact")
524 && let Some(name) = args.get(pos + 1)
525 && name.starts_with("verifier/")
526 {
527 // verifier/<sched>/<kernel>/<preset> cells bypass libtest
528 // entirely — the cell handler resolves the scheduler
529 // binary, kernel, and the cell's topology preset, runs
530 // collect_verifier_output, prints the result, and
531 // exits. No #[test] wrapper exists for declared
532 // schedulers (declare_scheduler! only emits a static),
533 // so it runs directly via run_verifier_cell — the same
534 // libtest bypass the ktstr/ branch below uses.
535 let code = run_verifier_cell(name);
536 try_flush_profraw();
537 std::process::exit(code);
538 } else if let Some(pos) = args.iter().position(|a| a == "--exact")
539 && let Some(name) = args.get(pos + 1)
540 && (name.starts_with("ktstr/")
541 || name.starts_with("gauntlet/")
542 || name.starts_with("host/"))
543 {
544 let bare = name
545 .strip_prefix("ktstr/")
546 .or_else(|| name.strip_prefix("gauntlet/"))
547 .or_else(|| name.strip_prefix("host/"))
548 .unwrap_or(name)
549 .split('/')
550 .next()
551 .unwrap_or(name);
552
553 // Reject malformed names like `gauntlet/` (trailing
554 // slash, no test name), `ktstr/`, and `host/` up front, so the
555 // operator sees a clear error instead of an opaque
556 // "unknown test" from the empty bare name.
557 if bare.is_empty() {
558 eprintln!(
559 "ktstr: malformed --exact test name {name:?} \
560 (resolves to an empty bare name after prefix strip)",
561 );
562 std::process::exit(1);
563 }
564
565 // Run the entry directly, bypassing libtest — the same
566 // pattern as the verifier/ branch above. The previous
567 // dispatch rewrote argv to the bare name and relied on a
568 // #[test] wrapper (emitted only by the #[ktstr_test]
569 // macro) for libtest to match it; raw
570 // `#[distributed_slice(KTSTR_TESTS)]` registrations have
571 // no wrapper, so libtest matched nothing and printed
572 // "running 0 tests" — a silent trivial-pass. run_named_test
573 // resolves the entry from KTSTR_TESTS by name and boots it
574 // for both registration styles, routing gauntlet/ to
575 // run_gauntlet_test (identical topology) and applying the
576 // host_only / performance_mode / bpf_map_write gates the
577 // wrapper path skipped.
578 let code = run_named_test(name);
579 try_flush_profraw();
580 std::process::exit(code);
581 }
582 }
583 } else {
584 // cargo-test-direct path: the standard rustc test harness
585 // runs only the bare `#[test]` wrappers `#[ktstr_test]`
586 // generates. Gauntlet expansion (topology-preset variants)
587 // lives inside `ktstr_main`'s `--list` + `--exact` handlers
588 // and is reachable ONLY under nextest. Every real ktstr
589 // entry produces topology-preset variants under nextest
590 // (`for_each_gauntlet_variant` iterates
591 // `crate::gauntlet::gauntlet_presets()`). Without nextest those
592 // variants would silently not run — coverage loss with no
593 // error. Emit a one-shot stderr `warning:` diagnostic (see
594 // the `eprintln!` below) when the binary carries any real
595 // entry so the user sees the gap instead of trusting a
596 // false green. Print once per process (cargo test invokes
597 // one test binary per crate; the ctor runs exactly once per
598 // test binary) so there is no need to gate with a
599 // std::sync::Once.
600 //
601 // `KTSTR_CARGO_TEST_MODE=1` opts out of the warning: the
602 // operator deliberately picked the cargo-test-direct path
603 // (e.g. for a single-test debug iteration without the
604 // nextest harness) and accepts that gauntlet variants
605 // won't run. The warning is still emitted under bare
606 // `cargo test` without the env var set so unaware users
607 // see the coverage gap.
608 if !crate::cargo_test_mode::cargo_test_mode_active() {
609 let total = KTSTR_TESTS.len();
610 let real = KTSTR_TESTS
611 .iter()
612 .filter(|e| !is_test_sentinel(e.name))
613 .count();
614 if real > 0 {
615 eprintln!(
616 "warning: {real} of {total} ktstr test entries registered in this binary \
617 will not generate their topology-preset gauntlet variants — NEXTEST env \
618 var is not set and the standard rustc harness does not expand them. Use \
619 `cargo nextest run` (or `cargo ktstr test`) to exercise the full gauntlet, \
620 or set KTSTR_CARGO_TEST_MODE=1 to opt into single-variant bare-`cargo test` \
621 mode without this warning.",
622 );
623 }
624 // Verifier cells are emitted by `list_verifier_cells_all`
625 // which runs ONLY from the NEXTEST listing branch above.
626 // A bare `cargo test` invocation on a binary carrying
627 // `declare_scheduler!` declarations gets zero verifier
628 // coverage — surface the gap with the same opt-out shape
629 // as the gauntlet warning so an unaware operator does not
630 // trust a green run that never reached the verifier.
631 // Eevdf + KernelBuiltin variants don't produce userspace
632 // binaries to verify, so they are excluded from the count
633 // (matching the emission-time filter in
634 // `list_verifier_cells_all`).
635 let verifier_schedulers = super::KTSTR_SCHEDULERS
636 .iter()
637 .filter(|s| {
638 !matches!(
639 s.binary,
640 super::SchedulerSpec::Eevdf | super::SchedulerSpec::KernelBuiltin { .. }
641 )
642 })
643 .count();
644 if verifier_schedulers > 0 {
645 eprintln!(
646 "warning: {verifier_schedulers} `declare_scheduler!` declaration(s) in this \
647 binary will not generate verifier cells — NEXTEST env var is not set and \
648 verifier cells are emitted only by ktstr's `--list` handler under nextest. \
649 Use `cargo ktstr verifier` to exercise the verifier sweep, or set \
650 KTSTR_CARGO_TEST_MODE=1 to acknowledge the verifier-cell-free path without \
651 this warning.",
652 );
653 }
654 }
655 }
656}
657}
658
659/// Predicate for "this entry is a unit-test sentinel, not a real
660/// `#[ktstr_test]` user entry." The lib-test binary registers a
661/// single sentinel entry (currently `"__unit_test_dummy__"`) so
662/// the dispatch + gauntlet plumbing has something to exercise
663/// under `cargo test --lib`; real user entries look like
664/// `"module::test_name"` or similar PascalCase-with-dots names.
665///
666/// Matching the sentinel by convention (`__` prefix + `__`
667/// suffix + `_test_` or `_dummy_` infix) rather than by literal
668/// equality keeps the filter robust when the sentinel is
669/// renamed, or when future scaffolding adds additional
670/// sentinel-shaped entries (e.g. `__unit_test_panics__`,
671/// `__unit_test_timeout__`). The literal-equality form would
672/// silently admit those future sentinels into the real-entry
673/// population and double-fire the "NEXTEST env var not set"
674/// warning or spuriously enable --list interception.
675fn is_test_sentinel(name: &str) -> bool {
676 // Real user-authored `#[ktstr_test]` entry names
677 // conventionally do not match the `__unit_test_*__` pattern
678 // (Rust's reserved-identifier convention for
679 // language-implementation and framework-internal names).
680 // The `#[ktstr_test]` proc macro does not validate this, so
681 // the predicate admits a real user entry in the unlikely
682 // case someone names one with the `__unit_test_*__` shape —
683 // collision would double-fire the "NEXTEST env var not set"
684 // warning / spuriously enable --list interception, but
685 // that's a diagnostic glitch, not a correctness failure.
686 name.starts_with("__unit_test_") && name.ends_with("__")
687}
688
689/// Export-self dispatch. `--ktstr-export-check-test=NAME` performs only the
690/// cheap registry ownership and static eligibility check;
691/// `--ktstr-export-test=NAME` builds the self-extracting `.run` file embedding
692/// `current_exe()` (this binary). Returns `Some(exit_code)` when either private
693/// discriminator is present and `None` otherwise.
694///
695/// `cargo ktstr export <NAME>` (the cargo-ktstr binary) is a router
696/// that compiles the workspace's tests, locates an eligible owner with the
697/// check-only arg, then exec's that selected binary once with the real export
698/// arg. The test binary embeds ITSELF — without that indirection, cargo-ktstr
699/// would package its own binary, which has no `#[ktstr_test]` registrations
700/// from the user's crate and can't reproduce the test on bare metal.
701///
702/// `--ktstr-export-output=PATH` overrides the default output path
703/// (`<NAME>.run` in the cwd). Both flags are leniently parsed by the
704/// helpers in `args.rs`; an empty NAME (`--ktstr-export-test=`)
705/// surfaces with diagnostic "requires a non-empty test name" and
706/// exit 1 so the router moves on to the next candidate.
707///
708/// # Exit-code contract
709///
710/// During the check-only phase the router discriminates between
711/// "this binary doesn't know the test" (exit 1) and "this binary
712/// has the test but rejects it" (exit 2). When ANY candidate exits
713/// 2, the router surfaces THAT candidate's stderr (the rejection
714/// reason: host_only, bpf_map_write, KernelBuiltin) rather than
715/// the generic "not found in any workspace test binary" message.
716/// Without the differentiation, an operator who exports a
717/// host_only test would see the misleading "not found" diagnostic
718/// even though the test exists.
719///
720/// Stub for the `export`-feature-disabled build. The router probes candidate
721/// test binaries with `--ktstr-export-check-test=NAME`; without this stub a
722/// binary compiled without `export` would fall through to the nextest
723/// harness, which would surface an opaque "unrecognised argument"
724/// error against an arg the operator never typed. The stub turns
725/// that into an actionable diagnostic by detecting the arg and
726/// emitting a build-config hint, then exiting 2 (matches the
727/// "registered but rejected" exit code so the router surfaces
728/// THIS binary's stderr rather than a sibling's "not registered"
729/// fallthrough). Recompile the test binary with the `export`
730/// feature (folded into `cli-bins` in the default feature set)
731/// to enable the real `cargo ktstr export` flow.
732#[cfg(not(feature = "export"))]
733fn maybe_dispatch_export() -> Option<i32> {
734 let args: Vec<String> = std::env::args().collect();
735 let _ = extract_export_check_test_arg(&args).or_else(|| extract_export_test_arg(&args))?;
736 eprintln!(
737 "ktstr export: this test binary was built without the `export` cargo \
738 feature, so `cargo ktstr export <name>` cannot reach the export pipeline \
739 from here. Rebuild with the default feature set (or pass \
740 `--features cli-bins`) and retry."
741 );
742 Some(2)
743}
744
745#[cfg(feature = "export")]
746fn maybe_dispatch_export() -> Option<i32> {
747 let args: Vec<String> = std::env::args().collect();
748 let check_name = extract_export_check_test_arg(&args);
749 let execute_name = extract_export_test_arg(&args);
750 let (name, check_only) = if let Some(name) = check_name {
751 (name, true)
752 } else {
753 (execute_name?, false)
754 };
755 let output = extract_export_output_arg(&args).map(std::path::PathBuf::from);
756
757 // Empty name: surface as a hard error rather than silently succeeding. The
758 // bounded selection protocol relies on the absent-test path returning a
759 // non-zero exit so the next candidate is tried.
760 if name.is_empty() {
761 eprintln!("ktstr export: --ktstr-export-test= requires a non-empty test name");
762 return Some(1);
763 }
764
765 // Look up the test ourselves so we can discriminate "not
766 // registered here" (exit 1, router falls through) from
767 // "registered but rejected" (exit 2, router surfaces this
768 // stderr). `export_test` itself returns anyhow::Error for both
769 // cases, which would conflate them at the exit-code level.
770 let Some(entry) = find_test(name) else {
771 eprintln!("ktstr export: no registered test named '{name}'");
772 return Some(1);
773 };
774
775 if check_only {
776 return match crate::export::validate_export_entry(entry) {
777 Ok(()) => Some(0),
778 Err(error) => {
779 eprintln!("ktstr export: {error:#}");
780 Some(2)
781 }
782 };
783 }
784
785 match crate::export::export_test(name, output) {
786 Ok(()) => Some(0),
787 Err(e) => {
788 eprintln!("ktstr export: {e:#}");
789 // The test exists in this binary but the export pipeline
790 // refused it (host_only / bpf_map_write / KernelBuiltin /
791 // I/O error). Exit 2 so the router prefers this stderr
792 // over a sibling binary's exit-1 "not registered" miss.
793 Some(2)
794 }
795 }
796}
797
798/// Shell-self dispatch: if `--ktstr-shell-test=NAME` is present in
799/// argv, look up `NAME` in the binary's own `KTSTR_TESTS` registry,
800/// serialize its shell-relevant fields to stdout as JSON, and exit.
801/// Returns `Some(exit_code)` when dispatched, `None` when absent.
802///
803/// `cargo ktstr shell --test <NAME>` (the cargo-ktstr binary) is a
804/// router that compiles the workspace's tests, exec's each test
805/// binary with this flag, and consumes the first stdout-JSON it
806/// gets (the router bails on ambiguous names — same `NAME`
807/// registered in two binaries). The router applies the
808/// descriptor's topology / memory / extra_include_files to the
809/// shell VM, then prints a one-line banner to stderr BEFORE VM
810/// boot naming the test + scheduler so the operator can repro the
811/// workload manually. (PS1-in-guest is a follow-up.)
812///
813/// # Stdout contract
814///
815/// The test binary MUST keep stdout silent on this dispatch path —
816/// `tracing` output MUST go to stderr. The router parses the entire
817/// stdout as a JSON descriptor; any prefix like an INFO log line
818/// will fail the parse.
819///
820/// # JSON shape
821///
822/// Serialized from [`crate::test_support::ShellTestDescriptor`] via
823/// `serde_json::to_string` — see that struct for the field-by-field
824/// contract. The struct lives in
825/// `crate::test_support::shell_descriptor` so producer and consumer
826/// share a single definition; adding a field there automatically
827/// propagates to both sides.
828///
829/// `scheduler_kind` discriminates `"eevdf" | "discover" | "path" |
830/// "kernel_builtin"` so the banner can hint at how to repro the
831/// scheduler (Discover/Path = userspace binary at `/bin/<n>`;
832/// KernelBuiltin = no binary, the shell-mode boot runs
833/// `scheduler_enable_cmds` before drop-to-busybox and
834/// `scheduler_disable_cmds` on shell exit; Eevdf = no setup needed).
835///
836/// # Exit-code contract
837///
838/// Matches `maybe_dispatch_export`:
839/// - `0`: test registered, JSON emitted to stdout.
840/// - `1`: test not registered in this binary (router falls
841/// through to the next candidate).
842/// - `2`: registered but rejected for shell mode (currently:
843/// `host_only` — no VM to drop into).
844fn maybe_dispatch_shell_test() -> Option<i32> {
845 let args: Vec<String> = std::env::args().collect();
846 let name = extract_shell_test_arg(&args)?;
847
848 if name.is_empty() {
849 eprintln!("ktstr shell: --ktstr-shell-test= requires a non-empty test name");
850 return Some(1);
851 }
852
853 let entry = match find_test(name) {
854 Some(e) => e,
855 None => {
856 eprintln!("ktstr shell: no registered test named '{name}'");
857 return Some(1);
858 }
859 };
860
861 if entry.host_only {
862 eprintln!(
863 "ktstr shell: test '{name}' has host_only = true; \
864 shell mode requires a guest VM to drop into. \
865 Either run the test directly with `cargo ktstr test {name}` \
866 (host_only tests don't boot a VM) or pick a non-host_only \
867 test for shell mode."
868 );
869 return Some(2);
870 }
871
872 let topo = &entry.topology;
873 let scheduler_kind = crate::test_support::SchedulerKind::from(&entry.scheduler.binary);
874 let (scheduler_enable_cmds, scheduler_disable_cmds) = match &entry.scheduler.binary {
875 crate::test_support::entry::SchedulerSpec::KernelBuiltin { enable, disable } => (
876 enable.iter().copied().map(String::from).collect(),
877 disable.iter().copied().map(String::from).collect(),
878 ),
879 _ => (Vec::new(), Vec::new()),
880 };
881
882 let descriptor = crate::test_support::ShellTestDescriptor {
883 numa_nodes: topo.numa_nodes,
884 llcs: topo.llcs,
885 cores: topo.cores_per_llc,
886 threads: topo.threads_per_core,
887 memory_mib: entry.memory_mib,
888 wprof: entry.wprof,
889 extra_include_files: entry
890 .extra_include_files
891 .iter()
892 .copied()
893 .map(String::from)
894 .collect(),
895 scheduler_name: entry.scheduler.name.to_string(),
896 scheduler_kind,
897 wprof_args: entry.wprof_args.map(String::from),
898 performance_mode: entry.performance_mode,
899 scheduler_enable_cmds,
900 scheduler_disable_cmds,
901 };
902
903 // serde_json::to_string produces RFC-8259-compliant escaping
904 // (`\uXXXX` with 4 hex digits, surrogate pairs for SMP code
905 // points) which Rust's Debug formatter does NOT — Debug uses
906 // `\u{1f4c2}` (braced form) for non-ASCII, breaking
907 // operator-supplied paths with non-ASCII chars (test built
908 // under `/home/<unicode-name>/proj`, `extra_include_files`
909 // listing emoji-named files, etc.). serde_json is already a
910 // workspace dep so adding this call doesn't widen the dep graph.
911 let payload = serde_json::to_string(&descriptor)
912 .expect("ShellTestDescriptor is a plain serde struct with no fallible field types");
913 println!("{payload}");
914 Some(0)
915}
916
917/// Host-side dispatch: if both `--ktstr-test-fn` and `--ktstr-topo` are
918/// present, boot a VM with the specified topology and run the test
919/// inside it. Returns `Some(exit_code)` if dispatched, `None` otherwise.
920fn maybe_dispatch_host_test() -> Option<i32> {
921 let args: Vec<String> = std::env::args().collect();
922 let name = extract_test_fn_arg(&args)?;
923 let topo_str = extract_topo_arg(&args)?;
924
925 let entry = match find_test(name) {
926 Some(e) => e,
927 None => {
928 eprintln!("ktstr_test: unknown test function '{name}'");
929 return Some(1);
930 }
931 };
932
933 let (numa_nodes, llcs, cores, threads) = match parse_topo_string(&topo_str) {
934 Some(t) => t,
935 None => {
936 eprintln!(
937 "ktstr_test: invalid --ktstr-topo format '{topo_str}' (expected NnNlNcNt, e.g. 1n2l4c2t)"
938 );
939 return Some(1);
940 }
941 };
942
943 let cpus = llcs * cores * threads;
944 let memory_mib = super::runtime::derive_test_memory_mib(cpus, entry);
945 let topo = TopoOverride {
946 numa_nodes,
947 llcs,
948 cores,
949 threads,
950 memory_mib,
951 };
952
953 match run_ktstr_test_with_topo(entry, &topo) {
954 Ok(_) => Some(0),
955 Err(e) => {
956 eprintln!("ktstr_test: {e:#}");
957 Some(1)
958 }
959 }
960}
961
962/// Host-side entry point: build a VM, boot it with `--ktstr-test-fn=NAME`,
963/// extract profraw from SHM, and return the test result.
964///
965/// Validates KVM access and auto-discovers a kernel image via
966/// `resolve_test_kernel()` when `KTSTR_TEST_KERNEL` is not set.
967pub fn run_ktstr_test(entry: &KtstrTestEntry) -> Result<AssertResult> {
968 // Directly-constructed entries bypass the proc-macro's
969 // compile-time checks. Call `validate` here so programmatic
970 // consumers (library callers pushing into `KTSTR_TESTS`
971 // dynamically) hit the same bail messages the macro produces at
972 // compile time.
973 entry.validate()?;
974
975 if entry.host_only {
976 return run_host_only_test_inner(entry);
977 }
978 if !entry.bpf_map_write.is_empty()
979 && let Ok(kernel) = resolve_test_kernel()
980 && crate::vmm::find_vmlinux(&kernel).is_none()
981 {
982 anyhow::bail!("vmlinux not found, bpf_map_write requires vmlinux");
983 }
984 run_ktstr_test_inner(entry, None)
985}
986
987/// Like `run_ktstr_test` but with an explicit topology override.
988/// Only consumed inside this module by `maybe_dispatch_host_test`;
989/// kept as a named helper so the `--ktstr-test-fn` + `--ktstr-topo`
990/// dispatch path reads symmetrically with the zero-override
991/// [`run_ktstr_test`] library entry point.
992fn run_ktstr_test_with_topo(entry: &KtstrTestEntry, topo: &TopoOverride) -> Result<AssertResult> {
993 run_ktstr_test_inner(entry, Some(topo))
994}
995
996/// Process exit code for a Pass verdict (and for the Skip path,
997/// which degenerates to Pass because the test never ran).
998///
999/// Defined as a `pub const` so external tooling (CI gates,
1000/// dashboard aggregators, nextest wrappers) can reference the
1001/// exit-code triad by name instead of duplicating the integer
1002/// literals. The trio [`EXIT_PASS`] / [`EXIT_FAIL`] /
1003/// [`EXIT_INCONCLUSIVE`] cover every verdict produced by the
1004/// `Fail > Inconclusive > Pass > Skip` lattice when projected
1005/// to a process exit code.
1006pub const EXIT_PASS: i32 = 0;
1007
1008/// Process exit code for a Fail verdict (or any expect_err
1009/// satisfaction failure).
1010///
1011/// See [`EXIT_PASS`] for the full triad rationale.
1012pub const EXIT_FAIL: i32 = 1;
1013
1014/// Process exit code for an Inconclusive verdict (a
1015/// zero-denominator ratio gate that could not evaluate).
1016///
1017/// Distinct from [`EXIT_PASS`] (which would silently green an
1018/// unevaluated gate) and [`EXIT_FAIL`] (which would conflate
1019/// "could not evaluate" with a real regression). External tooling
1020/// uses this code to triage Inconclusive runs separately — see
1021/// the README "Exit codes" section for the full operator contract.
1022pub const EXIT_INCONCLUSIVE: i32 = 2;
1023
1024/// Run a test result through expect_err logic and return an exit code.
1025///
1026/// Returns [`EXIT_PASS`] on pass, [`EXIT_FAIL`] on failure, and
1027/// [`EXIT_INCONCLUSIVE`] on Inconclusive — the 4-state lattice
1028/// `Fail > Inconclusive > Pass > Skip` projects to 3 distinct exit
1029/// codes (Skip degenerates to [`EXIT_PASS`] because the test never
1030/// ran). A Skip routes through the
1031/// dedicated FIRST match arm (`Ok(r) if r.is_skip()`), ahead of the
1032/// expect_err arm, so an expect_err test that produced no verdict (e.g.
1033/// a `post_vm_skip` on a load-starved placeholder dump) is not inverted
1034/// into a FAIL — a skipped test cannot "produce the expected error."
1035/// [`EXIT_INCONCLUSIVE`] lets
1036/// downstream tooling (CI gates, nextest summary aggregation, the
1037/// operator dashboard) triage zero-denominator runs distinctly from
1038/// real regressions.
1039///
1040/// `ResourceContention` does NOT map to a skip. Queue-based lock
1041/// acquisition waits for authoritative release; the type still
1042/// represents retryable host-resource syscall failures.
1043/// [`classify_host_error`] routes it to [`HostClass::Fail`] →
1044/// [`EXIT_FAIL`], a RETRYABLE failure nextest re-runs. That is the correct mechanism: a
1045/// skip is [`EXIT_PASS`], which nextest never retries, so the old
1046/// skip-on-contention silently dropped suite coverage whenever a
1047/// colocated peer's `LOCK_EX` overlapped the run. Chain-awareness (the
1048/// eval-side `"build ktstr_test VM"` / `"run ktstr_test VM"`
1049/// `.context(...)` wrappers nest the typed error) is handled inside
1050/// `classify_host_error` via the chain-walking `is_*` predicates.
1051fn result_to_exit_code(
1052 result: Result<AssertResult>,
1053 expect_err: bool,
1054 allow_inconclusive: bool,
1055) -> i32 {
1056 let no_skip = std::env::var_os(crate::KTSTR_NO_SKIP_MODE_ENV).is_some();
1057 match result {
1058 Ok(r) => ok_to_exit_code(r, expect_err, allow_inconclusive),
1059 Err(e) => err_to_exit_code(e, expect_err, no_skip),
1060 }
1061}
1062
1063/// Map an `Ok(AssertResult)` verdict to an exit code.
1064///
1065/// The sequential guards preserve the original `match` arm precedence
1066/// (first matching guard wins): `is_skip()` → `expect_err` →
1067/// `is_inconclusive()` → the trailing `EXIT_PASS` (the former
1068/// `Ok(_) => EXIT_PASS` arm). Reordering these would change which
1069/// verdict fires for a result matching more than one guard.
1070fn ok_to_exit_code(r: AssertResult, expect_err: bool, allow_inconclusive: bool) -> i32 {
1071 // A Skip degenerates to EXIT_PASS regardless of expect_err — the
1072 // test never evaluated, so there is no guest failure to "expect"
1073 // (the `Fail > Inconclusive > Pass > Skip` projection). This is the
1074 // `post_vm_skip` / host-incapacity (TopologyInsufficient,
1075 // PerfModeUnavailable) skip channel — NOT ResourceContention, which
1076 // `err_to_exit_code` routes to EXIT_FAIL (retryable). Without this
1077 // guard a post_vm_skip under expect_err
1078 // falls into the `expect_err` guard below and surfaces as "expected
1079 // error but test passed" (EXIT_FAIL) — a load-starvation
1080 // placeholder-dump skip becomes a flaky failure. End-to-end chain:
1081 // a post_vm callback returns Err(post_vm_skip(..)) → the eval gate
1082 // detects the HostSkipRequest marker, reports via report::test_skip,
1083 // and returns Ok(AssertResult::skip) → this guard maps it to
1084 // EXIT_PASS. is_skip() is true only when `outcomes` is non-empty and
1085 // every outcome is Outcome::Skip (assert/plan.rs); the empty-outcomes
1086 // Pass identity has is_skip()==false and falls through to the
1087 // trailing `EXIT_PASS`.
1088 if r.is_skip() {
1089 return EXIT_PASS;
1090 }
1091 if expect_err {
1092 // expect_err inverts on Pass and on Inconclusive: both
1093 // are "not a failure" in the operator's mental model,
1094 // and an expect_err scenario that produces an
1095 // Inconclusive verdict (denominator zero) failed to
1096 // produce the expected failure just like a Pass would.
1097 // Surface the inconclusive as exit code 2 to preserve
1098 // the distinct verdict, but treat it as expect_err
1099 // satisfaction failure (exit 1) — the test author
1100 // wanted a Fail, not "the gate could not run".
1101 //
1102 // `allow_inconclusive` does NOT relax the expect_err
1103 // contract: expect_err demands a real Fail, and an
1104 // Inconclusive verdict does not satisfy that
1105 // regardless of how the test author scopes
1106 // Inconclusive elsewhere. The dominant gate wins;
1107 // `allow_inconclusive` only relaxes the
1108 // EXIT_INCONCLUSIVE projection on the no-expect_err
1109 // path below.
1110 if r.is_inconclusive() {
1111 eprintln!(
1112 "expected error but test produced an Inconclusive verdict — \
1113 zero-denominator gate could not evaluate; expect_err is \
1114 unsatisfied"
1115 );
1116 return EXIT_FAIL;
1117 } else {
1118 eprintln!("expected error but test passed");
1119 return EXIT_FAIL;
1120 }
1121 }
1122 if r.is_inconclusive() {
1123 // `allow_inconclusive` opt-in: a test author may have
1124 // declared `#[ktstr_test(allow_inconclusive)]` to
1125 // signal "this test's Inconclusive arm is acceptable —
1126 // don't fail the CI gate." Route to EXIT_PASS in that
1127 // case (Inconclusive is still recorded in the sidecar
1128 // for stats tooling and the operator-facing failure
1129 // dump still renders the diagnostic). When the flag
1130 // is unset (the default) the verdict surfaces as
1131 // EXIT_INCONCLUSIVE so the operator triages it.
1132 if allow_inconclusive {
1133 eprintln!(
1134 "test produced an Inconclusive verdict but \
1135 `allow_inconclusive` is set — routing to EXIT_PASS \
1136 for CI gate, sidecar still records Inconclusive"
1137 );
1138 return EXIT_PASS;
1139 } else {
1140 return EXIT_INCONCLUSIVE;
1141 }
1142 }
1143 EXIT_PASS
1144}
1145
1146/// Map an `Err(anyhow::Error)` outcome to an exit code.
1147///
1148/// The sequential guards preserve the original `match` arm precedence
1149/// (first matching guard wins): the host-insufficiency classification
1150/// ([`classify_host_error`], covering kernel-unavailable → perf-mode →
1151/// cpu-budget → topology-unrepresentable → resource-contention →
1152/// topology-insufficient, shared with the `#[ktstr_test]` macro body) runs
1153/// FIRST, then the
1154/// marker-typed guards (`PostVmAssertionFailure` → `SchedulerBuildRefused`
1155/// → `SurvivesStormViolated` → `ExpectAutoReproSatisfied`), then the
1156/// `expect_err` inversion, then
1157/// the catch-all (the former `Err(e) => …` arm) operating on the
1158/// now-owned `e`. Reordering these would change which guard fires for an
1159/// error matching more than one guard. The host-insufficiency guard
1160/// order + per-class skip/fail policy live in `classify_host_error`, not
1161/// here, so this site and the macro cannot drift apart.
1162fn err_to_exit_code(e: anyhow::Error, expect_err: bool, no_skip: bool) -> i32 {
1163 if crate::test_support::is_framework_infrastructure_failure(&e) {
1164 // Framework faults are never resource insufficiency and never an
1165 // expected guest failure. Check the marker before host classification
1166 // so a nested errno or contextual message cannot turn it into a skip.
1167 eprintln!("{e:#}");
1168 return EXIT_FAIL;
1169 }
1170 // Host-insufficiency classification (kernel-unavailable, perf-mode,
1171 // cpu-budget, topology-unrepresentable, resource-contention,
1172 // topology-insufficient) is shared with the `#[ktstr_test]` macro body via
1173 // `classify_host_error` — the single source of truth for the guard
1174 // ORDER and the per-class skip/fail policy. This site renders the
1175 // verdict as an exit code; the macro renders the same `HostClass` as
1176 // libtest control flow. The bare `reason` carries no prefix: the skip
1177 // channel (`report::test_skip`) prepends `ktstr: SKIP:`, the fail
1178 // channel prepends `ktstr: FAIL:`. Placed first so a host-insufficiency
1179 // returns before the marker / expect_err / catch-all arms below — a
1180 // skip is a skip and an unconditional hard fail is a hard fail
1181 // regardless of `expect_err`.
1182 match classify_host_error(&e, no_skip) {
1183 HostClass::Skip { reason } => {
1184 crate::report::test_skip(format_args!("{reason}"));
1185 return EXIT_PASS;
1186 }
1187 HostClass::Fail { reason } => {
1188 eprintln!("ktstr: FAIL: {reason}");
1189 return EXIT_FAIL;
1190 }
1191 HostClass::NotHostClass => {}
1192 }
1193 if e.downcast_ref::<crate::test_support::eval::PostVmAssertionFailure>()
1194 .is_some()
1195 {
1196 // A host-side post_vm / post_vm_unconditional callback
1197 // failed. This is a real regression that must surface
1198 // regardless of expect_err / expect_auto_repro inversion —
1199 // those invert a GUEST-side expected failure, but a
1200 // HOST-side check is always honored. Positioned AFTER the
1201 // resource-contention / topology skip guards (a skip means
1202 // the test never ran, so there was no host-side state to
1203 // assert) but BEFORE the ExpectAutoReproSatisfied and
1204 // expect_err inversion guards so the host-side regression
1205 // wins. `downcast_ref` walks the anyhow context+source
1206 // chain (the marker rides as `.context(...)` from
1207 // run_ktstr_test_inner_impl); a raw `chain().any(is::<C>())`
1208 // would miss it (anyhow boxes context as ContextError<C,E>).
1209 eprintln!("{e:#}");
1210 return EXIT_FAIL;
1211 }
1212 if e.downcast_ref::<crate::test_support::eval::SchedulerBuildRefused>()
1213 .is_some()
1214 {
1215 // A Discover scheduler build FAILED; the resolver never falls back to
1216 // a possibly-stale pre-built binary — a scheduler that cannot be built
1217 // is a failed test. A host-side build-infra fault: always EXIT_FAIL,
1218 // never inverted by expect_err (mirrors PostVmAssertionFailure above):
1219 // an expect_err test must not let a broken build masquerade as the
1220 // guest-side expected failure.
1221 eprintln!("{e:#}");
1222 return EXIT_FAIL;
1223 }
1224 if e.downcast_ref::<crate::test_support::eval::SurvivesStormViolated>()
1225 .is_some()
1226 {
1227 // The marker rides ONLY when `entry.survives_storm` was set AND the
1228 // failure cause was a scheduler death (see
1229 // `render_failure_verdict_message`), so its presence alone proves the
1230 // survival assertion was violated — no `survives_storm` param needed
1231 // (mirrors the marker-presence arms for PostVmAssertionFailure /
1232 // SchedulerBuildRefused / ExpectAutoReproSatisfied below). Force
1233 // EXIT_FAIL with a survival-specific explainer. Positioned AFTER the
1234 // host-insufficiency / PostVmAssertionFailure / SchedulerBuildRefused
1235 // guards (a skip or host-side fault still dominates) but BEFORE the
1236 // ExpectAutoReproSatisfied and expect_err inversion arms so a survival
1237 // violation can never be inverted to PASS (defense-in-depth: the
1238 // validate-time survives_storm/expect_err mutex already forbids that
1239 // pairing). `downcast_ref` walks the anyhow context chain (the marker
1240 // rides as `.context(...)`).
1241 eprintln!(
1242 "ktstr: FAIL: survives_storm asserted but the scheduler did not \
1243 survive the run:\n{e:#}"
1244 );
1245 return EXIT_FAIL;
1246 }
1247 if e.downcast_ref::<crate::test_support::eval::ExpectAutoReproSatisfied>()
1248 .is_some()
1249 {
1250 // `expect_auto_repro = true` was satisfied: the primary
1251 // VM produced a Fail AND the auto-repro VM landed a
1252 // shape-valid `.repro.wprof.pb`. The eval layer attached
1253 // the marker as `anyhow::Context`. `downcast_ref` walks
1254 // the anyhow context+source chain (per anyhow's
1255 // documentation: "For errors with context, this method
1256 // returns true if E matches the type of the context C or
1257 // the type of the error on which the context has been
1258 // attached"). A `chain().any(|c| c.is::<E>())` walk on
1259 // the raw `&dyn StdError` chain would MISS the marker
1260 // because anyhow boxes context as `ContextError<C, E>`
1261 // whose underlying `is::<C>()` check returns false. The
1262 // diagnostic is printed so the operator sees both the
1263 // original failure trail and the inversion notice — the
1264 // verdict flips to PASS without erasing the failure
1265 // detail. Positioned AFTER the ResourceContention /
1266 // TopologyInsufficient guards so a skip-class outcome still
1267 // wins over inversion (a skip is a skip regardless of the
1268 // satisfaction signal). The macro-parse cross-attribute
1269 // check rejects `expect_auto_repro` combined with
1270 // `expect_err`, so the two inversion paths are mutually
1271 // exclusive at the entry layer.
1272 eprintln!("{e:#}");
1273 return EXIT_PASS;
1274 }
1275 if expect_err {
1276 // expect_err inverts a failure into a pass — UNLESS the
1277 // failure carries the
1278 // [`crate::test_support::eval::ScxBpfErrorMatcherMismatch`]
1279 // marker, which signals that the reproducer's scx_bpf_error
1280 // matcher rejected this particular failure. A matcher-
1281 // mismatch failure must surface even when expect_err = true:
1282 // the user authored the matcher to pin THIS specific bug,
1283 // and a different bug firing is itself a regression.
1284 //
1285 // `downcast_ref` walks the anyhow context+source chain
1286 // (anyhow's documented "For errors with context, this
1287 // method returns true if E matches the type of the context
1288 // C or the type of the error on which the context has been
1289 // attached" semantics). A `chain().any(|c| c.is::<E>())`
1290 // walk on the raw `&dyn StdError` chain would MISS the
1291 // marker because anyhow boxes context as
1292 // `ContextError<C, E>` whose underlying `is::<C>()` check
1293 // returns false.
1294 if e.downcast_ref::<crate::test_support::eval::ScxBpfErrorMatcherMismatch>()
1295 .is_some()
1296 {
1297 eprintln!("{e:#}");
1298 return EXIT_FAIL;
1299 } else {
1300 return EXIT_PASS;
1301 }
1302 }
1303 // Catch-all: a non-host-class, non-marker, non-expect_err error is a
1304 // real failure. (A KernelUnavailable does NOT reach here — it is a
1305 // skip-class host-insufficiency handled by the classify_host_error match
1306 // at the top.)
1307 eprintln!("{e:#}");
1308 EXIT_FAIL
1309}
1310
1311/// The final test verdict — the 4-state lattice `Fail > Inconclusive >
1312/// Pass > Skip` that [`result_to_exit_code`] projects to a process exit
1313/// code. Distinct from the exit code because the exit code collapses
1314/// `Skip` into [`EXIT_PASS`]; the sidecar finalize ([`final_outcome`])
1315/// needs all four to set the persisted `passed`/`skipped`/`inconclusive`
1316/// bits to the POST-inversion outcome.
1317#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1318pub(crate) enum Verdict {
1319 Pass,
1320 Fail,
1321 Skip,
1322 Inconclusive,
1323}
1324
1325impl Verdict {
1326 /// Project to the process exit code, matching the
1327 /// `EXIT_PASS`/`EXIT_FAIL`/`EXIT_INCONCLUSIVE` mapping
1328 /// [`result_to_exit_code`] produces (Skip degenerates to
1329 /// [`EXIT_PASS`]). Test-only: the anti-drift truth-table test
1330 /// (`final_outcome_projects_to_result_to_exit_code`) is its sole
1331 /// caller — production reads the [`Verdict`] directly via
1332 /// [`Verdict::sidecar_bits`].
1333 #[cfg(test)]
1334 pub(crate) fn to_exit_code(self) -> i32 {
1335 match self {
1336 Verdict::Pass | Verdict::Skip => EXIT_PASS,
1337 Verdict::Fail => EXIT_FAIL,
1338 Verdict::Inconclusive => EXIT_INCONCLUSIVE,
1339 }
1340 }
1341
1342 /// The persisted-sidecar verdict bits `(passed, skipped,
1343 /// inconclusive)` for this outcome. `Fail` is all-false (the
1344 /// [`crate::test_support::SidecarResult::is_fail`] "none set"
1345 /// encoding). Lets the sidecar finalize record the final verdict
1346 /// without [`crate::test_support::sidecar`] depending on this enum.
1347 pub(crate) fn sidecar_bits(self) -> (bool, bool, bool) {
1348 match self {
1349 Verdict::Pass => (true, false, false),
1350 Verdict::Skip => (false, true, false),
1351 Verdict::Inconclusive => (false, false, true),
1352 Verdict::Fail => (false, false, false),
1353 }
1354 }
1355}
1356
1357/// Classify a test result into the final [`Verdict`] — the same
1358/// classification [`result_to_exit_code`] performs, as a 4-state value
1359/// (it does not collapse `Skip` into `Pass` the way the exit code does)
1360/// and WITHOUT the operator-facing `eprintln` diagnostics.
1361///
1362/// Used to record the FINAL (post-`expect_err` / post-marker) outcome on
1363/// the sidecar so the footer, `stats` analysis, and `replay` reflect the
1364/// test's real pass/fail (matching nextest's exit code) rather than the
1365/// raw scenario verdict written mid-run.
1366///
1367/// MUST stay in lockstep with [`result_to_exit_code`]: the truth-table
1368/// test `final_outcome_projects_to_result_to_exit_code` asserts
1369/// `final_outcome(...).to_exit_code() == result_to_exit_code(...)` over a
1370/// matrix including the marker-carrying error arms, so the two cannot
1371/// drift. The arm order mirrors [`ok_to_exit_code`] / [`err_to_exit_code`]
1372/// first-match precedence exactly.
1373pub(crate) fn final_outcome(
1374 result: &Result<AssertResult>,
1375 expect_err: bool,
1376 allow_inconclusive: bool,
1377) -> Verdict {
1378 let no_skip = std::env::var_os(crate::KTSTR_NO_SKIP_MODE_ENV).is_some();
1379 match result {
1380 Ok(r) => {
1381 if r.is_skip() {
1382 return Verdict::Skip;
1383 }
1384 if expect_err {
1385 // expect_err on an Ok result is always a failure
1386 // (expected an error, got a non-error verdict) — both the
1387 // Pass and Inconclusive arms of ok_to_exit_code map here.
1388 return Verdict::Fail;
1389 }
1390 if r.is_inconclusive() {
1391 return if allow_inconclusive {
1392 Verdict::Pass
1393 } else {
1394 Verdict::Inconclusive
1395 };
1396 }
1397 Verdict::Pass
1398 }
1399 Err(e) => {
1400 if crate::test_support::is_framework_infrastructure_failure(e) {
1401 return Verdict::Fail;
1402 }
1403 match classify_host_error(e, no_skip) {
1404 HostClass::Skip { .. } => return Verdict::Skip,
1405 HostClass::Fail { .. } => return Verdict::Fail,
1406 HostClass::NotHostClass => {}
1407 }
1408 if e.downcast_ref::<crate::test_support::eval::PostVmAssertionFailure>()
1409 .is_some()
1410 {
1411 return Verdict::Fail;
1412 }
1413 if e.downcast_ref::<crate::test_support::eval::SchedulerBuildRefused>()
1414 .is_some()
1415 {
1416 return Verdict::Fail;
1417 }
1418 if e.downcast_ref::<crate::test_support::eval::SurvivesStormViolated>()
1419 .is_some()
1420 {
1421 // Lockstep with err_to_exit_code's SurvivesStormViolated arm
1422 // (same position: after SchedulerBuildRefused, before
1423 // ExpectAutoReproSatisfied / expect_err) so the persisted
1424 // sidecar verdict matches the exit code for a survival
1425 // violation — including the defense-in-depth bypass case
1426 // (marker + expect_err) the mutex normally forbids.
1427 return Verdict::Fail;
1428 }
1429 if e.downcast_ref::<crate::test_support::eval::ExpectAutoReproSatisfied>()
1430 .is_some()
1431 {
1432 return Verdict::Pass;
1433 }
1434 if expect_err {
1435 if e.downcast_ref::<crate::test_support::eval::ScxBpfErrorMatcherMismatch>()
1436 .is_some()
1437 {
1438 return Verdict::Fail;
1439 }
1440 return Verdict::Pass;
1441 }
1442 Verdict::Fail
1443 }
1444 }
1445}
1446
1447/// Whether a base test entry is "ignored" (skipped by default).
1448///
1449/// Entries declared with `#[ktstr_test(ignore)]` carry `ignored = true` from
1450/// macro codegen. Tests whose names start with `demo_` are also ignored --
1451/// they are demonstration/benchmarking tests that require manual opt-in.
1452fn is_ignored(entry: &KtstrTestEntry) -> bool {
1453 entry.ignored || entry.name.starts_with("demo_")
1454}
1455
1456/// Walk [`KTSTR_TESTS`] once per process and emit a stderr
1457/// `warning:` line for every duplicate `name` found.
1458///
1459/// Two entries with the same name would both match `find_test(name)`
1460/// (which returns the FIRST match), so the second registration is
1461/// silently shadowed — `cargo ktstr` would dispatch the first entry
1462/// and the second entry's body would never run, with no diagnostic
1463/// surfaced. The warning surfaces the collision so an operator can
1464/// rename one of the `#[ktstr_test]` functions; discovery itself
1465/// proceeds (find_test's first-wins behavior continues) so nextest's
1466/// `--list` output still lands in stdout. A panic here would abort
1467/// the whole listing — nextest would see no tests at all rather
1468/// than a partial set with a clear warning. The first-wins
1469/// shadowing remains a real bug, but the diagnostic is louder than
1470/// silence and the tradeoff (operator sees the warning AND a
1471/// usable test list) beats the alternative (operator sees a
1472/// panic backtrace and no test list).
1473///
1474/// `OnceLock<()>` gates the walk to fire EXACTLY ONCE per process:
1475/// every gauntlet variant resolves through `list_tests` (under
1476/// nextest's discovery and budget paths), so without the gate a
1477/// run with N variants would re-walk the slice N times and emit
1478/// the same warning N times. Each duplicate name surfaces exactly
1479/// once via the inner `seen`/`warned` HashSet pair so a
1480/// triple-collision (three entries sharing one name) does not
1481/// double-print the warning.
1482///
1483/// The pure detection logic lives in
1484/// [`warn_duplicate_test_names_inner`] so the duplicate-walker
1485/// is testable without process-wide global state. This wrapper
1486/// only owns the `OnceLock<()>` gate and the
1487/// `(KTSTR_TESTS, stderr)` plumbing.
1488fn warn_duplicate_test_names_once() {
1489 static CHECKED: std::sync::OnceLock<()> = std::sync::OnceLock::new();
1490 CHECKED.get_or_init(|| {
1491 warn_duplicate_test_names_inner(KTSTR_TESTS.iter().map(|e| e.name), &mut std::io::stderr());
1492 });
1493}
1494
1495/// Pure walker behind [`warn_duplicate_test_names_once`]: walks
1496/// the test-name iterator and emits one `warning:` line per
1497/// duplicate name to `sink`. Each duplicate name surfaces
1498/// exactly once (a triple-collision does NOT double-print)
1499/// via the inner `warned` HashSet.
1500///
1501/// Extracted from the OnceLock-gated wrapper so the duplicate
1502/// detection logic is testable without process-wide global
1503/// state — the wrapper handles "fire once per process" via its
1504/// own `OnceLock<()>` gate; this inner is a pure function over
1505/// `(names, sink)`. The wrapper passes
1506/// `KTSTR_TESTS.iter().map(|e| e.name)` as the iterator and
1507/// `std::io::stderr()` as the sink.
1508///
1509/// `Result<(), std::io::Error>` is collapsed to ignore-on-write
1510/// because the production wrapper writes to stderr where IO
1511/// errors are unrecoverable; tests pass a `Vec<u8>` sink which
1512/// never errors. The function name says "warn" — diagnostic
1513/// channel — and matches the wrapper's pre-existing
1514/// `eprintln!` semantics.
1515fn warn_duplicate_test_names_inner<'a, W: std::io::Write>(
1516 names: impl IntoIterator<Item = &'a str>,
1517 sink: &mut W,
1518) {
1519 use std::collections::HashSet;
1520 let names: Vec<&'a str> = names.into_iter().collect();
1521 let mut seen: HashSet<&'a str> = HashSet::with_capacity(names.len());
1522 let mut warned: HashSet<&'a str> = HashSet::new();
1523 for name in names {
1524 if !seen.insert(name) && warned.insert(name) {
1525 let _ = writeln!(
1526 sink,
1527 "warning: ktstr_test: duplicate test name {name:?} registered in KTSTR_TESTS — \
1528 two `#[ktstr_test]` entries share this name; the SECOND entry is \
1529 silently shadowed (find_test returns the first registration). \
1530 rename one of the functions to disambiguate.",
1531 );
1532 }
1533 }
1534}
1535
1536/// Collect test names for nextest discovery (--list --format terse).
1537///
1538/// Nextest calls the binary twice:
1539/// - Without `--ignored`: prints ALL tests (ignored and non-ignored).
1540/// - With `--ignored`: prints ONLY ignored tests.
1541///
1542/// Gauntlet variants are always ignored. Base tests are ignored when their
1543/// registered entry carries `ignored = true` or their name starts with
1544/// `demo_`.
1545///
1546/// When `KTSTR_BUDGET_SECS` is set, applies greedy coverage maximization
1547/// to select the subset of tests that maximizes feature coverage within
1548/// the time budget. Only selected tests are printed.
1549///
1550/// Calls [`warn_duplicate_test_names_once`] on the first invocation per
1551/// process so duplicate registrations surface a stderr `warning:`
1552/// line BEFORE any test name is printed (discovery itself proceeds
1553/// — find_test's first-wins behavior continues, but the operator
1554/// sees which name collided). Subsequent invocations are no-ops via
1555/// the inner `OnceLock` gate.
1556fn list_tests(ignored_only: bool) {
1557 warn_duplicate_test_names_once();
1558 let raw = std::env::var(crate::KTSTR_BUDGET_SECS_ENV).ok();
1559 let budget_secs: Option<f64> = raw.as_deref().and_then(|s| match s.parse::<f64>() {
1560 Ok(v) if v > 0.0 => Some(v),
1561 Ok(v) => {
1562 eprintln!("ktstr_test: KTSTR_BUDGET_SECS={v}: must be positive, ignoring");
1563 None
1564 }
1565 Err(e) => {
1566 eprintln!("ktstr_test: KTSTR_BUDGET_SECS={s:?}: {e}, ignoring");
1567 None
1568 }
1569 });
1570
1571 if let Some(budget) = budget_secs {
1572 list_tests_budget(ignored_only, budget);
1573 } else {
1574 list_tests_all(ignored_only);
1575 }
1576}
1577
1578/// Iterate topology presets that both fit the host capacity and
1579/// match the entry's `TopologyConstraints`. Shared between the
1580/// eager ("print every name") and budgeted ("push a candidate")
1581/// listers in `list_tests_*`.
1582fn for_each_gauntlet_variant<F>(
1583 entry: &KtstrTestEntry,
1584 presets: &[crate::gauntlet::TopoPreset],
1585 host_cpus: u32,
1586 host_llcs: u32,
1587 host_max_cpus_per_llc: u32,
1588 mut visit: F,
1589) where
1590 F: FnMut(&crate::gauntlet::TopoPreset),
1591{
1592 let no_perf_mode = super::runtime::no_perf_mode_for_entry(entry);
1593 for preset in presets {
1594 // Non-uniform presets (per-LLC core counts, e.g. 192cpu-11llc-smt)
1595 // are VERIFIER-ONLY: the gauntlet execution path reconstructs the
1596 // topology from a `TopoOverride` (numa/llcs/cores/threads only),
1597 // which cannot carry `llc_cores`, so a gauntlet variant would boot
1598 // a WRONG uniform shape. The verifier path passes the full
1599 // Topology (with llc_cores) directly, so it is the only path that
1600 // renders these shapes faithfully. Skip them here regardless of
1601 // constraints — this is why 192cpu-11llc-smt's forced overcommit is
1602 // realized only in the verifier battery.
1603 if preset.topology.llc_cores.is_some() {
1604 continue;
1605 }
1606 // No-perf-mode tests run KVM-emulated topology — guest sees the
1607 // declared NUMA / LLC / per-LLC layout regardless of host
1608 // hardware — so the host-side LLC count and per-LLC CPU width
1609 // do not constrain preset eligibility. Only the total-CPU
1610 // budget survives.
1611 let accepted = if no_perf_mode {
1612 entry
1613 .constraints
1614 .accepts_no_perf_mode(&preset.topology, host_cpus)
1615 } else {
1616 entry.constraints.accepts(
1617 &preset.topology,
1618 host_cpus,
1619 host_llcs,
1620 host_max_cpus_per_llc,
1621 )
1622 };
1623 if !accepted {
1624 continue;
1625 }
1626 visit(preset);
1627 }
1628}
1629
1630/// List all tests without budget filtering.
1631///
1632/// When `KTSTR_KERNEL_LIST` carries 2 or more entries, every test
1633/// name carries an extra `/{sanitized_kernel_label}` suffix so each
1634/// (test × kernel) pair becomes a distinct nextest test case;
1635/// nextest's parallelism, retries, and `-E` filtering all apply
1636/// natively. Single-kernel mode (0 or 1 entries) emits the
1637/// `gauntlet/{name}/{preset}` shape with no kernel suffix.
1638///
1639/// `KTSTR_CARGO_TEST_MODE=1` skips gauntlet variant emission and
1640/// the multi-kernel suffix path: each test gets exactly one
1641/// `ktstr/{name}: test` line for VM tests or `host/{name}: test` for
1642/// host-only tests. Bare `cargo test` doesn't have
1643/// access to the cargo-ktstr resolver that produces
1644/// `KTSTR_KERNEL_LIST`, so the multi-kernel branch can't apply
1645/// even if it were enabled — pin both behaviors explicitly so
1646/// the listing matches what the dispatch path will actually run.
1647fn list_tests_all(ignored_only: bool) {
1648 let cargo_test_mode = crate::cargo_test_mode::cargo_test_mode_active();
1649 let presets = crate::gauntlet::gauntlet_presets();
1650 let has_vmlinux = resolve_test_kernel()
1651 .ok()
1652 .and_then(|k| crate::vmm::find_vmlinux(&k))
1653 .is_some();
1654 let (host_cpus, host_llcs, host_max_cpus_per_llc) = super::host_capacity();
1655
1656 let kernel_list = read_kernel_list();
1657 let multi_kernel = kernel_list.len() > 1 && !cargo_test_mode;
1658 // Single-kernel mode (no list, or list has exactly one entry)
1659 // emits one variant per (test × preset) tuple with no kernel
1660 // suffix. Multi-kernel mode iterates every kernel as an outer
1661 // loop and appends `/{sanitized}` per variant. The empty-suffix
1662 // sentinel below is what the single-kernel branch passes to keep
1663 // the print path uniform.
1664 let kernel_suffixes: Vec<&str> = if multi_kernel {
1665 kernel_list.iter().map(|k| k.sanitized.as_str()).collect()
1666 } else {
1667 vec![""]
1668 };
1669
1670 for entry in KTSTR_TESTS.iter() {
1671 // Unit-test sentinel fixtures (`__unit_test_*__`) exist only to be
1672 // dispatched directly by lib unit tests (run_named_test / ELF stamp
1673 // readers). Listing them would boot real VM cells for stub bodies —
1674 // the perf-mode fixtures then face the perf isolation gate on hosts
1675 // where nothing meaningful is being measured.
1676 if is_test_sentinel(entry.name) {
1677 continue;
1678 }
1679 // bpf_map_write tests require vmlinux to resolve BPF map
1680 // addresses. Don't list them when vmlinux is unavailable —
1681 // they cannot run and would produce false PASS results.
1682 if !entry.bpf_map_write.is_empty() && !has_vmlinux {
1683 continue;
1684 }
1685
1686 if !ignored_only || is_ignored(entry) {
1687 if entry.host_only {
1688 println!("host/{}: test", entry.name);
1689 } else {
1690 for suffix in &kernel_suffixes {
1691 if suffix.is_empty() {
1692 println!("ktstr/{}: test", entry.name);
1693 } else {
1694 println!("ktstr/{}/{suffix}: test", entry.name);
1695 }
1696 }
1697 }
1698 }
1699
1700 // Host-only tests run on the host without a VM -- gauntlet
1701 // topology variants are meaningless.
1702 if entry.host_only {
1703 continue;
1704 }
1705
1706 // KTSTR_CARGO_TEST_MODE: skip gauntlet expansion. The
1707 // operator picked the bare-`cargo test` path; emit only
1708 // the base name so each `#[ktstr_test]` runs once with its
1709 // declared topology.
1710 if cargo_test_mode {
1711 continue;
1712 }
1713
1714 // Gauntlet variants are always ignored — users opt in with
1715 // --run-ignored. Presets that exceed the host's CPU count or
1716 // LLC count are filtered from the listing entirely.
1717 for_each_gauntlet_variant(
1718 entry,
1719 &presets,
1720 host_cpus,
1721 host_llcs,
1722 host_max_cpus_per_llc,
1723 |preset| {
1724 for suffix in &kernel_suffixes {
1725 if suffix.is_empty() {
1726 println!("gauntlet/{}/{}: test", entry.name, preset.name);
1727 } else {
1728 println!("gauntlet/{}/{}/{suffix}: test", entry.name, preset.name,);
1729 }
1730 }
1731 },
1732 );
1733 }
1734}
1735
1736/// True iff the given operator-resolved kernel `entry` matches one
1737/// of the `declared` kernel specs from a scheduler's
1738/// `declare_scheduler!` `kernels = [...]` declaration. Empty
1739/// `declared` accepts every entry (no per-scheduler filter).
1740///
1741/// Match semantics per spec variant (via [`crate::kernel_path::KernelId::parse`]):
1742/// - [`crate::kernel_path::KernelId::Version`]: raw-label string equality OR sanitized-label match
1743/// ([`sanitize_kernel_label`] of the spec string equals the entry's
1744/// sanitized label). Direct match catches the common case where
1745/// the dispatcher resolved `--kernel 6.14.2` and the scheduler
1746/// declared `kernels = ["6.14.2"]`.
1747/// - [`crate::kernel_path::KernelId::Range`]: range-membership check on the entry's raw
1748/// label via [`crate::kernel_path::decompose_version_for_compare`].
1749/// Lets schedulers declaring `kernels = ["6.14..6.16"]` match
1750/// any operator-supplied kernel whose version falls in
1751/// `[6.14, 6.16]` inclusive.
1752/// - [`crate::kernel_path::KernelId::Path`] / [`crate::kernel_path::KernelId::CacheKey`] / [`crate::kernel_path::KernelId::Git`]:
1753/// sanitized-label equality — the producer-side encoder
1754/// (`src/bin/cargo_ktstr/kernel/wire_format.rs`) emits a deterministic
1755/// label per variant (`path_…`, `git_owner_repo_kind_ref`, version
1756/// prefix from cache key), so identical specs on both sides
1757/// produce identical sanitized labels.
1758///
1759/// [`KernelId`]: crate::kernel_path::KernelId
1760#[cfg(test)]
1761fn sched_kernel_filter_accepts(declared: &[&'static str], entry: &KernelEntry) -> bool {
1762 super::entry::verifier_kernel_specs_accept(
1763 declared.iter().copied(),
1764 &entry.label,
1765 entry.sanitized.as_str(),
1766 )
1767}
1768
1769/// Single-spec match helper for [`sched_kernel_filter_accepts`].
1770/// Parses `spec` via [`crate::kernel_path::KernelId::parse`] and
1771/// dispatches on the variant. Pure logic — no network, no FS.
1772#[cfg(test)]
1773fn entry_matches_spec(entry: &KernelEntry, spec: &str) -> bool {
1774 super::entry::verifier_kernel_specs_accept(
1775 std::iter::once(spec),
1776 &entry.label,
1777 entry.sanitized.as_str(),
1778 )
1779}
1780
1781/// Format the `KTSTR_KERNEL_LIST is empty` diagnostic emitted by
1782/// [`run_verifier_cell`] when a verifier cell name reaches the cell
1783/// handler with no kernel-list to look the label up in. Extracted
1784/// from the inline eprintln! so the exact wording can be pinned in
1785/// unit tests without spawning a process.
1786fn format_empty_kernel_list_error(full_name: &str) -> String {
1787 format!(
1788 "ktstr verifier: cell {full_name}: KTSTR_KERNEL_LIST is empty. \
1789 Direct `--exact verifier/...` invocation outside `cargo ktstr verifier` \
1790 is not supported — the dispatcher owns kernel-set resolution. Run \
1791 `cargo ktstr verifier [--kernel SPEC]` instead.",
1792 )
1793}
1794
1795/// Format the "kernel label not in KTSTR_KERNEL_LIST" diagnostic.
1796/// `present` is the slice of sanitized labels actually present in
1797/// the list, in their KTSTR_KERNEL_LIST ordering. Extracted for the
1798/// same reason as [`format_empty_kernel_list_error`].
1799fn format_unknown_kernel_label_error(
1800 full_name: &str,
1801 kernel_label: &str,
1802 sched_name: &str,
1803 present: &[&str],
1804) -> String {
1805 format!(
1806 "ktstr verifier: cell {full_name}: kernel label {kernel_label:?} \
1807 not in KTSTR_KERNEL_LIST. Present labels: [{}]. \
1808 Either add --kernel <SPEC> to the dispatcher invocation so it \
1809 resolves into this label, or remove the matching entry from \
1810 declare_scheduler!(... kernels = [...]) for {sched_name}.",
1811 present.join(", "),
1812 )
1813}
1814
1815/// The set of PACKAGE names in the workspace rooted at `manifest_dir`,
1816/// queried once per dir via `cargo metadata`. [`list_verifier_cells_all`]
1817/// uses it to skip `declare_scheduler!` decls whose `Discover(pkg)` is
1818/// not a real member of the DECLARING crate's workspace — the
1819/// macro-expansion FIXTURES in tests/declare_scheduler.rs register into
1820/// `KTSTR_SCHEDULERS` but name packages that are not members of ktstr's
1821/// own workspace, so their cells must not be emitted.
1822///
1823/// `cargo metadata --no-deps` is the authoritative answer to "which
1824/// packages live in this workspace": it resolves glob members like
1825/// `"scheds/rust/*"` (which scx uses) and package-name≠dir-name renames
1826/// that a hand-parse of `[workspace] members` would miss.
1827///
1828/// Memoized per `manifest_dir` (the value is `Box::leak`ed to `'static`).
1829/// On `cargo metadata` failure the returned set is EMPTY (every
1830/// `Discover` cell in that workspace is then skipped) and a one-time
1831/// warning is emitted to stderr, matching the diagnostic style of the
1832/// surrounding lister code.
1833fn workspace_member_packages(manifest_dir: &str) -> &'static std::collections::HashSet<String> {
1834 use std::collections::HashMap;
1835 use std::sync::Mutex;
1836 use std::sync::OnceLock;
1837 static CACHE: OnceLock<Mutex<HashMap<String, &'static std::collections::HashSet<String>>>> =
1838 OnceLock::new();
1839 let cache = CACHE.get_or_init(|| Mutex::new(HashMap::new()));
1840 let mut guard = cache.lock().unwrap_or_else(|e| e.into_inner());
1841 if let Some(set) = guard.get(manifest_dir) {
1842 return set;
1843 }
1844 let set: &'static std::collections::HashSet<String> =
1845 Box::leak(Box::new(query_workspace_member_packages(manifest_dir)));
1846 guard.insert(manifest_dir.to_string(), set);
1847 set
1848}
1849
1850/// Run `cargo metadata --no-deps` against `<manifest_dir>/Cargo.toml` and
1851/// collect the `packages[].name` set. Returns an EMPTY set (with a
1852/// one-time stderr warning) when cargo cannot be spawned, exits non-zero,
1853/// or emits JSON the walker cannot parse — every `Discover` cell rooted
1854/// in that workspace is then gated out rather than emitted for a package
1855/// the runtime resolver could not build.
1856fn query_workspace_member_packages(manifest_dir: &str) -> std::collections::HashSet<String> {
1857 let manifest_path = crate::writable_source_path(manifest_dir).join("Cargo.toml");
1858 let output = std::process::Command::new("cargo")
1859 .args(["metadata", "--no-deps", "--format-version", "1"])
1860 .arg("--manifest-path")
1861 .arg(&manifest_path)
1862 .stdout(std::process::Stdio::piped())
1863 .stderr(std::process::Stdio::piped())
1864 .output();
1865 let output = match output {
1866 Ok(o) if o.status.success() => o,
1867 Ok(o) => {
1868 eprintln!(
1869 "ktstr verifier: `cargo metadata` for {} failed ({}); \
1870 skipping this workspace's Discover schedulers:\n{}",
1871 manifest_path.display(),
1872 o.status,
1873 String::from_utf8_lossy(&o.stderr).trim(),
1874 );
1875 return std::collections::HashSet::new();
1876 }
1877 Err(e) => {
1878 eprintln!(
1879 "ktstr verifier: could not run `cargo metadata` for {} ({e}); \
1880 skipping this workspace's Discover schedulers",
1881 manifest_path.display(),
1882 );
1883 return std::collections::HashSet::new();
1884 }
1885 };
1886 let Ok(meta) = serde_json::from_slice::<serde_json::Value>(&output.stdout) else {
1887 eprintln!(
1888 "ktstr verifier: `cargo metadata` for {} produced unparsable JSON; \
1889 skipping this workspace's Discover schedulers",
1890 manifest_path.display(),
1891 );
1892 return std::collections::HashSet::new();
1893 };
1894 meta.get("packages")
1895 .and_then(|p| p.as_array())
1896 .into_iter()
1897 .flatten()
1898 .filter_map(|pkg| pkg.get("name").and_then(|n| n.as_str()))
1899 .map(|s| s.to_string())
1900 .collect()
1901}
1902
1903fn claim_verifier_scheduler_name<'a>(
1904 emitted: &mut std::collections::HashSet<&'a str>,
1905 name: &'a str,
1906) -> bool {
1907 emitted.insert(name)
1908}
1909
1910/// Emit `verifier/<sched>/<kernel>/<preset>: test` lines — one per
1911/// (declared scheduler × kernel-list entry × accepted topology preset)
1912/// cell. Mirrors the gauntlet emission pattern in [`list_tests_all`] but
1913/// walks [`super::KTSTR_SCHEDULERS`] instead of [`KTSTR_TESTS`]. The
1914/// verifier sweeps each declared scheduler ACROSS topologies, because
1915/// attach/liveness is topology-dependent (a scheduler can attach on one
1916/// topology and wedge on another). Cells are paired with the
1917/// [`run_verifier_cell`] handler registered in
1918/// [`ktstr_test_early_dispatch`]'s `--exact verifier/...` branch.
1919///
1920/// The matrix dimension is `KTSTR_KERNEL_LIST` (always populated by the
1921/// `cargo ktstr verifier` dispatcher — even with a single
1922/// auto-discovered kernel, the dispatcher synthesizes a one-entry list
1923/// with a derived label). Each scheduler's `declare_scheduler!`
1924/// `kernels = [...]` declaration acts as a per-scheduler filter on the
1925/// matrix — `Version` / `Range` declarations match entries by
1926/// raw-label equality / range membership; `Path` / `CacheKey` / `Git`
1927/// declarations match by sanitized-label equality. An empty
1928/// `kernels = []` declaration accepts every entry in the list.
1929///
1930/// The topology dimension is [`crate::gauntlet::gauntlet_presets`], gated
1931/// per scheduler: the verifier VM always runs no_perf_mode, so a preset
1932/// is emitted only when the scheduler's constraints accept it under
1933/// [`super::TopologyConstraints::accepts_verifier`] — the verifier-only
1934/// gate that ignores DEFAULT caps (so an untouched scheduler reaches the
1935/// beyond-host battery shapes) and imposes NO host-size bound for the
1936/// correctness-only verify cells. A scheduler that accepts no preset
1937/// emits no cell.
1938///
1939/// After structural constraints, the scheduler's
1940/// [`super::Scheduler::verifier_exclude_topologies`] list removes exact
1941/// preset-name matches. This named exception applies only to verifier
1942/// cells; ordinary gauntlet variants are unaffected.
1943///
1944/// Schedulers declared with [`super::SchedulerSpec::Eevdf`] or
1945/// [`super::SchedulerSpec::KernelBuiltin`] are skipped at emission time
1946/// because neither has a userspace binary to load BPF programs from.
1947///
1948/// When [`crate::KTSTR_VERIFIER_SCHEDULER_ENV`] is set (the
1949/// `cargo ktstr verifier --scheduler <NAME>` filter), every declared
1950/// scheduler whose `name` does not equal the value is skipped, so the
1951/// sweep covers one scheduler across topologies instead of the full
1952/// declared-scheduler matrix. A value matching no declared scheduler
1953/// (or a non-BPF one) emits no cell; the dispatcher reports the empty
1954/// result set rather than silently sweeping nothing.
1955///
1956/// Cell names with `/` in `sched.name` or `preset.name` would corrupt
1957/// the splitn-based parse in [`run_verifier_cell`]; the emission elides
1958/// such cells with a stderr warning. When `KTSTR_KERNEL_LIST` is absent
1959/// (direct binary invocation outside the dispatcher), no cells emit.
1960fn list_verifier_cells_all() {
1961 use super::SchedulerSpec;
1962 let cell_ownership = match crate::verifier::verifier_cell_ownership_from_env() {
1963 Ok(ownership) => ownership,
1964 Err(error) => {
1965 eprintln!("ktstr verifier: cannot establish cell ownership while listing: {error:#}");
1966 std::process::exit(1);
1967 }
1968 };
1969 let kernel_list = read_kernel_list();
1970 if kernel_list.is_empty() {
1971 return;
1972 }
1973 let presets = crate::gauntlet::gauntlet_presets();
1974 let mut emitted_scheduler_names = std::collections::HashSet::new();
1975 // No host_capacity() read here: verifier preset selection has no
1976 // host-size bound (see accepts_verifier) — a battery shape lists on
1977 // any host regardless of CPU count.
1978
1979 // `cargo ktstr verifier --scheduler <NAME>` filter (via
1980 // KTSTR_VERIFIER_SCHEDULER): when set, sweep only the named declared
1981 // scheduler across topologies instead of the full declared-scheduler
1982 // matrix. Read once; unset (or non-unicode) leaves the sweep full.
1983 let scheduler_filter = std::env::var(crate::KTSTR_VERIFIER_SCHEDULER_ENV).ok();
1984
1985 for sched in super::KTSTR_SCHEDULERS.iter() {
1986 if let Some(want) = &scheduler_filter
1987 && sched.name != want.as_str()
1988 {
1989 continue;
1990 }
1991 if matches!(
1992 sched.binary,
1993 SchedulerSpec::Eevdf | SchedulerSpec::KernelBuiltin { .. }
1994 ) {
1995 continue;
1996 }
1997 if sched.name.contains('/') {
1998 eprintln!(
1999 "ktstr verifier: scheduler name {:?} contains '/' — skipping cell emission (would corrupt verifier/<sched>/<kernel>/<preset> parse)",
2000 sched.name,
2001 );
2002 continue;
2003 }
2004 // Skip declarations whose binary is not a real, buildable
2005 // scheduler. The invariant is "a cell emits iff the runtime
2006 // resolver can build it": emission checks package membership of
2007 // the DECLARING crate's workspace (via
2008 // [`workspace_member_packages`] keyed on `sched.manifest_dir`),
2009 // and the runtime resolver in `run_verifier_cell_inner` builds in
2010 // that SAME workspace with `cargo build -p <pkg>` run from
2011 // `sched.manifest_dir` — so the two stay in lockstep. The
2012 // macro-expansion FIXTURES in tests/declare_scheduler.rs
2013 // (`binary = "scx-full"`, `"scx-ee"`, …) are declared in ktstr's
2014 // own tests and name packages that are NOT members of ktstr's
2015 // workspace, so they are gated out; emitting their cells would
2016 // make `cargo ktstr verifier --run-ignored` fail on
2017 // `cargo build -p <fixture>` for a nonexistent package. A
2018 // `Discover` of a real workspace member (scx-ktstr) and a `Path`
2019 // that exists still emit.
2020 match sched.binary {
2021 SchedulerSpec::Discover(pkg)
2022 if !workspace_member_packages(sched.manifest_dir).contains(pkg) =>
2023 {
2024 continue;
2025 }
2026 SchedulerSpec::Path(p) if !std::path::Path::new(p).exists() => {
2027 continue;
2028 }
2029 _ => {}
2030 }
2031 let scheduler_json = super::SchedulerJson::from_scheduler(sched);
2032 if !scheduler_json.has_accepted_verifier_cell(
2033 kernel_list
2034 .iter()
2035 .map(|entry| (entry.label.as_str(), entry.sanitized.as_str())),
2036 &presets,
2037 ) {
2038 continue;
2039 }
2040 if let Some(ownership) = &cell_ownership {
2041 match ownership.owns_scheduler(&scheduler_json) {
2042 Ok(true) => {}
2043 Ok(false) => continue,
2044 Err(error) => {
2045 eprintln!(
2046 "ktstr verifier: cannot establish cell ownership for scheduler {:?}: \
2047 {error:#}",
2048 sched.name,
2049 );
2050 std::process::exit(1);
2051 }
2052 }
2053 }
2054 // The parent collapses exact declarations across binaries. Mirror
2055 // that identity rule inside the elected binary too: repeated links of
2056 // the same scheduler static/name still advertise one nextest cell set.
2057 if !claim_verifier_scheduler_name(&mut emitted_scheduler_names, sched.name) {
2058 continue;
2059 }
2060 for kernel_entry in &kernel_list {
2061 if !scheduler_json
2062 .accepts_verifier_kernel(&kernel_entry.label, kernel_entry.sanitized.as_str())
2063 {
2064 continue;
2065 }
2066 // One cell per (scheduler, kernel, topology preset). The
2067 // verifier sweep runs each scheduler's "does it verify,
2068 // attach, AND dispatch" check ACROSS topologies, because
2069 // both vary with topology: attach/liveness (a scheduler can
2070 // attach on one topology and wedge on another — odd LLC
2071 // counts, large CPU counts, SMT) and verified_insns (a
2072 // scheduler that bakes topology-derived config into .rodata
2073 // hands the verifier different known constants, so it
2074 // processes a different instruction count per topology). The
2075 // verifier VM always runs no_perf_mode, so preset eligibility
2076 // uses accepts_verifier: the KVM-emulated topology is gated by
2077 // the scheduler's declared scope, with DEFAULT caps treated as
2078 // "no opinion" and NO host-size bound — the correctness-only
2079 // verify cells tolerate overcommit at any ratio (storm-validated
2080 // + progress-watchdog), so beyond-host shapes always enter.
2081 for preset in presets.iter() {
2082 if preset.name.contains('/') {
2083 eprintln!(
2084 "ktstr verifier: preset name {:?} contains '/' — skipping cell (would corrupt parse)",
2085 preset.name,
2086 );
2087 continue;
2088 }
2089 if !scheduler_json.accepts_verifier_preset(preset) {
2090 continue;
2091 }
2092 println!(
2093 "verifier/{}/{}/{}: test",
2094 sched.name, kernel_entry.sanitized, preset.name,
2095 );
2096 }
2097 }
2098 }
2099}
2100
2101/// Apply the verifier-only topology policy for one scheduler/preset
2102/// pair. Kept separate from emission so named exclusions are directly
2103/// unit-testable without capturing a process-wide nextest listing.
2104#[cfg(test)]
2105fn scheduler_accepts_verifier_preset(
2106 sched: &super::Scheduler,
2107 preset: &crate::gauntlet::TopoPreset,
2108) -> bool {
2109 super::SchedulerJson::from_scheduler(sched).accepts_verifier_preset(preset)
2110}
2111
2112/// Whether a verifier-cell error is a typed guest-kernel/topology
2113/// incompatibility. Chain-aware so the collection path may add context
2114/// without turning an unsupported cell back into a scheduler failure.
2115fn is_verifier_topology_unsupported(e: &anyhow::Error) -> bool {
2116 e.chain().any(|cause| {
2117 cause
2118 .downcast_ref::<crate::verifier::VerifierTopologyUnsupported>()
2119 .is_some()
2120 })
2121}
2122
2123/// Parse `verifier/<sched_name>/<kernel_label>/<preset_name>`, look up
2124/// the declared scheduler in [`super::KTSTR_SCHEDULERS`] + the gauntlet
2125/// preset in [`crate::gauntlet::gauntlet_presets`] + the kernel in
2126/// [`KTSTR_KERNEL_LIST_ENV`](crate::KTSTR_KERNEL_LIST_ENV), resolve the
2127/// scheduler binary path per [`super::SchedulerSpec`], boot the verifier
2128/// VM on that topology via [`crate::verifier::collect_verifier_output`],
2129/// and print the rendered output. Returns 0 only when the scheduler
2130/// verified (BPF loaded), turned on (the guest attach gate reached
2131/// sched_ext `enabled`, surfaced via [`crate::verifier::AttachOutcome`]),
2132/// dispatched the injected workload while the scheduler child was live and
2133/// sched_ext remained enabled, survived to ktstr's intentional cleanup kill,
2134/// and published an explicit CRC-valid guest exit frame carrying code 0.
2135/// [`crate::verifier::VerifierVmResult::cell_verdict`] also rejects a
2136/// scheduler-exit frame, a missing terminal frame, a teardown hang
2137/// (`timed_out`), or a malformed cell name.
2138///
2139/// The per-cell kernel directory is resolved by sanitized-label
2140/// lookup in `KTSTR_KERNEL_LIST` — the
2141/// `cargo ktstr verifier` dispatcher always populates the list,
2142/// even with no `--kernel` flag (it synthesizes a single auto-
2143/// discovered entry). There is no single-kernel-mode fallback.
2144/// An unrecognised label or an absent list both surface as an
2145/// exit-1 diagnostic naming the present labels and pointing at
2146/// the dispatcher.
2147///
2148/// Eevdf + KernelBuiltin scheduler variants are filtered out at
2149/// emission time in [`list_verifier_cells_all`], so nextest
2150/// dispatch never reaches the SKIP arms in this function. The
2151/// SKIP arms remain as defense-in-depth for direct
2152/// `--exact verifier/<eevdf>/...` invocation outside nextest
2153/// (the only path that bypasses the emission-time filter); in
2154/// that case they emit a `SKIP` banner + exit 0.
2155fn run_verifier_cell_inner(
2156 full_name: &str,
2157 sched: &super::Scheduler,
2158 out_stats: &mut Vec<crate::verifier::ProgStats>,
2159 out_skipped: &mut bool,
2160) -> i32 {
2161 use super::SchedulerSpec;
2162
2163 let rest = match full_name.strip_prefix("verifier/") {
2164 Some(r) => r,
2165 None => {
2166 eprintln!("ktstr verifier: missing 'verifier/' prefix in {full_name:?}");
2167 return 1;
2168 }
2169 };
2170 let parts: Vec<&str> = rest.splitn(3, '/').collect();
2171 if parts.len() != 3 {
2172 eprintln!(
2173 "ktstr verifier: malformed cell name {full_name:?}; expected verifier/<sched>/<kernel>/<preset>",
2174 );
2175 return 1;
2176 }
2177 let (sched_name, kernel_label, preset_name) = (parts[0], parts[1], parts[2]);
2178
2179 // Emit the cell banner BEFORE every SKIP / FAIL branch so the
2180 // operator always sees which (scheduler, kernel, topology) tuple
2181 // produced the result. Without it an early-exit SKIP / FAIL would
2182 // surface as a bare error line nextest tags with the full cell name
2183 // but no per-axis context.
2184 println!("\n=== {sched_name} | kernel {kernel_label} | topology {preset_name} ===");
2185
2186 // Fail-fast on missing KVM with the canonical actionable error
2187 // (kvm group / kvm-ok hint). Without this preflight the operator
2188 // gets a deep error inside VM bring-up.
2189 if let Err(e) = crate::cli::check_kvm() {
2190 eprintln!("ktstr verifier: cell {full_name}: {e:#}");
2191 return 1;
2192 }
2193
2194 if sched.name != sched_name {
2195 eprintln!(
2196 "ktstr verifier: selected scheduler {:?} does not match cell {full_name:?}",
2197 sched.name,
2198 );
2199 return 1;
2200 }
2201
2202 // Resolve the cell's topology preset by its <preset> name segment.
2203 let preset_list = crate::gauntlet::gauntlet_presets();
2204 let Some(preset) = preset_list.iter().find(|p| p.name == preset_name) else {
2205 eprintln!("ktstr verifier: no gauntlet preset {preset_name:?} (cell {full_name:?})",);
2206 return 1;
2207 };
2208
2209 // Resolve the per-cell kernel directory by looking the cell's
2210 // sanitized label up in `KTSTR_KERNEL_LIST`. The
2211 // `cargo ktstr verifier` dispatcher always populates the list —
2212 // even with no `--kernel` flag it synthesizes a single auto-
2213 // discovered entry — so the lookup is the single source of
2214 // truth and there is no single-kernel-mode fallback that would
2215 // silently run a cell against an unrelated kernel.
2216 //
2217 // An empty list reaching this function means the test binary was
2218 // invoked outside the dispatcher (direct `--exact verifier/...`
2219 // under a hand-spawned nextest, for instance). Error with an
2220 // actionable message rather than fall through to auto-discovery.
2221 let kernel_list = read_kernel_list();
2222 let Some(kernel_entry) = kernel_list
2223 .iter()
2224 .find(|k| k.sanitized.as_str() == kernel_label)
2225 else {
2226 if kernel_list.is_empty() {
2227 eprintln!("{}", format_empty_kernel_list_error(full_name));
2228 } else {
2229 let present: Vec<&str> = kernel_list.iter().map(|k| k.sanitized.as_str()).collect();
2230 eprintln!(
2231 "{}",
2232 format_unknown_kernel_label_error(full_name, kernel_label, sched_name, &present,),
2233 );
2234 }
2235 return 1;
2236 };
2237
2238 let prebuilt = if sched.binary.has_bpf_scheduler() {
2239 match crate::scheduler_artifact::scheduler_artifact_from_env(
2240 Some(sched.name),
2241 &sched.binary,
2242 sched.manifest_dir,
2243 ) {
2244 Ok(path) => path,
2245 Err(e) => {
2246 eprintln!(
2247 "ktstr verifier: resolve parent-owned scheduler artifact for \
2248 {sched_name:?}: {e:#}"
2249 );
2250 return 1;
2251 }
2252 }
2253 } else {
2254 None
2255 };
2256 let sched_bin: std::path::PathBuf = if let Some(path) = prebuilt {
2257 path
2258 } else {
2259 match sched.binary {
2260 // A cargo-ktstr parent prebuilds every selected Discover package once
2261 // and exports the same immutable exact-identity manifest used by
2262 // ordinary and coverage tests. A direct/manual cell invocation has no
2263 // manifest and retains on-demand resolution. Once a manifest is
2264 // present, lookup failure is fatal and MUST NOT silently rebuild.
2265 SchedulerSpec::Discover(pkg) => {
2266 match crate::build_and_find_binary(pkg, sched.manifest_dir) {
2267 Ok(path) => path,
2268 Err(e) => {
2269 eprintln!("ktstr verifier: build scheduler {pkg:?}: {e:#}");
2270 return 1;
2271 }
2272 }
2273 }
2274 SchedulerSpec::Path(p) => {
2275 let path = std::path::PathBuf::from(p);
2276 if !path.exists() {
2277 eprintln!("ktstr verifier: scheduler binary not found: {p}");
2278 return 1;
2279 }
2280 path
2281 }
2282 // Eevdf + KernelBuiltin are filtered at list time in
2283 // list_verifier_cells_all, so nextest dispatch never reaches
2284 // these arms. The SKIP arms remain as defense-in-depth for
2285 // direct `--exact verifier/<eevdf>/...` invocation outside
2286 // nextest.
2287 SchedulerSpec::Eevdf => {
2288 *out_skipped = true;
2289 println!(
2290 "ktstr verifier: SKIP cell {full_name} (Eevdf has no userspace binary to verify)",
2291 );
2292 return 0;
2293 }
2294 SchedulerSpec::KernelBuiltin { .. } => {
2295 *out_skipped = true;
2296 println!(
2297 "ktstr verifier: SKIP cell {full_name} (KernelBuiltin has no userspace binary to verify)",
2298 );
2299 return 0;
2300 }
2301 }
2302 };
2303
2304 let ktstr_bin = match std::env::current_exe() {
2305 Ok(p) => p,
2306 Err(e) => {
2307 eprintln!(
2308 "ktstr verifier: locate ktstr binary via current_exe() (required so the \
2309 verifier VM can boot the same test binary as /init for guest-side dispatch): {e}",
2310 );
2311 return 1;
2312 }
2313 };
2314
2315 // Resolve the kernel-build DIR to the actual bootable image file.
2316 // `collect_verifier_output` -> `KtstrVm::builder().kernel()` loads the
2317 // path verbatim (build() does NOT extract a source tree), so passing
2318 // the raw dir makes the VMM loader read a directory as a bzImage and
2319 // fail with "Unable to read bzImage header". `find_image_in_dir`
2320 // handles both the build-tree (`arch/*/boot/bzImage`) and cache
2321 // (`<dir>/bzImage`) layouts — the same resolution the eval path uses.
2322 let kernel_path = if kernel_entry.kernel_dir.is_file() {
2323 kernel_entry.kernel_dir.clone()
2324 } else {
2325 match crate::kernel_path::find_image_in_dir(&kernel_entry.kernel_dir) {
2326 Some(img) => img,
2327 None => {
2328 eprintln!(
2329 "ktstr verifier: cell {full_name}: no kernel image \
2330 (arch/*/boot/bzImage or a cached bzImage) under {} — \
2331 build the kernel first",
2332 kernel_entry.kernel_dir.display(),
2333 );
2334 return 1;
2335 }
2336 }
2337 };
2338 // Pass the preset's Topology directly (192cpu-11llc-smt's per-LLC core
2339 // counts must survive into the guest CPUID; the TopologyJson wire
2340 // shape would drop them).
2341 let topology = preset.topology;
2342 let memory_min_mib =
2343 super::runtime::verifier_preset_memory_min_mib(topology.total_cpus(), preset.memory_mib);
2344 let launch = crate::verifier::VerifierSchedulerLaunchPlan::from_scheduler(sched);
2345
2346 // Raw mode is opt-in via the dispatcher's --raw flag, plumbed
2347 // through KTSTR_VERIFIER_RAW_ENV. Presence (any value, including
2348 // empty) enables raw rendering — matches the "set to any value"
2349 // semantics documented on the const and the dispatcher's
2350 // `cmd.env(KTSTR_VERIFIER_RAW_ENV, "1")` setter.
2351 let raw = std::env::var_os(crate::KTSTR_VERIFIER_RAW_ENV).is_some();
2352
2353 match crate::verifier::collect_verifier_output_with_memory_min(
2354 &sched_bin,
2355 &ktstr_bin,
2356 &kernel_path,
2357 &launch,
2358 topology,
2359 memory_min_mib,
2360 preset.forced_cpu_budget,
2361 ) {
2362 Ok(result) => {
2363 let output = crate::verifier::format_verifier_output("verifier", &result, raw);
2364 print!("{output}");
2365 // Propagate the scheduler's captured stderr to the test's
2366 // real stderr (best-effort — whatever streamed before a
2367 // watchdog kill). Emitted BEFORE the `... FAILED:` verdict
2368 // line below so the verdict stays the last thing on stderr.
2369 let sched_stderr = crate::verifier::format_verifier_stderr("verifier", &result, raw);
2370 if !sched_stderr.is_empty() {
2371 eprint!("{sched_stderr}");
2372 }
2373 // PASS requires verify + attach, contemporaneous dispatch
2374 // progress with a live/enabled scheduler, no observed scheduler
2375 // exit, cleanup liveness confirmation, and an explicit terminal
2376 // guest exit 0. `cell_verdict` names the first failing host-side
2377 // gate (timed_out / scheduler-exit → attach → dispatch → terminal
2378 // exit, root cause first).
2379 let code = match result.cell_verdict() {
2380 Ok(()) => 0,
2381 Err(reason) => {
2382 eprintln!("ktstr verifier: cell {full_name} FAILED: {reason}");
2383 1
2384 }
2385 };
2386 // Hand the per-program verified_insns out to the record writer
2387 // so the dispatcher can render the instruction-count tables.
2388 // Only this arm produces them; every earlier return (skip,
2389 // kernel resolution error, build failure) leaves them empty.
2390 *out_stats = result.stats;
2391 code
2392 }
2393 Err(e) if is_verifier_topology_unsupported(&e) => {
2394 *out_skipped = true;
2395 println!("ktstr verifier: SKIP cell {full_name} ({e:#})");
2396 0
2397 }
2398 Err(e) => {
2399 eprintln!("ktstr verifier: cell {full_name} FAILED: {e:#}");
2400 1
2401 }
2402 }
2403}
2404
2405/// Check parent-elected ownership before an exact verifier cell can launch or
2406/// write its deterministic record.
2407///
2408/// The environment-absent path preserves direct/manual invocation. Once a
2409/// manifest is present, malformed names and missing local declarations cannot
2410/// establish ownership and fail closed. A non-owner returns `Ok(None)` so the
2411/// wrapper can reject it without entering either the VM path or record writer.
2412fn select_verifier_scheduler_from<'a>(
2413 schedulers: impl IntoIterator<Item = &'a super::Scheduler>,
2414 scheduler_name: &str,
2415 expected: Option<&super::SchedulerJson>,
2416) -> anyhow::Result<&'a super::Scheduler> {
2417 let mut candidates = schedulers
2418 .into_iter()
2419 .filter(|scheduler| scheduler.name == scheduler_name);
2420 let Some(expected) = expected else {
2421 return candidates.next().ok_or_else(|| {
2422 anyhow::anyhow!("no declared scheduler {scheduler_name:?} exists in this test binary")
2423 });
2424 };
2425 candidates
2426 .find(|scheduler| super::SchedulerJson::from_scheduler(scheduler).eq(expected))
2427 .ok_or_else(|| {
2428 anyhow::anyhow!(
2429 "this test binary has no declaration matching the parent-selected full \
2430 identity for scheduler {scheduler_name:?}: {expected:?}"
2431 )
2432 })
2433}
2434
2435fn select_local_verifier_scheduler(
2436 scheduler_name: &str,
2437 expected: Option<&super::SchedulerJson>,
2438) -> anyhow::Result<&'static super::Scheduler> {
2439 select_verifier_scheduler_from(
2440 super::KTSTR_SCHEDULERS.iter().copied(),
2441 scheduler_name,
2442 expected,
2443 )
2444}
2445
2446fn current_binary_verifier_scheduler(
2447 full_name: &str,
2448) -> anyhow::Result<Option<&'static super::Scheduler>> {
2449 let rest = full_name
2450 .strip_prefix("verifier/")
2451 .ok_or_else(|| anyhow::anyhow!("missing 'verifier/' prefix in cell name {full_name:?}"))?;
2452 let parts = rest.splitn(3, '/').collect::<Vec<_>>();
2453 if parts.len() != 3 {
2454 anyhow::bail!(
2455 "malformed cell name {full_name:?}; expected \
2456 verifier/<sched>/<kernel>/<preset>"
2457 );
2458 }
2459 let scheduler_name = parts[0];
2460 let Some(ownership) = crate::verifier::verifier_cell_ownership_from_env()? else {
2461 return select_local_verifier_scheduler(scheduler_name, None).map(Some);
2462 };
2463 let Some(expected) = ownership.owned_scheduler(scheduler_name)? else {
2464 return Ok(None);
2465 };
2466 select_local_verifier_scheduler(scheduler_name, Some(expected)).map(Some)
2467}
2468
2469/// Run a verifier cell and, when the `cargo ktstr verifier` dispatcher
2470/// set [`crate::KTSTR_VERIFIER_RESULT_DIR_ENV`], record its
2471/// PASS/FAIL/SKIP outcome there so the dispatcher can render the
2472/// run-summary table after nextest returns. Best-effort + env-gated: a direct
2473/// `--exact verifier/...` invocation (env unset) behaves exactly as
2474/// [`run_verifier_cell_inner`], and a record-write failure never changes
2475/// the cell's exit code. A nextest RETRY re-runs this wrapper and
2476/// overwrites the cell's own record (deterministic filename), so the
2477/// final attempt's outcome is the one that lands in the table.
2478fn run_verifier_cell_after_ownership(
2479 full_name: &str,
2480 scheduler: anyhow::Result<Option<&super::Scheduler>>,
2481 execute: impl FnOnce(
2482 &str,
2483 &super::Scheduler,
2484 &mut Vec<crate::verifier::ProgStats>,
2485 &mut bool,
2486 ) -> i32,
2487) -> i32 {
2488 let scheduler = match scheduler {
2489 Ok(Some(scheduler)) => scheduler,
2490 Ok(None) => {
2491 eprintln!("ktstr verifier: refusing non-owner exact-cell dispatch for {full_name:?}");
2492 return 1;
2493 }
2494 Err(error) => {
2495 eprintln!(
2496 "ktstr verifier: cannot establish exact-cell ownership for {full_name:?}: \
2497 {error:#}"
2498 );
2499 return 1;
2500 }
2501 };
2502 let mut stats = Vec::new();
2503 let mut skipped = false;
2504 let code = execute(full_name, scheduler, &mut stats, &mut skipped);
2505 if let Some(dir) = std::env::var_os(crate::KTSTR_VERIFIER_RESULT_DIR_ENV) {
2506 crate::verifier::write_cell_record(
2507 std::path::Path::new(&dir),
2508 full_name,
2509 code == 0 && !skipped,
2510 skipped,
2511 &stats,
2512 );
2513 }
2514 code
2515}
2516
2517fn run_verifier_cell(full_name: &str) -> i32 {
2518 run_verifier_cell_after_ownership(
2519 full_name,
2520 current_binary_verifier_scheduler(full_name),
2521 run_verifier_cell_inner,
2522 )
2523}
2524
2525/// List tests with budget-based coverage maximization.
2526///
2527/// Collects all eligible tests as candidates, runs greedy selection,
2528/// and prints only the selected subset. Multi-kernel mode adds the
2529/// kernel suffix as a feature dimension so the budget selector
2530/// picks per-kernel coverage; single-kernel mode is unchanged.
2531///
2532/// `KTSTR_CARGO_TEST_MODE=1` is treated identically to
2533/// `list_tests_all`: the budget pipeline runs only over base test
2534/// candidates (no gauntlet-variant candidates, no multi-kernel
2535/// fan-out). The greedy selector still applies — a low budget
2536/// can still trim the base list — but the candidate set is the
2537/// same set that the dispatch path would actually run.
2538fn push_budget_base_candidates(
2539 candidates: &mut Vec<crate::budget::TestCandidate>,
2540 entry: &KtstrTestEntry,
2541 ignored_only: bool,
2542 base_ignored: bool,
2543 base_topo: &crate::vmm::topology::Topology,
2544 kernel_suffixes: &[&str],
2545) {
2546 use crate::budget::{TestCandidate, estimate_duration, extract_features};
2547
2548 if ignored_only && !base_ignored {
2549 return;
2550 }
2551
2552 // Host-only tests never boot a VM, so the kernel never affects what
2553 // runs. Emit one candidate without a kernel suffix even in multi-kernel
2554 // mode; VM tests retain one candidate per selected kernel.
2555 if entry.host_only {
2556 candidates.push(TestCandidate {
2557 name: format!("host/{}: test", entry.name),
2558 features: extract_features(entry, base_topo, false, entry.name),
2559 estimated_secs: estimate_duration(entry, base_topo),
2560 });
2561 } else {
2562 for suffix in kernel_suffixes {
2563 let name = if suffix.is_empty() {
2564 format!("ktstr/{}: test", entry.name)
2565 } else {
2566 format!("ktstr/{}/{suffix}: test", entry.name)
2567 };
2568 candidates.push(TestCandidate {
2569 name,
2570 features: extract_features(entry, base_topo, false, entry.name),
2571 estimated_secs: estimate_duration(entry, base_topo),
2572 });
2573 }
2574 }
2575}
2576
2577fn list_tests_budget(ignored_only: bool, budget_secs: f64) {
2578 use crate::budget::{TestCandidate, estimate_duration, extract_features, select};
2579
2580 let cargo_test_mode = crate::cargo_test_mode::cargo_test_mode_active();
2581 let presets = crate::gauntlet::gauntlet_presets();
2582 let has_vmlinux = resolve_test_kernel()
2583 .ok()
2584 .and_then(|k| crate::vmm::find_vmlinux(&k))
2585 .is_some();
2586 let (host_cpus, host_llcs, host_max_cpus_per_llc) = super::host_capacity();
2587 let mut candidates: Vec<TestCandidate> = Vec::new();
2588
2589 let kernel_list = read_kernel_list();
2590 let multi_kernel = kernel_list.len() > 1 && !cargo_test_mode;
2591 let kernel_suffixes: Vec<&str> = if multi_kernel {
2592 kernel_list.iter().map(|k| k.sanitized.as_str()).collect()
2593 } else {
2594 vec![""]
2595 };
2596
2597 for entry in KTSTR_TESTS.iter() {
2598 // Same sentinel exclusion as `list_tests_all`: fixtures never
2599 // become budget candidates.
2600 if is_test_sentinel(entry.name) {
2601 continue;
2602 }
2603 if !entry.bpf_map_write.is_empty() && !has_vmlinux {
2604 continue;
2605 }
2606
2607 let base_ignored = is_ignored(entry);
2608 let base_topo = entry.topology;
2609
2610 push_budget_base_candidates(
2611 &mut candidates,
2612 entry,
2613 ignored_only,
2614 base_ignored,
2615 &base_topo,
2616 &kernel_suffixes,
2617 );
2618
2619 if entry.host_only {
2620 continue;
2621 }
2622
2623 if cargo_test_mode {
2624 // No gauntlet candidates in cargo-test mode — the
2625 // dispatch path will never execute them and including
2626 // them in the budget candidate set would shift greedy
2627 // selection toward variants that resolve to "no test"
2628 // at run time.
2629 continue;
2630 }
2631
2632 for_each_gauntlet_variant(
2633 entry,
2634 &presets,
2635 host_cpus,
2636 host_llcs,
2637 host_max_cpus_per_llc,
2638 |preset| {
2639 for suffix in &kernel_suffixes {
2640 let test_name = if suffix.is_empty() {
2641 format!("gauntlet/{}/{}", entry.name, preset.name)
2642 } else {
2643 format!("gauntlet/{}/{}/{suffix}", entry.name, preset.name)
2644 };
2645 candidates.push(TestCandidate {
2646 name: format!("{test_name}: test"),
2647 features: extract_features(entry, &preset.topology, true, &test_name),
2648 estimated_secs: estimate_duration(entry, &preset.topology),
2649 });
2650 }
2651 },
2652 );
2653 }
2654
2655 let selected = select(&candidates, budget_secs);
2656 for &i in &selected {
2657 println!("{}", candidates[i].name);
2658 }
2659
2660 let stats = crate::budget::selection_stats(&candidates, &selected, budget_secs);
2661 eprintln!(
2662 "ktstr budget: {}/{} tests, {:.0}/{:.0}s used, {}/{} configurations covered",
2663 stats.selected,
2664 stats.total,
2665 stats.budget_used,
2666 stats.budget_total,
2667 stats.bits_covered,
2668 stats.bits_possible,
2669 );
2670}
2671
2672/// Strip an optional `/{sanitized_kernel_label}` suffix from `name`,
2673/// look up the matching [`KernelEntry`] in the multi-kernel list,
2674/// and re-export `KTSTR_KERNEL` to that entry's directory. Returns
2675/// the prefix-only name for the dispatch caller.
2676///
2677/// When `KTSTR_KERNEL_LIST` is unset / single-entry, the function
2678/// is a no-op pass-through: returns `(name, None)` and does not
2679/// touch the env. When the list has 2+ entries, the suffix is
2680/// REQUIRED and missing it surfaces as `Err` (the early-dispatch
2681/// caller turns that into exit code 1 with an actionable message)
2682/// — the suffix is part of every test name `--list` emitted, so a
2683/// `--exact` invocation that omits it can only come from operator
2684/// hand-construction or tooling that hasn't been taught the
2685/// multi-kernel naming.
2686fn strip_kernel_suffix<'a>(
2687 name: &'a str,
2688 kernel_list: &'a [KernelEntry],
2689) -> Result<(&'a str, Option<&'a KernelEntry>), String> {
2690 if kernel_list.len() <= 1 {
2691 return Ok((name, None));
2692 }
2693 // Multi-kernel: every test name carries `/kernel_…` as its
2694 // final segment. Iterate the labels rather than splitting on
2695 // `/` — the suffix always has exactly one extra `/` separator
2696 // before `kernel_…`, but the body of the test name CAN contain
2697 // `/` (gauntlet variants already do — `gauntlet/{name}/{preset}`),
2698 // so a naive `rsplit_once('/')` would accidentally peel the
2699 // preset segment instead.
2700 //
2701 // Distinct kernels in the same `KTSTR_KERNEL_LIST` produce
2702 // distinct sanitized labels in practice — the producer emits
2703 // semantic identifiers (version strings, git owner/repo/ref,
2704 // path basename + 6-char hash) that don't share suffixes
2705 // among the resolved set. If a future regression DID produce
2706 // labels where one is a strict suffix of another (e.g.
2707 // `kernel_6_14` vs `kernel_x_kernel_6_14`), the iterate-and-
2708 // first-match below would pick whichever appears first in
2709 // the kernel_list — deterministic but potentially wrong.
2710 // Producer-side regression detection would catch that
2711 // class of collision before it reaches this peeler.
2712 for entry in kernel_list {
2713 let needle = format!("/{}", entry.sanitized);
2714 if let Some(stripped) = name.strip_suffix(&needle) {
2715 return Ok((stripped, Some(entry)));
2716 }
2717 }
2718 Err(format!(
2719 "test name {name:?} has no recognised kernel suffix (KTSTR_KERNEL_LIST \
2720 carries {n} kernels — every test name must end with `/kernel_…`)",
2721 n = kernel_list.len(),
2722 ))
2723}
2724
2725/// Re-export `KTSTR_KERNEL` to the kernel directory carried by a
2726/// resolved [`KernelEntry`]. Called when a multi-kernel `--exact`
2727/// dispatch peels off the per-test kernel suffix.
2728///
2729/// SAFETY: nextest invokes the test binary's `--exact` handler in a
2730/// single-threaded context — there are no other readers of the env
2731/// at this point. The eventual VM-launch site reads `KTSTR_KERNEL`
2732/// via `find_kernel` after this returns; that read is sequenced
2733/// after the write per the program order.
2734fn export_kernel_for_variant(entry: &KernelEntry) {
2735 // SAFETY: see fn-level doc — single-threaded ctor / nextest
2736 // dispatch context.
2737 unsafe { std::env::set_var(crate::KTSTR_KERNEL_ENV, &entry.kernel_dir) };
2738}
2739
2740/// Parse a nextest-style test name and run it.
2741///
2742/// Handles VM base tests (`ktstr/{name}`), host-only tests (`host/{name}`),
2743/// gauntlet variants (`gauntlet/{name}/{preset}`), and bare names (backward
2744/// compatibility).
2745/// When `KTSTR_KERNEL_LIST` carries 2+ kernels,
2746/// VM-bound test names additionally end with
2747/// `/{sanitized_kernel_label}` — that suffix is peeled here and
2748/// the matching kernel directory is re-exported via
2749/// [`crate::KTSTR_KERNEL_ENV`] before the dispatch continues. `host_only`
2750/// tests are short-circuited BEFORE the suffix peel: they never
2751/// boot a VM, so the kernel-suffix listing path emits one
2752/// `host/{name}: test` entry without a kernel suffix regardless
2753/// of the kernel-list cardinality (see `list_tests_all` /
2754/// `list_tests_budget`), and routing them through
2755/// `strip_kernel_suffix` would surface as a "no recognised kernel
2756/// suffix" exit-1 error. Returns an exit code.
2757pub(crate) fn run_named_test(test_name: &str) -> i32 {
2758 let kernel_list = read_kernel_list();
2759
2760 // host_only short-circuit: in multi-kernel mode, host_only tests
2761 // are listed without a `/{sanitized_kernel_label}` suffix (see
2762 // `list_tests_all` / `list_tests_budget`, which emit a single
2763 // `host/{name}: test` line for host_only entries regardless of
2764 // the kernel-list cardinality — a host_only test never boots a
2765 // VM, so the kernel never affects what runs). Calling
2766 // `strip_kernel_suffix` on such a name in multi-kernel mode
2767 // would fail with the "no recognised kernel suffix" error and
2768 // misroute every host_only dispatch to exit 1.
2769 //
2770 // Resolve the host_only check from `find_test` BEFORE the
2771 // suffix peel so the multi-kernel branch only applies to
2772 // VM-bound tests. Single-kernel mode is unaffected — the
2773 // pass-through arm in `strip_kernel_suffix` returns the input
2774 // verbatim either way.
2775 let bare_for_lookup = test_name
2776 .strip_prefix("host/")
2777 .or_else(|| test_name.strip_prefix("ktstr/"))
2778 .unwrap_or(test_name);
2779
2780 if let Some(entry) = find_test(bare_for_lookup)
2781 && entry.host_only
2782 {
2783 return run_host_only_test(entry);
2784 }
2785
2786 let (test_name, kernel_entry) = match strip_kernel_suffix(test_name, &kernel_list) {
2787 Ok(pair) => pair,
2788 Err(e) => {
2789 eprintln!("{e}");
2790 return 1;
2791 }
2792 };
2793 if let Some(entry) = kernel_entry {
2794 export_kernel_for_variant(entry);
2795 }
2796
2797 if let Some(rest) = test_name.strip_prefix("gauntlet/") {
2798 return run_gauntlet_test(rest);
2799 }
2800
2801 let bare_name = test_name
2802 .strip_prefix("host/")
2803 .or_else(|| test_name.strip_prefix("ktstr/"))
2804 .unwrap_or(test_name);
2805 let entry = match find_test(bare_name) {
2806 Some(e) => e,
2807 None => {
2808 eprintln!("unknown test: {test_name}");
2809 return 1;
2810 }
2811 };
2812
2813 // Defense-in-depth: host_only re-check after suffix peel for the
2814 // edge case where the bare_for_lookup pre-strip lookup missed
2815 // (e.g. a future test name shape that doesn't match the
2816 // pre-strip form but does after the suffix peel).
2817 if entry.host_only {
2818 return run_host_only_test(entry);
2819 }
2820
2821 if entry.performance_mode && super::runtime::no_perf_mode_active() {
2822 crate::report::test_skip(format_args!(
2823 "{}: test requires performance_mode but --no-perf-mode or KTSTR_NO_PERF_MODE is active",
2824 bare_name,
2825 ));
2826 // See run_ktstr_test_inner for the sidecar-emission rationale.
2827 // Plain (non-gauntlet) dispatch: no TopoOverride, so the skip
2828 // records entry.topology (declared == booted for a plain test).
2829 record_skip_sidecar(entry, None);
2830 return 0;
2831 }
2832
2833 if super::runtime::perf_only_skips_entry(entry) {
2834 crate::report::test_skip(format_args!(
2835 "{bare_name}: KTSTR_PERF_ONLY is active and this test is not a performance_mode test",
2836 ));
2837 // Skip sidecar so the perf-delta pool records the skip (excluded
2838 // from the A/B compare) rather than a phantom missing result.
2839 record_skip_sidecar(entry, None);
2840 return 0;
2841 }
2842
2843 if !entry.bpf_map_write.is_empty()
2844 && let Ok(kernel) = resolve_test_kernel()
2845 && crate::vmm::find_vmlinux(&kernel).is_none()
2846 {
2847 eprintln!("FAIL: vmlinux not found, bpf_map_write requires vmlinux");
2848 return 1;
2849 }
2850
2851 let result = run_ktstr_test_inner(entry, None);
2852 result_to_exit_code(result, entry.expect_err, entry.allow_inconclusive)
2853}
2854
2855/// Run a host-only test directly without booting a VM.
2856/// Returns an exit code for nextest dispatch.
2857fn run_host_only_test(entry: &KtstrTestEntry) -> i32 {
2858 let result = run_host_only_test_inner(entry);
2859 result_to_exit_code(result, entry.expect_err, entry.allow_inconclusive)
2860}
2861
2862/// Inner host-only dispatch returning `Result<AssertResult>`.
2863///
2864/// Builds a minimal Ctx and calls the test function on the host.
2865/// Used for tests that need host tools (cargo, nested VMs).
2866///
2867/// Topology comes from real-host sysfs (`/sys/devices/system/cpu/`)
2868/// via [`crate::topology::TestTopology::from_system`]; the test's
2869/// declared VM topology is intentionally ignored for host_only
2870/// runs because the test author wrote it for a synthetic VM and
2871/// the host's actual CPU layout is what `WorkSpec::workers_pct` /
2872/// `AffinityIntent::LlcAligned` resolve against. Bails with an
2873/// actionable diagnostic when sysfs CPU enumeration fails — the
2874/// underlying causes are missing `/sys/devices/system/cpu/online`
2875/// (no /sys mount or container masking), unreadable contents (rare
2876/// permissions edge), corrupt sysfs string (kernel/hardware bug),
2877/// or an empty online-CPU set (degenerate cpuset namespace).
2878///
2879/// Cgroup parent defaults to `/sys/fs/cgroup/ktstr`; the operator
2880/// can override via `KTSTR_HOST_CGROUP_PARENT`. The override path
2881/// is validated upfront: it must be non-empty and rooted under
2882/// `/sys/fs/cgroup` so an accidental empty/relative/foreign value
2883/// produces a clear error instead of an opaque cgroupfs failure
2884/// later. Empty-string env value is treated as "unset" and falls
2885/// back to the default.
2886///
2887/// For cgroup-v2 user delegation (Mode B/C: systemd `Delegate=yes`,
2888/// container `nsdelegate`), the operator sets
2889/// `KTSTR_CGROUP_WALK_ROOT` to the delegation boundary so
2890/// [`crate::cgroup::CgroupManager::setup`]'s ancestor
2891/// `subtree_control` walk stops there instead of EACCES-ing at
2892/// `user.slice` / the container root. Defaults to `/sys/fs/cgroup`
2893/// (Mode A: root-owned tree).
2894fn run_host_only_test_inner(entry: &KtstrTestEntry) -> Result<AssertResult> {
2895 let topo = crate::topology::TestTopology::from_system().context(
2896 "host_only requires real-host topology from sysfs; \
2897 the sysfs CPU enumeration at /sys/devices/system/cpu/online \
2898 failed — likely causes: running outside a /sys-mounted \
2899 environment, sysfs contents unreadable (permissions / \
2900 container mask), corrupt online-CPU string, or a degenerate \
2901 cpuset namespace with no online CPUs",
2902 )?;
2903 let cgroup_parent = resolve_host_cgroup_parent()?;
2904 let cgroups = build_host_cgroup_manager(&cgroup_parent)?;
2905 let merged_assert = crate::assert::Assert::default_checks()
2906 .merge(&entry.scheduler.assert)
2907 .merge(&entry.assert);
2908 let ctx = crate::scenario::Ctx::builder(&cgroups, &topo)
2909 .duration(entry.duration)
2910 .settle(std::time::Duration::ZERO)
2911 .assert(merged_assert)
2912 .entry_name(entry.name)
2913 // host_only is host-side with no VM: the resolved topology is
2914 // the declared entry.topology (resolve_vm_topology(entry, None)),
2915 // so compute the variant hash directly rather than threading.
2916 .variant_hash(super::sidecar::variant_hash_from_parts(
2917 entry,
2918 &entry.topology,
2919 &super::args::current_work_type(),
2920 ))
2921 .build();
2922 (entry.func)(&ctx)
2923}
2924
2925/// Default cgroup parent path for `host_only` tests when
2926/// `KTSTR_HOST_CGROUP_PARENT` is unset. Suitable for both root
2927/// (writable directly) and non-root (operator pre-creates
2928/// `/sys/fs/cgroup/ktstr` with appropriate ownership, OR overrides via
2929/// `KTSTR_HOST_CGROUP_PARENT` to point at a path inside a delegated
2930/// subtree) invocations. See [`resolve_host_cgroup_parent`] for the
2931/// env-override path and `build_host_cgroup_manager` for the
2932/// cgroup-v2 Mode B/C delegation wire-up.
2933///
2934/// `pub` so tests can pin against it instead of mirroring
2935/// the literal in their own assertion strings (the
2936/// `resolve_host_cgroup_parent_*` unit tests in `dispatch_tests.rs`
2937/// assert unset/empty env falls back to this const). Treat as the
2938/// canonical default — operators set `KTSTR_HOST_CGROUP_PARENT` to
2939/// override.
2940pub const DEFAULT_HOST_CGROUP_PARENT: &str = "/sys/fs/cgroup/ktstr";
2941
2942/// Resolve the cgroup parent path for `host_only` tests.
2943///
2944/// Reads `KTSTR_HOST_CGROUP_PARENT`. Empty / unset falls back to
2945/// `DEFAULT_HOST_CGROUP_PARENT`. A set value must be rooted under
2946/// `/sys/fs/cgroup` (no relative paths, no random /tmp dirs) so an
2947/// accidental misconfiguration surfaces here rather than as an
2948/// opaque cgroupfs failure inside `CgroupManager::setup`.
2949///
2950/// Non-root callers are admitted: cgroup-v2 user delegation (Mode
2951/// B/C: systemd `Delegate=yes`, container `nsdelegate`) is handled
2952/// by `build_host_cgroup_manager` threading
2953/// [`crate::KTSTR_CGROUP_WALK_ROOT_ENV`] into
2954/// [`crate::cgroup::CgroupManager::with_walk_root`] so the
2955/// `subtree_control` walk bails at the delegation root instead of
2956/// EACCES-ing on `user.slice`.
2957pub fn resolve_host_cgroup_parent() -> Result<String> {
2958 let parent = match std::env::var(crate::KTSTR_HOST_CGROUP_PARENT_ENV) {
2959 Ok(s) if !s.is_empty() => s,
2960 _ => return Ok(DEFAULT_HOST_CGROUP_PARENT.to_string()),
2961 };
2962 if !parent.starts_with("/sys/fs/cgroup") || parent == "/sys/fs/cgroup" {
2963 anyhow::bail!(
2964 "KTSTR_HOST_CGROUP_PARENT={parent:?}: must be rooted under \
2965 /sys/fs/cgroup and name a non-root subdirectory \
2966 (e.g. /sys/fs/cgroup/ktstr or /sys/fs/cgroup/ktstr-foo); \
2967 unset or empty falls back to {DEFAULT_HOST_CGROUP_PARENT}",
2968 );
2969 }
2970 Ok(parent)
2971}
2972
2973/// Build a [`crate::cgroup::CgroupManager`] for a `host_only` test
2974/// run, threading [`crate::KTSTR_CGROUP_WALK_ROOT_ENV`] into
2975/// [`crate::cgroup::CgroupManager::with_walk_root`] when set.
2976///
2977/// The walk root override bounds [`crate::cgroup::CgroupManager::setup`]'s
2978/// ancestor `subtree_control` walk for cgroup-v2 Mode B/C
2979/// delegation: under systemd `Delegate=yes` or a container's
2980/// `nsdelegate`, the operator owns subtree_control writes only
2981/// inside the delegated subtree. Without the override the walk
2982/// starts at `/sys/fs/cgroup` and EACCES-es at `user.slice` or the
2983/// container root.
2984///
2985/// Empty / unset falls through to the default `/sys/fs/cgroup`
2986/// (Mode A: root-owned tree). [`crate::cgroup::CgroupManager::with_walk_root`]
2987/// validates that the chosen walk root is a prefix of `parent` —
2988/// misconfigurations surface as a focused error before the first
2989/// cgroupfs write rather than as an opaque downstream EACCES.
2990///
2991/// Non-root callers with no walk-root override are admitted here — the
2992/// precondition (root, or a cgroup-v2 delegated walk root) is enforced
2993/// lazily at [`crate::cgroup::CgroupManager::setup`], the first real
2994/// cgroup operation. `host_only` tests that never create a cgroup
2995/// (macro-attribute fixtures, host-topology reads, nested-VM verifier
2996/// orchestration) therefore run without root; only a test that actually
2997/// touches a cgroup hits the deferred non-root error.
2998fn build_host_cgroup_manager(cgroup_parent: &str) -> Result<crate::cgroup::CgroupManager> {
2999 let cg = crate::cgroup::CgroupManager::new(cgroup_parent);
3000 match std::env::var(crate::KTSTR_CGROUP_WALK_ROOT_ENV) {
3001 Ok(walk_root) if !walk_root.is_empty() => {
3002 // Defense-in-depth: walk_root must be rooted under
3003 // /sys/fs/cgroup. Mirrors the sibling
3004 // KTSTR_HOST_CGROUP_PARENT_ENV guard above so an operator
3005 // typo surfaces here instead of as a downstream cgroupfs
3006 // fs::write EACCES.
3007 if !walk_root.starts_with("/sys/fs/cgroup") {
3008 anyhow::bail!(
3009 "{env}={walk_root:?}: walk root must be rooted under /sys/fs/cgroup \
3010 (e.g. /sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service \
3011 for a systemd user session); the value supplied is outside the cgroup-v2 \
3012 mount and would EACCES on the first cgroupfs write",
3013 env = crate::KTSTR_CGROUP_WALK_ROOT_ENV,
3014 );
3015 }
3016 cg.with_walk_root(&walk_root).with_context(|| {
3017 format!(
3018 "{env}={walk_root:?}: walk-root override rejected (must be a prefix of \
3019 KTSTR_HOST_CGROUP_PARENT={cgroup_parent:?})",
3020 env = crate::KTSTR_CGROUP_WALK_ROOT_ENV,
3021 )
3022 })
3023 }
3024 // No KTSTR_CGROUP_WALK_ROOT override. Return the manager as-is;
3025 // the non-root precondition for managing cgroups under the
3026 // kernel-owned default walk root is checked lazily in
3027 // CgroupManager::setup (first real cgroup use). host_only tests
3028 // that never create a cgroup — macro-attribute fixtures,
3029 // host-topology reads, nested-VM verifier orchestration — must
3030 // not be failed here for a resource they never touch. A
3031 // non-root test that does create a cgroup gets the deferred
3032 // setup error pointing at with_walk_root; the operator on-ramp
3033 // is EITHER to run as root OR to set KTSTR_CGROUP_WALK_ROOT to a
3034 // delegated cgroup-v2 subtree (handled by the arm above).
3035 _ => Ok(cg),
3036 }
3037}
3038
3039/// Run a gauntlet variant test. `rest` is `{name}/{preset}`.
3040pub(crate) fn run_gauntlet_test(rest: &str) -> i32 {
3041 let parts: Vec<&str> = rest.splitn(2, '/').collect();
3042 if parts.len() != 2 {
3043 eprintln!("invalid gauntlet test name: gauntlet/{rest}");
3044 return 1;
3045 }
3046 let (test_name, preset_name) = (parts[0], parts[1]);
3047
3048 let entry = match find_test(test_name) {
3049 Some(e) => e,
3050 None => {
3051 eprintln!("unknown test: {test_name}");
3052 return 1;
3053 }
3054 };
3055
3056 let presets = crate::gauntlet::gauntlet_presets();
3057 let preset = match presets.iter().find(|p| p.name == preset_name) {
3058 Some(p) => p,
3059 None => {
3060 eprintln!("unknown gauntlet preset: {preset_name}");
3061 return 1;
3062 }
3063 };
3064
3065 let t = &preset.topology;
3066 let cpus = t.total_cpus();
3067
3068 let memory_mib = super::runtime::derive_test_memory_mib(cpus, entry);
3069 let topo = TopoOverride {
3070 numa_nodes: t.numa_nodes,
3071 llcs: t.llcs,
3072 cores: t.cores_per_llc,
3073 threads: t.threads_per_core,
3074 memory_mib,
3075 };
3076
3077 if entry.performance_mode && super::runtime::no_perf_mode_active() {
3078 crate::report::test_skip(format_args!(
3079 "{}: test requires performance_mode but --no-perf-mode or KTSTR_NO_PERF_MODE is active",
3080 test_name,
3081 ));
3082 // Gauntlet preset: record the preset's RESOLVED topology
3083 // (Topology::from(&topo)) so this skip shares a variant_hash
3084 // with a run of the same preset and distinguishes other presets.
3085 record_skip_sidecar(entry, Some(&topo));
3086 return 0;
3087 }
3088
3089 if super::runtime::perf_only_skips_entry(entry) {
3090 crate::report::test_skip(format_args!(
3091 "{test_name}: KTSTR_PERF_ONLY is active and this test is not a performance_mode test",
3092 ));
3093 // Gauntlet preset: record the preset's RESOLVED topology so the
3094 // skip shares a variant_hash with a run of the same preset.
3095 record_skip_sidecar(entry, Some(&topo));
3096 return 0;
3097 }
3098
3099 if !entry.bpf_map_write.is_empty()
3100 && let Ok(kernel) = resolve_test_kernel()
3101 && crate::vmm::find_vmlinux(&kernel).is_none()
3102 {
3103 eprintln!("FAIL: vmlinux not found, bpf_map_write requires vmlinux");
3104 return 1;
3105 }
3106
3107 let result = run_ktstr_test_inner(entry, Some(&topo));
3108 result_to_exit_code(result, entry.expect_err, entry.allow_inconclusive)
3109}
3110
3111/// Collect sidecar JSON files and return the full gauntlet analysis.
3112///
3113/// When `dir` is `Some`, reads sidecars from that directory. Otherwise
3114/// uses the default sidecar directory (`KTSTR_SIDECAR_DIR` override, or
3115/// `{CARGO_TARGET_DIR or "target"}/ktstr/{kernel}-{project_commit}/`,
3116/// where `{project_commit}` is the project HEAD short hex with
3117/// `-dirty` when the worktree differs).
3118///
3119/// Returns the concatenated output of `analyze_rows`, verifier stats,
3120/// callback profile, and KVM stats. Returns an empty string when no
3121/// sidecars are found.
3122pub fn analyze_sidecars(dir: Option<&std::path::Path>) -> String {
3123 let default_dir;
3124 let dir = match dir {
3125 Some(d) => d,
3126 None => {
3127 default_dir = sidecar_dir();
3128 &default_dir
3129 }
3130 };
3131 let sidecars = collect_sidecars(dir);
3132 if sidecars.is_empty() {
3133 return String::new();
3134 }
3135 let mut out = String::new();
3136 let rows: Vec<_> = sidecars.iter().map(crate::stats::sidecar_to_row).collect();
3137 if !rows.is_empty() {
3138 out.push_str(&crate::stats::analyze_rows(&rows));
3139 }
3140 let vstats = format_verifier_stats(&sidecars);
3141 if !vstats.is_empty() {
3142 out.push_str(&vstats);
3143 }
3144 let cprofile = format_callback_profile(&sidecars);
3145 if !cprofile.is_empty() {
3146 out.push_str(&cprofile);
3147 }
3148 let kstats = format_kvm_stats(&sidecars);
3149 if !kstats.is_empty() {
3150 out.push_str(&kstats);
3151 }
3152 out
3153}
3154
3155/// Discover plain `#[test]` items by re-invoking the binary without
3156/// NEXTEST, reading libtest's `--list` output, and printing only
3157/// names that don't match any KTSTR_TESTS entry. This lets plain
3158/// tests coexist with `#[ktstr_test]` in the same binary without
3159/// duplicating the ktstr entries.
3160///
3161/// `ignored_only` forwards `--ignored` onto the child `--list` call
3162/// so the echoed plain-test set matches the bucket nextest is
3163/// enumerating (all tests vs the `#[ignore]`-only subset). Omitting
3164/// the flag here lands every plain test in nextest's ignored set and
3165/// silently skips them by default — see the body comment.
3166fn list_plain_tests(ignored_only: bool) {
3167 use std::collections::HashSet;
3168 let ktstr_names: HashSet<&str> = KTSTR_TESTS.iter().map(|e| e.name).collect();
3169
3170 let exe = match std::env::current_exe() {
3171 Ok(p) => p,
3172 Err(_) => return,
3173 };
3174 let mut cmd = std::process::Command::new(exe);
3175 cmd.env_remove("NEXTEST");
3176 // Forward `--ignored` so the plain-test set echoed here matches the
3177 // bucket nextest is asking for. nextest computes its "ignored" set by
3178 // re-running the binary with `--list --ignored`; if this child always
3179 // lists ALL plain `#[test]` (no `--ignored`), every plain test lands
3180 // in nextest's ignored set and is silently skipped by default
3181 // (footgun #2). With the flag forwarded, only real `#[ignore]` plain
3182 // tests are reported under `--ignored`, so non-ignored plain tests run
3183 // by default like any other test.
3184 let mut list_args: Vec<&str> = vec!["--list", "--format", "terse"];
3185 if ignored_only {
3186 list_args.push("--ignored");
3187 }
3188 cmd.args(&list_args);
3189 cmd.stdout(std::process::Stdio::piped());
3190 cmd.stderr(std::process::Stdio::null());
3191 let output = match cmd.output() {
3192 Ok(o) => o,
3193 Err(_) => return,
3194 };
3195 let stdout = String::from_utf8_lossy(&output.stdout);
3196 for line in stdout.lines() {
3197 let name = line.strip_suffix(": test").unwrap_or(line);
3198 if !ktstr_names.contains(name) && !name.is_empty() {
3199 println!("{line}");
3200 }
3201 }
3202}
3203
3204/// `--list` subprotocol: emit ktstr/gauntlet test names without
3205/// exiting so the standard libtest harness can also print its own
3206/// test list afterward. This is what makes plain `#[test]` items
3207/// inside a ktstr_test integration-test binary visible to nextest.
3208///
3209/// Honours `--ignored` the same way [`ktstr_main`] does — when set,
3210/// only the ignored subset (gauntlet variants and `demo_` base
3211/// tests) is printed. Unlike `ktstr_main`, this function returns to
3212/// the caller after listing so the ctor's caller can fall through
3213/// to libtest's `main`.
3214fn ktstr_list_only() {
3215 let args: Vec<String> = std::env::args().collect();
3216 let ignored_only = args.iter().any(|a| a == "--ignored");
3217 list_tests(ignored_only);
3218}
3219
3220/// Nextest protocol handler.
3221///
3222/// Called automatically by [`ktstr_test_early_dispatch`] when running
3223/// under nextest with `--exact <ktstr_or_gauntlet_name>`.
3224/// Not intended for direct use.
3225///
3226/// - `--list --format terse`: output `ktstr/{name}: test\n` for VM base
3227/// tests, `host/{name}: test\n` for host-only tests, and
3228/// `gauntlet/{name}/{preset}: test\n` for gauntlet variants. (Discovery
3229/// uses `ktstr_list_only` instead to allow libtest to print its own list
3230/// afterward; this branch is preserved for direct callers of
3231/// `ktstr_main`.)
3232/// - `--exact NAME --nocapture`: run the named test, exit 0/1.
3233pub fn ktstr_main() -> ! {
3234 let args: Vec<String> = std::env::args().collect();
3235
3236 // Discovery mode: --list --format terse [--ignored]
3237 if args.iter().any(|a| a == "--list") {
3238 let ignored_only = args.iter().any(|a| a == "--ignored");
3239 list_tests(ignored_only);
3240 std::process::exit(0);
3241 }
3242
3243 // Execution mode: --exact NAME [--nocapture] [--ignored] [--bench]
3244 if let Some(pos) = args.iter().position(|a| a == "--exact") {
3245 if let Some(name) = args.get(pos + 1) {
3246 let code = run_named_test(name);
3247 std::process::exit(code);
3248 }
3249 eprintln!("--exact requires a test name");
3250 std::process::exit(1);
3251 }
3252
3253 // Fallback: no recognized arguments.
3254 eprintln!("usage: <binary> --list --format terse [--ignored]");
3255 eprintln!(" <binary> --exact <test_name> --nocapture");
3256 std::process::exit(1)
3257}
3258
3259#[cfg(test)]
3260#[path = "dispatch_tests.rs"]
3261mod tests;