Skip to main content

wa_wire_conformance/
lib.rs

1//! Replaying recorded stanzas through every engine and requiring them to agree.
2//!
3//! This is the property that makes `wa-wire` more than a wrapper:
4//!
5//! > Given the same traffic, every conforming engine must produce the same L1.
6//!
7//! Four independent implementations reading one input find bugs that no single
8//! implementation's own tests can, because a bug and its test are usually
9//! written by the same person on the same afternoon. Divergence is the signal.
10//!
11//! # What is compared
12//!
13//! Two layers, and they fail differently:
14//!
15//! - **L0** — the frame bytes each engine forwarded. Byte-identical frames mean
16//!   the engines saw the same stanza; different ones do not necessarily mean a
17//!   bug, because two encodings of one stanza are both valid.
18//! - **L1** — the events derived from those frames, compared by *meaning*. Two
19//!   engines that encode a value differently and derive the same event agree.
20//!   This is the layer where a divergence is a finding.
21//!
22//! That split matters: reporting every L0 difference would bury the L1 ones,
23//! and L1 is where correctness lives.
24//!
25//! ```
26//! use wa_wire_conformance::{ComparisonProfile, Recording, Tables, Verdict, compare};
27//! use wa_wire_codec::TokenTable;
28//!
29//! # fn example(engine_a: Recording<'_>, engine_b: Recording<'_>, table: TokenTable<'_>) {
30//! let report = compare(&engine_a, &engine_b, Tables::shared(table));
31//! if report.evaluate(ComparisonProfile::Interop) == Verdict::Pass {
32//!     // Same traffic, same events.
33//! } else {
34//!     for divergence in report.divergences() {
35//!         eprintln!("{divergence}");
36//!     }
37//! }
38//! # }
39//! ```
40
41#![no_std]
42#![cfg_attr(
43    test,
44    allow(
45        clippy::expect_used,
46        clippy::unwrap_used,
47        clippy::panic,
48        clippy::indexing_slicing,
49        clippy::arithmetic_side_effects,
50    )
51)]
52
53extern crate alloc;
54
55pub mod comparability;
56pub mod divergence;
57pub mod profile;
58pub mod recording;
59pub mod report;
60
61pub use comparability::Comparability;
62pub use divergence::{Divergence, Layer};
63pub use profile::{ComparisonProfile, Incomparable, Verdict};
64pub use recording::Recording;
65pub use report::{Report, Tables, compare, replay};