Testing Guide

This guide covers running tests for AstralBeam components. For examples of how tests are written, browse the existing test suites in the repository - they are the best templates for new tests.

Test Structure

bridge/
├── cli/
│   └── tests/
│       ├── unit/              # Unit tests
│       ├── integration/       # Integration tests
│       └── setup.ts           # Test configuration
├── contracts/
│   ├── eth/
│   │   └── test/             # Foundry tests
│   └── casper/
│       └── src/tests/        # Odra tests

TypeScript Tests (Relayer & CLI)

cd cli

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run a specific test file
npm test -- tests/integration/evm2casper.test.ts

# Run tests matching a pattern
npm test -- --testNamePattern="lock tokens"

# Watch mode
npm test -- --watch

Tests use Jest (jest.config.js in the cli directory). Integration tests have a 2-minute timeout and read their endpoints and keys from environment variables - see tests/setup.ts.

What to cover when contributing:

Unit-test pure logic (hashing, encoding, validation) with known-answer vectors
Integration-test full flows against a local or test network
Always include negative cases (insufficient approval, bad signatures, replayed nonces)

EVM Contract Tests (Foundry)

cd contracts/eth

# Run all tests
forge test

# Verbose output
forge test -vvvv

# Run a specific test file
forge test --match-path test/MultiSigLocker.t.sol

# Run a specific test function
forge test --match-test testLockTokens

# Gas report
forge test --gas-report

# Coverage
forge coverage

Foundry also supports fork testing against live networks via vm.createSelectFork - useful for verifying behavior against deployed contracts without spending real gas.

Casper Contract Tests (Odra)

cd contracts/casper

# Run all tests
cargo odra test

# Verbose output
cargo odra test -- --nocapture

# Run a specific test
cargo odra test test_mint_tokens

# With logs
RUST_LOG=debug cargo odra test

Cross-Language Test Vectors

The bridge's hashing and signature logic is implemented in both TypeScript (relayers) and Rust (Casper contracts). Shared test vectors ensure both implementations produce byte-identical results. If you change any hash computation, update and run the vector tests on both sides.

Continuous Integration

All test suites run in CI on every pull request. A PR must be green across TypeScript, Foundry, and Odra suites before review.

Testing