Testing¶

HyperbyteDB has a multi-layered test strategy spanning unit tests, integration tests, compatibility suites, end-to-end cluster tests, and benchmarks.

Test Suite Inventory¶

Running Tests¶

Unit tests¶

cargo test --lib

Runs all inline #[test] functions in src/. Fast, no external dependencies.

Integration tests¶

cargo test --test integration
cargo test --test raft_integration

These tests start an in-process HyperbyteDB server with real RocksDB and chDB. They create temporary directories and clean up after themselves.

Compatibility tests¶

cargo test --test compat

The tests/compat/ directory contains a comprehensive InfluxDB v1 compatibility suite:

All Rust tests¶

cargo test

Tests with features¶

cargo test --all-features

Run this when touching columnar-ingest or other feature-gated code paths.

End-to-end tests (Go)¶

cd tests/e2e
go test -v -timeout 5m

These tests require running HyperbyteDB instances. They test cluster scenarios: - cluster_test.go — Multi-node basic operations - drain_test.go — Graceful drain procedure - failover_test.go — Node failure and recovery - raft_test.go — Raft consensus behavior - replication_test.go — Write replication - rolling_restart_test.go — Rolling restart safety - sync_test.go — Data synchronization

Benchmarks¶

# Line protocol ingestion benchmarks
cargo bench --bench ingestion_line_protocol

# Columnar ingestion benchmarks (requires feature)
cargo bench --bench ingestion_columnar --features columnar-ingest

Criterion generates HTML reports in target/criterion/.

WalPort contract test¶

cargo test -p hyperbytedb --features sim --test wal_port_contract

This test runs an arbitrary, seeded sequence of WalPort operations against both MemoryWal (simulation-only, behind --features sim) and the real RocksDbWal, and asserts their outputs are byte-for-byte identical after every step. It is the semantic bridge between the HyperSim simulator and the production WAL adapter: any divergence caught here means a HyperSim finding might not transfer to production, or a production behavior is not being exercised under simulation. See hypersim/README.md § 8 for the rationale.

HyperSim (deterministic simulation)¶

# Full 100-run suite (release build, ~5m on 8 cores).
make hypersim-validate

# Fast developer loop (10 runs, debug build).
make hypersim-validate-dev

# Single run with a chosen seed.
cargo run --release -p hypersim --bin hypersim -- vopr-safety \
    --seed 0xDEADBEEF --virtual-hours 1

HyperSim is the TigerBeetle-style DST framework; see hypersim/README.md for architecture, fault model, invariants, and replay tooling. CI runs the 100-run suite on every PR.

Writing Tests¶

Unit tests¶

Add tests inline in the source file:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_something() {
        let result = my_function("input");
        assert_eq!(result, expected_output);
    }
}

Integration tests¶

Integration tests use a shared test harness that starts an in-process server:

// tests/integration.rs
use hyperbytedb::bootstrap::build_services;

#[tokio::test]
async fn test_write_and_query() {
    let app = setup_test_app().await;
    // Write data via the HTTP handler
    // Query and verify results
}

Compatibility tests¶

Follow the patterns in tests/compat/. Each test module focuses on a specific feature area and verifies InfluxDB v1 behavioral compatibility.

Test Architecture¶

In-process testing¶

Integration and compat tests run an in-process Axum application. This avoids the overhead of starting a separate process and allows direct access to internal state for assertions.

The test harness: 1. Creates temporary directories for WAL, metadata, data, and chDB. 2. Builds services via build_services(). 3. Constructs the Axum router. 4. Sends HTTP requests directly to the router (no network I/O). 5. Cleans up temporary directories on drop.

Cluster testing¶

Cluster tests (Raft integration, Go e2e) require multiple server instances. The Go tests in tests/e2e/ manage the lifecycle of multiple HyperbyteDB processes, waiting for health checks before running scenarios.

CI Test Matrix¶

The CI pipeline (.github/workflows/ci.yml) runs:

All jobs install system dependencies (clang, llvm-dev, libclang-dev, pkg-config, libssl-dev) and libchdb via curl -sL https://lib.chdb.io | bash.

See Also¶

• Building & CI — CI pipeline details
• Contributing — Review process and test expectations