# test-zeus-ai/testzeus-hercules architecture

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

- Interactive diagram: https://gitdiagram.com/test-zeus-ai/testzeus-hercules
- Repository: https://github.com/test-zeus-ai/testzeus-hercules

## Overview

─────────────────────────────
##### PROJECT TYPE & PURPOSE
─────────────────────────────
- The project is an open-source, AI-driven testing agent called “Hercules.”
- Its purpose is to simplify end-to-end test automation by converting Gherkin-based test cases into fully automated web interactions and validations.
- It integrates with LLMs (like GPT-4o and others) using a multi-agent architecture (Planner Agent and Browser Navigation Agent) and a robust tools library to execute web testing tasks, including API, security, accessibility, and visual validations.

─────────────────────────────
##### ANALYZING THE FILE STRUCTURE
─────────────────────────────
Review the top-level directories and files:
- Directories like “frontend,” “docs,” “helper_scripts,” “tests,” and “testzeus_hercules” hint at numerous facets:
- “frontend”: Contains both interactive and non-interactive UIs, possibly for demonstration or debugging purposes.
- “testzeus_hercules”: The core engine where agents, tools, memory management, and orchestration reside.
- “helper_scripts”: A collection of scripts to manage execution, setup, and additional tooling (like connecting to remote browser instances via CDP URLs).
- “tests”: Provides example Gherkin feature files and supporting test data, showing how automated tests are executed.
- Dockerfile, .env-example, and GitHub workflows underscore containerization and CI/CD integration.
- Notice configuration files (pyproject.toml, Makefile, environment docs), which indicate that the system’s behavior is heavily parameterized via environment variables and configuration management.

─────────────────────────────
##### EXTRACTING ARCHITECTURAL INSIGHTS FROM THE README
─────────────────────────────
The README elaborates on:
- How users provide input via Gherkin files, configure test parameters, and set environment variables.
- The multiple approaches to running Hercules (via PyPI package, Docker container, source code build, and helper scripts).
- A detailed explanation of the multi-agent architecture:
- “Planner Agent” decomposes tasks by interpreting Gherkin steps.
- “Browser Navigation Agent” leverages tools to perform actions (clicks, text entry, validations, etc.) via a dedicated Playwright manager.
- An emphasis on modularity in the Tools Library with “sensing tools” (to capture the DOM, current URL) and “action tools” (to interact with the browser).
- Integration with external services (like BrowserStack, LambdaTest, BrowserBase) and the setup for connecting to remote browser instances using CDP endpoints.
- Mechanisms for logging, output reporting (HTML and JUnit XML reports), and capturing execution proofs (screenshots, videos, network logs).

─────────────────────────────
─────────────────────────────

A. MAIN COMPONENTS & SUBSYSTEMS
a. User Interface / CLI Layer
- Represents how a user triggers tests (e.g., by running the “testzeus-hercules” command).
- Can also include interactive modes via the “frontend” folder where a browser-based UI is provided.

b. Input Components
- Gherkin Feature Files: Shown as external input files (located under “opt/input” and “tests”) that are fed into Hercules.
- Test Data and Configurations: Represented by the “opt/test_data” folder, environment files (.env), and agents_llm_config.json.

c. Core Engine/Orchestration
- Planner Agent: Acts as the decision-making component that breaks down each Gherkin step into actionable tasks.
- Browser Navigation Agent: Interacts with the browser for tests, using Playwright as a bridge.
- Memory Modules: Both dynamic (for session context) and static (pre-loaded data), located within testzeus_hercules/core/memory.

d. Tools Library
- Sensing Tools: Components like geturl, get_dom_with_content_type, etc.
- Action Tools: Components like click, enter_text, openurl, etc.
- Additional Tools: Located in “additional_tools” and integrated via configuration (through ADDITIONAL_TOOL_DIRS).

e. External Integration Subsystem
- Browser Services: Connections via Playwright and optional remote browser endpoints (e.g., CDP_ENDPOINT_URL for BrowserBase or BrowserStack).
- CI/CD & Docker Integration: Show the Docker container execution mode with volume mounts, environment files, and automation scripts.

f. Logging & Reporting
- Output Path: Directory structure for logs, HTML reports, JUnit XML files, and captured proofs (videos, screenshots, network logs).
- Chat Logs: Represent “chat_messages.json” in the log_files folder which captures the chain of thought for diagnostic purposes.

B. RELATIONSHIPS & DATA FLOWS
- Feedback loops where execution results (logs, proofs) are sent back to the core engine and eventually output to reporting directories.

C. ARCHITECTURAL PATTERNS & DESIGN PRINCIPLES
- Modular, multi-agentic architecture, where each agent and tool is clearly isolated and loosely coupled yet coordinated by the core runner.
- Separation between test planning and test execution, ensuring a clean division of responsibilities.
- Use of environment-driven configurations to allow dynamic behavior and cross-environment compatibility, especially for Docker/CICD environments.

D. TECHNOLOGIES & FRAMEWORKS
- Python 3.11: Foundational language version.
- Playwright: Used for browser automation across testing scenarios.
- Docker: For containerized testing deployments.
- LLMs: External APIs (OpenAI GPT-4o, Anthropic, etc.) for intelligent decision-making.
- CI/CD: GitHub workflows and Makefile for automation.

─────────────────────────────

##### FINAL REMINDER
─────────────────────────────

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface/CLI Layer
    subgraph "User Interface/CLI Layer"
        CLI["\"CLI\""]:::interface
        UI["\"Browser-based UI\""]:::interface
    end

    %% Input Components
    subgraph "Input Components"
        Gherkin["\"Gherkin Feature Files\""]:::input
        TestData["\"Test Data & Configurations\""]:::input
    end

    %% Core Engine/Orchestration
    subgraph "Core Engine/Orchestration"
        Runner["\"Core Runner\""]:::engine
        SimpleEngine["\"Simplified Engine\""]:::engine
        Planner["\"Planner Agent\""]:::agent
        NavAgent["\"Browser Navigation Agent\""]:::agent
    end

    %% Memory Modules
    subgraph "Memory Modules"
        Memory["\"Memory Modules\""]:::memory
    end

    %% Tools Library
    subgraph "Tools Library"
        Tools["\"Sensing & Action Tools\""]:::tools
        AdditionalTools["\"Additional Tools Extension\""]:::tools
    end

    %% External Integration Subsystem
    subgraph "External Integration Subsystem"
        LLM["\"LLM Integration Config\""]:::external
        Playwright["\"Playwright Manager\""]:::external
    end

    %% Logging & Reporting
    subgraph "Logging & Reporting"
        Logger["\"Logging Mechanism\""]:::reporting
        Reporter["\"Reporting & Output Utilities\""]:::reporting
    end

    %% Connections - User Interface to Input
    CLI -->|"initiates"| Gherkin
    UI  -->|"initiates"| Gherkin
    CLI -->|"initiates"| TestData
    UI  -->|"initiates"| TestData

    %% Input to Core Engine
    Gherkin -->|"supplies cases"| Runner
    TestData -->|"supplies configs"| Runner

    %% Core Engine orchestration
    Runner -->|"delegates"| Planner
    SimpleEngine -->|"delegates"| Planner
    Planner -->|"sends tasks"| NavAgent
    Planner -->|"queries"| LLM

    %% Browser Navigation Agent interactions
    NavAgent -->|"accesses"| Memory
    NavAgent -->|"invokes tools"| Tools
    NavAgent -->|"logs actions"| Logger

    %% Tools Library interactions
    Tools -->|"controls browser"| Playwright
    Tools -->|"reports status"| Logger
    Tools -->|"generates reports"| Reporter
    AdditionalTools -->|"extends"| Tools

    %% External integrations
    Playwright -->|"manages remote sessions"| Logger

    %% Logging & Reporting feedback
    Logger -->|"feeds back"| Runner
    Reporter -->|"outputs results"| Runner

    %% Click Events
    click CLI "https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/__main__.py"
    click UI "https://github.com/test-zeus-ai/testzeus-hercules/tree/main/frontend/interactive"
    click UI "https://github.com/test-zeus-ai/testzeus-hercules/tree/main/frontend/non-interactive"
    click Gherkin "https://github.com/test-zeus-ai/testzeus-hercules/tree/main/opt/input"
    click Gherkin "https://github.com/test-zeus-ai/testzeus-hercules/tree/main/tests"
    click TestData "https://github.com/test-zeus-ai/testzeus-hercules/tree/main/opt/test_data"
    click TestData "https://github.com/test-zeus-ai/testzeus-hercules/blob/main/.env-example"
    click Runner "https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/runner.py"
    click SimpleEngine "https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py"
    click Planner "https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/high_level_planner_agent.py"
    click NavAgent "https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/browser_nav_agent.py"
    click Memory "https://github.com/test-zeus-ai/testzeus-hercules/tree/main/testzeus_hercules/core/memory/"
    click Tools "https://github.com/test-zeus-ai/testzeus-hercules/tree/main/testzeus_hercules/core/tools/"
    click AdditionalTools "https://github.com/test-zeus-ai/testzeus-hercules/tree/main/additional_tools"
    click LLM "https://github.com/test-zeus-ai/testzeus-hercules/blob/main/agents_llm_config-example.json"
    click Playwright "https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/playwright_manager.py"
    click Logger "https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/browser_logger.py"
    click Reporter "https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/junit_helper.py"

    %% Styles
    classDef interface fill:#FFEEAA,stroke:#333,stroke-width:2px;
    classDef input fill:#A1D6E2,stroke:#333,stroke-width:2px;
    classDef engine fill:#F4CCCC,stroke:#333,stroke-width:2px;
    classDef agent fill:#FCE5CD,stroke:#333,stroke-width:2px;
    classDef memory fill:#D9EAD3,stroke:#333,stroke-width:2px;
    classDef tools fill:#D9D2E9,stroke:#333,stroke-width:2px;
    classDef external fill:#C9DAF8,stroke:#333,stroke-width:2px;
    classDef reporting fill:#FFF2CC,stroke:#333,stroke-width:2px;
```
