facett-map/tests/common/gpu_gate.rs
//! **THE DEVICE OPT-IN — one writer, and a vocabulary that has a word for every box we
//! actually run on.** Lane GG #5.
//!
//! # The defect this closes
//!
//! Three test files declared their own `gated()` over `$FACETT_TEST_GPU` and **two of the
//! three answered differently**:
//!
//! ```text
//! gpu_lane_paint_order.rs mode == "discrete" || mode == "software"
//! blit_cost.rs mode == "discrete" || mode == "software"
//! gpu_lane_share.rs env::var(GATE).is_ok() ← any value at all
//! ```
//!
//! So the same `FACETT_TEST_GPU=integrated` ran one file and skipped the other two, and a
//! skip in the first two is **filed as a FAILED matrix row on purpose** — a design that is
//! right (a skip must not read as a pass) and turns a vocabulary gap into a red board.
//!
//! # Why that gap matters now
//!
//! The owner's client box is a **Radeon 890M**, which is an INTEGRATED GPU, and the
//! vocabulary had no word for it. The only ways to run the seven device oracles on the
//! machine that shows the defects were to type `FACETT_TEST_GPU=discrete` — a false
//! statement about the hardware, in the variable whose whole job is to say what the
//! hardware is — or to accept a board full of red rows that mean "not run".
//!
//! Nothing downstream needed the lie: [`facett_core::render::gpu::adapter_wgpu`] ranks and
//! *prefers* a discrete adapter, it does not require one, and on a single-adapter box it
//! selects that adapter and prints what it selected. The word was missing only here.
//!
//! # The vocabulary
//!
//! `discrete` · `integrated` · `software` — the adapter classes `AdapterKind` already
//! names, minus the ones no test targets. Any of them means **run**. The value is not
//! checked against the adapter that turns up: it is an operator's opt-in ("this box has a
//! GPU I am willing to spend"), not an assertion, and the selector's own banner is what
//! reports which adapter actually answered.
//!
//! Unset means **skip**, and the skip is loud: `eprintln!` for a human plus a
//! `functional_status(.., false, ..)` row so a board cannot show it as green.
//!
//! # Why a `#[path]` include and not `mod common;`
//!
//! [`one_gpu.rs`](super)'s reason exactly: `common/mod.rs` is the wgpu DEVICE probe and
//! pulls `wgpu` in, and a file that only wants the env gate must stay buildable on a
//! default (feature-less) build.
//!
//! ```ignore
//! #[path = "common/gpu_gate.rs"]
//! mod gpu_gate;
//!
//! #[test]
//! fn something_that_renders() {
//! if !gpu_gate::gated("facett-map", "something_that_renders") {
//! return;
//! }
//! …
//! }
//! ```
#![allow(dead_code)]
/// The environment variable that opts a host into spending its GPU on the test suite.
pub const GATE: &str = "FACETT_TEST_GPU";
/// The adapter classes that mean **run**. Every box the fleet tests on is one of these:
/// oden's RTX 4090 (`discrete`), t14s's Radeon 890M (`integrated`), and a CI runner on
/// lavapipe (`software`).
pub const RUNNING_CLASSES: [&str; 3] = ["discrete", "integrated", "software"];
/// `true` when this host has opted in, and otherwise files the skip as a **non-passing**
/// matrix row under `crate_name` / `test_name` before returning `false`.
#[must_use]
pub fn gated(crate_name: &str, test_name: &str) -> bool {
let mode = std::env::var(GATE).unwrap_or_default();
if RUNNING_CLASSES.contains(&mode.as_str()) {
return true;
}
let how = RUNNING_CLASSES.join("|");
eprintln!(
"SKIPPED and therefore PROVED NOTHING: set {GATE}={how} so `{test_name}` runs on \
this box's GPU. A skip here is filed as a FAILED matrix row on purpose."
);
nornir_testmatrix::functional_status(
crate_name,
test_name,
false,
&format!("SKIPPED — {GATE} unset or unrecognised ({mode:?}), no device lane exercised"),
);
false
}