# Testing and compatibility

> Understand Heartwood's reference vectors, differential tests, and release checks.

Source: https://docs.iceroot.com/core/testing/

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

## 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

```sh
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:

```sh
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:

```sh
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.

## Compare the oracle runs

After completing the [reference setup](https://docs.iceroot.com/core/installation/index.md#reference-setup):

```sh
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.

## 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.
