[opensourcedex]

Hercules is a free, open source testing & quality assurance project written in Python and released under AGPL-3.0. It has 1,158 GitHub stars, 189 forks and 39 open issues, and was last pushed 1 months ago. On this registry it ranks #1 of 2 tracked projects in Testing & Quality Assurance, with 5 head-to-head comparisons available. It gained 6 stars over the last 6 tracked days.

What is Hercules?

Hercules is an open-source, AGPL-3.0 testing agent that turns plain Gherkin feature files into automated end-to-end UI, API, security, accessibility and visual tests for QA engineers, developers and platform teams who need browser-level coverage without writing or maintaining test code.

What it is

Hercules is a Python testing agent distributed through PyPI as testzeus-hercules and through Docker as testzeus/hercules. It lives in the Python and Playwright ecosystem, and it drives real browsers as an agent built around a large action model rather than a fixed script. Test authors write Gherkin steps in natural language; Hercules reads those features, plans the interaction, executes it against the application under test, and returns results. The project is maintained by TestZeus, published under AGPL-3.0, and supported by a community Slack, video tutorials, and a docs/ directory of extended material.

The concrete problem it solves is test maintenance. Conventional suites pin selectors, page objects and assertions into code that breaks every time the interface shifts, so a team spends its time repairing tests instead of testing. Hercules replaces that hand-written script layer with Gherkin intent: the same feature file survives markup and layout changes because the agent resolves the steps at run time. That shifts the work from "write and patch automation code" to "describe the behaviour once," which matters most on large enterprise platforms where the interface changes frequently and the automation backlog never clears.

Key capabilities

  • Gherkin-driven end-to-end execution: feature files written in simple, easy-to-write steps run without coding skills.
  • UI testing through Playwright browser automation, listed in the topics as playwright and end-to-end-testing.
  • API testing end to end, covered as its own workflow distinct from browser interaction.
  • Security testing run end to end as part of the same agent.
  • Accessibility validations, one of the five validation types named in the project description.
  • Visual validations and assertions using vision capabilities to check snapshots and components on the application.
  • Python sandbox execution, letting Gherkin tests run custom Python scripts with full Playwright access for advanced selector strategies, conditional logic and data processing; documented in docs/python_sandbox_execution.md.
  • Dynamic test data and multilingual content testing, both shown in the project's tutorial set.

Who uses it and how

  • Teams testing tricky enterprise platforms where frequent interface changes make code-based suites expensive to keep green.
  • QA groups that already write BDD scenarios and want end-to-end-testing coverage from feature files rather than a new framework.
  • Engineering teams running the agent inside a CI/CD pipeline, using testzeus/hercules as the container image for pipeline stages.
  • Organisations testing multilingual applications, where a single testcase validates content across languages.
  • Contributors and integrators extending the agent with community-driven tools to add custom capabilities.

Getting started

Install the Python package with pip install testzeus-hercules, or pull the testzeus/hercules Docker image. The project homepage is at https://testzeus.com/hercules, with installation covered in the TestZeus video guides.

How it compares

The registry provides no list of paid products this project replaces, so the comparison rests on the tools named in its own topic list. Hercules sits above playwright, which supplies the browser control layer, and alongside autogen-style agentic frameworks, adding a testing-specific agent that consumes Gherkin instead of requiring orchestration code. Teams already invested in Playwright keep that foundation and gain an agent layer on top of it.

When to use it — and when not to

Choose Hercules if the goal is intent-level test authoring and the cost of maintaining selector-based suites is the real bottleneck. A self-hoster operates the Python or Docker runtime, browser automation, and model access for the large action model that drives planning and execution. Reconsider if you need fully deterministic, model-free test execution, or if AGPL-3.0 copyleft is incompatible with embedding the agent in a closed-source product or offering it as a hosted service, since that licence obliges source disclosure.

project readme (upstream, from github) — read inline
2

💪 Hercules

PyPI Total Downloads Docker Pulls CI Test Slack

Testing modern web applications can be difficult, with frequent changes and complex features making it hard to keep up. That's where Hercules comes in. Hercules is the world's first open-source testing agent, built to handle the toughest testing tasks so you don't have to. It turns simple, easy-to-write Gherkin steps into fully automated end to end tests—no coding skills needed. Whether you're working with tricky enterprise platforms or running tests in your CI/CD pipeline, Hercules adapts to your needs and takes care of the details. With Hercules, testing becomes simple, reliable, and efficient, helping teams everywhere deliver better software. Here's a quick demo of lead creation using natural english language test (without any code):

HerculesUsage

As you saw, using Hercules is as simple as feeding in your Gherkin features, and getting the results: HerculesUsage

At TestZeus, we believe that trustworthy and open-source code is the backbone of innovation. That's why we've built Hercules to be transparent, reliable, and community-driven.

Our mission? To democratize and disrupt test automation, making top-tier testing accessible to everyone, not just the elite few. No more gatekeeping—everyone deserves a hero on their testing team!

Video Tutorials: @TestZeus

🚀 Getting Started with TestZeus Hercules

  • Introduction to TestZeus Hercules
    Learn about the core features of TestZeus Hercules and how it can streamline end-to-end testing for your projects. Autonomous execution with Hercules

  • Installation and Setup Guide
    Step-by-step instructions for installing and configuring TestZeus Hercules in your environment.
    Watch now

🧪 Writing and Executing Test Cases
  • Creating BDD Test Cases
    Learn how to write Behavior-Driven Development (BDD) test cases for Hercules and use dynamic testdata.
    Watch now
🌐 Integrations and Advanced Features
  • Testing Multilingual content
    Learn how Hercules interacts with web browsers to perform Testing on Multilingual content via Multilingual testcase.
    Watch now
🛠️ Customization and Community Tools
  • Enhancing Hercules with Community-Driven Tools
    Discover how to customize Hercules and incorporate additional tools provided by the community.
    Watch now
🛠️ API Testing
  • API testing all the way, new ways to do end to end
    Watch now
🛠️ Security Testing
🛠️ Visual validations and assertions
  • Using vision capabilities to check snapshots and components on the application
    Watch now
🐍 Python Sandbox Execution
  • Execute custom Python scripts directly from Gherkin tests
    Run complex automation workflows, custom business logic, and reusable components with full Playwright access. Perfect for scenarios that need advanced selector strategies, conditional logic, or data processing. Read the docs

Quick Example:

# In your feature file
And execute the apply_filter function from script at "scripts/apply_filter.py" with filter_type as "Turtle Neck"

# In opt/scripts/apply_filter.py
async def apply_filter(filter_type: str) -> dict:
    """Apply filter with multiple fallback strategies."""
    # page, logger, and other tools automatically available!
    await page.wait_for_selector('[data-filter-section]')
    
    # Try multiple selector strategies
    for selector in [f'input[value="{filter_type}"]', 
                     f'label:has-text("{filter_type}") input']:
        if await page.locator(selector).count() > 0:
            await page.locator(selector).click()
            break
    
    return {"status": "success", "filter": filter_type}

Features:

  • 🎯 Full Playwright API access
  • 🔒 Multi-tenant security (executor, data, API, restricted modes)
  • 📦 Auto-injected modules (page, browser, logger, asyncio, etc.)
  • 🔄 Reusable across multiple tests
  • ⚙️ Configurable via environment variables

Configuration:

# Set tenant for module access
export SANDBOX_TENANT_ID="executor_agent"  # Full access: requests, pandas, numpy, BeautifulSoup

# Or use CLI
testzeus-hercules --sandbox-tenant-id executor_agent --input-file test.feature

⚙️ Installation and Usage

Hercules offers multiple ways to get started, catering to different user preferences and requirements. If you are new to the Python ecosystem and don't know where to begin, dont worry and read the footnotes on understanding the basics.

For a quick taste of the solution, you can try the notebook here: Open In Colab

  • Note: Colab might ask you to restart the session after installing TestZeus Hercules dependencies. Please restart the session if required and continue the execution. Also, we recommend one of the approaches below for getting the full flavor of the solution.

Approach 1: Using PyPI Package

Installation

Install Hercules from PyPI:

pip install testzeus-hercules

Hercules uses Playwright to interact with web pages, so you need to install Playwright and its dependencies:

playwright install --with-deps

For detailed information about project structure and running tests, please refer to our Run Guide. For migration-specific runtime behavior, see docs/Migration/MIGRATION.md and docs/Migration/ARCHITECTURE.md.

Basic Parameters

Once installed, you will need to provide some basic parameters to run Hercules:

  • --input-file INPUT_FILE: Path to the input Gherkin feature file to be tested.
  • --output-path OUTPUT_PATH: Path to the output directory. The path of JUnit XML result and HTML report for the test run.
  • --test-data-path TEST_DATA_PATH: Path to the test data directory. The path where Hercules expects test data to be present; all test data used in feature testing should be present here.
  • --project-base PROJECT_BASE: Path to the project base directory. This is an optional parameter; if you populate this, --input-file, --output-path, and --test-data-path are not required, and Hercules will assume all the three folders exist in the following format inside the project base:
PROJECT_BASE/
├── gherkin_files/
├── input/
│   └── test.feature
├── log_files/
├── output/
│   └── run_<timestamp>/
│       ├── test.feature_result.html
│       └── test.feature_result.xml
├── proofs/
│   └── User_opens_Google_homepage/
│       └── run_<timestamp>/
│           ├── network_logs.json
│           ├── screenshots/
│           └── videos/
└── test_data/
    └── test_data.txt
  • --agents-llm-config-file AGENTS_LLM_CONFIG_FILE: Optional path to an agents_llm_config.json file for per-agent model routing.
  • --agents-llm-config-file-ref-key AGENTS_LLM_CONFIG_FILE_REF_KEY: Optional top-level provider/profile key inside that file.
  • --llm-model, --llm-model-api-key, --llm-model-base-url, and related direct LLM flags are still supported for simple single-profile setups. Use agents_llm_config.json when you need separate planner, navigation, memory, and helper model settings.
Environment Variables

In addition to command-line parameters, Hercules supports various environment variables for configuration:

  • LLM_MODEL_NAME: Model name for direct single-model setup. Example: gpt-4o
  • LLM_MODEL_API_KEY: API key for the selected model provider.
  • `L

readme truncated — read the full docs on github

Frequently asked questions

Is Hercules free to use?

Hercules is open source under the AGPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does Hercules do?

Open-source testing agent for UI, API, security, accessibility & visual QA

What is Hercules written in?

Hercules is primarily written in Python. Its source is publicly available at https://github.com/test-zeus-ai/testzeus-hercules, and it has 1,158 GitHub stars.