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?