Files

TAMARA LIPOWSKI c12affb3ca docs: Add README and logging to match python package

- The readme is useful for us during development. This should be eventually removed and replaced with gitbook docs.

2025-09-03 08:55:29 -04:00

3.9 KiB

Raw Blame History

Protocol Testing

Rust-based integration testing framework for Tycho protocol implementations.

Prerequisites

PostgreSQL Database: Start the required PostgreSQL instance using Docker:
```
docker-compose up -d
```
Environment Variables: Source the environment variables:
```
source .env
```
Or set them manually:
- DATABASE_URL: PostgreSQL connection string (default: postgres://postgres:mypassword@localhost:5431/tycho_indexer_0)
- RPC_URL: Ethereum RPC endpoint
- SUBSTREAMS_API_TOKEN: Authentication token for Substreams API
- AUTH_API_KEY: API key for authentication

Running Tests

Basic Usage

cargo run -- --package <PACKAGE_NAME>

Command Line Options

--package <NAME> (required): Name of the package to test
--tycho-logs <BOOL>: Enable tycho logs (default: true)
--db-url <URL>: Postgres database URL (default: postgres://postgres:mypassword@localhost:5431/tycho_indexer_0)
--vm-traces <BOOL>: Enable tracing during VM simulations (default: false)

Examples

Run tests with default settings:

cargo run -- --package uniswap-v2

Run tests with VM tracing enabled:

cargo run -- --package uniswap-v2 --vm-traces true

Run tests with custom database URL:

cargo run -- --package uniswap-v2 --db-url postgres://user:pass@localhost:5432/custom_db

Run tests in silent mode (disable tycho logs):

cargo run -- --package uniswap-v2 --tycho-logs false

Logging Configuration

The application uses tracing for structured logging. Control log levels using the RUST_LOG environment variable:

Log Levels

# Show test results and progress (recommended)
export RUST_LOG=info

# Show all detailed logs including debug information
export RUST_LOG=debug

# Show only errors (silent mode)
export RUST_LOG=error

# Hide all logs (completely silent)
export RUST_LOG=warn

Test Output Formatting

The test runner outputs results similar to:

Running 2 tests ...

--------------------------------

TEST 1: balancer_weighted_pool_test

✅ Protocol component validation passed.

✅ Token balance validation passed.

Amount out for 0x5c6ee304399dbdb9c8ef030ab642b10820db8f56000200000000000000000014: calculating for tokens "BAL"/"WETH"
Spot price "BAL"/"WETH": 0.123456

✅ Simulation validation passed.

✅ balancer_weighted_pool_test passed.

--------------------------------

Tests finished! 
RESULTS: 2/2 passed.

Module-specific Logging

# Enable debug logs for specific modules
export RUST_LOG=protocol_testing=debug,tycho_client=info

# Disable logs for noisy modules
export RUST_LOG=info,hyper=warn,reqwest=warn

Running with Different Log Levels

# Standard test run with progress output
RUST_LOG=info cargo run -- --package uniswap-v2

# Detailed debug output
RUST_LOG=debug cargo run -- --package uniswap-v2

# Minimal output (errors only)
RUST_LOG=error cargo run -- --package uniswap-v2

Test Configuration

Tests are configured via YAML files located in the substreams package directory:

Test configuration: ../substreams/<package>/integration_test.tycho.yaml
Substreams configuration: ../substreams/<package>/substreams.yaml

What the Tests Do

Component Validation: Verifies that all expected protocol components are present in Tycho after indexing
State Validation: Compares indexed component states against expected values
Balance Verification: Validates token balances by querying the blockchain directly (can be skipped)
Simulation Testing: Runs Tycho simulation engine to verify protocol functionality

Troubleshooting

Database Connection Issues: Ensure PostgreSQL is running via docker-compose up -d
RPC Errors: Verify RPC_URL is set and accessible
Missing Substreams: Check that the package directory exists in ../substreams/<package>/
Build Failures: Ensure all dependencies are installed and environment variables are set

3.9 KiB Raw Blame History