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}