API Reference¶

Configuration¶

User-facing configuration models for rampa.

All scenario, executor, threshold, and option configuration is defined here as pydantic models with validation. These models are the user’s primary interface for configuring load tests.

>>> import rampa.config

rampa.config.parse_duration(value) ¶ function function rampa.config.parse_duration(value) ¶

Parse a human-readable duration string into a timedelta.

Supports h, m, s, and ms components. At least one component must be present.

Parameters:

value (str | datetime.timedelta) – Duration string (e.g. "30s", "1m30s", "2h") or an existing timedelta.

Returns:

Parsed duration.

Return type:

datetime.timedelta

Raises:

ValueError – If the string cannot be parsed.
>>> parse_duration("30s") –
datetime.timedelta(seconds=30) –
>>> parse_duration("1m30s") –
datetime.timedelta(seconds=90) –
>>> parse_duration("2h") –
datetime.timedelta(seconds=7200) –
>>> parse_duration("500ms") –
datetime.timedelta(microseconds=500000) –
>>> parse_duration("1h30m15s") –
datetime.timedelta(seconds=5415) –
>>> parse_duration(datetime.timedelta(seconds=10)) –
datetime.timedelta(seconds=10) –

rampa.config.Duration ¶ data data rampa.config.Duration ¶: A timedelta that can be constructed from a human-readable string.

alias of Annotated[timedelta, BeforeValidator(func=parse_duration, json_schema_input_type=PydanticUndefined)]

class rampa.config.Stage ¶ class class class rampa.config.Stage ¶

Bases: BaseModel

A single ramp stage with a target VU or rate count and duration.

>>> import datetime
>>> Stage(
...     duration=datetime.timedelta(seconds=30), target=100,
... ).target
100
>>> Stage(
...     duration=datetime.timedelta(minutes=1), target=0,
... ).duration
datetime.timedelta(seconds=60)

class rampa.config.ScenarioConfig ¶ class class class rampa.config.ScenarioConfig ¶

Bases: BaseModel

Configuration for a single test scenario.

Each scenario maps to an executor that controls how iterations are scheduled. Executor-specific fields are validated by the executor, not by this model.

>>> import datetime
>>> cfg = ScenarioConfig(
...     executor="constant-vus",
...     vus=10,
...     duration=datetime.timedelta(seconds=30),
... )
>>> cfg.executor
'constant-vus'
>>> cfg.vus
10

class rampa.config.Options ¶ class class class rampa.config.Options ¶

Bases: BaseModel

Shortcut execution options.

These provide a simpler alternative to explicit scenarios for common cases. When both shortcuts and scenarios are provided, validation rejects the config.

>>> import datetime
>>> Options(
...     vus=10, duration=datetime.timedelta(seconds=30),
... ).vus
10

class rampa.config.Config ¶ class class class rampa.config.Config ¶

Bases: BaseModel

Top-level test configuration.

Either scenarios or shortcut options (vus, duration, etc.) may be provided, but not both.

>>> import datetime
>>> cfg = Config(
...     scenarios={"smoke": ScenarioConfig(
...         executor="constant-vus",
...         vus=1,
...         duration=datetime.timedelta(seconds=10),
...     )},
... )
>>> "smoke" in cfg.scenarios
True
>>> cfg.scenarios["smoke"].executor
'constant-vus'

Engine¶

Headless engine and run controller for rampa.

The engine owns execution state and cleanup. Frontends own presentation, JSON shape, and process exit behavior. This separation enables CLI, TUI, MCP, pytest, and GitHub Action integration without reaching into internals.

>>> import rampa.engine

class rampa.engine.EngineOptions ¶ class class class rampa.engine.EngineOptions ¶

API Reference¶

Configuration¶

Engine¶

Events¶

Worker¶

HTTP Client¶

Metrics¶

Thresholds¶

Loader¶