Testing and compatibility
Heartwood runs the same input through Rust and a pinned Solar reference, then compares their outputs and modeled rejection classes.
Test layers
Section titled “Test layers”| Level | Comparison | Availability |
|---|---|---|
| L0 | Committed reference vectors | Implemented |
| L1 | Random and mutated requests | Implemented |
| L2 | Block sequences, state digests, and restart paths | Implemented |
| L3 | One 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 compared | Implemented |
| L4 | Reference devnets with Heartwood relays that restart, sync from an empty store and follow a partition and its heal | Implemented |
Everyday checks
Section titled “Everyday checks”make checkThis 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:
cargo test -p heartwood-crypto --locked --all-featuresmake test-p2pmake test-forgermake test-cliCheck every dependency’s advisories, licences and sources with:
make denyThis 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.
Compare the oracle runs
Section titled “Compare the oracle runs”After completing the reference setup:
make oracle-imagemake e2eThe 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.
Preserve evidence
Section titled “Preserve evidence”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.