Skip to content

Basic Examples

Jump to bottom
kurok edited this page Mar 11, 2026 · 1 revision

Basic Examples

Here are the most common things you'll want to do with pywrkr. Just copy and paste these commands.

Change how many connections to use

More connections = more load on your server. The default is 10.

# Light load: 5 connections
pywrkr http://localhost:8080/ -c 5

# Medium load: 100 connections
pywrkr http://localhost:8080/ -c 100

# Heavy load: 500 connections
pywrkr http://localhost:8080/ -c 500

How to choose? Start small (10-50) and increase until you see errors or high latency. That's your server's limit.

Change how long the test runs

The default is 10 seconds. For more accurate results, run longer.

# Quick check: 5 seconds
pywrkr http://localhost:8080/ -d 5

# Standard test: 30 seconds
pywrkr http://localhost:8080/ -d 30

# Thorough test: 5 minutes (300 seconds)
pywrkr http://localhost:8080/ -d 300

Send an exact number of requests

Instead of running for a set time, send exactly N requests and stop. This is useful when you want to compare "same workload, different configs."

# Send exactly 1,000 requests using 50 connections
pywrkr http://localhost:8080/ -n 1000 -c 50

# Send 10,000 requests using 100 connections
pywrkr http://localhost:8080/ -n 10000 -c 100

Test a POST endpoint

By default, pywrkr sends GET requests. Here's how to send POST with a body:

# Simple POST with JSON body
pywrkr http://localhost:8080/api/data -m POST \
    -b '{"name": "test", "value": 42}' \
    -H "Content-Type: application/json"

POST with data from a file

If your body is large, put it in a file:

# Save your request body to a file
echo '{"name": "test", "value": 42}' > body.json

# Use the file
pywrkr http://localhost:8080/api/data -m POST \
    -p body.json \
    -H "Content-Type: application/json"

Test with authentication

# Basic HTTP auth (username:password)
pywrkr http://localhost:8080/api/protected -A admin:secret123

Test with custom headers

# Add an API key header
pywrkr http://localhost:8080/api -H "Authorization: Bearer my-token-here"

# Add multiple headers
pywrkr http://localhost:8080/api \
    -H "Authorization: Bearer my-token" \
    -H "X-Custom-Header: some-value"

Test with cookies

# Send a session cookie
pywrkr http://localhost:8080/ -C "session=abc123"

# Multiple cookies
pywrkr http://localhost:8080/ -C "session=abc123" -C "lang=en"

Bypass caches (cache-busting)

If your server has a cache (like a CDN), each request might return a cached response instead of hitting your actual server. Use -R to add a unique parameter to every request, so nothing gets cached.

# Without -R: all requests hit the same cached URL
# With -R: each request gets a unique URL like /api?_cb=abc123
pywrkr http://localhost:8080/api -R -c 100 -d 30

See detailed latency breakdown

Want to know where the time is spent? DNS lookup? Connecting? Waiting for the server?

pywrkr https://example.com/ --latency-breakdown -d 10

This shows time spent on each phase:

  • DNS Lookup — finding the server's IP address
  • TCP Connect — opening the connection
  • TLS Handshake — setting up encryption (HTTPS only)
  • TTFB — waiting for the server to respond
  • Transfer — downloading the response body

Combine options

You can mix and match everything:

# 200 connections, 60 seconds, POST with auth, save JSON results
pywrkr http://localhost:8080/api/data \
    -c 200 -d 60 \
    -m POST -b '{"key": "val"}' \
    -H "Content-Type: application/json" \
    -A admin:secret \
    --latency-breakdown \
    --json results.json

Next steps

Clone this wiki locally