mirror of
https://github.com/logos-blockchain/logos-blockchain-testing.git
synced 2026-01-02 13:23:13 +00:00
938d782f8d
Refactors long deployer functions into smaller phase helpers.
- k8s deploy_with_observability
- Before: env/capability observability merge + cluster setup + client/telemetry/block feed init + endpoint printing + Runner construction.
- After: resolve_observability_inputs/init_kube_client/build_node_clients_or_fail/
build_telemetry_or_fail/spawn_block_feed_or_fail/maybe_print_endpoints/finalize_runner.
- k8s prepare_assets/build_values
- Before: cfgsync render + tempdir + script/KZG/chart/values resolution in one function; duplicated validator/executor env building.
- After: create_assets_tempdir/render_and_write_cfgsync/resolve_kzg_path/
render_and_write_values/testnet_image + build_node_group/build_node_values.
- k8s install_release
- Before: mixed KZG arg resolution + long CLI arg chain + debug logging.
- After: resolve_kzg_install_args/build_install_command/maybe_log_install_output.
- compose DeploymentOrchestrator::deploy
- Before: env/cap observability merge + readiness + endpoint logging/printing + Runner construction.
- After: resolve_observability_inputs/wait_for_readiness_or_grace_period/
log_observability_endpoints/maybe_print_endpoints.
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.