ktstr/assert/builder.rs
1use super::*;
2
3/// Unified assertion configuration. Carries both worker checks and
4/// monitor thresholds as a single composable type. Each `Option` field
5/// acts as an override — `None` means "inherit from parent layer".
6///
7/// Construct via [`Assert::NO_OVERRIDES`] (preferred const baseline)
8/// or [`Assert::default_checks`] (currently aliases NO_OVERRIDES);
9/// chain builder methods on either base (all builders are `const fn`
10/// except [`Assert::expect_scx_bpf_error_matches`], which compiles a
11/// regex at construction). Use the resulting `Assert` value as the
12/// `assert` field of a [`Scheduler`](crate::test_support::Scheduler)
13/// declared via [`declare_scheduler!`](crate::declare_scheduler) — the
14/// macro accepts `assert = Assert::NO_OVERRIDES.foo()`-style chains
15/// at the scheduler level. The `#[ktstr_test]` proc macro does NOT
16/// accept an `assert = …` attribute on test entries; per-field
17/// attribute shortcuts (`max_gap_ms = N`, `not_stuck = true`, …)
18/// compose into the equivalent struct literal at expansion time.
19///
20/// Merge order: `Assert::default_checks()` -> `Scheduler.assert` -> per-test `assert`.
21/// `default_checks()` is `NO_OVERRIDES` — all assertions are opt-in.
22///
23/// ```
24/// # use ktstr::assert::Assert;
25/// // Scheduler opts into imbalance checking.
26/// let sched_assert = Assert::NO_OVERRIDES.max_imbalance_ratio(5.0);
27///
28/// // Merge: defaults <- scheduler <- test.
29/// let merged = Assert::default_checks()
30/// .merge(&sched_assert)
31/// .merge(&Assert::NO_OVERRIDES.max_gap_ms(5000));
32///
33/// assert_eq!(merged.not_stuck, None); // not opted in
34/// assert_eq!(merged.max_imbalance_ratio, Some(5.0)); // from sched
35/// assert_eq!(merged.max_gap_ms, Some(5000)); // from test
36/// ```
37///
38/// # Serde roundtrip — covers the 20 threshold/check fields only
39///
40/// The serde derive at the struct level covers the 20 threshold +
41/// flag fields (every `Option<bool/u64/f64/u32/usize>` plus the bare
42/// `enforce_monitor_thresholds: bool`). The two reproducer-matcher
43/// fields ([`Self::expect_scx_bpf_error_contains`] and
44/// [`Self::expect_scx_bpf_error_matches`]) carry `#[serde(skip)]`
45/// because their `&'static str` shape cannot round-trip through a
46/// borrowed deserializer — see each field's doc for the rationale.
47/// Sidecar consumers comparing
48/// threshold config across runs treat reproducer matcher strings as
49/// part of the test identity (encoded by name in the sidecar key),
50/// not part of the threshold payload, so the skip is operationally
51/// transparent today.
52#[must_use = "builder methods return a new Assert; discard means config is lost"]
53#[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize)]
54pub struct Assert {
55 // Worker checks
56 /// Enable zero-work, fairness-spread, and stuck-gap checks across
57 /// worker reports. `Some(true)` enables, `Some(false)` explicitly
58 /// disables (overriding any enabling merge from a lower layer),
59 /// `None` inherits from the merge parent.
60 pub not_stuck: Option<bool>,
61 /// Enable per-worker CPU isolation checks (ensure workers remain
62 /// within their assigned cpuset). Same tri-state semantics as
63 /// `not_stuck`.
64 pub isolation: Option<bool>,
65 /// Max per-worker progress gap in milliseconds of worker CPU-TIME:
66 /// fails if any worker consumed more than this much
67 /// `CLOCK_THREAD_CPUTIME_ID` between 1024-work-unit progress
68 /// checkpoints (compute-without-progress — a livelock or a
69 /// pathologically expensive iteration). CPU-denominated, so the gate
70 /// is dilation-safe: host preemption and guest run-queue wait accrue
71 /// no CPU. A BLOCKED or starved-runnable worker likewise accrues no
72 /// CPU — blocked-stuck detection is the cell watchdog's domain. The
73 /// historical wall-clock gap rides in the failure message (and
74 /// `WorkerReport::max_gap_wall_ms`) as evidence.
75 pub max_gap_ms: Option<u64>,
76 /// Max per-cgroup fairness spread as a percentage. Fails if the
77 /// range between the most- and least-served workers exceeds this
78 /// fraction of their mean.
79 pub max_spread_pct: Option<f64>,
80
81 // Throughput checks
82 /// Max coefficient of variation for work_units/cpu_time across workers.
83 /// Catches placement unfairness where some workers get less CPU than others.
84 pub max_throughput_cv: Option<f64>,
85 /// Minimum work_units per CPU-second. Catches cases where all workers
86 /// are equally slow (CV passes but absolute throughput is too low).
87 pub min_work_rate: Option<f64>,
88
89 // Benchmarking checks
90 /// Max p99 wake latency in NANOSECONDS. Fails if the pooled
91 /// p99 across every worker's `wake_latencies_ns` exceeds this.
92 ///
93 /// # Unit-name gotcha
94 ///
95 /// The threshold is `_ns`, but the paired reporting field on
96 /// [`CgroupStats::p99_wake_latency_us`] and the re-pooled run-level
97 /// `worst_p99_wake_latency_us` ext metric (a `MetricKind::Distribution`)
98 /// are MICROSECONDS. The two surfaces are intentionally split:
99 /// - the threshold uses NS for precision (typical scheduler
100 /// wake latencies are single-digit µs, so sub-µs resolution
101 /// matters for regression gates);
102 /// - the reporting fields use US for readability in
103 /// `perf-delta` / dashboard output.
104 ///
105 /// Both are computed from the same underlying
106 /// [`WorkerReport::wake_latencies_ns`] samples — see
107 /// [`assert_benchmarks`] for the threshold path and
108 /// [`assert_not_stuck`] for the reporting path. A bare
109 /// comparison of `max_p99_wake_latency_ns` against
110 /// `CgroupStats::p99_wake_latency_us` is a unit-mismatch bug;
111 /// `assert_benchmarks` never does this — it consumes the raw
112 /// `wake_latencies_ns` directly — and
113 /// `assert_p99_ns_threshold_compares_against_ns_latencies` pins
114 /// that contract.
115 pub max_p99_wake_latency_ns: Option<u64>,
116 /// Max wake latency coefficient of variation. Fails if CV exceeds this.
117 pub max_wake_latency_cv: Option<f64>,
118 /// Minimum iterations per CPU-second (`iterations / cpu_time_sec`)
119 /// per worker. Fails if any worker is below. CPU-denominated so the
120 /// floor is intrinsically dilation-safe — host preemption inflates
121 /// wall time but not CPU time — measuring the workload, not the
122 /// host. In performance mode (wall ≈ CPU) it matches the historical
123 /// wall-rate number; a worker that spent zero CPU time rates 0 and
124 /// fails any positive floor. See [`assert_benchmarks`].
125 pub min_iteration_rate: Option<f64>,
126 /// Max migration ratio (migrations/iterations). Fails if any cgroup exceeds this.
127 pub max_migration_ratio: Option<f64>,
128
129 // Monitor checks
130 /// Max `nr_running` / LLC imbalance ratio observed by the monitor.
131 /// Fails if the worst sample's imbalance exceeds this.
132 pub max_imbalance_ratio: Option<f64>,
133 /// Max local DSQ depth observed by the monitor. Fails if any
134 /// sampled CPU's local DSQ grew beyond this.
135 pub max_local_dsq_depth: Option<u32>,
136 /// Treat an rq_clock-stuck verdict from the monitor as a hard failure. Same
137 /// tri-state semantics as `not_stuck`.
138 pub fail_on_rq_clock_stuck: Option<bool>,
139 /// Minimum number of consecutive samples that must exceed the
140 /// monitor threshold before a verdict is raised. Smooths out
141 /// single-sample spikes.
142 pub sustained_samples: Option<usize>,
143 /// Max `select_cpu_fallback` activity per average delivered vCPU
144 /// CPU-second. Fails if a sustained monitor interval exceeds this rate.
145 pub max_fallback_rate: Option<f64>,
146 /// Max `keep_last` activity per average delivered vCPU CPU-second.
147 /// Fails if a sustained monitor interval exceeds this rate.
148 pub max_keep_last_rate: Option<f64>,
149 /// Promote monitor threshold violations from report-only to
150 /// pass/fail. When `false` (the default), the monitor still walks
151 /// every sample and records every violation in the verdict's
152 /// `details`, but the verdict's `passed` stays `true`. Tests that
153 /// want monitor violations to fail the run call
154 /// [`Self::with_monitor_defaults`], which populates each monitor
155 /// threshold from `MonitorThresholds::new()`
156 /// and sets this flag to `true`.
157 pub enforce_monitor_thresholds: bool,
158
159 // NUMA checks
160 /// Minimum fraction of pages on the expected NUMA node(s) (0.0-1.0).
161 /// Expected nodes are derived from the worker's
162 /// [`MemPolicy`](crate::workload::MemPolicy) at evaluation time.
163 /// Fails if the observed locality fraction falls below this.
164 pub min_page_locality: Option<f64>,
165 /// Maximum ratio of NUMA-node-migrated pages to total allocated
166 /// pages (0.0-1.0). Distinct from [`max_migration_ratio`](Self::max_migration_ratio)
167 /// which measures CPU migrations per iteration. Fails if the
168 /// observed migration ratio exceeds this.
169 pub max_cross_node_migration_ratio: Option<f64>,
170 /// Maximum fraction of pages on slow-tier (memory-only) NUMA nodes
171 /// (0.0-1.0). For CXL memory tiering tests: fails if more than
172 /// this fraction of pages land on memory-only nodes. Requires
173 /// `slow_tier_nodes` to be set at evaluation time.
174 pub max_slow_tier_ratio: Option<f64>,
175
176 /// Reproducer-mode literal-substring matcher for the captured
177 /// `scx_bpf_error` text. When `Some(literal)`, the eval pipeline
178 /// scans the combined scheduler log + sched_ext dump for a
179 /// substring match against `literal` and fails the test if the
180 /// substring is absent.
181 ///
182 /// Use this for the common case of pinning an exact error
183 /// fragment like `apply_cell_config returned -EINVAL` without
184 /// having to escape regex metacharacters. For pattern matching
185 /// with anchors / character classes / wildcards, use
186 /// [`Self::expect_scx_bpf_error_matches`] instead — the two
187 /// fields are orthogonal and can both be set (both must match).
188 ///
189 /// Requires the entry's `expect_err = true` — a reproducer
190 /// matcher only fires on expected-error tests; setting this on
191 /// a passing test would assert "the test passed AND contained
192 /// this error text," which is contradictory. The eval-time
193 /// validation rejects that combination with a clear diagnostic.
194 ///
195 /// Stored as `&'static str` so the const-fn `Self::merge`
196 /// composes without cloning. Empty strings are rejected at
197 /// evaluation (an empty literal would silently match every
198 /// message and turn this assertion into a no-op).
199 /// `#[serde(skip)]` because the field's `&'static str` shape
200 /// cannot round-trip through a borrowed deserializer (no source-
201 /// string lifetime to bind to). Reproducer matcher strings are
202 /// test-author static literals carried in the test definition
203 /// itself, not per-run data the sidecar needs to roundtrip — so
204 /// skipping them on the wire keeps the JSON shape clean without
205 /// losing any sidecar-consumer functionality. Skipped fields
206 /// default to `None` on deserialize per `Option::default()`.
207 ///
208 /// The `Option<Cow<'static, str>>` alternative that WOULD
209 /// roundtrip is rejected because it cascade-breaks
210 /// `Scheduler::assert`'s const-fn (`Cow` has a heap destructor,
211 /// which breaks the const-fn assignment path used by
212 /// `declare_scheduler!` macro statics). A future decomposition
213 /// into a `ReproducerMatchers` sub-config could revisit this if
214 /// sidecar-loaded test definitions ever need the strings to
215 /// survive end-to-end.
216 #[serde(skip)]
217 pub expect_scx_bpf_error_contains: Option<&'static str>,
218
219 /// Reproducer-mode regex matcher for the captured `scx_bpf_error`
220 /// text. When `Some(pattern)`, the eval pipeline compiles the
221 /// pattern via the `regex` crate, scans the combined scheduler
222 /// log + sched_ext dump, and fails the test if the regex does
223 /// not match anywhere in the corpus.
224 ///
225 /// The pattern is a full regex — special characters
226 /// (`. * + ? ( ) [ ] { } | ^ $ \`) carry their regex meaning.
227 /// For literal-substring matching, prefer
228 /// [`Self::expect_scx_bpf_error_contains`] to avoid escape
229 /// footguns. The captured corpus is the multi-line concatenation
230 /// of the scheduler log and `--- sched_ext dump ---`; the regex
231 /// crate's default flags apply: `^` and `$` anchor to the start /
232 /// end of the WHOLE corpus (not individual lines), and `.` does
233 /// NOT cross `\n`. Opt in to line-level anchoring with `(?m)`
234 /// (e.g. `(?m)^apply_cell_config$`) and to newline-spanning
235 /// `.` with `(?s)`. A bare `apply_cell_config` matches the
236 /// token anywhere in the corpus.
237 ///
238 /// Requires the entry's `expect_err = true` — same rationale
239 /// as [`Self::expect_scx_bpf_error_contains`]. Patterns are
240 /// validated at construction: empty literals, invalid regex
241 /// syntax, and any pattern satisfying `is_match("")` all
242 /// panic via the [`Self::expect_scx_bpf_error_matches`]
243 /// builder. The `is_match("")` predicate catches two
244 /// no-op classes with one check: patterns that match every
245 /// position (e.g. `a?`, `.*`, `(?:)`) trivially pass against
246 /// any corpus, and patterns that match only the empty string
247 /// (e.g. `^$`) trivially fail against any non-empty corpus —
248 /// real captured scheduler-output corpora are non-empty, so
249 /// both classes are equally no-op pins. Bare `\b` (word
250 /// boundary) slips the gate because the empty string
251 /// contains no word characters; see the builder docstring
252 /// for the operator-direction.
253 /// `#[serde(skip)]` for the same reason as
254 /// [`Self::expect_scx_bpf_error_contains`] above: `&'static str`
255 /// doesn't roundtrip + the matcher pattern is test-definition
256 /// data, not sidecar-roundtrip data. Skipped fields default to
257 /// `None` on deserialize.
258 #[serde(skip)]
259 pub expect_scx_bpf_error_matches: Option<&'static str>,
260}
261
262impl Assert {
263 /// Human-readable multi-line dump of every threshold field. Each
264 /// field renders as ` name: value` (`none` when the option is
265 /// `None`, i.e. inherited or unset). Used by
266 /// `cargo ktstr show-thresholds <test>` to expose the resolved
267 /// merged `Assert` (`default_checks().merge(&entry.scheduler.assert).
268 /// merge(&entry.assert)`) without forcing the operator to read
269 /// the Debug impl or source. Output is a sequence of indented
270 /// `row` lines ending with a newline; the caller owns any
271 /// outer section header (the `show-thresholds` CLI already
272 /// prints `Test: ...` / `Scheduler: ...` / `Resolved assertion
273 /// thresholds:` lines above the threshold block, and
274 /// `format_human` emits no outer header of its own so it does
275 /// not duplicate that banner).
276 pub fn format_human(&self) -> String {
277 use std::fmt::Write;
278 let mut out = String::new();
279 fn row<T: std::fmt::Display>(out: &mut String, name: &str, v: &Option<T>) {
280 match v {
281 Some(x) => writeln!(out, " {name:<38}: {x}").unwrap(),
282 None => writeln!(out, " {name:<38}: none").unwrap(),
283 }
284 }
285 row(&mut out, "not_stuck", &self.not_stuck);
286 row(&mut out, "isolation", &self.isolation);
287 row(&mut out, "max_gap_ms", &self.max_gap_ms);
288 row(&mut out, "max_spread_pct", &self.max_spread_pct);
289 row(&mut out, "max_throughput_cv", &self.max_throughput_cv);
290 row(&mut out, "min_work_rate", &self.min_work_rate);
291 row(
292 &mut out,
293 "max_p99_wake_latency_ns",
294 &self.max_p99_wake_latency_ns,
295 );
296 row(&mut out, "max_wake_latency_cv", &self.max_wake_latency_cv);
297 row(&mut out, "min_iteration_rate", &self.min_iteration_rate);
298 row(&mut out, "max_migration_ratio", &self.max_migration_ratio);
299 row(&mut out, "max_imbalance_ratio", &self.max_imbalance_ratio);
300 row(&mut out, "max_local_dsq_depth", &self.max_local_dsq_depth);
301 row(
302 &mut out,
303 "fail_on_rq_clock_stuck",
304 &self.fail_on_rq_clock_stuck,
305 );
306 row(&mut out, "sustained_samples", &self.sustained_samples);
307 row(&mut out, "max_fallback_rate", &self.max_fallback_rate);
308 row(&mut out, "max_keep_last_rate", &self.max_keep_last_rate);
309 row(&mut out, "min_page_locality", &self.min_page_locality);
310 row(
311 &mut out,
312 "max_cross_node_migration_ratio",
313 &self.max_cross_node_migration_ratio,
314 );
315 row(&mut out, "max_slow_tier_ratio", &self.max_slow_tier_ratio);
316 row(
317 &mut out,
318 "expect_scx_bpf_error_contains",
319 &self.expect_scx_bpf_error_contains,
320 );
321 row(
322 &mut out,
323 "expect_scx_bpf_error_matches",
324 &self.expect_scx_bpf_error_matches,
325 );
326 out
327 }
328
329 /// Identity element for [`Assert::merge`]: every Option field is
330 /// `None` and `enforce_monitor_thresholds` is `false`, so neither
331 /// side of a merge with `NO_OVERRIDES` is altered.
332 /// Identical to the value returned by [`Self::default_checks`] —
333 /// the const is for spread-into-struct-literal composition, the
334 /// const fn is the method-style entry point.
335 pub const NO_OVERRIDES: Assert = Assert {
336 not_stuck: None,
337 isolation: None,
338 max_gap_ms: None,
339 max_spread_pct: None,
340 max_throughput_cv: None,
341 min_work_rate: None,
342 max_p99_wake_latency_ns: None,
343 max_wake_latency_cv: None,
344 min_iteration_rate: None,
345 max_migration_ratio: None,
346 max_imbalance_ratio: None,
347 max_local_dsq_depth: None,
348 fail_on_rq_clock_stuck: None,
349 sustained_samples: None,
350 max_fallback_rate: None,
351 max_keep_last_rate: None,
352 enforce_monitor_thresholds: false,
353 min_page_locality: None,
354 max_cross_node_migration_ratio: None,
355 max_slow_tier_ratio: None,
356 expect_scx_bpf_error_contains: None,
357 expect_scx_bpf_error_matches: None,
358 };
359
360 /// Baseline of the runtime merge chain
361 /// `default_checks().merge(&scheduler.assert).merge(&entry.assert)`.
362 ///
363 /// All checks are off by default — tests opt in to the assertions
364 /// they care about via scheduler-level or per-test `Assert`
365 /// overrides.
366 ///
367 /// For spread-into-struct-literal composition
368 /// (`Assert { not_stuck: Some(true), ..Assert::NO_OVERRIDES }`)
369 /// use the equivalent const [`Self::NO_OVERRIDES`]; this const fn
370 /// is the method-style entry point that pairs with `.verdict()`
371 /// and the builder setters.
372 pub const fn default_checks() -> Assert {
373 Self::NO_OVERRIDES
374 }
375
376 /// Build a fresh [`Verdict`] under this `Assert`'s threshold
377 /// config. The returned accumulator carries no claim records; call
378 /// the typed `claim_<field>` methods generated by
379 /// [`#[derive(Claim)]`](ktstr_macros::Claim) on stats structs as
380 /// `stats.claim_<field>(&mut verdict)`, or use the
381 /// [`claim!`](crate::claim) macro on a local/expression, then
382 /// call [`Verdict::into_result`] to produce the final
383 /// [`AssertResult`].
384 ///
385 /// This is the entry point of the pointwise-claim API. The
386 /// `Assert` itself remains pure threshold config and stays
387 /// `Copy`; per-test claims accumulate on the returned `Verdict`,
388 /// which owns its own buffers (details, stats).
389 ///
390 /// ```
391 /// # use ktstr::assert::Assert;
392 /// let r = Assert::default_checks().verdict().into_result();
393 /// assert!(r.is_pass(), "no claims means passing verdict");
394 /// ```
395 pub fn verdict(self) -> Verdict {
396 Verdict::with_assert(self)
397 }
398
399 pub const fn check_not_stuck(mut self) -> Self {
400 self.not_stuck = Some(true);
401 self
402 }
403
404 pub const fn check_isolation(mut self) -> Self {
405 self.isolation = Some(true);
406 self
407 }
408
409 pub const fn max_gap_ms(mut self, ms: u64) -> Self {
410 self.max_gap_ms = Some(ms);
411 self
412 }
413
414 pub const fn max_spread_pct(mut self, pct: f64) -> Self {
415 self.max_spread_pct = Some(pct);
416 self
417 }
418
419 pub const fn max_throughput_cv(mut self, v: f64) -> Self {
420 self.max_throughput_cv = Some(v);
421 self
422 }
423
424 pub const fn min_work_rate(mut self, v: f64) -> Self {
425 self.min_work_rate = Some(v);
426 self
427 }
428
429 pub const fn max_p99_wake_latency_ns(mut self, v: u64) -> Self {
430 self.max_p99_wake_latency_ns = Some(v);
431 self
432 }
433
434 pub const fn max_wake_latency_cv(mut self, v: f64) -> Self {
435 self.max_wake_latency_cv = Some(v);
436 self
437 }
438
439 pub const fn min_iteration_rate(mut self, v: f64) -> Self {
440 self.min_iteration_rate = Some(v);
441 self
442 }
443
444 pub const fn max_migration_ratio(mut self, v: f64) -> Self {
445 self.max_migration_ratio = Some(v);
446 self
447 }
448
449 pub const fn max_imbalance_ratio(mut self, v: f64) -> Self {
450 self.max_imbalance_ratio = Some(v);
451 self
452 }
453
454 pub const fn max_local_dsq_depth(mut self, v: u32) -> Self {
455 self.max_local_dsq_depth = Some(v);
456 self
457 }
458
459 /// Control whether a monitor rq_clock-stuck verdict fails the assertion.
460 pub const fn fail_on_rq_clock_stuck(mut self, v: bool) -> Self {
461 self.fail_on_rq_clock_stuck = Some(v);
462 self
463 }
464
465 /// Set the number of consecutive over-threshold samples required
466 /// before the monitor raises a verdict.
467 pub const fn sustained_samples(mut self, v: usize) -> Self {
468 self.sustained_samples = Some(v);
469 self
470 }
471
472 pub const fn max_fallback_rate(mut self, v: f64) -> Self {
473 self.max_fallback_rate = Some(v);
474 self
475 }
476
477 pub const fn max_keep_last_rate(mut self, v: f64) -> Self {
478 self.max_keep_last_rate = Some(v);
479 self
480 }
481
482 pub const fn min_page_locality(mut self, v: f64) -> Self {
483 self.min_page_locality = Some(v);
484 self
485 }
486
487 pub const fn max_cross_node_migration_ratio(mut self, v: f64) -> Self {
488 self.max_cross_node_migration_ratio = Some(v);
489 self
490 }
491
492 pub const fn max_slow_tier_ratio(mut self, v: f64) -> Self {
493 self.max_slow_tier_ratio = Some(v);
494 self
495 }
496
497 /// True when any worker-level check field is `Some`. A pure query on
498 /// the configured checks — it no longer gates per-cgroup telemetry
499 /// (telemetry is built unconditionally per handle in
500 /// [`crate::scenario`]'s collect path; worker-check assertions are the
501 /// only opt-in part). Retained as public API for callers composing an
502 /// `Assert` who need to know whether any worker check is set.
503 pub const fn has_worker_checks(&self) -> bool {
504 self.not_stuck.is_some()
505 || self.isolation.is_some()
506 || self.max_gap_ms.is_some()
507 || self.max_spread_pct.is_some()
508 || self.max_throughput_cv.is_some()
509 || self.min_work_rate.is_some()
510 || self.max_p99_wake_latency_ns.is_some()
511 || self.max_wake_latency_cv.is_some()
512 || self.min_iteration_rate.is_some()
513 || self.max_migration_ratio.is_some()
514 || self.min_page_locality.is_some()
515 || self.max_cross_node_migration_ratio.is_some()
516 || self.max_slow_tier_ratio.is_some()
517 }
518
519 /// Merge `other` on top of `self`. Each `Some` field in `other`
520 /// overrides the corresponding field in `self`; `None` fields
521 /// inherit from `self`.
522 ///
523 /// [`Assert::NO_OVERRIDES`] is the two-sided identity:
524 /// `x.merge(&NO_OVERRIDES)` and `NO_OVERRIDES.merge(&x)` both yield
525 /// `x`. The runtime composes scheduler- and test-level overrides as
526 /// `Assert::default_checks().merge(&scheduler.assert).merge(&test.assert)`,
527 /// so a `NO_OVERRIDES` at either override layer leaves the defaults
528 /// untouched -- which means "no override," not "no checks."
529 pub const fn merge(&self, other: &Assert) -> Assert {
530 // `Option::or` is not yet const-stable, so each field expands
531 // a match rather than calling `other.x.or(self.x)`. Keep it
532 // this way until `const fn` can call `Option::or`; at that
533 // point the 21 match blocks collapse to 21 `.or()` calls.
534 Assert {
535 not_stuck: match other.not_stuck {
536 Some(v) => Some(v),
537 None => self.not_stuck,
538 },
539 isolation: match other.isolation {
540 Some(v) => Some(v),
541 None => self.isolation,
542 },
543 max_gap_ms: match other.max_gap_ms {
544 Some(v) => Some(v),
545 None => self.max_gap_ms,
546 },
547 max_spread_pct: match other.max_spread_pct {
548 Some(v) => Some(v),
549 None => self.max_spread_pct,
550 },
551 max_throughput_cv: match other.max_throughput_cv {
552 Some(v) => Some(v),
553 None => self.max_throughput_cv,
554 },
555 min_work_rate: match other.min_work_rate {
556 Some(v) => Some(v),
557 None => self.min_work_rate,
558 },
559 max_p99_wake_latency_ns: match other.max_p99_wake_latency_ns {
560 Some(v) => Some(v),
561 None => self.max_p99_wake_latency_ns,
562 },
563 max_wake_latency_cv: match other.max_wake_latency_cv {
564 Some(v) => Some(v),
565 None => self.max_wake_latency_cv,
566 },
567 min_iteration_rate: match other.min_iteration_rate {
568 Some(v) => Some(v),
569 None => self.min_iteration_rate,
570 },
571 max_migration_ratio: match other.max_migration_ratio {
572 Some(v) => Some(v),
573 None => self.max_migration_ratio,
574 },
575 max_imbalance_ratio: match other.max_imbalance_ratio {
576 Some(v) => Some(v),
577 None => self.max_imbalance_ratio,
578 },
579 max_local_dsq_depth: match other.max_local_dsq_depth {
580 Some(v) => Some(v),
581 None => self.max_local_dsq_depth,
582 },
583 fail_on_rq_clock_stuck: match other.fail_on_rq_clock_stuck {
584 Some(v) => Some(v),
585 None => self.fail_on_rq_clock_stuck,
586 },
587 sustained_samples: match other.sustained_samples {
588 Some(v) => Some(v),
589 None => self.sustained_samples,
590 },
591 max_fallback_rate: match other.max_fallback_rate {
592 Some(v) => Some(v),
593 None => self.max_fallback_rate,
594 },
595 max_keep_last_rate: match other.max_keep_last_rate {
596 Some(v) => Some(v),
597 None => self.max_keep_last_rate,
598 },
599 enforce_monitor_thresholds: self.enforce_monitor_thresholds
600 || other.enforce_monitor_thresholds,
601 min_page_locality: match other.min_page_locality {
602 Some(v) => Some(v),
603 None => self.min_page_locality,
604 },
605 max_cross_node_migration_ratio: match other.max_cross_node_migration_ratio {
606 Some(v) => Some(v),
607 None => self.max_cross_node_migration_ratio,
608 },
609 max_slow_tier_ratio: match other.max_slow_tier_ratio {
610 Some(v) => Some(v),
611 None => self.max_slow_tier_ratio,
612 },
613 expect_scx_bpf_error_contains: match other.expect_scx_bpf_error_contains {
614 Some(v) => Some(v),
615 None => self.expect_scx_bpf_error_contains,
616 },
617 expect_scx_bpf_error_matches: match other.expect_scx_bpf_error_matches {
618 Some(v) => Some(v),
619 None => self.expect_scx_bpf_error_matches,
620 },
621 }
622 }
623
624 /// Extract an `AssertPlan` for worker-side checks.
625 pub(crate) fn worker_plan(&self) -> AssertPlan {
626 AssertPlan {
627 not_stuck: self.not_stuck.unwrap_or(false),
628 isolation: self.isolation.unwrap_or(false),
629 max_gap_ms: self.max_gap_ms,
630 max_spread_pct: self.max_spread_pct,
631 max_throughput_cv: self.max_throughput_cv,
632 min_work_rate: self.min_work_rate,
633 max_p99_wake_latency_ns: self.max_p99_wake_latency_ns,
634 max_wake_latency_cv: self.max_wake_latency_cv,
635 min_iteration_rate: self.min_iteration_rate,
636 max_migration_ratio: self.max_migration_ratio,
637 min_page_locality: self.min_page_locality,
638 max_cross_node_migration_ratio: self.max_cross_node_migration_ratio,
639 max_slow_tier_ratio: self.max_slow_tier_ratio,
640 }
641 }
642
643 /// Run the configured worker checks against one cgroup's reports.
644 ///
645 /// `cpuset` is the CPU set for isolation checks. `numa_nodes` is
646 /// the NUMA node IDs covered by the cpuset (for page locality and
647 /// slow-tier checks). Derive via
648 /// [`TestTopology::numa_nodes_for_cpuset`](crate::topology::TestTopology::numa_nodes_for_cpuset).
649 pub fn assert_cgroup(
650 &self,
651 reports: &[crate::workload::WorkerReport],
652 cpuset: Option<&BTreeSet<usize>>,
653 ) -> AssertResult {
654 self.worker_plan().assert_cgroup(reports, cpuset, None)
655 }
656
657 /// Run worker checks with explicit NUMA node set for page locality.
658 pub fn assert_cgroup_with_numa(
659 &self,
660 reports: &[crate::workload::WorkerReport],
661 cpuset: Option<&BTreeSet<usize>>,
662 numa_nodes: Option<&BTreeSet<usize>>,
663 ) -> AssertResult {
664 self.worker_plan()
665 .assert_cgroup(reports, cpuset, numa_nodes)
666 }
667
668 /// Run NUMA page locality check.
669 ///
670 /// `observed` is the fraction of pages on expected nodes (0.0-1.0).
671 /// `total_pages` and `local_pages` are for diagnostics.
672 pub fn assert_page_locality(
673 &self,
674 observed: f64,
675 total_pages: u64,
676 local_pages: u64,
677 ) -> AssertResult {
678 assert_page_locality(observed, self.min_page_locality, total_pages, local_pages)
679 }
680
681 /// Run cross-node migration ratio check.
682 ///
683 /// `migrated_pages` is the `/proc/vmstat` `numa_pages_migrated` delta.
684 /// `total_pages` is total allocated pages from numa_maps.
685 pub fn assert_cross_node_migration(
686 &self,
687 migrated_pages: u64,
688 total_pages: u64,
689 ) -> AssertResult {
690 assert_cross_node_migration(
691 migrated_pages,
692 total_pages,
693 self.max_cross_node_migration_ratio,
694 )
695 }
696
697 /// Extract `MonitorThresholds` for monitor-side evaluation.
698 pub(crate) fn has_monitor_thresholds(&self) -> bool {
699 self.max_imbalance_ratio.is_some()
700 || self.max_local_dsq_depth.is_some()
701 || self.fail_on_rq_clock_stuck.is_some()
702 || self.sustained_samples.is_some()
703 || self.max_fallback_rate.is_some()
704 || self.max_keep_last_rate.is_some()
705 }
706
707 pub(crate) fn monitor_thresholds(&self) -> crate::monitor::MonitorThresholds {
708 use crate::monitor::MonitorThresholds;
709 let d = MonitorThresholds::new();
710 MonitorThresholds {
711 max_imbalance_ratio: self.max_imbalance_ratio.unwrap_or(d.max_imbalance_ratio),
712 max_local_dsq_depth: self.max_local_dsq_depth.unwrap_or(d.max_local_dsq_depth),
713 fail_on_rq_clock_stuck: self
714 .fail_on_rq_clock_stuck
715 .unwrap_or(d.fail_on_rq_clock_stuck),
716 sustained_samples: self.sustained_samples.unwrap_or(d.sustained_samples),
717 max_fallback_rate: self.max_fallback_rate.unwrap_or(d.max_fallback_rate),
718 max_keep_last_rate: self.max_keep_last_rate.unwrap_or(d.max_keep_last_rate),
719 enforce: self.enforce_monitor_thresholds,
720 }
721 }
722
723 /// Opt into pass/fail enforcement for monitor thresholds. Without
724 /// this call, monitor violations are reported in the verdict's
725 /// `details` but do not fail the test. With it, any monitor
726 /// threshold violation fails the test.
727 ///
728 /// Also populates any unset monitor-threshold field with the
729 /// canonical default from `MonitorThresholds::new()`
730 /// — so a test that only cares about `max_keep_last_rate` can chain
731 /// `.max_keep_last_rate(N).with_monitor_defaults()` and get the
732 /// other five enforced at their canonical defaults.
733 pub const fn with_monitor_defaults(mut self) -> Self {
734 use crate::monitor::MonitorThresholds;
735 let d = MonitorThresholds::new();
736 if self.max_imbalance_ratio.is_none() {
737 self.max_imbalance_ratio = Some(d.max_imbalance_ratio);
738 }
739 if self.max_local_dsq_depth.is_none() {
740 self.max_local_dsq_depth = Some(d.max_local_dsq_depth);
741 }
742 if self.fail_on_rq_clock_stuck.is_none() {
743 self.fail_on_rq_clock_stuck = Some(d.fail_on_rq_clock_stuck);
744 }
745 if self.sustained_samples.is_none() {
746 self.sustained_samples = Some(d.sustained_samples);
747 }
748 if self.max_fallback_rate.is_none() {
749 self.max_fallback_rate = Some(d.max_fallback_rate);
750 }
751 if self.max_keep_last_rate.is_none() {
752 self.max_keep_last_rate = Some(d.max_keep_last_rate);
753 }
754 self.enforce_monitor_thresholds = true;
755 self
756 }
757
758 /// Const-fn builder for [`Self::expect_scx_bpf_error_contains`].
759 /// Chains with the other const-fn setters so a scheduler-def or
760 /// per-test assertion block can compose
761 /// `Assert::NO_OVERRIDES.expect_scx_bpf_error_contains(...).check_not_stuck()`.
762 ///
763 /// Empty strings panic at construction (an empty literal would
764 /// silently match every message and turn this assertion into a
765 /// no-op); pass a non-empty fragment that should appear in the
766 /// expected `scx_bpf_error` message.
767 ///
768 /// # Panics
769 /// When `literal` is empty.
770 #[must_use = "builder methods consume self; bind the result"]
771 pub const fn expect_scx_bpf_error_contains(mut self, literal: &'static str) -> Self {
772 assert!(
773 !literal.is_empty(),
774 "Assert::expect_scx_bpf_error_contains: literal must be non-empty",
775 );
776 self.expect_scx_bpf_error_contains = Some(literal);
777 self
778 }
779
780 /// Builder for [`Self::expect_scx_bpf_error_matches`]. The
781 /// pattern is a regex; special characters retain their regex
782 /// meaning. For literal-substring matching, prefer
783 /// [`Self::expect_scx_bpf_error_contains`] to avoid escape
784 /// footguns.
785 ///
786 /// Validates the pattern at construction: rejects empty
787 /// patterns, rejects invalid regex syntax, and rejects any
788 /// pattern that satisfies `is_match("")`. The empty-string
789 /// match predicate catches two related no-op classes:
790 /// patterns that match every position (e.g. `a?`, `.*`,
791 /// `(?:)`) trivially pass against any corpus, and patterns
792 /// that match only the empty string (e.g. `^$`) trivially
793 /// fail against any non-empty corpus — every real captured
794 /// scheduler-output corpus is non-empty, so the latter is
795 /// equally a no-op pin in practice. Both are useless;
796 /// `is_match("")` catches both with one check.
797 ///
798 /// Bare `\b` (word boundary) slips this gate because the
799 /// empty string contains no word characters, so `\b` finds
800 /// no transition and `is_match("")` returns false; yet `\b`
801 /// matches the first word boundary in any real corpus,
802 /// turning a bare-`\b` pin into a vacuous "any non-empty
803 /// log passes" assertion. Use a substring of the expected
804 /// error text rather than a standalone boundary assertion.
805 /// All other documented assertions (`\A`, `\z`, `^`, `$`,
806 /// `\B`) match the empty string at position 0 and ARE
807 /// caught by the gate.
808 ///
809 /// Unlike the sibling [`Self::expect_scx_bpf_error_contains`]
810 /// (which is `const fn`), this builder is non-const because
811 /// the construction-time regex compilation requires heap
812 /// allocation. Callers needing a const builder for a regex
813 /// matcher must build the `Assert` via struct literal —
814 /// the evaluator's defense-in-depth catches invalid syntax
815 /// reached via that bypass at first evaluation, but the
816 /// vacuous-pattern gate only fires on the builder path.
817 ///
818 /// # Panics
819 /// When `pattern` is empty, is invalid regex syntax, or
820 /// matches the empty string.
821 #[must_use = "builder methods consume self; bind the result"]
822 pub fn expect_scx_bpf_error_matches(mut self, pattern: &'static str) -> Self {
823 assert!(
824 !pattern.is_empty(),
825 "Assert::expect_scx_bpf_error_matches: pattern must be non-empty",
826 );
827 let compiled = regex::Regex::new(pattern).unwrap_or_else(|e| {
828 panic!(
829 "Assert::expect_scx_bpf_error_matches: pattern {pattern:?} is not valid regex: {e}",
830 )
831 });
832 assert!(
833 !compiled.is_match(""),
834 "Assert::expect_scx_bpf_error_matches: pattern {pattern:?} matches the empty \
835 string (e.g. `a?`, `.*`, `(?:)`, `^$`); such patterns vacuously match any \
836 corpus and turn the matcher into a no-op — use a meaningful pattern that \
837 requires at least one character",
838 );
839 self.expect_scx_bpf_error_matches = Some(pattern);
840 self
841 }
842
843 /// Evaluate the reproducer-mode `scx_bpf_error` matchers against
844 /// the captured text corpus. Returns an empty Vec when no matcher
845 /// is configured or when every configured matcher matches; returns
846 /// a non-empty Vec of `AssertDetail` entries on failure.
847 ///
848 /// Each configured matcher contributes at most one detail. Both
849 /// fields can be set simultaneously (`AND` semantics — both must
850 /// match).
851 ///
852 /// Preconditions enforced by the evaluator:
853 /// 1. `expect_err = true` must be set when either matcher is
854 /// configured. Setting the matcher on a passing-test contract
855 /// is a misuse — surfaced with an `expect_err = true` reminder
856 /// diagnostic.
857 /// 2. The regex pattern in
858 /// [`Self::expect_scx_bpf_error_matches`] must compile via
859 /// the `regex` crate. Invalid syntax surfaces as a diagnostic
860 /// naming the pattern and the compile error.
861 ///
862 /// `captured_text` is the concatenation of the raw scheduler-log
863 /// stream (the bulk-port merged `SchedLog` frames, or the test
864 /// process `output` fallback when no frames arrived) and the
865 /// `--- sched_ext dump ---` extract — both surfaces where
866 /// `scx_bpf_error` printk lands. The matcher sees the WHOLE
867 /// stream, not the marker-extracted section; lines outside the
868 /// `SCHED_OUTPUT_START..SCHED_OUTPUT_END` markers are included.
869 pub fn evaluate_scx_bpf_error_match(
870 &self,
871 captured_text: &str,
872 expect_err: bool,
873 ) -> Vec<AssertDetail> {
874 let mut details = Vec::new();
875 if self.expect_scx_bpf_error_contains.is_none()
876 && self.expect_scx_bpf_error_matches.is_none()
877 {
878 return details;
879 }
880 if !expect_err {
881 details.push(AssertDetail::new(
882 DetailKind::Other,
883 "expect_scx_bpf_error_contains or expect_scx_bpf_error_matches \
884 requires expect_err = true on the test entry — the matcher narrows \
885 which failure counts as the expected bug, and only applies to \
886 expected-error tests; set #[ktstr_test(expect_err = true, ...)] or \
887 drop the matcher",
888 ));
889 return details;
890 }
891 // Truncate at a UTF-8 char boundary at or below 400 bytes so
892 // the excerpt length stays within the "up to 400 bytes follow:"
893 // budget. `chars().take(400)` would count codepoints instead,
894 // and a multi-byte corpus would exceed the byte budget — the
895 // boundary walk steps back to the nearest char start.
896 let excerpt = || -> &str {
897 let len = captured_text.len();
898 if len <= 400 {
899 captured_text
900 } else {
901 let mut end = 400;
902 while end > 0 && !captured_text.is_char_boundary(end) {
903 end -= 1;
904 }
905 &captured_text[..end]
906 }
907 };
908 if let Some(literal) = self.expect_scx_bpf_error_contains
909 && !captured_text.contains(literal)
910 {
911 details.push(AssertDetail::new(
912 DetailKind::Other,
913 format!(
914 "expect_scx_bpf_error_contains({literal:?}): substring not found \
915 in the scheduler log + sched_ext dump corpus (the expected bug \
916 did not fire, or its message text changed). Captured corpus \
917 {} bytes; up to 400 bytes follow:\n{}",
918 captured_text.len(),
919 excerpt(),
920 ),
921 ));
922 }
923 if let Some(pattern) = self.expect_scx_bpf_error_matches {
924 match regex::Regex::new(pattern) {
925 Ok(re) => {
926 if !re.is_match(captured_text) {
927 details.push(AssertDetail::new(
928 DetailKind::Other,
929 format!(
930 "expect_scx_bpf_error_matches({pattern:?}): regex did \
931 not match the scheduler log + sched_ext dump corpus \
932 (the expected bug did not fire, or its message text \
933 changed). Captured corpus {} bytes; up to 400 bytes \
934 follow:\n{}",
935 captured_text.len(),
936 excerpt(),
937 ),
938 ));
939 }
940 }
941 Err(e) => {
942 details.push(AssertDetail::new(
943 DetailKind::Other,
944 format!(
945 "expect_scx_bpf_error_matches({pattern:?}): regex \
946 compilation failed: {e}. Fix the pattern at the test \
947 declaration site — the matcher cannot evaluate against an \
948 invalid pattern",
949 ),
950 ));
951 }
952 }
953 }
954 details
955 }
956}