How alteryx/locust-grasshopper works
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)