test-zeus-ai/testzeus-hercules

What is it?

Key features

• 01Runs Gherkin feature files as automated browser end-to-end tests without writing code.
• 02Covers UI, API, security (Nuclei), accessibility (WCAG 2.0 to 2.2) and visual validations.
• 03Produces JUnit XML and HTML reports, with video, screenshots and network logs as proofs.
• 04Routes planner, navigation and helper roles to different LLMs via configuration.
• 05Connects to remote browsers over CDP, including BrowserBase, BrowserStack and LambdaTest.
• 06Supports mobile device emulation using Playwright device descriptors.

Use cases

• Automating regression tests for complex web applications from plain-English scenarios.
• Running browser tests inside CI/CD pipelines using the Docker image.
• Adding security and accessibility checks to existing end-to-end test suites.
• Letting QA staff who do not code write and maintain automated UI tests.

Quick start

1. 1

   Install Hercules from PyPI

   pip install testzeus-hercules
2. 2

   Install Playwright and its browser dependencies

   playwright install --with-deps
3. 3

   Set the LLM_MODEL_NAME, LLM_MODEL_API_KEY and LLM_MODEL_BASE_URL environment variables for your model provider

4. 4

   Run Hercules on a Gherkin feature file

   testzeus-hercules --input-file opt/input/test.feature --output-path opt/output --test-data-path opt/test_data

Things to know

• !Licensed under AGPL-3.0, a strong copyleft license that may restrict how you can use it in proprietary products.
• !Running tests requires an LLM provider API key or a self-hosted model.

Topics

FAQ

What is testzeus-hercules?

Open-source AI testing agent that turns Gherkin feature files into automated end-to-end browser, API, security, accessibility and visual tests. Hercules is an open-source testing agent that runs end-to-end tests written in Gherkin, the plain-English Given/When/Then format. Users describe a scenario in a feature file, and Hercules uses an LLM-driven planner and browser navigation helpers built on Playwright to carry out the steps, then reports results as JUnit XML and HTML, with video, screenshots and network logs saved as proofs.

Is testzeus-hercules free to use? What license does it have?

testzeus-hercules is open source under the AGPL-3.0 license. Check the license terms before using it in commercial products.

Is testzeus-hercules still maintained?

Actively maintained. The last commit to testzeus-hercules was on Oct 14, 2026.

What can I use testzeus-hercules for?

Automating regression tests for complex web applications from plain-English scenarios. Running browser tests inside CI/CD pipelines using the Docker image. Adding security and accessibility checks to existing end-to-end test suites. Letting QA staff who do not code write and maintain automated UI tests.

How do I install testzeus-hercules?

Install Hercules from PyPI: pip install testzeus-hercules Install Playwright and its browser dependencies: playwright install --with-deps Set the LLM_MODEL_NAME, LLM_MODEL_API_KEY and LLM_MODEL_BASE_URL environment variables for your model provider Run Hercules on a Gherkin feature file: testzeus-hercules --input-file opt/input/test.feature --output-path opt/output --test-data-path opt/test_data

Where can I get testzeus-hercules?

The source code and installation instructions are on GitHub: https://github.com/test-zeus-ai/testzeus-hercules