Skip to main content

keystate_core/testing/
assertions.rs

1//! The concrete assertions an adapter's contract tests call.
2
3use serde::{Serialize, de::DeserializeOwned};
4use std::fmt::Debug;
5
6use crate::canonical::roundtrip;
7use crate::verify::{entity_label, rows_by_entity};
8use crate::{CanonicalRealm, FieldManifest, ManifestVerifier, Severity, resolve_path};
9
10/// Assert that canonical serialization is byte-stable: two serializations of
11/// identical input must produce identical bytes.
12///
13/// Run this on every collection an adapter builds — a value built the same
14/// way must hash the same way.
15#[track_caller]
16pub fn assert_canonical_deterministic<T: Serialize>(value: &T) {
17    let a = crate::canonical_bytes(value).expect("canonical serialization (#1)");
18    let b = crate::canonical_bytes(value).expect("canonical serialization (#2)");
19    assert_eq!(
20        a, b,
21        "canonical serialization produced different bytes for identical input"
22    );
23}
24
25/// Assert that canonical bytes deserialize back to a semantically identical
26/// value — the envelope, each entity, and the volatile section must all
27/// survive the roundtrip.
28#[track_caller]
29pub fn assert_serialization_roundtrip<T: Serialize + DeserializeOwned + PartialEq + Debug>(
30    value: &T,
31) {
32    roundtrip(value).expect("value must survive a canonical serialization roundtrip");
33}
34
35/// Assert the volatile-segregation contract: every manifest-volatile field
36/// must appear in the volatile section for every existing row, and must not
37/// leak into the config body.
38#[track_caller]
39pub fn assert_volatile_segregation(realm: &CanonicalRealm, manifest: &FieldManifest) {
40    manifest
41        .validate()
42        .expect("manifest must be self-consistent before segregation is checked");
43    let rows = rows_by_entity(realm);
44    for fe in manifest.fields.iter().filter(|f| f.volatile) {
45        let Some(entity_rows) = rows.get(&fe.entity) else {
46            continue;
47        };
48        for (row_id, row) in entity_rows {
49            assert!(
50                !resolve_path(row, &fe.path),
51                "volatile field '{}' must not appear in the config body of {} '{}'",
52                fe.path,
53                entity_label(fe.entity),
54                row_id
55            );
56            assert!(
57                realm.volatile.get(fe.entity, row_id, &fe.path).is_some(),
58                "volatile field '{}' must be captured in the volatile section for {} '{}'",
59                fe.path,
60                entity_label(fe.entity),
61                row_id
62            );
63        }
64    }
65}
66
67/// Assert a manifest passes its own self-consistency checks (unique
68/// expectations, sane backend identity, valid paths).
69#[track_caller]
70pub fn assert_manifest_valid(manifest: &FieldManifest) {
71    manifest
72        .validate()
73        .expect("manifest failed self-consistency checks");
74}
75
76/// Assert an extraction verifies against its manifest with zero
77/// `Error`-severity findings.
78#[track_caller]
79pub fn assert_verification_complete(realm: &CanonicalRealm, manifest: &FieldManifest) {
80    let report = ManifestVerifier
81        .verify(realm, manifest)
82        .expect("verification ran without error");
83    let errors: Vec<_> = report
84        .issues
85        .iter()
86        .filter(|i| i.severity == Severity::Error)
87        .collect();
88    assert!(
89        errors.is_empty(),
90        "verification found {} error(s): {:#?}",
91        errors.len(),
92        errors
93    );
94}
95
96#[cfg(test)]
97mod tests {
98    use super::*;
99    use crate::testing::sample::{sample_manifest, sample_realm};
100
101    #[test]
102    fn sample_data_passes_the_whole_suite() {
103        let realm = sample_realm();
104        let manifest = sample_manifest();
105
106        assert_manifest_valid(&manifest);
107        assert_canonical_deterministic(&realm);
108        assert_serialization_roundtrip(&realm);
109        assert_serialization_roundtrip(&manifest);
110        assert_volatile_segregation(&realm, &manifest);
111        assert_verification_complete(&realm, &manifest);
112    }
113
114    #[test]
115    fn segregation_contract_catches_leaks() {
116        let mut realm = sample_realm();
117        // Re-introduce the volatile field into the config body.
118        realm.users[0].native["last_login"] = serde_json::json!("2026-08-15T10:00:00Z");
119        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
120            assert_volatile_segregation(&realm, &sample_manifest());
121        }));
122        assert!(
123            result.is_err(),
124            "volatile leak should trip the contract test"
125        );
126    }
127}