Volley ⚡

Volley is an open-source, dual-language distributed load-testing platform engineered for extreme performance and strict zero-GC latency guarantees.

It is designed to cleanly separate the Control Plane (written in Go) from the Load Generation Engine (written in Rust), tied together via a strictly typed gRPC Protobuf schema.

Why Volley?

Most load testing tools embed scripting languages (like V8 or Lua) directly into their load generation engine. This causes massive garbage collection (GC) pauses under heavy concurrency, leading to inaccurate latency measurements (the "coordinated omission" problem).

Volley fixes this by separating the scripting from the execution:

1. Python SDK: You write test plans in Python using a fluent, declarative builder.
2. Go Controller: The Go CLI parses your Python script once, generating a declarative Protobuf TestPlan.
3. Rust Agents: The Rust execution engine natively parses the Protobuf and generates asynchronous Tokio/Hyper HTTP load without any embedded runtime overhead.

---

🚀 Quickstart

Prerequisites

• Go 1.23+
• Rust & Cargo
• Podman (for local cluster provisioning)
• Python 3.8+

Installation

1. Install the CLI:

   cd volley-core
   go build -o volley ./cmd/cli

   Note: Add the volley executable to your system PATH.

2. Install the Python SDK:

   cd volley-sdk
   pip install -e .

Writing Your First Test

Create a file called test.py anywhere on your machine:

import volley

def test():
    return (
        volley.scenario("checkout-flow")
        .stage(target_vus=0, duration="0s")
        .stage(target_vus=100, duration="30s")   # Ramp up to 100 virtual users
        .stage(target_vus=100, duration="2m")    # Hold at 100 virtual users
        .stage(target_vus=0, duration="15s")     # Ramp down
        .request("GET", "https://api.example.com/health")
        .check("status == 200")                  # Declarative assertion
        .abort_if("error_rate > 0.05")           # Safety threshold
    )

test()

Running the Test

To run the test locally, Volley will automatically bootstrap a Controller and Agent via local Podman containers:

volley run test.py

Output:

✅ Script compiled. Launching local fleet...
2026/06/24 19:58:24 Starting local Volley Controller container...
2026/06/24 19:58:24 Cluster provisioned successfully. Streaming telemetry...

VUs        | p50 (ms)   | p95 (ms)   | p99 (ms)   | Error Rate
----------------------------------------------------------------
100        | 24         | 85         | 120        | 0.00      %

---

💻 CLI Command Guide

The volley CLI tool acts as both the script compiler and the fleet orchestrator.

Command	Description
volley run <script.py>	Compiles the plan, provisions a local Podman cluster, runs the test, and streams telemetry to the terminal.
volley validate <script.py>	Validates the Python script syntax offline and ensures the checks map correctly to the protobuf schema without making network calls.
volley plan <script.py>	Compiles the script and prints the raw JSON/Protobuf TestPlan payload to stdout. Ideal for debugging or committing declarative plans to git.

---

🛠️ Contributing & Architecture

Are you a developer looking to understand how Volley is built? We'd love your contributions! Please read the Developer Guide to understand the system architecture, how the Write-Ahead Log works, and how to compile the gRPC stubs.