rampa¶

Async Python load testing, inspired by k6.

Write an async scenario function, run it, get request metrics with percentiles, checks, thresholds, and correct exit codes.

With uvx run installed:

$ uvx rampa --help

Then run it from the terminal:

$ uvx rampa run load_test.py

$ uvx rampa run load_test.py --vus 10 --duration 30s

$ uvx rampa check load_test.py

With uvx run installed:

$ uvx --exclude-newer P7D --exclude-newer-package rampa=2099-01-01 rampa --help

Then run it from the terminal:

$ uvx --exclude-newer P7D --exclude-newer-package rampa=2099-01-01 rampa run load_test.py

$ uvx --exclude-newer P7D --exclude-newer-package rampa=2099-01-01 rampa run load_test.py --vus 10 --duration 30s

$ uvx --exclude-newer P7D --exclude-newer-package rampa=2099-01-01 rampa check load_test.py

With uvx run installed:

$ uvx --no-config rampa --help

Then run it from the terminal:

$ uvx --no-config rampa run load_test.py

$ uvx --no-config rampa run load_test.py --vus 10 --duration 30s

$ uvx --no-config rampa check load_test.py

With pipx run installed:

$ pipx run rampa --help

Then run it from the terminal:

$ pipx run rampa run load_test.py

$ pipx run rampa run load_test.py --vus 10 --duration 30s

$ pipx run rampa check load_test.py

With pipx run installed:

$ pipx run rampa --help

Then run it from the terminal:

$ pipx run rampa run load_test.py

$ pipx run rampa run load_test.py --vus 10 --duration 30s

$ pipx run rampa check load_test.py

pip has no per-package cooldown override, so this snippet runs without cooldown enforcement. Switch to the `uvx run` or `uv add` tab — they apply the cooldown to transitive deps via `--exclude-newer` while exempting rampa itself via `--exclude-newer-package`.

With pipx run installed:

$ pipx run rampa --help

Then run it from the terminal:

$ pipx run rampa run load_test.py

$ pipx run rampa run load_test.py --vus 10 --duration 30s

$ pipx run rampa check load_test.py

With uv add installed:

$ uv add rampa

Then run it from the terminal:

$ uv run rampa run load_test.py

$ uv run rampa run load_test.py --vus 10 --duration 30s

$ uv run rampa check load_test.py

With uv add installed:

$ uv add --exclude-newer P7D --exclude-newer-package rampa=2099-01-01 rampa

Then run it from the terminal:

$ uv run rampa run load_test.py

$ uv run rampa run load_test.py --vus 10 --duration 30s

$ uv run rampa check load_test.py

With uv add installed:

$ uv add --no-config rampa

Then run it from the terminal:

$ uv run rampa run load_test.py

$ uv run rampa run load_test.py --vus 10 --duration 30s

$ uv run rampa check load_test.py

$ pip install --user --upgrade rampa

Then run it from the terminal:

$ rampa run load_test.py

$ rampa run load_test.py --vus 10 --duration 30s

$ rampa check load_test.py

$ pip install --user --upgrade rampa

Then run it from the terminal:

$ rampa run load_test.py

$ rampa run load_test.py --vus 10 --duration 30s

$ rampa check load_test.py

$ pip install --user --upgrade rampa

Then run it from the terminal:

$ rampa run load_test.py

$ rampa run load_test.py --vus 10 --duration 30s

$ rampa check load_test.py

With uvx installed:

$ claude mcp add rampa -- uvx rampa-mcp

With uvx installed:

$ claude mcp add rampa -- uvx --exclude-newer P7D --exclude-newer-package rampa-mcp=2099-01-01 rampa-mcp

With uvx installed:

$ claude mcp add rampa -- uvx --no-config rampa-mcp

With uvx installed:

$ claude mcp add rampa --scope user -- uvx rampa-mcp

With uvx installed:

$ claude mcp add rampa --scope user -- uvx --exclude-newer P7D --exclude-newer-package rampa-mcp=2099-01-01 rampa-mcp

With uvx installed:

$ claude mcp add rampa --scope user -- uvx --no-config rampa-mcp

With uvx installed:

$ claude mcp add rampa --scope project -- uvx rampa-mcp

With uvx installed:

$ claude mcp add rampa --scope project -- uvx --exclude-newer P7D --exclude-newer-package rampa-mcp=2099-01-01 rampa-mcp

With uvx installed:

$ claude mcp add rampa --scope project -- uvx --no-config rampa-mcp

With pipx installed:

$ claude mcp add rampa -- pipx run rampa-mcp

With pipx installed:

$ claude mcp add rampa -- pipx run rampa-mcp

pip has no per-package cooldown override, so this snippet runs without cooldown enforcement. Switch to the uvx tab — it applies the cooldown to transitive deps via `--exclude-newer` while exempting rampa-mcp itself via `--exclude-newer-package`.

With pipx installed:

$ claude mcp add rampa -- pipx run rampa-mcp

With pipx installed:

$ claude mcp add rampa --scope user -- pipx run rampa-mcp

With pipx installed:

$ claude mcp add rampa --scope user -- pipx run rampa-mcp

With pipx installed:

$ claude mcp add rampa --scope user -- pipx run rampa-mcp

With pipx installed:

$ claude mcp add rampa --scope project -- pipx run rampa-mcp

With pipx installed:

$ claude mcp add rampa --scope project -- pipx run rampa-mcp

With pipx installed:

$ claude mcp add rampa --scope project -- pipx run rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ claude mcp add rampa -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ claude mcp add rampa -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ claude mcp add rampa -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ claude mcp add rampa --scope user -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ claude mcp add rampa --scope user -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ claude mcp add rampa --scope user -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ claude mcp add rampa --scope project -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ claude mcp add rampa --scope project -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ claude mcp add rampa --scope project -- rampa-mcp

With uvx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "uvx",
            "args": ["rampa-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With uvx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "rampa-mcp=2099-01-01", "rampa-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With uvx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "uvx",
            "args": ["rampa-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: claude_desktop_config.json

With pipx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "pipx",
            "args": ["run", "rampa-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With pipx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "pipx",
            "args": ["run", "rampa-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With pipx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "pipx",
            "args": ["run", "rampa-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then use this config:

{
    "mcpServers": {
        "rampa": {
            "command": "rampa-mcp"
        }
    }
}

Config file: claude_desktop_config.json

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then use this config:

{
    "mcpServers": {
        "rampa": {
            "command": "rampa-mcp"
        }
    }
}

Config file: claude_desktop_config.json

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then use this config:

{
    "mcpServers": {
        "rampa": {
            "command": "rampa-mcp"
        }
    }
}

Config file: claude_desktop_config.json

With uvx installed:

$ codex mcp add rampa -- uvx rampa-mcp

With uvx installed:

$ codex mcp add rampa -- uvx --exclude-newer P7D --exclude-newer-package rampa-mcp=2099-01-01 rampa-mcp

With uvx installed:

$ codex mcp add rampa -- uvx --no-config rampa-mcp

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.rampa]
command = "uvx"
args = ["rampa-mcp"]

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.rampa]
command = "uvx"
args = ["--exclude-newer", "P7D", "--exclude-newer-package", "rampa-mcp=2099-01-01", "rampa-mcp"]

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.rampa]
command = "uvx"
args = ["rampa-mcp"]
env = { UV_NO_CONFIG = "1" }

With pipx installed:

$ codex mcp add rampa -- pipx run rampa-mcp

With pipx installed:

$ codex mcp add rampa -- pipx run rampa-mcp

With pipx installed:

$ codex mcp add rampa -- pipx run rampa-mcp

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.rampa]
command = "pipx"
args = ["run", "rampa-mcp"]

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.rampa]
command = "pipx"
args = ["run", "rampa-mcp"]

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.rampa]
command = "pipx"
args = ["run", "rampa-mcp"]

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ codex mcp add rampa -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ codex mcp add rampa -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ codex mcp add rampa -- rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.rampa]
command = "rampa-mcp"

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.rampa]
command = "rampa-mcp"

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.rampa]
command = "rampa-mcp"

With uvx installed:

$ gemini mcp add --scope user rampa uvx -- rampa-mcp

With uvx installed:

$ gemini mcp add --scope user rampa uvx -- --exclude-newer P7D --exclude-newer-package rampa-mcp=2099-01-01 rampa-mcp

With uvx installed:

$ gemini mcp add --scope user rampa uvx -- --no-config rampa-mcp

With uvx installed:

$ gemini mcp add --scope project rampa uvx -- rampa-mcp

With uvx installed:

$ gemini mcp add --scope project rampa uvx -- --exclude-newer P7D --exclude-newer-package rampa-mcp=2099-01-01 rampa-mcp

With uvx installed:

$ gemini mcp add --scope project rampa uvx -- --no-config rampa-mcp

With pipx installed:

$ gemini mcp add --scope user rampa pipx -- run rampa-mcp

With pipx installed:

$ gemini mcp add --scope user rampa pipx -- run rampa-mcp

With pipx installed:

$ gemini mcp add --scope user rampa pipx -- run rampa-mcp

With pipx installed:

$ gemini mcp add --scope project rampa pipx -- run rampa-mcp

With pipx installed:

$ gemini mcp add --scope project rampa pipx -- run rampa-mcp

With pipx installed:

$ gemini mcp add --scope project rampa pipx -- run rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ gemini mcp add --scope user rampa rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ gemini mcp add --scope user rampa rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ gemini mcp add --scope user rampa rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ gemini mcp add --scope project rampa rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ gemini mcp add --scope project rampa rampa-mcp

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then register:

$ gemini mcp add --scope project rampa rampa-mcp

With uvx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "uvx",
            "args": ["rampa-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "rampa-mcp=2099-01-01", "rampa-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "uvx",
            "args": ["rampa-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "uvx",
            "args": ["rampa-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With uvx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "rampa-mcp=2099-01-01", "rampa-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With uvx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "uvx",
            "args": ["rampa-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: ~/.cursor/mcp.json

With pipx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "pipx",
            "args": ["run", "rampa-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With pipx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "pipx",
            "args": ["run", "rampa-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With pipx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "pipx",
            "args": ["run", "rampa-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With pipx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "pipx",
            "args": ["run", "rampa-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With pipx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "pipx",
            "args": ["run", "rampa-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With pipx installed:

{
    "mcpServers": {
        "rampa": {
            "command": "pipx",
            "args": ["run", "rampa-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then use this config:

{
    "mcpServers": {
        "rampa": {
            "command": "rampa-mcp"
        }
    }
}

Config file: .cursor/mcp.json (in repo)

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then use this config:

{
    "mcpServers": {
        "rampa": {
            "command": "rampa-mcp"
        }
    }
}

Config file: .cursor/mcp.json (in repo)

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then use this config:

{
    "mcpServers": {
        "rampa": {
            "command": "rampa-mcp"
        }
    }
}

Config file: .cursor/mcp.json (in repo)

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then use this config:

{
    "mcpServers": {
        "rampa": {
            "command": "rampa-mcp"
        }
    }
}

Config file: ~/.cursor/mcp.json

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then use this config:

{
    "mcpServers": {
        "rampa": {
            "command": "rampa-mcp"
        }
    }
}

Config file: ~/.cursor/mcp.json

Install the packages first:

$ pip install --user --upgrade rampa-mcp

Then use this config:

{
    "mcpServers": {
        "rampa": {
            "command": "rampa-mcp"
        }
    }
}

Config file: ~/.cursor/mcp.json

Your first load test¶

import asyncio
import rampa

@rampa.scenario(executor="constant-vus", vus=10, duration="30s")
async def default(worker: rampa.Worker) -> None:
    resp = await worker.http.get("https://httpbin.org/get")
    worker.check(resp, {"status is 200": lambda r: r.status == 200})

$ rampa run load_test.py

Quickstart

Write and run your first scenario in 60 seconds.

Getting Started

CLI

rampa run, rampa check, rampa doctor from the terminal.

CLI

Library

Executors, metrics, thresholds, and the Python API.

Library

pytest

Run load tests inside your test suite with @pytest.mark.rampa_scenario.

pytest Plugin

MCP

Start, stop, and query load tests from AI agents.

MCP Server

Development

Contributing, benchmarks, and architecture.

Development

What you get¶

Six executor types¶

Closed-model (VU-based) and open-model (arrival-rate) scheduling, matching k6’s executor vocabulary.

Executor	Model	Use when
`constant-vus`	Closed	Fixed concurrency for a duration
`ramping-vus`	Closed	Ramp concurrency up/down through stages
`shared-iterations`	Closed	Run exactly N total iterations
`per-vu-iterations`	Closed	Each VU runs exactly N iterations
`constant-arrival-rate`	Open	Maintain a fixed request rate
`ramping-arrival-rate`	Open	Ramp request rate through stages

Automatic HTTP metrics¶

Every HTTP request auto-emits timing metrics with per-phase decomposition (blocked, connecting, sending, waiting, receiving), failure classification, and data transfer counters.

Threshold expressions¶

config = rampa.Config(
    thresholds={
        "http_req_duration": ["p(95)<500", "avg<200"],
        "http_req_failed": ["rate<0.01"],
    },
)

Threshold breaches produce exit code 1 for CI integration.

Multiple frontends and outputs¶

CLI — rampa run with --progress live status or --tui dashboard
TUI — interactive Textual dashboard with live metrics and keyboard control
pytest plugin — @pytest.mark.rampa_scenario for test suites
unittest mixin — RampaTestCase for unittest integration
MCP server — rampa-mcp for AI agent integration
Output backends — CSV, InfluxDB, Prometheus, OTEL, webhooks via --output
CI comparison — python -m rampa.ci.compare for benchmark diffs

rampa¶

Dependency cooldowns

Dependency cooldowns

Your first load test¶

What you get¶

Six executor types¶

Automatic HTTP metrics¶

Threshold expressions¶

Multiple frontends and outputs¶