Skip to content
IceRootDocs

Testing and compatibility

Heartwood runs the same input through Rust and a pinned Solar reference, then compares their outputs and modeled rejection classes.

LevelComparisonAvailability
L0Committed reference vectorsImplemented
L1Random and mutated requestsImplemented
L2Block sequences, state digests, and restart pathsImplemented
L3One scenario on a reference devnet, observed first by a reference relay and then by a Heartwood relay; one scenario on a devnet of reference nodes and on a devnet of Heartwood relays and forgers; and a Heartwood devnet through faults and forger failover; with answers and state digests comparedImplemented
L4Reference devnets with Heartwood relays that restart, sync from an empty store and follow a partition and its healImplemented
Terminal window
make check

This builds the workspace, runs Clippy with warnings treated as errors, checks formatting, and runs the default test suites and the committed-vector comparison. It also runs the release feature check, the crate layer checks and rustdoc. Integration tests marked ignore are excluded from make check; the production CI runs those separately. You can test the crypto crate, the peer client, the forger or the commands directly:

Terminal window
cargo test -p heartwood-crypto --locked --all-features
make test-p2p
make test-forger
make test-cli

Check every dependency’s advisories, licences and sources with:

Terminal window
make deny

This needs cargo-deny and network access to fetch the advisory database, so make check does not run it.

make binary-tests runs the heartwood binary’s tests, the slow ones included. make devnet-smoke starts a forging devnet of one node for 20 blocks, then one of five nodes for a round. make check does not run either.

After completing the reference setup:

Terminal window
make oracle-image
make e2e

The end-to-end target compares vector generation inside the oracle image and in the local reference checkout, then runs L0. Both checkouts must use the configured reference revision.

Vectors are JSONL records with metadata and a SHA-256 manifest. They capture the reference revision, environment, network configuration, input, and computed output or error.

A mismatch identifies the JSON path or first differing byte. Investigate the input and its network rules before changing the expected record. Documented differences and skipped cases remain visible in the report.

make vectors-install updates committed vectors intentionally. The genesis vector class depends on a separate maintainer tool, so a regeneration missing that class is rejected instead of overwriting the complete set.