Load Testing Hub

Load Testing Hub is a Python library and CLI tool designed to upload performance testing results into the load-testing-hub-api. It provides a convenient connector for reading and transforming Locust reports and sending them to the Load Testing Hub API over HTTP.

Key Features

• Easy integration with Locust reports (CSV/JSON).
• Raw Python API for programmatic usage.
• CLI support for quick uploads from configuration files (YAML or JSON).
• Pydantic-powered configuration for strict validation and clear error messages.

Installation

pip install load-testing-hub

For development:

git clone https://github.com/Nikita-Filonov/load-testing-hub.git
cd load-testing-hub
pip install -e .

Usage

1. Python API

You can upload Locust results directly from your Python code by using the raw API:

import asyncio
from pathlib import Path

from load_testing_hub import (
    Service,
    Scenario,
    Pipeline,
    upload_locust_report,
    UploadLocustReportParams
)


# Main async function to upload Locust test results
async def main():
    await upload_locust_report(
        UploadLocustReportParams(
            # Base URL of the Load Testing Hub API
            api_url="http://localhost:8000",

            # Information about the service for which results are uploaded
            service=Service(id=1),

            # Scenario metadata (name, configuration file, version, and load parameters)
            scenario=Scenario(
                id=1,
                name="get accounts",  # Scenario name
                file="./scenarios/get_accounts/v1.0.conf",  # Path to scenario config file
                version="v1.0",  # Scenario version
                number_of_users=500,  # Number of virtual users in the test
                runtime_duration="3m"  # Test duration (3 minutes)
            ),

            # CI/CD pipeline that triggered the load test execution
            trigger_pipeline=Pipeline(
                ci_job_url="http://localhost:8001/pipeline/1/job/3",  # URL of the triggering job
                ci_pipeline_url="http://localhost:8001/pipeline/1",  # URL of the triggering pipeline
                ci_project_version="v1.11.0"  # Project version under test
            ),

            # CI/CD pipeline where the load test scenarios are located
            load_tests_pipeline=Pipeline(
                ci_job_url="http://localhost:8001/pipeline/3/job/9",  # URL of the load tests job
                ci_pipeline_url="http://localhost:8001/pipeline/3",  # URL of the load tests pipeline
            ),

            # Paths to Locust report files
            csv_locust_stats_file=Path("locust_stats.csv"),  # Aggregated statistics
            json_locust_ratio_file=Path("locust_ratio.json"),  # Response time percentiles
            csv_locust_exceptions_file=Path("locust_exceptions.csv"),  # Exceptions during test
            csv_locust_stats_history_file=Path("locust_stats_history.csv"),  # Time-series stats
        )
    )


# Run the async main function
asyncio.run(main())

2. CLI Usage

The package provides a built-in CLI command for uploading reports.

Example with YAML configuration

Configuration file (./examples/locust.yaml):

# Base URL of the Load Testing Hub API
api_url: http://localhost:8000

# Information about the service for which results are uploaded
service:
  id: 1  # Unique service identifier

# Scenario metadata
scenario:
  id: 1  # Unique scenario identifier
  name: "get account"  # Scenario name (for reference in the UI or reports)
  file: "./scenarios/get_accounts/v1.0.conf"  # Path to the scenario configuration file
  version: "v1.0"  # Version of the scenario
  number_of_users: 500  # Number of virtual users executed in the test
  runtime_duration: "3m"  # Test runtime duration (3 minutes)

# CI/CD pipeline that triggered the load test execution
trigger_pipeline:
  ci_job_url: "http://localhost:8001/pipeline/1/job/3"  # URL of the triggering job
  ci_pipeline_url: "http://localhost:8001/pipeline/1"  # URL of the triggering pipeline
  ci_project_version: "v1.11.0"  # Project version under test

# CI/CD pipeline where the load test scenarios are located
load_tests_pipeline:
  ci_job_url: "http://localhost:8001/pipeline/3/job/9"  # URL of the load tests job
  ci_pipeline_url: "http://localhost:8001/pipeline/3"  # URL of the load tests pipeline

# Paths to Locust output files generated after test execution
csv_locust_stats_file: "locust_stats.csv"  # Aggregated test statistics
json_locust_ratio_file: "locust_ratio.json"  # Percentile and ratio statistics
csv_locust_exceptions_file: "locust_exceptions.csv"  # Exceptions captured during the test
csv_locust_stats_history_file: "locust_stats_history.csv"  # Time-series performance stats

Command:

load-testing-hub upload-locust-report --yaml-config=./examples/locust.yaml

Example with JSON configuration

Configuration file (./examples/locust.json):

{
  "api_url": "http://localhost:8000",
  "service": {
    "id": 1
  },
  "scenario": {
    "id": 1,
    "name": "get account",
    "file": "./scenarios/get_accounts/v1.0.conf",
    "version": "v1.0",
    "number_of_users": 500,
    "runtime_duration": "3m"
  },
  "trigger_pipeline": {
    "ci_job_url": "http://localhost:8001/pipeline/1/job/3",
    "ci_pipeline_url": "http://localhost:8001/pipeline/1",
    "ci_project_version": "v1.11.0"
  },
  "load_tests_pipeline": {
    "ci_job_url": "http://localhost:8001/pipeline/3/job/9",
    "ci_pipeline_url": "http://localhost:8001/pipeline/3"
  },
  "csv_locust_stats_file": "locust_stats.csv",
  "json_locust_ratio_file": "locust_ratio.json",
  "csv_locust_exceptions_file": "locust_exceptions.csv",
  "csv_locust_stats_history_file": "locust_stats_history.csv"
}

Command:

load-testing-hub upload-locust-report --json-config=./examples/locust.json