Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/visible/cruel/llms.txt

Use this file to discover all available pages before exploring further.

The test command runs chaos tests against an endpoint, injecting failures, delays, and timeouts to validate your application’s resilience.

​
Syntax

cruel test <url> [options]

​
Arguments

​
url
string
required
The endpoint URL to test (e.g., https://api.example.com/users)

​
Options

​
--count
number
default:"10"
Number of requests to send during the test
​
--fail
number
Failure rate between 0 and 1 (e.g., 0.1 = 10% failure rate)
​
--delay
number | string
Delay in milliseconds or min-max range (e.g., 100 or “100-500”)
​
--timeout
number
Timeout rate between 0 and 1 (e.g., 0.05 = 5% timeout rate)
​
--preset
string
Use a predefined chaos configuration preset instead of individual optionsAvailable: development, staging, production, harsh, nightmare, apocalypse
​
--retry
number
Number of retry attempts for failed requests with exponential backoff
​
--circuit
number
Circuit breaker threshold - number of failures before circuit opens

​
Basic Usage

cruel test https://api.example.com

​
Using Presets

cruel test https://api.example.com --preset development

​
Advanced Usage

​
With Retry Logic

Test with automatic retries and exponential backoff: 
cruel test https://api.example.com --fail 0.3 --retry 3 --count 20

​
With Circuit Breaker

Test with circuit breaker pattern to prevent cascading failures: 
cruel test https://api.example.com --fail 0.5 --circuit 5 --count 30
The circuit opens after 5 failures and times out after 10 seconds.

​
Combined Options

Combine multiple chaos patterns: 
cruel test https://api.example.com \
  --fail 0.2 \
  --delay 200 \
  --timeout 0.1 \
  --retry 3 \
  --circuit 10 \
  --count 50

​
Output Example

$ cruel test https://api.example.com --fail 0.1 --count 20

testing https://api.example.com
requests: 20
config: {"fail":0.1}

..X.......X.........

results:
  success: 18/20 (90%)
  failed: 2/20 (10%)
  timeouts: 0/20 (0%)

latency:
  avg: 145ms
  min: 98ms
  max: 234ms
  p50: 142ms
  p95: 198ms
  p99: 234ms

​
Output Indicators

During the test, real-time feedback is shown:
  • . (green) - Successful request
  • X (red) - Failed request
  • T (yellow) - Timed out request

​
Results Breakdown

​
Success Metrics

  • success: Number and percentage of successful requests
  • failed: Number and percentage of failed requests
  • timeouts: Number and percentage of timed out requests

​
Latency Metrics

  • avg: Average response time
  • min: Minimum response time
  • max: Maximum response time
  • p50: 50th percentile (median)
  • p95: 95th percentile
  • p99: 99th percentile

​
Configuration Details

When you run a test, the CLI displays your configuration: 
testing https://api.example.com
requests: 20
config: {"fail":0.1,"delay":500}
retry: 3 attempts
circuit breaker: 5 threshold
This shows:
  • The URL being tested
  • Number of requests that will be sent
  • Chaos configuration applied
  • Retry configuration (if enabled)
  • Circuit breaker threshold (if enabled)

​
Error Handling

If you forget to provide a URL: 
$ cruel test
error: url required
usage: cruel test <url> [options]

​
Use Cases

​
Validate Error Handling

Test that your application handles failures gracefully: 
cruel test https://api.example.com --fail 0.5 --count 100

​
Test Timeout Resilience

Validate timeout handling and recovery: 
cruel test https://api.example.com --timeout 0.2 --count 50

​
Simulate Network Latency

Test performance under network delays: 
cruel test https://api.example.com --delay 1000 --count 30

​
Test Retry Logic

Validate that retries work correctly: 
cruel test https://api.example.com --fail 0.3 --retry 5

​
Stress Test Circuit Breaker

Test circuit breaker opens and recovers: 
cruel test https://api.example.com --fail 0.8 --circuit 3 --count 50

Build docs developers (and LLMs) love

Get started for freeTalk to us