Test Patterns

Overload provides 10 distinct test patterns, each designed to simulate a specific real-world traffic scenario.

1. Burst

What it does: Fires a specific number of total requests as fast as possible, constrained only by the concurrency limit.

When to use: Max throughput testing. Useful for seeing how fast your API can process a set batch of requests, or for simple smoke tests.

How it works: Creates N tasks immediately and runs them through an asyncio.Semaphore to limit simultaneous connections to concurrency.

overload run --collection api.json --pattern burst --requests 500 --concurrency 50

2. Load

What it does: Simulates sustained traffic over a period of time in a 3-phase shape: Ramp Up → Hold → Ramp Down.

When to use: Standard performance testing. Verifies that the system can handle expected peak traffic volumes over an extended period.

How it works: Controls the exact Requests Per Second (RPS) issued using interval-based scheduling. During ramp phases, the RPS increases/decreases step-by-step each second.

overload run --collection api.json --pattern load --rps 100 --duration 600

3. Stress

What it does: Gradually steps up the RPS until the system starts failing (exceeds an error threshold) or reaches a defined maximum.

When to use: Finding the absolute limits of your infrastructure. Identifies the point at which your application degrades or crashes.

How it works: Runs at start_rps for step_duration_seconds, then adds step_rps. At each step, it calculates the error rate (4xx/5xx responses). If the rate exceeds failure_threshold_pct, the test stops and reports the breaking point.

overload run --collection api.json --pattern stress

4. Spike

What it does: Runs steady baseline traffic, followed by a sudden, massive surge in traffic, returning to baseline afterward.

When to use: Elasticity testing. Verifies if autoscaling triggers correctly and if the system recovers gracefully after a traffic flood.

How it works: 3 explicit phases with instantaneous RPS changes between them (no gradual ramping).

overload run --collection api.json --pattern spike

5. Soak

What it does: Maintains a steady, moderate RPS for a very long duration (typically hours).

When to use: Detecting memory leaks, connection pool exhaustion, unclosed file descriptors, and long-term performance drift.

How it works: A simple, flat RPS profile that runs until the duration expires.

overload run --collection api.json --pattern soak --duration 3600

6. Ramp

What it does: Linearly increases traffic from a starting RPS to an ending RPS over a series of steps.

When to use: Capacity planning. Useful for observing system metrics as load smoothly increases, without the abruptness of a load or spike test.

How it works: Calculates steps between ramp_start_rps and ramp_end_rps using step_rps.

overload run --collection api.json --pattern ramp

7. Breakpoint

What it does: Automatically finds the exact RPS where your API degrades by performing a binary search between a low and high RPS.

When to use: Precisely identifying your system's SLA limits (e.g., "At what exact RPS does P95 latency exceed 2 seconds?").

How it works: Probes the midpoint RPS for 5 seconds. If P95 latency or error rate exceeds thresholds, the high bound becomes the midpoint. If it succeeds, the low bound becomes the midpoint. Repeats until the bounds are within precision_rps of each other.

overload run --collection api.json --pattern breakpoint

8. Custom

What it does: Executes a user-defined sequence of stages, each with a specific duration and RPS.

When to use: Simulating highly specific, complex real-world traffic patterns that don't fit standard models.

How it works: Iterates through the provided JSON array of stages sequentially.

overload run --collection api.json --pattern custom --stages '[{"duration":60,"rps":50},{"duration":30,"rps":200},{"duration":60,"rps":10}]'

9. Rate Limit

What it does: Specifically designed to verify that an API's rate limiting (429 Too Many Requests) mechanism works correctly.

When to use: Validating API Gateway configurations, WAF rules, or application-level rate limiters.

How it works: Phase 1 (Burst): Fires rate_limit_requests instantly to trigger burst limits.
Phase 2 (Ramp): Steps up from 10 RPS to cap * 2. At each step, it checks if ≥50% of responses are 429s.

overload run --collection api.json --pattern ratelimit

10. Sequential

What it does: Executes requests in the exact order they appear in the Postman collection, waiting for each to finish before starting the next.

When to use: Functional flow testing. e.g., Login (save token to variable) → Create Item → Update Item → Delete Item.

How it works: Bypasses the async load engine entirely. A simple loop over requests for iterations times, applying delay_ms between requests.

overload sequential --collection api.json --iterations 5 --delay 500