# alteryx/locust-grasshopper architecture

> Architecture diagram of the GitHub repository alteryx/locust-grasshopper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alteryx/locust-grasshopper
- Repository: https://github.com/alteryx/locust-grasshopper

## Overview

##### Project Type and Purpose
- This is an open-source Python framework (“locust-grasshopper”) that wraps and extends Locust + Pytest to make authoring and running load tests against an API simple and boilerplate-free. It provides configuration sources, scenario processing, custom metrics (checks, trends, thresholds), and time-series DB reporting via InfluxDB (with Grafana example infra).

##### High-Level Structure (from file tree)
- Top-level config & metadata: `pyproject.toml`, `setup.py`, GitHub workflows, pre-commit hooks.
- Source code in `src/grasshopper/lib`:
- configuration/ – GHConfiguration loader & fixtures
- fixtures/ – pytest fixtures for wiring tests
- journeys/ – BaseJourney class and user-defined journey mechanics
- reporting/ – console reporters & reporter extension interfaces
- grasshopper.py – core entrypoint (`Grasshopper.launch_test`)
- Examples: `example/` (sample pytest load test, YAML scenarios, Docker-Compose observability infra)
- Tests: `tests/unit/`, `tests/integration/`

##### Key Architectural Components
a. User/Test Layer
- pytest test file (e.g. `example/test_example.py`)
- Scenario YAML files (parameterization for multiple scenarios)
- Pytest fixtures (`complete_configuration`, `grasshopper_config_file_path`, `extra_env_var_keys`, etc.)
b. Configuration Loader
- Merges sources in precedence: CLI args → env vars → YAML scenario → config file → defaults
- Produces a `GHConfiguration` object passed to tests and journeys
c. Core Runner (`Grasshopper.launch_test`)
- Sets up a Locust `Environment`
- Registers custom listeners (InfluxDBListener) and console reporters
- Spawns Locust runners and orchestrates test start/stop
d. Journey Execution
- `BaseJourney` subclasses define user behavior with Locust’s `@task`
- Each journey holds its `scenario_args` and `defaults`
- Utility decorators (`@custom_trend`) and functions (`check`) hook into Locust events/requests
e. Metrics & Reporting
- Locust core emits events: requests, exceptions, checks, custom trends
- Database listener (InfluxDB) ingests these events into time-series tables (`locust_requests`, `locust_checks`, etc.)
- Console reporter aggregates and prints summary at test end
f. External Infrastructure
- InfluxDB + Grafana (optional) for metrics storage and dashboards (example Docker-Compose under `example/observability_infrastructure`)

##### Relationships & Data Flow
1. Tester invokes pytest (pointing at test file or YAML scenarios) → pytest CLI plugin parses **Grasshopper** options
2. Pytest fixtures load and merge configuration → supply `complete_configuration` to test
3. Test calls `Grasshopper.launch_test(user_classes, **complete_configuration)`
4. Grasshopper sets up Locust environment, registers listeners/reporters
5. Locust spawns virtual users executing journey tasks
6. Each HTTP request or custom trend emits metrics → sent to console and InfluxDB listener → InfluxDB
7. After runtime expires or criteria met → Locust shutdown → final summary printed

##### Architectural Patterns & Principles
- Plugin/Listener Pattern: custom listeners (InfluxDBListener) attached to Locust events
- Fixture Pattern: pytest fixtures modularize configuration and extension points
- Decorator Pattern: `@custom_trend` wraps tasks to time and tag multi-step operations
- Layered Configuration: clear precedence and merging of config sources
- Modular Design: separate concerns (config, execution, metrics, reporting, utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Extension Points"
    TestFile["Example Test File"]:::pytest
    Scenario["Scenario Definitions (YAML)"]:::pytest
    Fixtures["Pytest Fixtures"]:::pytest
  end

  subgraph "Core Engine"
    ConfigLoader["Configuration Loader\n(GHConfiguration)"]:::core
    CoreRunner["Core Runner\n(Grasshopper.launch_test)"]:::core
    LaunchHelper["Test Launch Helper"]:::core
    LocustEnv["Locust Environment & Executor"]:::core
    LoadShapes["Load Shape Definitions"]:::core
    BaseJourney["Base Journey Class"]:::core
    CompositeJourney["Composite Journey Utility"]:::core
    Decorators["@custom_trend Decorator Hooks"]:::core
    CheckUtils["Check Utilities"]:::core
    MetricsHelpers["Metrics Helpers"]:::core
    EventListeners["Event Listeners\n(InfluxDBListener)"]:::core
    ConsoleReporter["Console Reporter"]:::core
    ReporterInterfaces["Reporter Interfaces & Extensions"]:::core
  end

  subgraph "Infrastructure"
    InfluxDB["InfluxDB"]:::external
    Grafana["Grafana"]:::external
  end

  TestFile -->|invokes| Fixtures
  Scenario -->|provides scenarios| Fixtures
  Fixtures -->|supplies configuration| ConfigLoader
  ConfigLoader -->|produces GHConfiguration| CoreRunner
  CoreRunner -->|calls| LaunchHelper
  LaunchHelper -->|sets up| LocustEnv
  CoreRunner -->|registers shapes| LoadShapes
  CoreRunner -->|registers listeners| EventListeners
  LocustEnv -->|spawns users| BaseJourney
  BaseJourney -->|uses| Decorators
  BaseJourney -->|uses| CheckUtils
  BaseJourney -->|emits metrics| MetricsHelpers
  MetricsHelpers -->|forwards events| EventListeners
  EventListeners -->|writes to| InfluxDB
  LocustEnv -->|prints summary| ConsoleReporter
  ConsoleReporter -->|extends via| ReporterInterfaces
  InfluxDB -->|visualizes in| Grafana

  click TestFile "https://github.com/alteryx/locust-grasshopper/blob/main/example/test_example.py"
  click Scenario "https://github.com/alteryx/locust-grasshopper/blob/main/example/example_scenarios.YAML"
  click Fixtures "https://github.com/alteryx/locust-grasshopper/tree/main/src/grasshopper/lib/fixtures/"
  click ConfigLoader "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/configuration/gh_configuration.py"
  click CoreRunner "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/grasshopper.py"
  click LaunchHelper "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/util/launch.py"
  click LoadShapes "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/util/shapes.py"
  click Decorators "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/util/decorators.py"
  click CheckUtils "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/util/check_constants.py"
  click MetricsHelpers "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/util/metrics.py"
  click EventListeners "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/util/listeners.py"
  click BaseJourney "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/journeys/base_journey.py"
  click CompositeJourney "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/journeys/temp_gh_composite.py"
  click ConsoleReporter "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/reporting/er_basic_console_reporter.py"
  click ReporterInterfaces "https://github.com/alteryx/locust-grasshopper/blob/main/src/grasshopper/lib/reporting/iextendedreporter.py"
  click InfluxDB "https://github.com/alteryx/locust-grasshopper/blob/main/example/observability_infrastructure/docker-compose.yml"
  click Grafana "https://github.com/alteryx/locust-grasshopper/tree/main/example/observability_infrastructure/provisioning/dashboards/"

  classDef pytest fill:#e0f7fa,stroke:#006064,stroke-width:1px
  classDef core fill:#bbdefb,stroke:#0d47a1,stroke-width:1px
  classDef external fill:#ffe0b2,stroke:#e65100,stroke-width:1px
  classDef section fill:#eeeeee,stroke:#999999,stroke-width:2px
```
