Logos Testing Framework

Declarative, multi-node blockchain testing for the Logos network

The Logos Testing Framework enables you to test consensus and transaction workloads across local processes, Docker Compose, and Kubernetes deployments—all with a unified scenario API.

Get Started

Core Concept

Everything in this framework is a Scenario.

A Scenario is a controlled experiment over time, composed of:

• Topology — The cluster shape (nodes, network layout)
• Workloads — Traffic and conditions that exercise the system (transactions, chaos)
• Expectations — Success criteria verified after execution (liveness, inclusion, recovery)
• Duration — The time window for the experiment

This single abstraction makes tests declarative, portable, and composable.

How It Works

flowchart LR
    Build[Define Scenario] --> Deploy[Deploy Topology]
    Deploy --> Execute[Run Workloads]
    Execute --> Evaluate[Check Expectations]
    
    style Build fill:#e1f5ff
    style Deploy fill:#fff4e1
    style Execute fill:#ffe1f5
    style Evaluate fill:#e1ffe1

1. Define Scenario — Describe your test: topology, workloads, and success criteria
2. Deploy Topology — Launch nodes using host, compose, or k8s runners
3. Run Workloads — Drive transactions and chaos operations
4. Check Expectations — Verify consensus liveness, inclusion, and system health

Key Features

Declarative API

• Express scenarios as topology + workloads + expectations
• Reuse the same test definition across different deployment targets
• Compose complex tests from modular components

Multiple Deployment Modes

• Host Runner: Local processes for fast iteration
• Compose Runner: Containerized environments with node control
• Kubernetes Runner: Production-like cluster testing

Built-in Workloads

• Transaction submission with configurable rates
• Chaos testing with controlled node restarts

Comprehensive Observability

• Real-time block feed for monitoring consensus progress
• Prometheus/Grafana integration for metrics
• Per-node log collection and debugging

Quick Example

use std::time::Duration;

use testing_framework_core::scenario::ScenarioBuilder;
use testing_framework_core::scenario::Deployer as _;
use testing_framework_runner_local::LocalDeployer;
use testing_framework_workflows::ScenarioBuilderExt;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut scenario = ScenarioBuilder::topology_with(|t| {
        t.network_star()
            .nodes(3)
    })
    .transactions_with(|tx| tx.rate(10).users(5))
    .expect_consensus_liveness()
    .with_run_duration(Duration::from_secs(60))
    .build();

    let deployer = LocalDeployer::default();
    let runner = deployer.deploy(&scenario).await?;
    runner.run(&mut scenario).await?;

    Ok(())
}

View complete examples

Choose Your Path

New to the Framework?

Start with the Quickstart Guide for a hands-on introduction that gets you running tests in minutes.

Ready to Write Tests?

Explore the User Guide to learn about authoring scenarios, workloads, expectations, and deployment strategies.

Setting Up CI/CD?

Jump to Operations & Deployment for prerequisites, environment configuration, and continuous integration patterns.

Extending the Framework?

Check the Developer Reference to implement custom workloads, expectations, and runners.

Project Context

Logos is a modular blockchain protocol composed of nodes that participate in consensus and produce blocks.

Meaningful testing must be performed in multi-node environments that include real networking and timing behavior.

The Logos Testing Framework provides the infrastructure to orchestrate these multi-node scenarios reliably across development, CI, and production-like environments.

Learn more about the protocol: Logos Project Documentation

Documentation Structure

Quick Links

• What You Will Learn — Overview of book contents and learning path
• Quickstart — Get up and running in 10 minutes
• Examples — Concrete scenario patterns
• Troubleshooting — Common issues and solutions
• Environment Variables — Complete configuration reference

Ready to start? Head to the Quickstart