A comprehensive testing framework for the Logos blockchain implementation, providing declarative scenario definitions, multiple deployment backends, and production-grade observability.

Overview

This framework enables you to define, deploy, and execute integration tests for Logos blockchain scenarios across different environments—from local processes to containerized Kubernetes deployments—using a unified API.

Key capabilities:

Declarative scenario model — Define topology, workloads, and success criteria using a fluent builder API
Multiple deployment backends — Local processes, Docker Compose, or Kubernetes
Built-in workloads — Transaction injection, DA (Data Availability) traffic, and restart-based chaos (requires node control; compose runner supported)
Observability-first — Integrated Prometheus metrics, structured logging, and OpenTelemetry support
Production-ready — Used in CI/CD pipelines with reproducible containerized environments

Quick Start

Prerequisites

Rust toolchain (nightly)
versions.env file at repository root (included)
For Docker Compose: Docker daemon
For Kubernetes: Cluster access, kubectl, and helm

Run Your First Test

# Host mode (local processes) - fastest iteration
scripts/run/run-examples.sh -t 60 -v 1 -e 1 host

# Compose mode (Docker containers) - reproducible environment
scripts/run/run-examples.sh -t 60 -v 1 -e 1 compose

# K8s mode (Kubernetes cluster) - production-like fidelity
scripts/run/run-examples.sh -t 60 -v 1 -e 1 k8s

The script handles circuit setup, binary building, image preparation, and scenario execution automatically.

Documentation

Complete documentation available at: https://logos-blockchain.github.io/logos-blockchain-testing/

Essential Guides

Topic	Link
Getting Started	Quickstart Guide
Core Concepts	Testing Philosophy
Examples	Basic \| Advanced
Deployment Options	Runners Overview
API Reference	Builder API
Operations	Setup & Configuration
Troubleshooting	Common Issues

Repository Structure

logos-blockchain-testing/
├── testing-framework/     # Core library crates
│   ├── core/             # Scenario model, runtime orchestration
│   ├── workflows/        # Workloads (tx, DA, chaos) and expectations
│   ├── configs/          # Node configuration builders
│   ├── runners/          # Deployment backends (local, compose, k8s)
│   └── assets/stack/     # Docker/K8s deployment assets
├── examples/             # Runnable demo binaries
│   └── src/bin/          # local_runner, compose_runner, k8s_runner
├── scripts/              # Helper utilities (run-examples.sh, build-bundle.sh)
└── book/                 # Documentation sources (mdBook)

Architecture

The framework follows a clear separation of concerns:

Scenario Definition → Topology Builder → Deployer → Runner → Workloads → Expectations

Scenario: Declarative description of test intent (topology + workloads + success criteria)
Deployer: Provisions infrastructure on chosen backend (host/compose/k8s)
Runner: Orchestrates execution, manages lifecycle, collects observability
Workloads: Generate traffic and conditions (transactions, DA blobs, chaos)
Expectations: Evaluate success/failure based on observed behavior

Development

Building the Documentation

# Install mdBook
cargo install mdbook mdbook-mermaid

# Build and serve locally
cd book && mdbook serve
# Open http://localhost:3000

Running Tests

# Run framework unit tests
cargo test

# Run integration examples
scripts/run/run-examples.sh -t 60 -v 2 -e 1 host

Creating Prebuilt Bundles

For compose/k8s deployments, you can create prebuilt bundles to speed up image builds:

# Build Linux bundle (required for compose/k8s)
scripts/build/build-bundle.sh --platform linux

# Use the bundle when building images
export NOMOS_BINARIES_TAR=.tmp/nomos-binaries-linux-v0.3.1.tar.gz
scripts/build/build_test_image.sh

Environment Variables

Key environment variables for customization:

Variable	Purpose	Default
`POL_PROOF_DEV_MODE=true`	Required — Disable expensive proof generation (set automatically by `scripts/run/run-examples.sh`)	(none)
`NOMOS_TESTNET_IMAGE`	Docker image tag for compose/k8s	`logos-blockchain-testing:local`
`NOMOS_DEMO_VALIDATORS`	Number of validator nodes	Varies by example
`NOMOS_DEMO_EXECUTORS`	Number of executor nodes	Varies by example
`NOMOS_LOG_DIR`	Directory for persistent log files	(temporary)
`NOMOS_LOG_LEVEL`	Logging verbosity	`info`

See Operations Guide for complete configuration reference.

CI/CD Integration

The framework is designed for CI/CD pipelines:

Host runner: Fast smoke tests with minimal overhead
Compose runner: Reproducible containerized environment with Prometheus
K8s runner: Production-like cluster validation

Example CI workflow: .github/workflows/lint.yml (see compose_smoke job)

License

This project is part of the Logos blockchain implementation.

Support

For issues, questions, or contributions, please refer to the Troubleshooting Guide or file an issue in this repository.

Languages

Rust 81.8%

Shell 17.4%

JavaScript 0.4%

CSS 0.2%

Smarty 0.2%

README.md

Logos Blockchain Testing Framework