logos-blockchain-testing/book/src/project-context-primer.md

# Logos Testing Framework

**Declarative, multi-node blockchain testing for the Logos network**

The Logos Testing Framework enables you to test consensus and transaction workloads across local processes, Docker Compose, and Kubernetes deployments—all with a unified scenario API.

[**Get Started**](quickstart.md)

---

## Core Concept

**Everything in this framework is a Scenario.**

A Scenario is a controlled experiment over time, composed of:
- **Topology** — The cluster shape (nodes, network layout)
- **Workloads** — Traffic and conditions that exercise the system (transactions, chaos)
- **Expectations** — Success criteria verified after execution (liveness, inclusion, recovery)
- **Duration** — The time window for the experiment

This single abstraction makes tests declarative, portable, and composable.

---

## How It Works

```mermaid
flowchart LR
    Build[Define Scenario] --> Deploy[Deploy Topology]
    Deploy --> Execute[Run Workloads]
    Execute --> Evaluate[Check Expectations]
    
    style Build fill:#e1f5ff
    style Deploy fill:#fff4e1
    style Execute fill:#ffe1f5
    style Evaluate fill:#e1ffe1
```

1. **Define Scenario** — Describe your test: topology, workloads, and success criteria
2. **Deploy Topology** — Launch nodes using host, compose, or k8s runners
3. **Run Workloads** — Drive transactions and chaos operations
4. **Check Expectations** — Verify consensus liveness, inclusion, and system health

---

## Key Features

**Declarative API**
- Express scenarios as topology + workloads + expectations
- Reuse the same test definition across different deployment targets
- Compose complex tests from modular components

**Multiple Deployment Modes**
- **Host Runner**: Local processes for fast iteration
- **Compose Runner**: Containerized environments with node control
- **Kubernetes Runner**: Production-like cluster testing

**Built-in Workloads**
- Transaction submission with configurable rates
- Chaos testing with controlled node restarts

**Comprehensive Observability**
- Real-time block feed for monitoring consensus progress
- Prometheus/Grafana integration for metrics
- Per-node log collection and debugging

---

## Quick Example

```rust,ignore
use std::time::Duration;

use testing_framework_core::scenario::ScenarioBuilder;
use testing_framework_core::scenario::Deployer as _;
use testing_framework_runner_local::LocalDeployer;
use testing_framework_workflows::ScenarioBuilderExt;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut scenario = ScenarioBuilder::topology_with(|t| {
        t.network_star()
            .nodes(3)
    })
    .transactions_with(|tx| tx.rate(10).users(5))
    .expect_consensus_liveness()
    .with_run_duration(Duration::from_secs(60))
    .build();

    let deployer = LocalDeployer::default();
    let runner = deployer.deploy(&scenario).await?;
    runner.run(&mut scenario).await?;

    Ok(())
}
```

[View complete examples](examples.md)

---

## Choose Your Path

### New to the Framework?

Start with the **[Quickstart Guide](quickstart.md)** for a hands-on introduction that gets you running tests in minutes.

### Ready to Write Tests?

Explore the **[User Guide](part-ii.md)** to learn about authoring scenarios, workloads, expectations, and deployment strategies.

### Setting Up CI/CD?

Jump to **[Operations & Deployment](part-v.md)** for prerequisites, environment configuration, and continuous integration patterns.

### Extending the Framework?

Check the **[Developer Reference](part-iii.md)** to implement custom workloads, expectations, and runners.

---

## Project Context

**Logos** is a modular blockchain protocol composed of nodes that participate in consensus and produce blocks.

Meaningful testing must be performed in multi-node environments that include real networking and timing behavior.

The Logos Testing Framework provides the infrastructure to orchestrate these multi-node scenarios reliably across development, CI, and production-like environments.

**Learn more about the protocol:** [Logos Project Documentation](https://nomos-tech.notion.site/project)

---

## Documentation Structure

| Section | Description |
|---------|-------------|
| **[Foundations](part-i.md)** | Architecture, philosophy, and design principles |
| **[User Guide](part-ii.md)** | Writing and running scenarios, workloads, and expectations |
| **[Developer Reference](part-iii.md)** | Extending the framework with custom components |
| **[Operations & Deployment](part-iv.md)** | Setup, CI integration, and environment configuration |
| **[Appendix](part-v.md)** | Quick reference, troubleshooting, FAQ, and glossary |

---

## Quick Links

- **[What You Will Learn](what-you-will-learn.md)** — Overview of book contents and learning path
- **[Quickstart](quickstart.md)** — Get up and running in 10 minutes
- **[Examples](examples.md)** — Concrete scenario patterns
- **[Troubleshooting](troubleshooting.md)** — Common issues and solutions
- **[Environment Variables](environment-variables.md)** — Complete configuration reference

---

**Ready to start?** Head to the **[Quickstart](quickstart.md)**