Crate commonware_conformance

Expand description

Automatically assert the stability of encoding and mechanisms over time.

This crate provides a unified infrastructure for verifying that implementations maintain backward compatibility by comparing output against known-good hash values stored in TOML files.

§The `Conformance` Trait

The core abstraction is the Conformance trait, which represents types that can produce deterministic bytes from a seed.

This enables conformance testing across different domains, for example:

Codec: Verify wire format stability
Storage: Verify on-disk format stability
Network: Verify message ordering consistency

§Storage Format

Test vectors are stored in a TOML file with a single hash per type:

["Vec<u8>"]
n_cases = 100
hash = "abc123..."

["Vec<u16>"]
n_cases = 100
hash = "def456..."

The hash is computed by generating n_cases commitments (using seeds 0..n_cases), and hashing all the bytes together.

§Regeneration Mode

When cfg(generate_conformance_tests) is set, tests regenerate their expected hashes in the TOML file. Use this to intentionally update the format:

RUSTFLAGS="--cfg generate_conformance_tests" cargo test

Macros§

conformance_tests: Define conformance tests for Conformance types.

Structs§

ConformanceFile: A conformance test file containing test data for multiple types.
TypeEntry: Conformance test data for a single type.

Enums§

ConformanceError: Errors that can occur when loading conformance files.

Constants§

DEFAULT_CASES: Default number of test cases when not explicitly specified.

Traits§

Conformance: Trait for types that can produce deterministic bytes for conformance testing.

Functions§

compute_conformance_hash: Compute the conformance hash for a type using the Conformance trait.
run_conformance_test: Run conformance tests using the Conformance trait.