CloadTester 🚀

CloadTester (cloadtester) is a high-performance Python API load testing library backed by a native C++ multithreaded engine.

Unlike pure Python threading libraries which are constrained by the Global Interpreter Lock (GIL), CloadTester executes concurrent HTTP/HTTPS requests on true native OS C++ threads (std::thread), unlocking true parallel multi-core performance.

Key Features

• True Parallel Multithreading: C++ releases the Python GIL during load test execution.
• High Accuracy & Microsecond Precision: High-resolution timer metrics (std::chrono).
• Zero Third-Party Binary Dependencies: Uses native platform APIs (WinHTTP on Windows, POSIX Sockets on Linux/macOS).
• Rich Latency Analytics: Calculates Min, Mean, Max, P50, P90, P95, and P99 percentiles along with Requests Per Second (RPS).
• Python API & CLI Tool: Use as a standard Python module or via the command-line interface cload-test.

Installation

Install directly from PyPI (once published):

pip install cloadtester

Or install locally for development:

pip install -e .

Quick Start Guide

1. Using Python API

from cloadtester import LoadTester
from cloadtester.reporter import print_summary

# Configure your API load test
tester = LoadTester(
    url="https://httpbin.org/post",
    method="POST",
    headers={"Authorization": "Bearer sample_token"},
    json_payload={"user_id": 101, "action": "benchmark"},
    timeout_ms=5000
)

# Run with 10 threads, performing a total of 100 requests
result = tester.run(num_threads=10, total_requests=100)

# Print formatted summary report
print_summary(result)

# Access programmatically
print(f"RPS: {result.requests_per_sec:.2f}")
print(f"P95 Latency: {result.percentile(95):.2f} ms")

2. Using Command-Line Tool (cload-test)

# Simple GET request load test
cload-test https://httpbin.org/get -t 10 -n 100

# POST request with JSON payload and custom headers
cload-test https://httpbin.org/post -m POST -t 20 -n 200 -d '{"key": "value"}' -H "Content-Type: application/json"

How to Publish to PyPI

Follow these steps to publish cloadtester to PyPI:

Step 1: Install Publishing Dependencies

pip install build twine

Step 2: Build Source Distribution and Binary Wheel

python -m build

This generates dist/cloadtester-0.1.0.tar.gz and dist/cloadtester-0.1.0-*.whl.

Step 3: Check Build Distribution

twine check dist/*

Step 4: Upload to PyPI

To upload to TestPyPI first:

twine upload --repository testpypi dist/*

To upload to production PyPI:

twine upload dist/*

License

MIT License. Free for commercial and open-source use.