# nicolelwl85/taurus architecture

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

- Interactive diagram: https://gitdiagram.com/nicolelwl85/taurus
- Repository: https://github.com/nicolelwl85/taurus

## Overview

##### Project Type and Purpose
- Taurus is a Python-based, open-source command-line tool that provides a unified wrapper over performance/functional testing engines (JMeter, Gatling, Locust, Grinder, Selenium WebDriver, etc.).
- Its goal is to hide the complexity of those tools behind a simple YAML-based configuration and a single CLI (bzt).

##### Key Components from File Structure
- CLI & Entry Point:
- bzt/cli.py – parses commands and options, loads configuration, invokes the Engine
- bzt/__init__.py, bzt/bza.py – package entry
- Core Engine & Workflow:
- bzt/engine.py – orchestrates test execution lifecycle
- bzt/utils.py – shared utilities
- bzt/requests_model.py – internal request abstraction
- Plugin Modules (bzt/modules):
- executor modules (jmeter, gatling, locustio, grinder, siege, soapui, tsung, etc.)
- functional modules (selenium, chrome, javascript, python, ruby)
- provisioning modules (cloud, local)
- aggregator modules (defaultAggregator, functionalAggregator, consolidatingAggregator)
- reporting modules (console, JUnitXML, HTML, BlazemeterUploader)
- monitoring modules
- pass/fail modules
- Resources (bzt/resources):
- Templates and helper scripts for each engine (JMX-to-YAML, wrappers, config templates)
- Tests & Examples:
- tests/ – unit tests for every module, engine, CLI command
- examples/ – sample YAML scenarios for each engine and framework
- Documentation Site (site/):
- PHP and Markdown files driving the project website and knowledge base
- Packaging & Deployment:
- setup.py, Dockerfile, build scripts, Travis/AppVeyor, installer scripts

a. Components to Represent
1. CLI Layer (bzt CLI)
2. Configuration Parser (YAML reader)
3. Core Engine Scheduler
4. Plugin Loader & Module Registry
5. Executor Modules (one per tool)
6. Provisioning Modules (cloud/local)
7. Aggregator & Pass/Fail Modules
8. Reporter Modules (console, files, remote API)
9. External Tools & Services (JMeter, Gatling, Selenium, Locust, Grinder, Blazemeter API)
10. File System (resources, templates, output artifacts)
11. Documentation Site Generator (site/) – optional in core diag

b. Relationships & Data Flows
- User runs `bzt test.yml` → CLI Layer
- CLI invokes Configuration Parser → produces internal config model
- Core Engine Scheduler uses Module Registry to instantiate:
- Provisioning → prepares environment (cloud or local)
- Executors → launch underlying tools with generated configs or scripts
- Aggregators & Monitors → collect metrics in real time
- Reporters → consume aggregated results, output to console/files or upload
- Executors interact with External Tools/Services (shell, REST, Java processes)
- Resources folder supplies templates and scripts to Executors
- Test artifacts (logs, metrics, reports) written to output directory

c. Architectural Patterns & Design Principles
- Plugin architecture: each module implements a common Executor/Reporting interface for extensibility
- Separation of concerns: clear layers for CLI, engine orchestration, execution, aggregation, reporting
- YAML configuration driven: decouples user config from execution logic
- Dependency injection via module registry

d. Key Technologies & Frameworks
- Python 3.x (backwards‐compat via bzt/six)
- PyPI packaging (setup.py)
- YAML parsing (PyYAML)
- Subprocess / threading for tool invocation
- REST clients for cloud/Blazemeter integration
- Java wrappers/plugins for TestNG/JUnit (in java/ folder)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI1["bzt/cli.py"]:::cli
        CLI2["bzt/bza.py"]:::cli
    end

    %% Configuration Parser
    subgraph "Configuration Parser"
        CP1["bzt/jmx2yaml.py"]:::parser
        CP2["bzt/soapui2yaml.py"]:::parser
    end

    %% Core Engine
    subgraph "Core Engine"
        Engine["Core Engine Scheduler<br/>(bzt/engine.py)"]:::core
        Utils["bzt/utils.py"]:::core
        ReqModel["bzt/requests_model.py"]:::core
    end

    %% Plugin Loader & Registry
    subgraph "Plugin Loader & Module Registry"
        InitMod["bzt/modules/__init__.py"]:::core
        Services["bzt/modules/services.py"]:::core
    end

    %% Executor Modules
    subgraph "Executor Modules" 
        JMeter["jmeter.py"]:::plugin
        Gatling["gatling.py"]:::plugin
        Locust["locustio.py"]:::plugin
        Grinder["grinder.py"]:::plugin
        ShellExec["shellexec.py"]:::plugin
        AB["ab.py"]:::plugin
        Siege["siege.py"]:::plugin
        SoapUI["soapui.py"]:::plugin
        Tsung["tsung.py"]:::plugin
    end

    %% Functional Testing Modules
    subgraph "Functional Modules"
        Selenium["selenium.py"]:::plugin
        Chrome["chrome.py"]:::plugin
        JavaScript["javascript.py"]:::plugin
        PythonMod["python.py"]:::plugin
        Ruby["ruby.py"]:::plugin
        Functional["functional.py"]:::plugin
    end

    %% Provisioning
    Provision["bzt/modules/provisioning.py"]:::plugin

    %% Aggregator & Pass/Fail
    subgraph "Aggregator & Pass/Fail"
        Aggregator["aggregator.py"]:::plugin
        PassFail["passfail.py"]:::plugin
    end

    %% Reporter Modules
    subgraph "Reporter Modules"
        Console["console.py"]:::plugin
        Reporting["reporting.py"]:::plugin
        BlazeMeter["blazemeter.py"]:::plugin
    end

    %% Monitoring
    Monitoring["monitoring.py"]:::plugin

    %% Resources & FS
    subgraph "File System & Resources"
        Resources["bzt/resources/"]:::fs
        Output["Output Artifacts"]:::fs
        Tests["tests/"]:::fs
        Examples["examples/"]:::fs
        Site["site/"]:::fs
        Packaging["Packaging & Deployment"]:::fs
    end

    %% External Tools & Services
    subgraph "External Tools & Services"
        ExtJMeter["JMeter"]:::external
        ExtGatling["Gatling"]:::external
        ExtSelenium["Selenium WebDriver"]:::external
        ExtLocust["Locust"]:::external
        ExtGrinder["Grinder"]:::external
        ExtBlaze["BlazeMeter API"]:::external
    end

    %% Connections
    CLI1 -->|"load config"| CP1
    CLI1 -->|"load config"| CP2
    CP1 -->|"config model"| Engine
    CP2 -->|"config model"| Engine
    CLI2 --> Engine

    Engine -->|"load plugins"| InitMod
    Engine --> Services
    Engine --> Provision
    Engine --> JMeter
    Engine --> Gatling
    Engine --> Locust
    Engine --> Grinder
    Engine --> ShellExec
    Engine --> AB
    Engine --> Siege
    Engine --> SoapUI
    Engine --> Tsung
    Engine --> Selenium
    Engine --> Chrome
    Engine --> JavaScript
    Engine --> PythonMod
    Engine --> Ruby
    Engine --> Functional
    Engine --> Aggregator
    Engine --> PassFail
    Engine --> Console
    Engine --> Reporting
    Engine --> BlazeMeter
    Engine --> Monitoring

    JMeter -->|"launch process"| ExtJMeter
    Gatling -->|"launch process"| ExtGatling
    Selenium -->|"start driver"| ExtSelenium
    Locust --> ExtLocust
    Grinder --> ExtGrinder
    BlazeMeter -->|"REST API"| ExtBlaze

    JMeter -->|"use templates"| Resources
    Gatling --> Resources
    SoapUI --> Resources

    Aggregator --> Output
    PassFail --> Output
    Console --> Output
    Reporting --> Output
    BlazeMeter --> Output
    Monitoring --> Output

    Tests --> CLI1
    Tests --> Engine
    Tests --> JMeter
    Examples --> CP1
    Examples --> CP2
    Site --> Packaging

    %% Click Events
    click CLI1 "https://github.com/nicolelwl85/taurus/blob/master/bzt/cli.py"
    click CLI2 "https://github.com/nicolelwl85/taurus/blob/master/bzt/bza.py"
    click CP1 "https://github.com/nicolelwl85/taurus/blob/master/bzt/jmx2yaml.py"
    click CP2 "https://github.com/nicolelwl85/taurus/blob/master/bzt/soapui2yaml.py"
    click Engine "https://github.com/nicolelwl85/taurus/blob/master/bzt/engine.py"
    click Utils "https://github.com/nicolelwl85/taurus/blob/master/bzt/utils.py"
    click ReqModel "https://github.com/nicolelwl85/taurus/blob/master/bzt/requests_model.py"
    click InitMod "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/__init__.py"
    click Services "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/services.py"
    click JMeter "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/jmeter.py"
    click Gatling "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/gatling.py"
    click Locust "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/locustio.py"
    click Grinder "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/grinder.py"
    click ShellExec "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/shellexec.py"
    click AB "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/ab.py"
    click Siege "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/siege.py"
    click SoapUI "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/soapui.py"
    click Tsung "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/tsung.py"
    click Selenium "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/selenium.py"
    click Chrome "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/chrome.py"
    click JavaScript "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/javascript.py"
    click PythonMod "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/python.py"
    click Ruby "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/ruby.py"
    click Functional "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/functional.py"
    click Provision "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/provisioning.py"
    click Aggregator "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/aggregator.py"
    click PassFail "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/passfail.py"
    click Console "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/console.py"
    click Reporting "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/reporting.py"
    click BlazeMeter "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/blazemeter.py"
    click Monitoring "https://github.com/nicolelwl85/taurus/blob/master/bzt/modules/monitoring.py"
    click Resources "https://github.com/nicolelwl85/taurus/tree/master/bzt/resources/"
    click Tests "https://github.com/nicolelwl85/taurus/tree/master/tests/"
    click Examples "https://github.com/nicolelwl85/taurus/tree/master/examples/"
    click Site "https://github.com/nicolelwl85/taurus/tree/master/site/"
    click Packaging "https://github.com/nicolelwl85/taurus/blob/master/setup.py"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef parser fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef core fill:#85C1E9,stroke:#1B4F72,color:#1B2631;
    classDef plugin fill:#ABEBC6,stroke:#145A32,color:#145A32;
    classDef external fill:#F9E79F,stroke:#7D6608,color:#7D6608;
    classDef fs fill:#EAECEE,stroke:#909497,color:#424949;
```
