testzeus-hercules

<img width="100" height="100" alt="2" src="https://github.com/user-attachments/assets/9e8c73cf-d0f9-4dc2-b5e6-98f2ce45a601" />

# 💪 Hercules

[![PyPI Total Downloads](https://static.pepy.tech/badge/testzeus-hercules)](https://pepy.tech/projects/testzeus-hercules)
![Docker Pulls](https://img.shields.io/docker/pulls/testzeus/hercules)
[![CI Test](https://github.com/test-zeus-ai/testzeus-hercules/actions/workflows/main-test.yml/badge.svg)](https://github.com/test-zeus-ai/testzeus-hercules/actions/workflows/main-test.yml)
[![Slack](https://img.shields.io/badge/slack-TestZeus-brightgreen.svg?logo=slack)](https://join.slack.com/t/testzeuscommunityhq/shared_invite/zt-376oeo99x-3RAWe_C0H7x9zP0rtACcPA)

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 platforms like Salesforce 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](statics/LeadcreationDemo.gif)



As you saw, using Hercules is as simple as feeding in your Gherkin features, and getting the results:
![HerculesUsage](statics/assets/hercules.svg)

At [TestZeus](www.testzeus.com), 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](https://www.youtube.com/@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](statics/assets/introvideothumbnail2.png)](https://youtu.be/_m_NDjM6aZ0?si=ArtVKz8uSgGWTcAK)

- **Installation and Setup Guide**  
  Step-by-step instructions for installing and configuring TestZeus Hercules in your environment.  
  _[Watch now](https://youtu.be/9D-SZGoDrfc?si=GL0IArWkB1ZgBdx5)_

---

#### 🧪 **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](https://www.youtube.com/watch?v=yJD0cZ7Bx6Q&t)_

---

#### 🌐 **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](https://youtu.be/vI9iGSqKpGA?si=6NGAvKnwFboSyHT2)_
---

#### 🛠️ **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](https://youtu.be/C8hUy5leRF0?si=yVMpZ7WFcI01BoI3)_
---

#### 🛠️ **API Testing**
- **API testing all the way, new ways to do end to end**  
  _[Watch now](https://youtu.be/qMt89DQH6LQ?si=lcSJbKOCaqqUGeQ8)_
---

#### 🛠️ **Security Testing**
- **Security Testing done end to end**  
  _[Watch now](https://youtu.be/o6MmfTakIh4?si=JL8iu4e3i85SWrxU)_

#### 🛠️ **Visual validations and assertions**
- **Using vision capabilities to check snapshots and components on the application**  
  _[Watch now](https://youtu.be/EKzllLEguhw)_

#### 🐍 **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](docs/python_sandbox_execution.md)

**Quick Example:**
```gherkin
# In your feature file
And execute the apply_filter function from script at "scripts/apply_filter.py" with filter_type as "Turtle Neck"
```

```python
# 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:**
```bash
# Set tenant for module access
export SANDBOX_TENANT_ID="executor_agent"  # Full access: requests, pandas, numpy, BeautifulSoup

# Or use CLI
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](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1YiZsXem1POTwkcr17QqflXnihhuSqwM2?usp=sharing)
- **Note**: Colab might ask you to restart the session as python3.11 and some libs are installed during the installation of testzeus-hercules. 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:

```bash
pip install testzeus-hercules
```

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

```bash
playwright install --with-deps
```

For detailed information about project structure and running tests, please refer to our [Run Guide](docs/run_guide.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/
│   ├── test.feature_result.html
│   └── test.feature_result.xml
├── proofs/
│   └── User_opens_Google_homepage/
│       ├── network_logs.json
│       ├── screenshots/
│       └── videos/
└── test_data/
    └── test_data.txt
```

- `--llm-model LLM_MODEL`: Name 

[truncated…]