Reorganize k8s runner modules

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.

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.

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,
 };
 

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<std::process::Child>) {
 }
 
 async fn cleanup_pending(client: &Client, namespace: &str, guard: &mut Option<RunnerCleanup>) {
-    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));
     }
 }
 

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)]

testing-framework/runners/k8s/src/infrastructure/mod.rs

@@ -0,0 +1,3 @@
+pub mod assets;
+pub mod cluster;
+pub mod helm;

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};

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.

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;

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},