Documentation

Quick Load Test — Quick Start

The fastest way to stress-test a URL. Raw HTTP requests, up to 100,000 per second.

1. Go to theloadtester.com/test.html and select Quick Load Test
2. Paste the URL you want to test
3. Choose RPS (requests per second), duration, and regions
4. Complete domain verification (see Domain Verification)
5. Pay with USDC or USDT (free tier: no payment needed)
6. Watch live metrics stream in real time
7. Download your PDF report when done

Free Tier Limits

Scenario Test — Quick Start

Simulate real user journeys through your app using Playwright browser automation.

1. Go to theloadtester.com/test.html?mode=scenario
2. Create one or more scenarios using Upload, Record, or Visual Builder
3. Each scenario downloads as an encrypted .loadtest file — keep these on your computer
4. Upload your .loadtest files and set the percentage split (must total 100%)
5. Set virtual user count, duration, and regions
6. Complete domain verification
7. Pay and launch — watch 500 real browser instances execute your scenarios simultaneously
8. Download PDF report with per-step timing, bottlenecks, and error screenshots

Scenario Tier Limits

Create Scenarios — Upload Script

Write or paste a Playwright script. LoadTester runs it in a headless Chromium browser for each virtual user.

Script format

Export a single async function that receives a browser instance:

// login-flow.js — example scenario script
module.exports = async function(browser) {
  const page = await browser.newPage();

  // Navigate
  await page.goto('https://yourapp.com/login');

  // Fill form
  await page.fill('#email', 'load-test@example.com');
  await page.fill('#password', 'TestPassword123!');
  await page.click('[type="submit"]');

  // Wait for navigation
  await page.waitForURL('**/dashboard', { timeout: 10000 });

  // Verify something is on screen
  await page.waitForSelector('.dashboard-title');

  // Screenshot (captured in report)
  await page.screenshot({ path: 'dashboard.png' });

  await page.close();
};

Limitations

• Each script runs in an isolated Chromium context — no shared state between virtual users
• Maximum script execution time: 5 minutes per virtual user iteration
• No file system access (screenshots go into the report)
• No network proxies or custom certificates
• External domains beyond the test target may be blocked

Create Scenarios — Record

Record your interactions with your site. We open it in a real browser and capture every click, fill, and navigation as Playwright steps.

1. Enter your site's URL and a scenario name
2. Click Start Recording — your site opens in a new browser window
3. Click through the user journey you want to simulate
4. When finished, click Stop Recording
5. Review the captured steps, then click Download .loadtest

The recording captures: navigate, click, fill, select, check, keyboard events, and page assertions.

Create Scenarios — Visual Builder

Build a scenario step-by-step with no code. Select a step type, fill in the parameters, and click Add Step.

Available step types

Example scenario: browse products

navigate("https://shop.example.com")
wait(1000)
click(".products-grid .product-card:first-child")
wait(500)
screenshot("product-page")
assert(".product-title", "Running Shoes")
click(".add-to-cart")
navigate("https://shop.example.com/cart")
assert(".cart-count", "1")

The .loadtest File Format

A .loadtest file is an encrypted binary blob. You keep it — we store nothing. Upload it when you are ready to run the test.

What is inside

The file contains AES-256-GCM encrypted JSON with the following structure:

// Decrypted content (only our servers can read this)
{
  "version": 1,
  "name": "Login flow",
  "created": 1712345678000,
  "type": "script" | "visual" | "recorded",
  "steps": [...] // or "script": "..."
}

File layout

# Binary layout: [IV 12 bytes][Auth Tag 16 bytes][Ciphertext N bytes]

The encryption key never leaves our servers. The file is useless without us — that is intentional. We cannot be used as a DDoS relay because only we control when execution happens.

Domain Verification

Before any test runs, you must prove you control the target domain. This prevents LoadTester from being used to attack sites you don't own.

How it works

1. Start configuring a test — we generate a unique test ID (e.g. lt_a3f9b2c1)
2. Create a file at: /.well-known/loadtester-verify/{test-id}
3. File content must be: {test-id}:verified:{year} (shown on the test page)
4. Click Check Verification — we fetch the file and confirm ownership
5. Test proceeds to payment

Quick setup examples

# Bash / any Linux server
mkdir -p /var/www/html/.well-known/loadtester-verify
echo "lt_a3f9b2c1:verified:2026" > /var/www/html/.well-known/loadtester-verify/lt_a3f9b2c1

# nginx — add to server block
location /.well-known/loadtester-verify/ {
  root /var/www/html;
  add_header Content-Type text/plain;
}

# Node.js / Express
app.get('/.well-known/loadtester-verify/:id', (req, res) => {
  res.send(`${req.params.id}:verified:2026`);
});

Verification TTL

The verification is valid for the duration of the test. After the test ends, you can remove the file. Each new test requires a new verification (new test ID).

Metrics Explained

Requests Per Second (RPS)

The number of HTTP requests (or browser scenario iterations) completed per second. Reported per-region and as an aggregate. In scenario mode, this counts completed Playwright script executions, not individual page actions.

Latency Percentiles

A large gap between P50 and P99 indicates high variance — some requests are much slower than average, often a sign of database lock contention, GC pauses, or cold cache hits.

Error Rate

Percentage of requests that returned a 4xx or 5xx HTTP status code, timed out, or (in scenario mode) failed to complete the Playwright script. Anything above 0.1% under load is worth investigating.

Throughput (bytes/sec)

Total bytes transferred from the server to LoadTester per second. Useful for detecting bandwidth bottlenecks.

Per-step latency (Scenario mode)

Each Playwright step is timed individually. The PDF report shows a waterfall chart of time spent on: navigation, waiting for elements, form fills, and assertions. This pinpoints exactly which part of your flow is slow.

PDF Reports

Every test produces a PDF report. Download it immediately when the test completes. We delete all data after the session ends — the PDF is your only record.

What is in the report

• Test configuration summary (URL, RPS/users, duration, regions)
• Aggregate metrics: total requests, error rate, peak RPS, P50/P95/P99
• Throughput over time chart (time series)
• Latency over time chart
• Per-region breakdown: Americas, Frankfurt, London, Singapore
• Status code distribution
• Scenario mode: Per-step latency waterfall, bottleneck identification, error screenshots
• Conclusion: pass/fail thresholds if configured, recommendations

API Reference

Integrate LoadTester into your CI/CD pipeline. All endpoints accept and return JSON. Authentication via X-LoadTester-Key header (API access keys are generated from your account dashboard).

Base URL

https://api.theloadtester.com

POST /api/simple-test

{
  "url": "https://api.example.com/health",
  "rps": 10000,
  "duration": 600,
  "regions": ["americas", "europe-de", "europe-uk", "asia"],
  "testId": "lt_a3f9b2c1"
}

// Response:
{ "id": "lt_a3f9b2c1", "status": "running", "streamUrl": "/api/test/lt_a3f9b2c1/stream" }

GET /api/test/:id/stream (SSE)

# Each event data is JSON:
{
  "rps": 9823,
  "p50": 48,
  "p95": 134,
  "p99": 289,
  "errRate": 0.003,
  "elapsed": 45,
  "duration": 600,
  "regions": {
    "americas": { "rps": 3950, "latency": 42 },
    "europe-de": { "rps": 1980, "latency": 61 },
    "europe-uk": { "rps": 2010, "latency": 67 },
    "asia": { "rps": 1883, "latency": 95 }
  }
}

curl Examples

Verify domain

curl -X POST https://api.theloadtester.com/api/verify-domain \
  -H "Content-Type: application/json" \
  -d '{"testId":"lt_a3f9b2c1","verifyUrl":"https://yoursite.com/.well-known/loadtester-verify/lt_a3f9b2c1"}'

Start a simple test (free tier)

curl -X POST https://api.theloadtester.com/api/simple-test \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/health",
    "rps": 100,
    "duration": 60,
    "regions": ["americas"],
    "testId": "lt_a3f9b2c1"
  }'

Stream results

curl -N https://api.theloadtester.com/api/test/lt_a3f9b2c1/stream

Download report

curl -o report.pdf https://api.theloadtester.com/api/test/lt_a3f9b2c1/report

GitHub Actions Integration

# .github/workflows/load-test.yml
name: Load Test on Deploy

on:
  workflow_run:
    workflows: ["Deploy to Production"]
    types: [completed]

jobs:
  load-test:
    runs-on: ubuntu-latest
    if: github.event.workflow_run.conclusion == 'success'
    steps:
      - name: Setup verification file
        run: |
          TEST_ID="lt_ci_$(date +%s)"
          echo "$TEST_ID" > /tmp/test_id
          # Deploy verification file to your server
          ssh user@yourserver.com \
            "echo '$TEST_ID:verified:2026' > /var/www/.well-known/loadtester-verify/$TEST_ID"

      - name: Verify domain
        run: |
          TEST_ID=$(cat /tmp/test_id)
          curl -f -X POST https://api.theloadtester.com/api/verify-domain \
            -H "Content-Type: application/json" \
            -d "{\"testId\":\"$TEST_ID\",\"verifyUrl\":\"https://yoursite.com/.well-known/loadtester-verify/$TEST_ID\"}"

      - name: Start load test
        run: |
          TEST_ID=$(cat /tmp/test_id)
          curl -f -X POST https://api.theloadtester.com/api/simple-test \
            -H "Content-Type: application/json" \
            -d "{\"url\":\"https://yoursite.com/api/health\",\"rps\":100,\"duration\":60,\"regions\":[\"americas\"],\"testId\":\"$TEST_ID\"}"

      - name: Wait and download report
        run: |
          sleep 75
          TEST_ID=$(cat /tmp/test_id)
          curl -o load-test-report.pdf \
            https://api.theloadtester.com/api/test/$TEST_ID/report

      - name: Upload report artifact
        uses: actions/upload-artifact@v4
        with:
          name: load-test-report
          path: load-test-report.pdf

GitLab CI Integration

# .gitlab-ci.yml — add after deploy stage
load-test:
  stage: verify
  needs: [deploy]
  script:
    - export TEST_ID="lt_ci_$(date +%s)"
    # Serve verification file on your target
    - ssh user@server "echo '$TEST_ID:verified:2026' > /var/www/.well-known/loadtester-verify/$TEST_ID"
    # Verify ownership
    - |
      curl -f -X POST https://api.theloadtester.com/api/verify-domain \
        -H "Content-Type: application/json" \
        -d "{\"testId\":\"$TEST_ID\",\"verifyUrl\":\"https://yoursite.com/.well-known/loadtester-verify/$TEST_ID\"}"
    # Start test
    - |
      curl -f -X POST https://api.theloadtester.com/api/simple-test \
        -H "Content-Type: application/json" \
        -d "{\"url\":\"https://yoursite.com\",\"rps\":100,\"duration\":60,\"regions\":[\"americas\"],\"testId\":\"$TEST_ID\"}"
    - sleep 75
    - curl -o report.pdf "https://api.theloadtester.com/api/test/$TEST_ID/report"
  artifacts:
    paths:
      - report.pdf
    expire_in: 7 days

Playwright Script Guide

Supported Playwright APIs

• page.goto(url, options) — Navigate to a URL
• page.click(selector, options) — Click an element
• page.fill(selector, value) — Fill an input
• page.type(selector, text) — Type character by character
• page.selectOption(selector, value) — Select dropdown option
• page.waitForSelector(selector, options) — Wait for element
• page.waitForURL(url, options) — Wait for navigation
• page.waitForTimeout(ms) — Pause
• page.screenshot(options) — Capture screenshot
• page.evaluate(fn) — Run JavaScript in page context
• expect(page).toHaveURL(url) — Assert URL
• expect(locator).toHaveText(text) — Assert text

Best practices for load test scripts

• Use dedicated test accounts — not production data
• Add waitForSelector after navigation instead of fixed delays
• Keep scripts under 2 minutes per iteration for best results
• Add screenshot() calls at key steps — they appear in error reports
• Handle expected redirects with waitForURL
• Do not use hardcoded sleep calls — use Playwright's built-in waits

Regions

Free tier tests run from americas only. Paid tiers run all selected regions simultaneously, with traffic split evenly across regions.

Pricing Reference

Simple Mode (raw HTTP)

Scenario Mode (Playwright browsers)

All payments in USDC or USDT on Demo L2 (chain ID 845302). Non-refundable. No subscriptions, no recurring charges.