From 6202224350d6c170a77308581ad8c941cb3dbfd5 Mon Sep 17 00:00:00 2001 From: andrussal Date: Wed, 10 Dec 2025 15:42:32 +0100 Subject: [PATCH] Reorganize k8s runner modules --- README.md | 161 +++++++++++++++++- docs/index.md | 4 +- testing-framework/runners/k8s/src/deployer.rs | 17 +- .../k8s/src/{ => infrastructure}/assets.rs | 0 .../k8s/src/{ => infrastructure}/cluster.rs | 14 +- .../k8s/src/{ => infrastructure}/helm.rs | 2 +- .../runners/k8s/src/infrastructure/mod.rs | 3 + testing-framework/runners/k8s/src/lib.rs | 12 +- .../k8s/src/{ => lifecycle}/block_feed.rs | 0 .../k8s/src/{ => lifecycle}/cleanup.rs | 2 +- .../runners/k8s/src/{ => lifecycle}/logs.rs | 0 .../runners/k8s/src/lifecycle/mod.rs | 4 + .../src/{ => lifecycle}/wait/deployment.rs | 0 .../src/{ => lifecycle}/wait/forwarding.rs | 0 .../src/{ => lifecycle}/wait/http_probe.rs | 0 .../k8s/src/{ => lifecycle}/wait/mod.rs | 0 .../src/{ => lifecycle}/wait/orchestrator.rs | 2 +- .../k8s/src/{ => lifecycle}/wait/ports.rs | 0 .../src/{ => lifecycle}/wait/prometheus.rs | 0 19 files changed, 188 insertions(+), 33 deletions(-) rename testing-framework/runners/k8s/src/{ => infrastructure}/assets.rs (100%) rename testing-framework/runners/k8s/src/{ => infrastructure}/cluster.rs (96%) rename testing-framework/runners/k8s/src/{ => infrastructure}/helm.rs (98%) create mode 100644 testing-framework/runners/k8s/src/infrastructure/mod.rs rename testing-framework/runners/k8s/src/{ => lifecycle}/block_feed.rs (100%) rename testing-framework/runners/k8s/src/{ => lifecycle}/cleanup.rs (99%) rename testing-framework/runners/k8s/src/{ => lifecycle}/logs.rs (100%) create mode 100644 testing-framework/runners/k8s/src/lifecycle/mod.rs rename testing-framework/runners/k8s/src/{ => lifecycle}/wait/deployment.rs (100%) rename testing-framework/runners/k8s/src/{ => lifecycle}/wait/forwarding.rs (100%) rename testing-framework/runners/k8s/src/{ => lifecycle}/wait/http_probe.rs (100%) rename testing-framework/runners/k8s/src/{ => lifecycle}/wait/mod.rs (100%) rename testing-framework/runners/k8s/src/{ => lifecycle}/wait/orchestrator.rs (99%) rename testing-framework/runners/k8s/src/{ => lifecycle}/wait/ports.rs (100%) rename testing-framework/runners/k8s/src/{ => lifecycle}/wait/prometheus.rs (100%) diff --git a/README.md b/README.md index 3a0a135..bc056ee 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,157 @@ -# Nomos Testing +# Logos Blockchain Testing Framework -This repo is the standalone Nomos testing framework. For docs, quick start, and examples, read the mdBook at https://logos-co.github.io/nomos-testing/ (sources in `book/`) — start with: -- What you’ll learn: https://logos-co.github.io/nomos-testing/what-you-will-learn.html -- Quick examples: https://logos-co.github.io/nomos-testing/examples.html and https://logos-co.github.io/nomos-testing/examples-advanced.html -- Runners (compose/k8s/local): https://logos-co.github.io/nomos-testing/runners.html +A comprehensive testing framework for the Logos blockchain implementation, providing declarative scenario definitions, multiple deployment backends, and production-grade observability. -Key crates live under `testing-framework/` (core, runners, workflows, configs) with integration tests in `tests/workflows/`. Compose/k8s assets sit in `testing-framework/assets/stack/`. +## 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 chaos engineering +- **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 and `kubectl` + +### Run Your First Test + +```bash +# Host mode (local processes) - fastest iteration +scripts/run-examples.sh -t 60 -v 1 -e 1 host + +# Compose mode (Docker containers) - reproducible environment +scripts/run-examples.sh -t 60 -v 1 -e 1 compose + +# K8s mode (Kubernetes cluster) - production-like fidelity +scripts/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](https://logos-blockchain.github.io/logos-blockchain-testing/quickstart.html) | +| **Core Concepts** | [Testing Philosophy](https://logos-blockchain.github.io/logos-blockchain-testing/testing-philosophy.html) | +| **Examples** | [Basic](https://logos-blockchain.github.io/logos-blockchain-testing/examples.html) \| [Advanced](https://logos-blockchain.github.io/logos-blockchain-testing/examples-advanced.html) | +| **Deployment Options** | [Runners Overview](https://logos-blockchain.github.io/logos-blockchain-testing/runners.html) | +| **API Reference** | [Builder API](https://logos-blockchain.github.io/logos-blockchain-testing/dsl-cheat-sheet.html) | +| **Operations** | [Setup & Configuration](https://logos-blockchain.github.io/logos-blockchain-testing/operations.html) | +| **Troubleshooting** | [Common Issues](https://logos-blockchain.github.io/logos-blockchain-testing/troubleshooting.html) | + +## 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 + +```bash +# Install mdBook +cargo install mdbook mdbook-mermaid + +# Build and serve locally +cd book && mdbook serve +# Open http://localhost:3000 +``` + +### Running Tests + +```bash +# Run framework unit tests +cargo test + +# Run integration examples +scripts/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: + +```bash +# Build Linux bundle (required for compose/k8s) +scripts/build-bundle.sh --platform linux + +# Use the bundle when building images +export NOMOS_BINARIES_TAR=.tmp/nomos-binaries-linux-v0.3.1.tar.gz +testing-framework/assets/stack/scripts/build_test_image.sh +``` + +## Environment Variables + +Key environment variables for customization: + +| Variable | Purpose | Default | +|----------|---------|---------| +| `POL_PROOF_DEV_MODE=true` | **Required** — Disable expensive proof generation | (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](https://logos-blockchain.github.io/logos-blockchain-testing/operations.html) 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](https://logos-blockchain.github.io/logos-blockchain-testing/troubleshooting.html) or file an issue in this repository. diff --git a/docs/index.md b/docs/index.md index ccf61fd..da6181b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ -# Nomos testing documentation +# Logos Blockchain Testing Framework Documentation The documentation is published via the mdBook pipeline. If you reached this page, visit the book instead: -- Latest published book: https://logos-co.github.io/nomos-testing/book/ +- Latest published book: https://logos-blockchain.github.io/logos-blockchain-testing/ This placeholder exists to satisfy the GitHub Pages build job that expects a `docs/` directory. diff --git a/testing-framework/runners/k8s/src/deployer.rs b/testing-framework/runners/k8s/src/deployer.rs index 3739e27..f367e05 100644 --- a/testing-framework/runners/k8s/src/deployer.rs +++ b/testing-framework/runners/k8s/src/deployer.rs @@ -8,15 +8,16 @@ use testing_framework_core::{ use tracing::{error, info}; use crate::{ - assets::{AssetsError, prepare_assets}, - block_feed::spawn_block_feed_with, - cleanup::RunnerCleanup, - cluster::{ - ClusterEnvironment, NodeClientError, PortSpecs, RemoteReadinessError, build_node_clients, - cluster_identifiers, collect_port_specs, ensure_cluster_readiness, install_stack, - kill_port_forwards, metrics_handle_from_port, wait_for_ports_or_cleanup, + infrastructure::{ + assets::{AssetsError, prepare_assets}, + cluster::{ + ClusterEnvironment, NodeClientError, PortSpecs, RemoteReadinessError, + build_node_clients, cluster_identifiers, collect_port_specs, ensure_cluster_readiness, + install_stack, kill_port_forwards, metrics_handle_from_port, wait_for_ports_or_cleanup, + }, + helm::HelmError, }, - helm::HelmError, + lifecycle::{block_feed::spawn_block_feed_with, cleanup::RunnerCleanup}, wait::ClusterWaitError, }; diff --git a/testing-framework/runners/k8s/src/assets.rs b/testing-framework/runners/k8s/src/infrastructure/assets.rs similarity index 100% rename from testing-framework/runners/k8s/src/assets.rs rename to testing-framework/runners/k8s/src/infrastructure/assets.rs diff --git a/testing-framework/runners/k8s/src/cluster.rs b/testing-framework/runners/k8s/src/infrastructure/cluster.rs similarity index 96% rename from testing-framework/runners/k8s/src/cluster.rs rename to testing-framework/runners/k8s/src/infrastructure/cluster.rs index edc1f2c..464a62b 100644 --- a/testing-framework/runners/k8s/src/cluster.rs +++ b/testing-framework/runners/k8s/src/infrastructure/cluster.rs @@ -12,10 +12,9 @@ use url::ParseError; use uuid::Uuid; use crate::{ - assets::RunnerAssets, - cleanup::RunnerCleanup, host::node_host, - logs::dump_namespace_logs, + infrastructure::assets::RunnerAssets, + lifecycle::{cleanup::RunnerCleanup, logs::dump_namespace_logs}, wait::{ClusterPorts, ClusterReady, NodeConfigPorts, wait_for_cluster_ready}, }; @@ -72,7 +71,7 @@ impl ClusterEnvironment { dump_namespace_logs(&self.client, &self.namespace).await; kill_port_forwards(&mut self.port_forwards); if let Some(guard) = self.cleanup.take() { - Box::new(guard).cleanup(); + CleanupGuard::cleanup(Box::new(guard)); } } @@ -228,7 +227,8 @@ pub async fn install_stack( namespace = %namespace, "installing helm release" ); - crate::helm::install_release(assets, release, namespace, validators, executors).await?; + crate::infrastructure::helm::install_release(assets, release, namespace, validators, executors) + .await?; tracing::info!(release = %release, "helm install succeeded"); let preserve = env::var("K8S_RUNNER_PRESERVE").is_ok(); @@ -288,9 +288,9 @@ pub fn kill_port_forwards(handles: &mut Vec) { } async fn cleanup_pending(client: &Client, namespace: &str, guard: &mut Option) { - crate::logs::dump_namespace_logs(client, namespace).await; + crate::lifecycle::logs::dump_namespace_logs(client, namespace).await; if let Some(guard) = guard.take() { - Box::new(guard).cleanup(); + CleanupGuard::cleanup(Box::new(guard)); } } diff --git a/testing-framework/runners/k8s/src/helm.rs b/testing-framework/runners/k8s/src/infrastructure/helm.rs similarity index 98% rename from testing-framework/runners/k8s/src/helm.rs rename to testing-framework/runners/k8s/src/infrastructure/helm.rs index 6c5d46c..c0ec10e 100644 --- a/testing-framework/runners/k8s/src/helm.rs +++ b/testing-framework/runners/k8s/src/infrastructure/helm.rs @@ -3,7 +3,7 @@ use std::{io, process::Stdio}; use thiserror::Error; use tokio::process::Command; -use crate::assets::{RunnerAssets, cfgsync_port_value, workspace_root}; +use crate::infrastructure::assets::{RunnerAssets, cfgsync_port_value, workspace_root}; /// Errors returned from Helm invocations. #[derive(Debug, Error)] diff --git a/testing-framework/runners/k8s/src/infrastructure/mod.rs b/testing-framework/runners/k8s/src/infrastructure/mod.rs new file mode 100644 index 0000000..6bd03c5 --- /dev/null +++ b/testing-framework/runners/k8s/src/infrastructure/mod.rs @@ -0,0 +1,3 @@ +pub mod assets; +pub mod cluster; +pub mod helm; diff --git a/testing-framework/runners/k8s/src/lib.rs b/testing-framework/runners/k8s/src/lib.rs index 216941d..4cf8f5d 100644 --- a/testing-framework/runners/k8s/src/lib.rs +++ b/testing-framework/runners/k8s/src/lib.rs @@ -1,11 +1,9 @@ -mod assets; -mod block_feed; -mod cleanup; -mod cluster; mod deployer; -mod helm; mod host; -mod logs; -mod wait; +mod infrastructure; +mod lifecycle; +pub mod wait { + pub use crate::lifecycle::wait::*; +} pub use deployer::{K8sDeployer, K8sRunnerError}; diff --git a/testing-framework/runners/k8s/src/block_feed.rs b/testing-framework/runners/k8s/src/lifecycle/block_feed.rs similarity index 100% rename from testing-framework/runners/k8s/src/block_feed.rs rename to testing-framework/runners/k8s/src/lifecycle/block_feed.rs diff --git a/testing-framework/runners/k8s/src/cleanup.rs b/testing-framework/runners/k8s/src/lifecycle/cleanup.rs similarity index 99% rename from testing-framework/runners/k8s/src/cleanup.rs rename to testing-framework/runners/k8s/src/lifecycle/cleanup.rs index 41c7c60..545cf70 100644 --- a/testing-framework/runners/k8s/src/cleanup.rs +++ b/testing-framework/runners/k8s/src/lifecycle/cleanup.rs @@ -9,7 +9,7 @@ use tokio::{ }; use tracing::warn; -use crate::helm::uninstall_release; +use crate::infrastructure::helm::uninstall_release; /// Tears down Helm release and namespace after a run unless preservation is /// set. diff --git a/testing-framework/runners/k8s/src/logs.rs b/testing-framework/runners/k8s/src/lifecycle/logs.rs similarity index 100% rename from testing-framework/runners/k8s/src/logs.rs rename to testing-framework/runners/k8s/src/lifecycle/logs.rs diff --git a/testing-framework/runners/k8s/src/lifecycle/mod.rs b/testing-framework/runners/k8s/src/lifecycle/mod.rs new file mode 100644 index 0000000..4354505 --- /dev/null +++ b/testing-framework/runners/k8s/src/lifecycle/mod.rs @@ -0,0 +1,4 @@ +pub mod block_feed; +pub mod cleanup; +pub mod logs; +pub mod wait; diff --git a/testing-framework/runners/k8s/src/wait/deployment.rs b/testing-framework/runners/k8s/src/lifecycle/wait/deployment.rs similarity index 100% rename from testing-framework/runners/k8s/src/wait/deployment.rs rename to testing-framework/runners/k8s/src/lifecycle/wait/deployment.rs diff --git a/testing-framework/runners/k8s/src/wait/forwarding.rs b/testing-framework/runners/k8s/src/lifecycle/wait/forwarding.rs similarity index 100% rename from testing-framework/runners/k8s/src/wait/forwarding.rs rename to testing-framework/runners/k8s/src/lifecycle/wait/forwarding.rs diff --git a/testing-framework/runners/k8s/src/wait/http_probe.rs b/testing-framework/runners/k8s/src/lifecycle/wait/http_probe.rs similarity index 100% rename from testing-framework/runners/k8s/src/wait/http_probe.rs rename to testing-framework/runners/k8s/src/lifecycle/wait/http_probe.rs diff --git a/testing-framework/runners/k8s/src/wait/mod.rs b/testing-framework/runners/k8s/src/lifecycle/wait/mod.rs similarity index 100% rename from testing-framework/runners/k8s/src/wait/mod.rs rename to testing-framework/runners/k8s/src/lifecycle/wait/mod.rs diff --git a/testing-framework/runners/k8s/src/wait/orchestrator.rs b/testing-framework/runners/k8s/src/lifecycle/wait/orchestrator.rs similarity index 99% rename from testing-framework/runners/k8s/src/wait/orchestrator.rs rename to testing-framework/runners/k8s/src/lifecycle/wait/orchestrator.rs index c4f46e4..e525414 100644 --- a/testing-framework/runners/k8s/src/wait/orchestrator.rs +++ b/testing-framework/runners/k8s/src/lifecycle/wait/orchestrator.rs @@ -5,7 +5,7 @@ use super::{ ClusterPorts, ClusterReady, ClusterWaitError, NodeConfigPorts, PROMETHEUS_HTTP_PORT, PROMETHEUS_HTTP_PROBE_TIMEOUT, PROMETHEUS_SERVICE_NAME, }; -use crate::wait::{ +use crate::lifecycle::wait::{ deployment::wait_for_deployment_ready, forwarding::{kill_port_forwards, port_forward_group, port_forward_service}, http_probe::{wait_for_node_http_nodeport, wait_for_node_http_port_forward}, diff --git a/testing-framework/runners/k8s/src/wait/ports.rs b/testing-framework/runners/k8s/src/lifecycle/wait/ports.rs similarity index 100% rename from testing-framework/runners/k8s/src/wait/ports.rs rename to testing-framework/runners/k8s/src/lifecycle/wait/ports.rs diff --git a/testing-framework/runners/k8s/src/wait/prometheus.rs b/testing-framework/runners/k8s/src/lifecycle/wait/prometheus.rs similarity index 100% rename from testing-framework/runners/k8s/src/wait/prometheus.rs rename to testing-framework/runners/k8s/src/lifecycle/wait/prometheus.rs