LoadStrike SDK for Python

LoadStrike is a developer-first load testing SDK for Python services, jobs, and automated test suites. Use it to describe real workflows in Python, execute them in-process, and collect structured reports from the same codebase that owns the system under test.

What This SDK Is For

• Author scenario-based load tests in Python.
• Generate safe starter scenarios from captured HAR, OpenTelemetry trace JSON, browser recordings, or message pairs with Trace-to-test Autopilot.
• Model transaction flows across HTTP and event-driven systems.
• Apply load simulations, thresholds, and custom metrics during execution.
• Split a single load profile across weighted scenario mixes.
• Generate local reports and, on Enterprise, forward results to supported reporting sinks.

Built-in transport coverage includes HTTP, Kafka, RabbitMQ, NATS, Redis Streams, Azure Event Hubs, Push Diffusion, and delegate-based custom streams. Local report output supports HTML, Markdown, TXT, and CSV, and Enterprise can publish to InfluxDB, TimescaleDB, Grafana Loki, Datadog, Splunk HEC, OpenTelemetry Collector, and the expanded built-in sink family.

For Kafka OAuthBearer authentication, set oauth_bearer_token_endpoint_url and provide ClientId and ClientSecret in additional_settings. The native Python runtime exchanges those credentials for an access token and caches it until shortly before expiry; optional Scope, Audience, and GrantType values are included in the token request.

Requirements

• Python 3.9 or later

Install

pip install loadstrike

Quick Start

from loadstrike_sdk import (
    LoadStrikeResponse,
    LoadStrikeRunner,
    LoadStrikeScenario,
    LoadStrikeSimulation,
    LoadStrikeStep,
)


def run_orders(context):
    return LoadStrikeStep.run(
        "publish-order",
        context,
        lambda: LoadStrikeResponse.ok("200"),
    ).as_reply()


scenario = (
    LoadStrikeScenario.create("orders", run_orders)
    .with_load_simulations(LoadStrikeSimulation.inject(10, 1, 20))
)

result = (
    LoadStrikeRunner.register_scenarios(scenario)
    .use_load_engine_v2()
    .with_max_in_flight(5000)
    .with_runner_key("rkl_your_runner_key")
    .run()
)

run() returns the detailed run result, including generated report files, scenario statistics, metrics, and sink status.

Load Engine V2

Call .use_load_engine_v2() explicitly for the versioned smooth-pacing and bounded-work contract. V2 spreads fixed-rate arrivals across their interval and uses one process-wide in-flight ceiling shared by scenarios and colocated logical agents. The default is 10,000; call .with_max_in_flight(...) after the V2 opt-in to override it with a value from 1 through 1,000,000.

The requested rate is offered scenario invocations per interval. Compare it with achieved starts, delivery percentage, scheduler lag, and transport throughput. If the generator is late or at capacity, the arrival is dropped and disclosed as a generator warning rather than counted as an application failure. One scenario invocation may contain several requests, Kafka records, or browser operations, so size Playwright workloads by browser capacity and report Kafka records and bytes per second separately.

V2 supports LoadStrikeTrafficMix with one deterministic global rank space across its weighted lanes and agent shards. Cross-platform tracking is not yet supported by the Python V2 profile and is rejected before traffic instead of running with partial accounting.

Non-correlated V2 scenarios can run through the local-development cluster or a remote NATS cluster. Give every agent a stable identity with .with_agent_id("agent-a"), and configure the coordinator with the same exact participant set using .with_agents_count(2).with_expected_agent_ids("agent-a", "agent-b"). Remote execution waits for that compatible set before starting; a missing result owner is reported as incomplete rather than silently producing a partial aggregate. Existing V1 cluster behavior is unchanged.

HTML reports include a Generator Delivery tab whenever scheduler delivery data, raw observation delivery statistics, generator or reporting warnings, or incomplete reporting are available. Results without reporting-completeness status show N/A rather than reporting loss. Application failures remain separate from generator and reporting warnings.

Raw Iteration Reporting

Observation-capable reporting sinks receive one compact record for every scenario attempt, including retry attempts and nested steps. Retries share a logical iteration ID while keeping distinct attempt indexes and final-attempt markers. Warm-up and load phases, simulation and shard identity, timestamps, observed and reported latency, outcome, status code, and response size are included; reply messages, payloads, bodies, and headers are not.

Records are buffered without delaying scenario callbacks and normally flush in compressed chunks every five seconds. The defaults and portal-compatible common shape are 50,000 observations or 8 MiB; runs without a portal sink may select the documented larger limits. Buffer pressure, a single record that cannot fit a batch, and per-sink queue pressure drop reporting observations with explicit warnings; they do not turn a successful system-under-test response into an application failure. Metric-only destinations disclose that they cannot retain arbitrary strings or nested steps.

Portal reporting calculates cumulative p50, p75, p95, and p99 from all final load-phase outcomes received for each scenario and run. Separate successful and failed percentiles remain available for diagnosis. The SDK does not send SDK-calculated percentile fields as the authoritative portal or observation-capable sink result.

Custom reporting sinks opt in with save_iteration_batch or SaveIterationBatch and may implement the matching stream-completion callback. Existing aggregate lifecycle callbacks remain source compatible.

Built-in observability sinks also publish one correlation.outcome.final event for every gathered or ungrouped correlation row, including the tracking and event IDs, source and destination, status, latency, success state, and GatherBy field/value. The aggregate run.result.final event remains available separately.

Traffic Mixes

Use LoadStrikeTrafficMix on Pro and Enterprise plans when one total load profile should be distributed across multiple scenario lanes. For example, a 1000 requests-per-second profile with scenario weights of 60, 30, and 10 sends roughly 600 requests per second to the first scenario, 300 to the second, and 100 to the third.

Each lane is still a normal scenario with its own named steps, thresholds, reports, and portal results. Register the mix with LoadStrikeRunner.register_traffic_mix(...) or add it to a runner with .add_traffic_mix(...).

Trace-To-Test Autopilot

Use LoadStrikeAutopilot.generate(...) to infer a starter plan from a captured artifact. Set RunnerKey on the Autopilot options so generation can validate the Trace-To-Test Autopilot entitlement. Check result.Readiness and result.ReadinessFailures first; call result.build_scenario() only when it is LoadStrikeAutopilotReadiness.Ready, then execute the scenario through the normal runner with a valid RunnerKey.

Use SecretBindings to map redaction locations such as header:Authorization or body:$.client_secret to environment variables, TrackingSelector when the selector cannot be inferred, and EndpointBindings, AllowedReplayHosts, or BaseUrlRewrite when a replay target must be bound. Secret values are resolved when the generated scenario runs; they are not written into the generated plan. Any gate satisfied by user setup is omitted from ReadinessFailures.

Runner Keys

Runnable workloads require a RunnerKey. Supply it with .with_runner_key(...) or through your application configuration before calling run().

Documentation

• Product documentation: https://loadstrike.com/documentation