870280e354
Refactors long cfgsync helpers into smaller steps.
- ConfigRepo::run
- Before: wait/timeout + lock draining + config generation + per-host response sending in one block.
- After: wait_for_hosts_with_timeout/take_waiting_hosts/generate_node_configs/
send_error_to_all/send_timeout_to_all/send_configs_to_all_hosts.
- try_create_providers
- Before: mixed validation + duplicated locator parsing for DA/Blend.
- After: validate_provider_inputs/build_da_providers/build_blend_providers/locator_for_host.
Logos Blockchain Testing Framework
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.envfile at repository root (included)- For Docker Compose: Docker daemon
- For Kubernetes: Cluster access,
kubectl, andhelm
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.
Links
- Documentation: https://logos-blockchain.github.io/logos-blockchain-testing/
- Logos Project: https://github.com/logos-co
- Nomos Node: https://github.com/logos-co/nomos-node
Support
For issues, questions, or contributions, please refer to the Troubleshooting Guide or file an issue in this repository.