Skip to content

antlabs/quickurl

BranchesTags

Repository files navigation

quickurl

quickurl = quick + url

A modern, high-performance HTTP benchmarking tool written in Rust, inspired by wrk, with native support for parsing curl commands.

Turn your everyday quickurl into a scalable load test in seconds — no configuration needed. Just copy, paste, and go.

Features

  • 🚀 High-performance HTTP load testing
  • 🔧 Parse curl commands with --parse-curl option
  • 📁 Multiple curl commands from file with load distribution strategies
  • 📊 Detailed statistics similar to wrk
  • 📈 Per-endpoint statistics - TPS, latency, status codes for each endpoint
  • 🎨 Live Terminal UI with real-time charts and statistics
  • 🎭 Mock HTTP Server - Built-in test server for benchmarking validation
  • ⚡ Async I/O for maximum performance
  • 🎯 Configurable connections, threads, and duration
  • 📉 Latency distribution analysis
  • ⌨️ Interactive controls (press 'q' to stop early)
  • 🔀 Load strategies: random, round-robin

Installation

cargo install --path .

Or build from source:

git clone https://github.com/antlabs/quickurl.git
cd quickurl
cargo build --release

Usage

Basic Usage

# Simple GET request
quickurl -c 100 -d 30s http://example.com

# POST request with custom headers
quickurl -c 50 -d 10s -X POST -H "Content-Type: application/json" -d '{"key":"value"}' http://api.example.com

Parse Curl Commands

# Parse a curl command and use it for benchmarking
quickurl --parse-curl "curl -X POST -H 'Content-Type: application/json' -d '{\"name\":\"test\"}' http://api.example.com/users" -c 100 -d 30s

Options

  • -c, --connections: Number of HTTP connections to keep open (default: 10)
  • -d, --duration: Duration of test (default: 10s)
  • -t, --threads: Number of threads to use (default: 2)
  • -R, --rate: Work rate (requests/sec) 0=unlimited (default: 0)
  • --timeout: Socket/request timeout (default: 30s)
  • --parse-curl: Parse curl command and use it for benchmarking
  • --parse-curl-file: Parse multiple curl commands from file (one per line)
  • --load-strategy: Load distribution strategy: random, round-robin (default: random)
  • -X, --method: HTTP method (default: GET)
  • -H, --header: HTTP header to add to request
  • -d, --data: HTTP request body
  • --content-type: Content-Type header
  • -v, --verbose: Verbose output
  • --latency: Print latency statistics
  • --live-ui: Enable live terminal UI with real-time stats (interactive mode)
  • --use-nethttp: Force use standard library net/http instead of pulse

Examples

Basic Load Test

quickurl -c 100 -d 30s -t 4 http://example.com

Output:

Running 30s test @ http://example.com
  4 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    12.34ms   5.67ms  123.45ms    75.23%
    Req/Sec     2.34k     0.12k    3.45k     89.12%
  280000 requests in 30.00s, 45.67MB read
Requests/sec:   9333.33
Transfer/sec:     1.52MB

Load Test with Curl Command

quickurl --parse-curl "curl -X POST -H 'Authorization: Bearer token123' -H 'Content-Type: application/json' -d '{\"user\":\"test\"}' https://api.example.com/login" -c 50 -d 10s --latency

Rate Limited Test

# Limit to 1000 requests per second
quickurl -c 10 -d 60s -R 1000 http://example.com

Multiple Curl Commands

Test multiple endpoints simultaneously with different load distribution strategies:

# Create a file with multiple curl commands (one per line)
cat > endpoints.txt << EOF
curl https://api.example.com/users
curl -X POST https://api.example.com/orders -H "Content-Type: application/json" -d '{"item":"book"}'
curl https://api.example.com/products
curl https://api.example.com/search?q=test
EOF

# Random distribution (default) - randomly select from endpoints
quickurl --parse-curl-file endpoints.txt -c 100 -d 60s --use-nethttp

# Round-robin distribution - evenly distribute across endpoints
quickurl --parse-curl-file endpoints.txt --load-strategy round-robin -c 100 -d 60s --use-nethttp

# With rate limiting
quickurl --parse-curl-file endpoints.txt --load-strategy random -c 50 -d 30s -R 1000 --use-nethttp

File Format:

  • One curl command per line
  • Empty lines are ignored
  • Lines starting with # are treated as comments
  • Supports all curl options (headers, methods, data, etc.)

Load Strategies:

  • random: Randomly select an endpoint for each request (default)
  • round-robin: Evenly distribute requests across all endpoints

Per-Endpoint Statistics:

When testing multiple endpoints, quickurl automatically provides detailed statistics for each endpoint:

=== Per-Endpoint Statistics ===

[https://api.example.com/users]
  Requests:     250
  Requests/sec: 50.00
  Latency:      avg=120.50ms, min=45.20ms, max=350.80ms
  Status codes: [200] 248 (99.2%), [500] 2 (0.8%)
  Data:         125.5KB total, 25.1KB/sec

[https://api.example.com/orders]
  Requests:     245
  Errors:       5 (2.0%)
  Requests/sec: 49.00
  Latency:      avg=145.30ms, min=60.10ms, max=420.50ms
  Status codes: [200] 230 (93.9%), [400] 10 (4.1%)
  Data:         98.2KB total, 19.6KB/sec

Each endpoint shows:

  • Requests: Total number of requests sent to this endpoint
  • Errors: Number of failed requests (connection errors, timeouts)
  • Requests/sec (TPS): Throughput for this specific endpoint
  • Latency: Average, minimum, and maximum response times
  • Status codes: HTTP status code distribution with percentages
  • Data: Total data transferred and transfer rate

Live Terminal UI

Enable real-time interactive UI with live statistics:

# Basic live UI
quickurl --live-ui -c 100 -d 60s --use-nethttp http://example.com

# Live UI with rate limiting
quickurl --live-ui -c 1000 -d 300s -R 5000 --use-nethttp http://api.example.com

# Live UI with multiple endpoints
quickurl --parse-curl-file endpoints.txt --live-ui -c 100 -d 60s --use-nethttp

The live UI displays:

  • Progress Bar: Visual progress indicator with elapsed/total time
  • Real-time Stats: Requests, slowest/fastest/average latency, requests per second
  • Status Code Distribution: HTTP status codes with color coding (2xx=green, 4xx=yellow, 5xx=red)
  • Error Statistics: Connection errors and error rate
  • Request Chart: Bar chart showing requests per second over time
  • Response Time Histogram: Latency distribution (p50, p75, p90, p95, p99)
  • Per-Endpoint Table (multi-endpoint mode): Real-time statistics for each endpoint

Multi-Endpoint Live UI:

When testing multiple endpoints with --parse-curl-file, the Live UI automatically displays an additional table showing per-endpoint statistics:

┌─Per-Endpoint Statistics (live)────────────────────────────┐
│ Endpoint              │ Req/s │ Avg    │ Min   │ Max     │
├───────────────────────┼───────┼────────┼───────┼─────────┤
│ /api/fast             │ 1000  │ 10ms   │ 5ms   │ 50ms    │
│ /api/slow             │  950  │ 105ms  │ 95ms  │ 150ms   │
│ /api/error            │  957  │ 15ms   │ 10ms  │ 30ms    │
└───────────────────────┴───────┴────────┴───────┴─────────┘

Each row shows:

  • Endpoint URL (truncated if too long)
  • Requests per second (TPS)
  • Average, minimum, and maximum latency
  • Error count and percentage

Interactive Controls:

  • Press q or Ctrl+C to stop the test early
  • UI updates every second with live data

Note: Live UI currently requires --use-nethttp flag.

Mock HTTP Server

Start a built-in mock HTTP server for testing and benchmarking:

# Start a simple echo server (returns request details)
quickurl --mock-server --mock-port 8080

# Custom response with delay
quickurl --mock-server --mock-port 8080 --mock-delay 100ms --mock-response '{"status":"ok"}'

# Custom status code
quickurl --mock-server --mock-port 8080 --mock-status 500 --mock-response '{"error":"server error"}'

# Use configuration file for multiple routes
quickurl --mock-server --mock-config examples/mock-server.yaml

Mock Server Configuration File (mock-server.yaml):

port: 8080

routes:
  # Echo endpoint - returns request details
  - path: /echo
    method: GET
    echo: true

  # Fast endpoint - no delay
  - path: /fast
    method: GET
    status_code: 200
    response: '{"message": "Fast response"}'

  # Slow endpoint - 100ms delay
  - path: /slow
    method: GET
    status_code: 200
    delay: 100ms
    response: '{"message": "Slow response"}'

  # Error endpoint
  - path: /error
    method: GET
    status_code: 500
    response: '{"error": "Internal server error"}'

  # POST endpoint with echo
  - path: /api/users
    method: POST
    status_code: 201
    echo: true

Testing the Mock Server:

# Terminal 1: Start mock server
quickurl --mock-server --mock-config examples/mock-server.yaml

# Terminal 2: Run benchmark against it
quickurl -c 100 -d 30s --use-nethttp http://localhost:8080/fast
quickurl -c 100 -d 30s --use-nethttp http://localhost:8080/slow

# Test multiple endpoints
cat > endpoints.txt << EOF
curl http://localhost:8080/fast
curl http://localhost:8080/slow
curl http://localhost:8080/error
EOF

quickurl --parse-curl-file endpoints.txt -c 50 -d 30s --use-nethttp

Mock Server Features:

  • Echo mode: Returns request details (method, headers, body)
  • Custom responses: Define JSON or text responses
  • Configurable delays: Simulate slow endpoints
  • Status codes: Test error handling
  • Multiple routes: Define different endpoints with different behaviors
  • Request logging: See all incoming requests in real-time

Batch Testing with Configuration Files

quickurl supports batch testing through YAML or JSON configuration files, allowing you to run multiple tests with different parameters in a single command.

Basic Batch Testing

# Run batch tests from YAML configuration
quickurl --batch-config examples/batch-config.yaml

# Run batch tests from JSON configuration
quickurl --batch-config examples/batch-config.json

# Run tests sequentially instead of concurrently
quickurl --batch-config batch-tests.yaml --batch-sequential

# Limit concurrent batch tests (default: 3)
quickurl --batch-config batch-tests.yaml --batch-concurrency 5

# Generate different report formats
quickurl --batch-config batch-tests.yaml --batch-report csv
quickurl --batch-config batch-tests.yaml --batch-report json

Configuration File Format

YAML Format (batch-config.yaml)

version: "1.0"
tests:
  - name: "用户登录API"
    curl: 'curl -X POST https://api.example.com/login -H "Content-Type: application/json" -d "{\"username\":\"test\",\"password\":\"123456\"}"'
    connections: 100
    duration: "30s"
    threads: 4
    
  - name: "获取用户信息"
    curl: 'curl -H "Authorization: Bearer token123" https://api.example.com/user/profile'
    connections: 50
    duration: "60s"
    threads: 2
    
  - name: "创建订单API"
    curl: 'curl -X POST https://api.example.com/orders -H "Content-Type: application/json" -d "{\"product_id\":1,\"quantity\":2}"'
    connections: 80
    duration: "45s"
    rate: 100
    timeout: "10s"
    verbose: true

JSON Format (batch-config.json)

{
  "version": "1.0",
  "tests": [
    {
      "name": "API健康检查",
      "curl": "curl https://api.example.com/health",
      "connections": 10,
      "duration": "10s"
    },
    {
      "name": "用户注册接口",
      "curl": "curl -X POST https://api.example.com/register -H \"Content-Type: application/json\" -d \"{\\\"email\\\":\\\"[email protected]\\\",\\\"password\\\":\\\"password123\\\"}\"",
      "connections": 50,
      "duration": "30s",
      "threads": 3,
      "rate": 200
    }
  ]
}

Configuration Parameters

Each test in the batch configuration supports the following parameters:

Parameter Type Description Default
name string Test name (required) -
curl string Curl command to parse (required) -
connections int Number of HTTP connections 10
duration string Test duration (e.g., "30s", "5m") 10s
threads int Number of threads 2
rate int Requests per second limit (0=unlimited) 0
timeout string Request timeout (e.g., "5s") 30s
verbose bool Enable verbose output false
use_nethttp bool Force use standard net/http false

Batch Testing Options

Option Description Default
--batch-config Path to batch configuration file (YAML/JSON) -
--batch-concurrency Maximum concurrent batch tests 3
--batch-sequential Run tests sequentially instead of concurrently false
--batch-report Report format: text, csv, json text

Batch Test Output

Text Report (Default)

=== Batch Test Report ===

Total Tests: 3
Success Rate: 100.00%
Total Time: 1m30s
Start Time: 2024-01-15 10:30:00
End Time: 2024-01-15 10:31:30

=== Test Results ===

1. 用户登录API
   Duration: 30.2s
   Status: SUCCESS
   Requests: 15000
   RPS: 496.67
   Avg Latency: 201ms

2. 获取用户信息
   Duration: 60.1s
   Status: SUCCESS
   Requests: 30000
   RPS: 499.17
   Avg Latency: 100ms

=== Performance Summary ===

Total Requests: 45000
Combined RPS: 995.84
Latency Stats:
  Average: 150ms
  Median:  120ms
  Min:     50ms
  Max:     500ms

CSV Report

quickurl --batch-config batch-tests.yaml --batch-report csv > results.csv

JSON Report

quickurl --batch-config batch-tests.yaml --batch-report json > results.json

URL Template Variables

quickurl supports dynamic URL template variables that allow you to generate different values for each request, making it perfect for realistic load testing scenarios.

Built-in Template Functions

Function Description Usage Example
random Random number in range {{random:min-max}} {{random:1-1000}}
uuid Generate UUID {{uuid}} 550e8400-e29b-41d4-a716-446655440000
timestamp Current timestamp {{timestamp:format}} {{timestamp:unix}}
now Alias for timestamp {{now:format}} {{now:rfc3339}}
sequence Incrementing numbers {{sequence:start}} {{sequence:1}}
choice Random selection {{choice:a,b,c}} {{choice:GET,POST,PUT}}

Template Formats

Timestamp Formats

  • unix - Unix timestamp (default): 1640995200
  • unix_ms - Unix timestamp in milliseconds: 1640995200000
  • rfc3339 - RFC3339 format: 2022-01-01T00:00:00Z
  • iso8601 - ISO8601 format
  • date - Date only: 2022-01-01
  • time - Time only: 15:04:05

Basic Template Usage

Simple Random User ID

# Test with random user IDs from 1 to 1000
quickurl -c 50 -d 30s 'https://api.example.com/users/{{random:1-1000}}'

UUID Session Testing

# Each request gets a unique session ID
quickurl -c 20 -d 60s 'https://api.example.com/data?session={{uuid}}'

Timestamp-based Requests

# Include current timestamp in requests
quickurl -c 10 -d 30s 'https://api.example.com/events?timestamp={{timestamp:unix}}'

Sequential Page Testing

# Test pagination with incrementing page numbers
quickurl -c 5 -d 60s 'https://api.example.com/items?page={{sequence:1}}&limit=20'

Custom Variable Definitions

Define your own variables using the --var option:

# Define custom variables
quickurl --var user_id=random:1-10000 \
     --var method=choice:GET,POST,PUT \
     --var session=uuid \
     -c 30 -d 45s \
     'https://api.example.com/{{method}}/users/{{user_id}}?session={{session}}'

Advanced Template Examples

E-commerce API Simulation

quickurl --var user_id=random:1-10000 \
     --var product_id=random:100-999 \
     --var quantity=choice:1,2,3,4,5 \
     --var payment=choice:credit_card,paypal,apple_pay \
     -c 50 -d 60s \
     --parse-curl 'curl -X POST https://shop.example.com/api/orders \
                   -H "Content-Type: application/json" \
                   -d "{\"user_id\":{{user_id}},\"product_id\":{{product_id}},\"quantity\":{{quantity}},\"payment_method\":\"{{payment}}\",\"timestamp\":\"{{timestamp:rfc3339}}\"}"}'

Multi-endpoint Testing

quickurl --var endpoint=choice:users,orders,products,reviews \
     --var id=random:1-1000 \
     --var action=choice:view,edit,delete \
     -c 25 -d 30s \
     'https://api.example.com/{{endpoint}}/{{id}}/{{action}}'

Template Variables in Batch Configuration

Template variables work seamlessly with batch configuration files:

version: "1.0"
tests:
  - name: "Dynamic User API Test"
    curl: 'curl https://api.example.com/users/{{random:1-10000}}'
    connections: 50
    duration: "30s"
    
  - name: "Session-based Requests"
    curl: 'curl -H "X-Session-ID: {{uuid}}" -H "X-Timestamp: {{timestamp:unix}}" https://api.example.com/data'
    connections: 30
    duration: "45s"
    
  - name: "Sequential Pagination"
    curl: 'curl "https://api.example.com/posts?page={{sequence:1}}&limit=10"'
    connections: 10
    duration: "60s"

Run with custom variables:

quickurl --batch-config template-test.yaml \
     --var api_key=uuid \
     --var region=choice:us-east,us-west,eu-central

Template Variable Help

Get detailed help and examples for template variables:

# Show all available template functions and examples
quickurl --help-templates

Template Variable Best Practices

  1. Realistic Data Generation: Use appropriate ranges and choices that match your real-world data
  2. Performance Considerations: Template parsing adds minimal overhead but consider it for very high-rate tests
  3. Debugging: Use -v (verbose) flag to see original and processed URLs/commands
  4. Variable Reuse: Define commonly used variables once with --var instead of inline functions
  5. Batch Testing: Combine template variables with batch configuration for comprehensive test suites

Advanced Batch Testing Examples

API Load Testing Suite

version: "1.0"
tests:
  - name: "Health Check"
    curl: 'curl https://api.example.com/health'
    connections: 5
    duration: "10s"
    
  - name: "Authentication"
    curl: 'curl -X POST https://api.example.com/auth -d "username=test&password=123"'
    connections: 20
    duration: "30s"
    
  - name: "Data Retrieval"
    curl: 'curl -H "Authorization: Bearer token" https://api.example.com/data'
    connections: 100
    duration: "60s"
    rate: 500
    
  - name: "Heavy Processing"
    curl: 'curl -X POST https://api.example.com/process -d @large-payload.json'
    connections: 10
    duration: "120s"
    timeout: "30s"

E-commerce API Testing

version: "1.0"
tests:
  - name: "Product Search"
    curl: 'curl "https://shop.example.com/api/search?q=laptop"'
    connections: 50
    duration: "45s"
    
  - name: "Add to Cart"
    curl: 'curl -X POST https://shop.example.com/api/cart -H "Content-Type: application/json" -d "{\"product_id\":123,\"quantity\":1}"'
    connections: 30
    duration: "30s"
    
  - name: "Checkout Process"
    curl: 'curl -X POST https://shop.example.com/api/checkout -H "Authorization: Bearer token" -d @checkout-data.json'
    connections: 20
    duration: "60s"
    rate: 50

Output Format

The output format is similar to wrk:

  • Thread Stats: Average, standard deviation, and maximum latency
  • Req/Sec: Requests per second statistics
  • Total Summary: Total requests, duration, and data transferred
  • Error Summary: Connection, read, write, and timeout errors (if any)
  • Status Code Distribution: HTTP status code breakdown
  • Latency Distribution: Percentile breakdown (with --latency flag)

Performance

quickurl is designed for high performance:

  • Async I/O using tokio runtime
  • Efficient connection pooling
  • Minimal memory allocation during testing
  • Multi-threaded architecture

License

MIT License - see LICENSE file for details.

About

rust实现的http压测仓库， gurl的rust版本

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages