Back to Common Questions

Common Questions / Troubleshooting

How do I test a Substreams package?

Updated

Test at four levels: unit tests on your handlers, tests against real block fixtures, an end-to-end substreams run over a small range, and performance checks. Start with unit tests; they run natively in Rust without compiling to WASM.

How do I unit test a handler?

The substreams::testing::map! macro invokes a map handler directly:

use substreams::testing;

let result = testing::map!(map_events(block)).unwrap();
assert!(!result.events.is_empty());

For time-dependent logic, testing::clock() supplies clock information.

How do I test against real blocks?

Export a block with firecore, then decode it in a test:

firecore tools firehose-single-block-client mainnet.eth.streamingfast.io:443 17000000 \
    --output=bytes --bytes-encoding=base64 \
    > ./src/testdata/ethereum_mainnet_17000000.binpb.base64

For controlled scenarios, build Block values in code. Run your handlers over several fixture blocks to check results across a range.

How do I run an end-to-end check?

substreams run -s 17000000 -t +100 map_events --network mainnet

You can wrap this in an #[ignore] Rust test and run it with cargo test -- --ignored.

What should CI run?

cargo test
cargo build --target wasm32-unknown-unknown --release
cargo clippy -- -D warnings
cargo fmt -- --check

See the testing reference for Criterion benchmarks and builder patterns. The substreams-testing agent skill also covers these patterns.


Frequently asked questions

Can an AI assistant write the tests? Yes — the skills include testing guidance. Still run them yourself; see how reliable is AI-generated indexing code.


Get an API key at thegraph.market.

Related: What is Substreams? · How do I build a blockchain indexer with an AI coding assistant? · How do I upgrade to Substreams 0.8?