ktstr/test_support/
host_class.rs

1//! Shared classification of test-body host-insufficiency errors.
2//!
3//! Single source of truth for the guard ORDER and the per-class
4//! skip/fail policy applied to the typed host-resource errors a test
5//! build/run can surface. Both consumers call [`classify_host_error`]
6//! and only choose the rendering:
7//! - `err_to_exit_code` (in `super::dispatch`) maps [`HostClass`] to a
8//!   process exit code (skip → `EXIT_PASS`, fail → `EXIT_FAIL`).
9//! - the `#[ktstr_test]` macro body maps it to libtest control flow
10//!   (skip → `eprintln!` + `return`, fail → `panic!`).
11//!
12//! Keeping the classification here — not duplicated in each consumer —
13//! means a reorder or a new host-class type is a one-function edit both
14//! sites inherit, eliminating the dispatch-vs-codegen guard-order
15//! divergence (the two sites previously ordered the same guards
16//! differently, correct only by the types' mutual exclusivity).
17//!
18//! Scope: the SIX host-insufficiency types BOTH sites classify —
19//! [`KernelUnavailable`] (no kernel image resolved — the harness cannot
20//! boot a VM here), [`PerfModeUnavailable`], [`CpuBudgetUnsatisfiable`],
21//! [`TopologyUnrepresentable`], [`ResourceContention`], and
22//! [`TopologyInsufficient`]. A `KernelUnavailable` reaches this classifier
23//! on every nextest invocation: nextest suppresses the plain `#[test]`
24//! wrapper, so a VM entry runs as `ktstr/{name}` (and a host-only entry as
25//! `host/{name}`) via the `--exact` dispatch → `run_named_test` →
26//! `err_to_exit_code`, NOT the macro body. It is a SKIP
27//! by default — a developer running `cargo nextest run`, or `cargo ktstr
28//! test` without `--kernel`, on a kernel-less host gets a clean skip rather
29//! than a hard fail on every entry — promoted to a FAIL under
30//! `KTSTR_NO_SKIP_MODE`. This cannot mask a CI kernel-build failure: a
31//! `--kernel` the orchestrator FAILS to build bails in cargo-ktstr
32//! (`resolve_kernel_set`) before nextest is spawned, so `KernelUnavailable`
33//! here only ever means "no kernel was requested", never "a requested
34//! kernel failed to build".
35//!
36//! [`PerfModeUnavailable`]: crate::vmm::host_topology::PerfModeUnavailable
37//! [`CpuBudgetUnsatisfiable`]: crate::vmm::host_topology::CpuBudgetUnsatisfiable
38//! [`TopologyUnrepresentable`]: crate::vmm::host_topology::TopologyUnrepresentable
39//! [`ResourceContention`]: crate::vmm::host_topology::ResourceContention
40//! [`TopologyInsufficient`]: crate::vmm::host_topology::TopologyInsufficient
41//! [`KernelUnavailable`]: crate::test_support::eval::KernelUnavailable
42
43use super::{
44    is_cpu_budget_unsatisfiable, is_kernel_unavailable, is_perf_mode_unavailable,
45    is_resource_contention, is_topology_insufficient, is_topology_unrepresentable,
46};
47use crate::test_support::eval::KernelUnavailable;
48use crate::vmm::host_topology::{
49    CpuBudgetUnsatisfiable, PerfModeUnavailable, ResourceContention, TopologyInsufficient,
50    TopologyUnrepresentable,
51};
52
53/// Outcome of classifying a test-body error against the
54/// host-insufficiency taxonomy.
55///
56/// The `reason` strings are BARE — they carry NO `ktstr: SKIP:` /
57/// `ktstr: FAIL:` prefix. Each consumer adds the prefix in its own
58/// channel: dispatch routes [`Skip`](HostClass::Skip) through
59/// `report::test_skip` (which prepends `ktstr: SKIP:`) and `eprintln!`s
60/// [`Fail`](HostClass::Fail) as `ktstr: FAIL: {reason}`; the macro
61/// `eprintln!`s the skip and `panic!`s the fail with the same two
62/// prefixes.
63#[derive(Debug, Clone, PartialEq, Eq)]
64pub enum HostClass {
65    /// Not one of the six host-insufficiency types — the consumer
66    /// applies its own per-site handling (dispatch: the
67    /// `PostVmAssertionFailure` / `ExpectAutoReproSatisfied` /
68    /// `expect_err` / catch-all arms; macro: the `expect_err` swallow or
69    /// the `expect_ok` panic).
70    NotHostClass,
71    /// The host cannot run the test and no retry changes that
72    /// (`KTSTR_NO_SKIP_MODE` unset). A visible, non-failing skip.
73    Skip { reason: String },
74    /// A failure: an unconditional hard-fail type
75    /// (`CpuBudgetUnsatisfiable` / `TopologyUnrepresentable`), a
76    /// `ResourceContention` (RETRYABLE — the run path already waited the
77    /// holder out, so a residual hit is re-run by nextest, never skipped),
78    /// or a skip-class type promoted to a failure under `KTSTR_NO_SKIP_MODE`.
79    Fail { reason: String },
80}
81
82/// Walk the error chain for a `T` cause and clone its reason string.
83///
84/// Chain-aware (mirrors the `is_*` predicates): a typed error wrapped in
85/// `.context(...)` (e.g. the eval-layer `"build ktstr_test VM"` /
86/// `"run ktstr_test VM"` wrappers) is still found. Falls back to
87/// `"<unknown>"` if the cause is somehow absent — only reachable if an
88/// `is_*` predicate matched a `T` this extractor then missed, which the
89/// shared chain walk makes impossible in practice.
90fn extract_reason<T, F>(e: &anyhow::Error, reason: F) -> String
91where
92    T: std::error::Error + Send + Sync + 'static,
93    F: Fn(&T) -> String,
94{
95    e.chain()
96        .find_map(|cause| cause.downcast_ref::<T>().map(&reason))
97        .unwrap_or_else(|| "<unknown>".to_string())
98}
99
100/// Tag a host-DRIVEN skip-class error with the short class string the
101/// end-of-run footer groups by, or `None` when `e` is not one of the
102/// three host-insufficiency skip types.
103///
104/// Scoped deliberately narrower than [`classify_host_error`]: only the
105/// two types whose skip is caused by GENUINE, PERMANENT host
106/// incapacity — [`TopologyInsufficient`] (host lacks the CPUs/LLCs to
107/// boot the topology) and [`PerfModeUnavailable`] (host too small for
108/// perf mode). These are host-SHAPE facts: no retry and no waiting
109/// changes them, so the footer's "what could THIS HOST not run" block
110/// is the right home.
111///
112/// [`ResourceContention`] is DELIBERATELY excluded: a busy slot is
113/// TRANSIENT, not a host-shape fact. Queue-based lock acquisition
114/// waits for authoritative release, while other transient host
115/// resource failures are routed to a RETRYABLE failure by
116/// [`classify_host_error`], never a
117/// host-skip marker — so a colocated peer's `LOCK_EX` can never be
118/// mislabelled "this host cannot run". The unconditional hard-fail
119/// types and `KernelUnavailable` ("harness not configured", not a
120/// host-shape fact) are excluded for the same "not permanent host
121/// incapacity" reason. Chain-aware via the shared `is_*` predicates;
122/// guard order is arbitrary (the two types are mutually exclusive).
123pub(crate) fn host_skip_class(e: &anyhow::Error) -> Option<&'static str> {
124    if is_topology_insufficient(e) {
125        Some("topology_insufficient")
126    } else if is_perf_mode_unavailable(e) {
127        Some("perf_mode_unavailable")
128    } else {
129        None
130    }
131}
132
133/// Classify a test-body error against the host-insufficiency taxonomy.
134///
135/// `no_skip` is `KTSTR_NO_SKIP_MODE` — passed in (not read from the
136/// environment here) so the function stays pure and unit-testable
137/// without env mutation. Each caller reads the env once
138/// (`result_to_exit_code` for dispatch; the generated body for the
139/// macro) and threads it in.
140///
141/// The guard ORDER and the per-class skip/fail policy below are the
142/// single source of truth shared by both consumers. `expect_err` is
143/// deliberately NOT a parameter: a host-class outcome is invariant under
144/// it (a skip stays a skip, a hard fail stays a hard fail) — `expect_err`
145/// is a test-outcome concern each consumer handles after a
146/// [`HostClass::NotHostClass`] result. The `reason` strings reconstruct
147/// the exact banners the two sites emitted before this was extracted
148/// (minus the prefix, which the consumer adds).
149pub fn classify_host_error(e: &anyhow::Error, no_skip: bool) -> HostClass {
150    if is_kernel_unavailable(e) {
151        // No kernel image resolved: the harness cannot boot a VM here (the
152        // binary was run outside `cargo ktstr test`, or `cargo ktstr test`
153        // was run without `--kernel` on a host with no cached/discoverable
154        // kernel). A skip by default — a missing kernel on the runner is a
155        // "not configured here" condition, not a test failure — promoted to
156        // a FAIL under KTSTR_NO_SKIP_MODE for runs that demand execution. A
157        // requested-but-unbuildable `--kernel` bails in cargo-ktstr before
158        // nextest spawns, so this never masks a CI kernel-build failure.
159        let reason = extract_reason::<KernelUnavailable, _>(e, |k| k.diagnostic.clone());
160        return if no_skip {
161            HostClass::Fail {
162                reason: format!(
163                    "harness not configured under --no-skip-mode: {reason}. \
164                     Provide a kernel via --kernel or KTSTR_TEST_KERNEL, or drop \
165                     --no-skip-mode."
166                ),
167            }
168        } else {
169            HostClass::Skip {
170                reason: format!("harness not configured: {reason}"),
171            }
172        };
173    }
174    if is_perf_mode_unavailable(e) {
175        let reason = extract_reason::<PerfModeUnavailable, _>(e, |p| p.reason.clone());
176        return if no_skip {
177            HostClass::Fail {
178                reason: format!(
179                    "performance mode unavailable under --no-skip-mode: {reason}. \
180                     Provision a host with the required CPU / LLC count, narrow the \
181                     test topology, or drop --perf-mode / --no-skip-mode."
182                ),
183            }
184        } else {
185            HostClass::Skip {
186                reason: format!("performance mode unavailable: {reason}"),
187            }
188        };
189    }
190    if is_cpu_budget_unsatisfiable(e) {
191        let reason = extract_reason::<CpuBudgetUnsatisfiable, _>(e, |b| b.reason.clone());
192        return HostClass::Fail {
193            reason: format!("cpu budget unsatisfiable: {reason}"),
194        };
195    }
196    if is_topology_unrepresentable(e) {
197        let reason = extract_reason::<TopologyUnrepresentable, _>(e, |t| t.reason.clone());
198        return HostClass::Fail {
199            reason: format!("topology unrepresentable: {reason}"),
200        };
201    }
202    if is_resource_contention(e) {
203        let reason = extract_reason::<ResourceContention, _>(e, |rc| rc.reason.clone());
204        // TRANSIENT contention, never permanent host incapacity.
205        // Producers include one-shot non-waiting lock acquisition and
206        // the transient-KVM-errno mapper in `crate::vmm::contention`
207        // (ENOMEM / EMFILE / EBUSY under host pressure). Queue-based
208        // test acquisition waits for authoritative flock release and
209        // does not invent this verdict from elapsed wall time. The
210        // remaining producers resolve on re-run, so route to a RETRYABLE
211        // failure nextest re-runs — NOT a silent skip (a skip is a pass
212        // nextest never retries, which silently guts suite coverage) and
213        // NOT a "this host cannot run" host-skip. `no_skip` does not
214        // change this: it is already a failure.
215        return HostClass::Fail {
216            reason: format!(
217                "transient resource contention: {reason}. Retryable — nextest \
218                 re-runs the cell; this is host busyness, not host incapacity. \
219                 A persistent hit means the host is oversubscribed, not unable \
220                 to run the test."
221            ),
222        };
223    }
224    if is_topology_insufficient(e) {
225        let reason = extract_reason::<TopologyInsufficient, _>(e, |ti| ti.reason.clone());
226        return if no_skip {
227            HostClass::Fail {
228                reason: format!(
229                    "host topology insufficient under --no-skip-mode: {reason}. \
230                     Either provision a host with the required CPU / LLC count, or drop \
231                     --no-skip-mode / KTSTR_NO_SKIP_MODE to accept the skip."
232                ),
233            }
234        } else {
235            HostClass::Skip {
236                reason: format!("host topology insufficient: {reason}"),
237            }
238        };
239    }
240    HostClass::NotHostClass
241}
242
243#[cfg(test)]
244mod tests {
245    use super::*;
246
247    /// A no-kernel host (KernelUnavailable) skips by default — a missing
248    /// kernel on the runner is "not configured here", not a test failure —
249    /// and is promoted to a hard fail under `no_skip`. The bare reason is
250    /// the extracted diagnostic.
251    #[test]
252    fn kernel_unavailable_skip_then_fail() {
253        let mk = || {
254            anyhow::Error::new(KernelUnavailable {
255                diagnostic: "no kernel image resolved".into(),
256            })
257        };
258        match classify_host_error(&mk(), false) {
259            HostClass::Skip { reason } => {
260                assert_eq!(reason, "harness not configured: no kernel image resolved");
261            }
262            other => panic!("expected Skip, got {other:?}"),
263        }
264        match classify_host_error(&mk(), true) {
265            HostClass::Fail { reason } => {
266                assert!(reason.starts_with("harness not configured under --no-skip-mode:"));
267                assert!(reason.contains("no kernel image resolved"));
268            }
269            other => panic!("expected Fail, got {other:?}"),
270        }
271    }
272
273    /// A perf-mode-too-small error skips by default and is promoted to a
274    /// hard fail only under `no_skip`. The reason text is the bare,
275    /// prefix-free form each consumer renders.
276    #[test]
277    fn perf_mode_unavailable_skip_then_fail() {
278        let mk = || {
279            anyhow::Error::new(PerfModeUnavailable {
280                reason: "host too small for perf topology".into(),
281            })
282        };
283        match classify_host_error(&mk(), false) {
284            HostClass::Skip { reason } => {
285                assert_eq!(
286                    reason,
287                    "performance mode unavailable: host too small for perf topology"
288                );
289            }
290            other => panic!("expected Skip, got {other:?}"),
291        }
292        match classify_host_error(&mk(), true) {
293            HostClass::Fail { reason } => {
294                assert!(reason.starts_with("performance mode unavailable under --no-skip-mode:"));
295                assert!(reason.contains("host too small for perf topology"));
296            }
297            other => panic!("expected Fail, got {other:?}"),
298        }
299    }
300
301    /// Resource contention is a RETRYABLE FAILURE, never a skip — under
302    /// BOTH `no_skip` settings. The run path already waited the holder out;
303    /// anything that still surfaces must be re-run by nextest, not silently
304    /// greened (a skip is EXIT_PASS, which nextest never retries) and never
305    /// tagged "this host cannot run".
306    #[test]
307    fn resource_contention_is_retryable_fail() {
308        let mk = || {
309            anyhow::Error::new(ResourceContention {
310                reason: "all 3 LLC slots busy".into(),
311            })
312        };
313        for no_skip in [false, true] {
314            match classify_host_error(&mk(), no_skip) {
315                HostClass::Fail { reason } => {
316                    assert!(
317                        reason.contains("resource contention") && reason.contains("transient"),
318                        "must name transient contention (no_skip={no_skip}); got: {reason}",
319                    );
320                    assert!(
321                        !reason.contains("this host cannot run"),
322                        "must NOT read as host incapacity (no_skip={no_skip}); got: {reason}",
323                    );
324                }
325                other => panic!("expected Fail (no_skip={no_skip}), got {other:?}"),
326            }
327        }
328    }
329
330    /// Topology insufficient: skip default, fail under `no_skip`.
331    #[test]
332    fn topology_insufficient_skip_then_fail() {
333        let mk = || {
334            anyhow::Error::new(TopologyInsufficient {
335                reason: "host has too few CPUs".into(),
336            })
337        };
338        assert_eq!(
339            classify_host_error(&mk(), false),
340            HostClass::Skip {
341                reason: "host topology insufficient: host has too few CPUs".into()
342            }
343        );
344        match classify_host_error(&mk(), true) {
345            HostClass::Fail { reason } => {
346                assert!(reason.starts_with("host topology insufficient under --no-skip-mode:"));
347            }
348            other => panic!("expected Fail, got {other:?}"),
349        }
350    }
351
352    /// Cpu-budget-unsatisfiable is an UNCONDITIONAL hard fail — `no_skip`
353    /// does not change it (it is already a failure).
354    #[test]
355    fn cpu_budget_unsatisfiable_always_fails() {
356        let mk = || {
357            anyhow::Error::new(CpuBudgetUnsatisfiable {
358                reason: "--cpu-cap exceeds allowed CPUs".into(),
359            })
360        };
361        for no_skip in [false, true] {
362            match classify_host_error(&mk(), no_skip) {
363                HostClass::Fail { reason } => {
364                    assert_eq!(
365                        reason,
366                        "cpu budget unsatisfiable: --cpu-cap exceeds allowed CPUs"
367                    );
368                }
369                other => panic!("expected Fail (no_skip={no_skip}), got {other:?}"),
370            }
371        }
372    }
373
374    /// Topology-unrepresentable is an UNCONDITIONAL hard fail.
375    #[test]
376    fn topology_unrepresentable_always_fails() {
377        let mk = || {
378            anyhow::Error::new(TopologyUnrepresentable {
379                reason: "aarch64 vcpus exceed GICv3 redistributor capacity".into(),
380            })
381        };
382        for no_skip in [false, true] {
383            match classify_host_error(&mk(), no_skip) {
384                HostClass::Fail { reason } => {
385                    assert!(reason.starts_with("topology unrepresentable:"));
386                }
387                other => panic!("expected Fail (no_skip={no_skip}), got {other:?}"),
388            }
389        }
390    }
391
392    /// `host_skip_class` tags exactly the two PERMANENT host-shape skip
393    /// types and nothing else — the footer's host-skip block is scoped to
394    /// "what could THIS HOST not run", so a hard-fail type, a transient
395    /// contention, KernelUnavailable, or a plain error must yield `None`.
396    #[test]
397    fn host_skip_class_tags_only_host_shape_skips() {
398        assert_eq!(
399            host_skip_class(&anyhow::Error::new(TopologyInsufficient {
400                reason: "too few CPUs".into()
401            })),
402            Some("topology_insufficient"),
403        );
404        assert_eq!(
405            host_skip_class(&anyhow::Error::new(PerfModeUnavailable {
406                reason: "host too small".into()
407            })),
408            Some("perf_mode_unavailable"),
409        );
410        // Transient contention is NOT a host-shape skip: a busy slot is
411        // waited out / retried, never "this host cannot run". Chain-aware
412        // form must also yield None so a `.context(...)`-wrapped contention
413        // can never leak into the host-skip footer.
414        assert_eq!(
415            host_skip_class(&anyhow::Error::new(ResourceContention {
416                reason: "slots busy".into()
417            })),
418            None,
419        );
420        assert_eq!(
421            host_skip_class(
422                &anyhow::Error::new(ResourceContention {
423                    reason: "slots busy".into()
424                })
425                .context("run ktstr_test VM")
426            ),
427            None,
428        );
429        // Not host-shape: a hard-fail type, a missing kernel, a plain error.
430        assert_eq!(
431            host_skip_class(&anyhow::Error::new(CpuBudgetUnsatisfiable {
432                reason: "cap too big".into()
433            })),
434            None,
435        );
436        assert_eq!(
437            host_skip_class(&anyhow::Error::new(KernelUnavailable {
438                diagnostic: "no kernel".into()
439            })),
440            None,
441        );
442        assert_eq!(
443            host_skip_class(&anyhow::anyhow!("scheduler regression")),
444            None
445        );
446    }
447
448    /// A plain (non-typed) error and the test-outcome markers are NOT
449    /// host-class — the classifier returns `NotHostClass` so each
450    /// consumer's own marker / expect_err / catch-all handling runs. A
451    /// classifier that swallowed these would erase real failures.
452    #[test]
453    fn non_host_error_is_not_host_class() {
454        let plain = anyhow::anyhow!("scheduler regression: workload did not get the CPU it needs");
455        assert_eq!(classify_host_error(&plain, false), HostClass::NotHostClass);
456        assert_eq!(classify_host_error(&plain, true), HostClass::NotHostClass);
457    }
458
459    /// Chain-aware: a typed error wrapped in `.context(...)` (the
460    /// production shape — the eval layer wraps every build/run error)
461    /// still classifies, and the extracted reason is the inner typed
462    /// reason, NOT the wrapping context layer.
463    #[test]
464    fn classifies_through_context_wrap() {
465        let wrapped = anyhow::Error::new(ResourceContention {
466            reason: "all 3 LLC slots busy".into(),
467        })
468        .context("build ktstr_test VM")
469        .context("run ktstr_test VM");
470        match classify_host_error(&wrapped, false) {
471            HostClass::Fail { reason } => {
472                // Extracted reason is the inner typed reason, not the
473                // wrapping context layer.
474                assert!(
475                    reason.contains("all 3 LLC slots busy"),
476                    "must surface the inner typed reason; got: {reason}",
477                );
478            }
479            other => panic!("expected Fail, got {other:?}"),
480        }
481    }
482}