crates/nornir-bench/src/selftest.rs
//! # Functional-status emit bridge — `nornir-bench` → test matrix
//!
//! The single internal call site this crate uses to push a *functional* row
//! into the [`nornir_testmatrix`] matrix, so `nornir test --features testmatrix`
//! records whether `nornir-bench`'s real surfaces (the `register_bench!` /
//! `registered_bench_ids` discovery seam, a bencher's `run`, the `BenchRun`
//! test gate, metric-unit classification, and the `history_outcome` sannr
//! contract) ACTUALLY work.
//!
//! ## Release strips everything
//! The `testmatrix` cargo feature gates the whole bridge: with it OFF (the
//! release default) [`emit`] is an `#[inline]` no-op and `nornir-testmatrix` is
//! not even linked. Lit ONLY under `cargo … --features testmatrix`.
/// The aspect tag every self-emitted row carries (matches `functional_row`).
pub const ASPECT_FUNCTIONAL: &str = "functional";
/// Push ONE functional-status row for a single real check (feature ON).
#[cfg(feature = "testmatrix")]
#[inline]
pub fn emit(component: &str, check: &str, ok: bool, detail: &str) {
nornir_testmatrix::functional_status(component, check, ok, detail);
}
/// No-op stub when the `testmatrix` feature is OFF (release builds).
#[cfg(not(feature = "testmatrix"))]
#[inline]
pub fn emit(_component: &str, _check: &str, _ok: bool, _detail: &str) {}
/// `assert!`-with-emit: assert on the real return value AND record the verdict
/// as a matrix row.
#[macro_export]
macro_rules! assert_emit {
($component:expr, $check:expr, $ok:expr, $($detail:tt)+) => {{
let __ok: bool = $ok;
let __detail = ::std::format!($($detail)+);
$crate::selftest::emit($component, $check, __ok, &__detail);
::std::assert!(__ok, "{}::{} — {}", $component, $check, __detail);
}};
}
// ─── inject-and-assert wiring test (feature ON only) ─────────────────────────
#[cfg(all(test, feature = "testmatrix"))]
mod wiring {
use crate::api::{self, Bencher};
use crate::{
direction_of, history_outcome, unit_of, BenchResult, BenchRun, MetricDirection, TestOutcome,
};
use std::collections::HashMap;
/// A test-only bencher so this crate's OWN `register_bench!` → inventory →
/// `registered_bench_ids()` seam is exercised end to end (feature+test only).
struct WiringDemo;
impl Bencher for WiringDemo {
fn id(&self) -> &'static str {
"selftest.wiring_demo"
}
fn run(&self) -> anyhow::Result<BenchResult> {
let mut m = serde_json::Map::new();
m.insert("ops_sec".into(), serde_json::json!(123.0));
Ok(BenchResult { name: "wiring_demo".into(), metrics: m , ..Default::default() })
}
}
crate::register_bench!(WiringDemo);
/// Exercise `nornir-bench`'s real surfaces, emit an honest row per surface,
/// then drain the process-global functional buffer and assert the rows
/// landed — proving the emit bridge is wired end to end.
#[test]
fn emits_honest_rows_for_bench_surfaces() {
// Surface: the register_bench! → registered_bench_ids discovery seam
// (#39) — sees THIS crate's registered bencher, sorted + deduped.
let ids = api::registered_bench_ids();
let reg_ok = ids.contains(&"selftest.wiring_demo".to_string())
&& ids.windows(2).all(|w| w[0] <= w[1]);
assert_emit!("nornir-bench", "register_bench_discovered_and_sorted", reg_ok, "ids={ids:?}");
// Surface: a bencher's run() yields its BenchResult envelope.
let res = WiringDemo.run();
let run_ok = res.as_ref().map(|r| r.name == "wiring_demo").unwrap_or(false);
assert_emit!("nornir-bench", "bencher_run_returns_result", run_ok, "ok={}", res.is_ok());
// Surface: BenchRun's no-regression test gate.
let run = BenchRun {
id: crate::Uuid::nil(),
machine_facts: None,
date: "2026-07-06".into(),
timestamp: None,
version: "0.1.0".into(),
machine: "m".into(),
cores: 12,
results: res.into_iter().collect(),
tests: vec![TestOutcome {
name: "t".into(),
passed: true,
duration_ms: None,
message: None,
}],
};
assert_emit!(
"nornir-bench",
"benchrun_all_tests_passed",
run.all_tests_passed(),
"failed={:?}",
run.failed_tests()
);
// Surface: metric-unit classification (throughput = mbs/high, latency = low).
let unit_ok = unit_of("throughput_mbs").map(|u| u.name == "mbs").unwrap_or(false)
&& direction_of(&HashMap::new(), "decode_ms") == MetricDirection::Low;
assert_emit!("nornir-bench", "metric_unit_direction_classified", unit_ok, "mbs+ms ok");
// Surface: history_outcome sannr contract (RAGNARÖK: empty is RED).
let empty = history_outcome("demo", Vec::new(), 0);
crate::selftest::emit(
"nornir-bench",
"history_empty_is_red",
!empty.is_sannr(),
&format!("is_sannr={}", empty.is_sannr()),
);
let populated = history_outcome("demo", vec![run.clone()], 0);
assert_emit!("nornir-bench", "history_populated_is_sannr", populated.is_sannr(), "sannr");
// Surface: the bench regression gate (diff). A throughput drop past the
// tolerance gates; an improvement does not.
let base = BenchRun {
id: crate::Uuid::nil(),
machine_facts: None,
results: vec![BenchResult::measured(
"z.decode",
[("decode_mbs".to_string(), serde_json::json!(800.0))].into_iter().collect(),
)],
..run.clone()
};
let slower = BenchRun {
id: crate::Uuid::nil(),
machine_facts: None,
results: vec![BenchResult::measured(
"z.decode",
[("decode_mbs".to_string(), serde_json::json!(700.0))].into_iter().collect(),
)],
..run.clone()
};
let d = slower.diff(&base);
assert_emit!(
"nornir-bench",
"diff_flags_throughput_regression",
d.is_regression(5.0) && d.worst().map(|w| w.metric == "decode_mbs").unwrap_or(false),
"worst={:?}",
d.worst().map(|w| w.regression_pct())
);
let up = base.diff(&slower); // now 700 → 800: an improvement
assert_emit!(
"nornir-bench",
"diff_improvement_is_not_regression",
!up.is_regression(5.0),
"regressions={}",
up.regressions(5.0).len()
);
let rows = nornir_testmatrix::drain_functional_rows();
for want in [
"register_bench_discovered_and_sorted",
"bencher_run_returns_result",
"benchrun_all_tests_passed",
"metric_unit_direction_classified",
"history_empty_is_red",
"history_populated_is_sannr",
"diff_flags_throughput_regression",
"diff_improvement_is_not_regression",
] {
assert!(
rows.iter().any(|r| r.suite == "nornir-bench" && r.test_name == want && r.status == "pass"),
"missing green row {want}: {rows:?}"
);
}
assert!(rows.iter().all(|r| r.aspect == "functional"), "rows={rows:?}");
}
}