Struct Capability
pub struct Capability(/* private fields */);Expand description
Whether a fixture supports one optional operation, and if not, why not.
§Why this is an opaque struct rather than a public enum
The obvious spelling is enum Capability { Supported, Declined(&'static str) },
and it has one hole: Declined("") is a perfectly good value of that type.
The requirement that a declined capability names a reason would then be
prose, enforced by a meta-test somebody has to remember to write.
Making the field private moves the check into the only constructor, where an
assert! inside a const fn can reject the empty string at compile time.
See declined for exactly when that fires — it is later
than one would like, and worth knowing.
Implementations§
§impl Capability
impl Capability
pub const SUPPORTED: Self
pub const SUPPORTED: Self
The fixture supports this operation, and rules requiring it will run.
pub const fn declined(reason: &'static str) -> Self
pub const fn declined(reason: &'static str) -> Self
The fixture does not support this operation, for the stated reason.
The reason is not a formality. It is printed for every rule the decision skips, so that it can land in the adapter’s CI log where both a reviewer and a user of the adapter can read it. Write the real one: why this store cannot do it, not that it cannot.
“Printed” means printed under --show-output. A skipped rule is a
test that passes, and libtest discards a passing test’s stdout, so a
default cargo test in an adapter’s own CI shows none of these lines —
see RuleOutcome::report, which measures exactly that. Write the
reason for the reader who runs the flag, and configure your CI to pass
it if you want the reason in front of anyone else.
§Panics
Panics if reason is empty. Because this is a const fn, a panic at
const-evaluation time is a compile error rather than a run-time one:
use happenstance_testkit::Capability;
const REOPEN: Capability = Capability::declined("");
fn main() {
let _ = REOPEN;
}The doctest above is spelled bare compile_fail, never
compile_fail,E0080. This diagnostic family has bitten the repository
before: rustdoc on 1.97.1 silently ignores an error-code annotation it
cannot match, so the stricter-looking spelling is the weaker check.
Where it does not fire. A free const like the one above fails at
cargo check. An associated const in a Fixture impl does not: an
associated const is evaluated lazily, only when monomorphised code reads
it, and that is after check and clippy have both stopped. It fails at
codegen — so cargo build and cargo test catch it and cargo clippy
does not.
pub const fn is_supported(self) -> bool
pub const fn is_supported(self) -> bool
Whether rules requiring this capability should run.