4. Testing
We provide a comprehensive testing suite for Substreams modules. The testing suite is designed to facilitate end-to-end testing, ensuring that your Substreams modules function as expected. For unit tests, please use standard Rust unit testing practices.
Overview
The testing suite builds the .spkg
for your Substreams module, indexes a specified block range, and verifies that the expected state has been correctly indexed by Tycho. Additionally, it will also try to simulate some transactions using the SwapAdapter
interface.
Prerequisites
Before continuing, ensure the following tools and libraries are installed on your system:
Latest version of the tycho-indexer binary in your PATH. If an appropriate binary for your machine cannot be found on the tycho releases, you will need to clone the tycho-indexer repo and build the binary release yourself (follow these instructions).
Docker: Containerization platform for running applications in isolated environments.
Conda: Package and environment manager for Python and other languages.
AWS cli: Tool to manage AWS services from the command line.
Git: Version control tool
Rust: Programming language and toolchain
GCC: GNU Compiler Collection
libpq: PostgreSQL client library
OpenSSL (libssl): OpenSSL development library
pkg-config: Helper tool for managing compiler flags
Conda: Python package manager
pip: Python package installer
Test Configuration
Tests are defined in a yaml
file. A documented template can be found at substreams/ethereum-template/integration_test.tycho.yaml
. The configuration file should include:
The target Substreams config file.
The corresponding SwapAdapter and args to build it.
The expected protocol types.
The tests to be run.
Each test will index all blocks between start-block
and stop-block
, verify that the indexed state matches the expected state and optionally simulate transactions using SwapAdapter
interface.
You will also need the VM Runtime file for the adapter contract. Our testing script should be able to build it using your test config. The script to generate this file manually is available under evm/scripts/buildRuntime.sh
.
Setup testing environment
To set up your test env, run the setup env script. It will create a conda virtual env and install all dependencies.
This script must be run from within the tycho-protocol-sdk/testing
directory.
Lastly, you need to activate the conda env:
Running Tests
Step 1: Export Environment Variables
Export the required environment variables for the execution. You can find the available environment variables in the .env.default
file. Please create a .env
file in the testing
directory and set the required environment variables.
Environment Variables
RPC_URL
Description: The URL for the Ethereum RPC endpoint. This is used to fetch the storage data. The node needs to be an archive node, and support debug_storageRangeAt.
Example:
export RPC_URL="https://ethereum-mainnet.core.chainstack.com/123123123123"
SUBSTREAMS_API_TOKEN
Description: The API token for accessing Substreams services. This token is required for authentication.
Example:
export SUBSTREAMS_API_TOKEN=eyJhbGci...
Step 2: Set up tests
If you do not have one already, you will need to build the wasm file of the package you wish to test. This can be done by navigating to the package directory and running:
Then, run a local postgres test database using docker compose. This needs to be done from within the testing directory.
Step 3: Run tests
Run tests for your package. This must be done from the main project directory.
Example
If you want to run tests for ethereum-balancer-v2
, use:
Testing CLI args
A list and description of all available CLI args can be found using:
Last updated