💪 Hercules

测试现代 Web 应用程序可能非常困难，频繁的变更和复杂的功能让人难以跟上节奏。这就是 Hercules 的用武之地。Hercules 是全球首个开源测试智能体（testing agent），专为应对最棘手的测试任务而构建，让你无需亲自动手。它能将简单易写的 Gherkin 步骤自动转换为完整的 端到端（end to end） 测试——无需任何编码技能。无论你是在处理像 Salesforce 这样复杂的平台，还是在 CI/CD 流水线中运行测试，Hercules 都能灵活适配你的需求并处理所有细节。借助 Hercules，测试变得简单、可靠且高效，帮助全球团队交付更优质的软件。以下是一个使用自然语言编写的测试用例（无需代码）创建潜在客户（lead）的快速演示：

如你所见，使用 Hercules 就像输入你的 Gherkin 特性文件并获取结果一样简单：

在 TestZeus，我们坚信 可信赖且开源的代码 是创新的基石。因此，我们打造了 Hercules，使其具备透明性、可靠性，并由社区驱动。

我们的使命？让测试自动化民主化并颠覆传统，使顶级测试能力不再仅为少数精英所享有，而是人人皆可使用。不再有技术壁垒——每个测试团队都值得拥有一位英雄！

视频教程：@TestZeus

---

🚀 TestZeus Hercules 快速入门

• TestZeus Hercules 简介
  了解 TestZeus Hercules 的核心功能，以及它如何为你的项目简化端到端测试。
  

• 安装与设置指南
  分步指导如何在你的环境中安装和配置 TestZeus Hercules。
  立即观看

---

🧪 编写与执行测试用例

• 创建 BDD 测试用例
  学习如何为 Hercules 编写行为驱动开发（Behavior-Driven Development, BDD）测试用例，并使用动态测试数据。
  立即观看

---

🌐 集成与高级功能

• 多语言内容测试
  了解 Hercules 如何通过多语言测试用例与 Web 浏览器交互，执行多语言内容的测试。
  立即观看

---

🛠️ 自定义与社区工具

• 使用社区驱动的工具增强 Hercules
  探索如何自定义 Hercules 并集成社区提供的额外工具。
  立即观看

---

🛠️ API 测试

• 全方位 API 测试，端到端的新方式
  立即观看

---

🛠️ 安全测试

• 端到端的安全测试
  立即观看

🛠️ 视觉验证与断言

• 利用视觉能力检查应用中的快照和组件
  立即观看

🐍 Python 沙箱执行（Python Sandbox Execution）

• 直接从 Gherkin 测试中执行自定义 Python 脚本
  运行复杂的自动化工作流、自定义业务逻辑和可复用组件，并拥有完整的 Playwright 访问权限。非常适合需要高级选择器策略、条件逻辑或数据处理的场景。阅读文档

快速示例：

# 在你的 feature 文件中
And execute the apply_filter function from script at "scripts/apply_filter.py" with filter_type as "Turtle Neck"

# 在 opt/scripts/apply_filter.py 中
async def apply_filter(filter_type: str) -> dict:
    """Apply filter with multiple fallback strategies."""
    # page, logger 和其他工具自动可用！
    await page.wait_for_selector('[data-filter-section]')
    
    # 尝试多种选择器策略
    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}

特性：

• 🎯 完整的 Playwright API 访问权限
• 🔒 多租户安全机制（执行器、数据、API、受限模式）
• 📦 自动注入模块（page、browser、logger、asyncio 等）
• 🔄 可在多个测试中复用
• ⚙️ 可通过环境变量配置

配置方式：

# 设置租户以控制模块访问权限
export SANDBOX_TENANT_ID="executor_agent"  # 完全访问权限：requests、pandas、numpy、BeautifulSoup

# 或通过 CLI 使用
hercules --sandbox-tenant-id executor_agent --input-file test.feature

---

⚙️ 安装与使用

Hercules 提供多种入门方式，以满足不同用户的偏好和需求。
如果你刚接触 Python 生态系统，不知道从何开始，别担心，请阅读文末关于基础知识的说明。

若想快速体验该解决方案，你可以尝试以下 Notebook：

• 注意：Colab 可能会提示你重启会话，因为在安装 testzeus-hercules 时会安装 python3.11 和部分依赖库。如有需要，请重启会话后继续执行。此外，我们建议采用以下方法之一，以获得完整的解决方案体验。

方法一：使用 PyPI 包

安装

从 PyPI 安装 Hercules：

pip install testzeus-hercules

Hercules 使用 Playwright（一个用于与网页交互的自动化工具）来操作网页，因此你需要安装 Playwright 及其依赖项：

playwright install --with-deps

有关项目结构和运行测试的详细信息，请参阅我们的 运行指南。

基本参数

安装完成后，你需要提供一些基本参数来运行 Hercules：

• --input-file INPUT_FILE：待测试的 Gherkin feature 文件路径。
• --output-path OUTPUT_PATH：输出目录路径。测试运行生成的 JUnit XML 结果和 HTML 报告将保存在此路径下。
• --test-data-path TEST_DATA_PATH：测试数据目录路径。Hercules 期望测试数据位于此路径下；所有在 feature 测试中使用的测试数据都应存放于此。
• --project-base PROJECT_BASE：项目根目录路径。这是一个可选参数；如果提供了该参数，则无需再指定 --input-file、--output-path 和 --test-data-path，Hercules 会假定这三个文件夹以如下格式存在于项目根目录中：

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：Agent 使用的 LLM（大语言模型，Large Language Model）名称（推荐使用 gpt-4o，但也支持其他模型）。
• --llm-model-api-key LLM_MODEL_API_KEY：LLM 模型的 API 密钥，例如 sk-proj-k.......。

环境变量

除了命令行参数外，Hercules 还支持通过多种环境变量进行配置：

• BROWSER_TYPE：使用的浏览器类型（chromium、firefox、webkit）。默认值：chromium
• HEADLESS：是否以无头模式（headless mode）运行浏览器（true、false）。默认值：true
• BROWSER_RESOLUTION：浏览器窗口分辨率（格式：宽度,高度）。示例：1920,1080
• BROWSER_COOKIES：为浏览器上下文设置 Cookie。格式：Cookie 对象的 JSON 数组。示例：[{"name": "session", "value": "123456", "domain": "example.com", "path": "/"}]
• RECORD_VIDEO：是否录制测试执行视频（true、false）。默认值：true
• TAKE_SCREENSHOTS：测试过程中是否截取屏幕截图（true、false）。默认值：true

完整的环境变量列表请参见我们的 环境变量指南。

运行 Hercules

在传入所有必需参数后，运行 Hercules 的命令应如下所示：

testzeus-hercules --input-file opt/input/test.feature --output-path opt/output --test-data-path opt/test_data --llm-model gpt-4o --llm-model-api-key sk-proj-k.......

⚙️ 在 Windows 机器上运行 Hercules

要在 Windows 机器上设置并运行 Hercules，请按以下步骤操作：

1. 以管理员模式打开 PowerShell：

   • 点击开始菜单，搜索 PowerShell，然后右键点击 Windows PowerShell。
   • 选择 以管理员身份运行，以管理员模式打开 PowerShell。

2. 导航到辅助脚本文件夹：

   • 使用 cd 命令进入包含 hercules_windows_setup.ps1 脚本的文件夹。例如：

     cd path\to\helper_scripts
     

3. 运行设置脚本：

   • 执行脚本来安装和配置 Hercules：

     .\hercules_windows_setup.ps1
     

4. 按照屏幕提示操作：

   • 脚本将引导您安装 Python、Playwright、FFmpeg 以及其他必需的依赖项。

5. 运行 Hercules：

   • 设置完成后，您可以使用以下命令在 PowerShell 或命令提示符中运行 Hercules：

     testzeus-hercules --input-file opt/input/test.feature --output-path opt/output --test-data-path opt/test_data --llm-model gpt-4o --llm-model-api-key sk-proj-k.......
     

---

TestZeus-Hercules 支持的 AI 模型（AI Models）

• Anthropic：兼容 Haiku 3.5 及以上版本。
• Groq：支持任何具备函数调用（function calling）和代码生成能力的版本。
• Mistral：支持任何具备函数调用和代码生成能力的版本，如 Mistral-large、Mistral-medium。仅限重型模型（heavy models）。
• OpenAI：完全兼容 GPT-4o/o3-mini 及以上版本。注意：OpenAI GPT-4o-mini 仅支持用于子代理（sub-agents），对于规划器（planner）仍建议使用 GPT-4o。
• Ollama：支持具备函数调用能力的中型模型；重型模型仅支持 70b 及以上版本。
• Gemini：可以使用，推荐通过 LiteLLM（如下所示）方式接入。
• Deepseek：仅支持 deepseek-chat v3。
• 托管平台（Hosting）：支持 AWS Bedrock、GCP VertexAI、AzureAI。[已测试模型包括 OpenAI、Anthropic Sonnet 和 Haiku、具备函数调用能力的 Llama 60b 以上模型]

注意：请确保您使用的模型能够处理代理类任务（agentic activities），例如函数调用。例如较大的模型如 OpenAI GPT-4o、Llama >70B、Mistral large 等。您可以使用如下 agent_config 文件填写 LiteLLM 的详细信息 [https://docs.litellm.ai/docs/simple_proxy]：

{
  "litellm-flash": {
    "planner_agent": {
      "model_name": "gemini-2.5-flash",
      "model_api_key": "sfasdfsadgbw",
      "model_base_url": "https://litellm-proxydeployment",
      "llm_config_params": {
        "cache_seed": 1234,
        "temperature": 0,
        "seed": 12345
      }
    },
    "nav_agent":  {
      "model_name": "gemini-2.5-flash",
      "model_api_key": "sfasdfsadgbw",
      "model_base_url": "https://litellm-proxydeployment",
      "llm_config_params": {
        "cache_seed": 1234,
        "temperature": 0,
        "seed": 12345
      }
    },
    "mem_agent":  {
      "model_name": "gemini-2.5-flash",
      "model_api_key": "sfasdfsadgbw",
      "model_base_url": "https://litellm-proxydeployment",
      "llm_config_params": {
        "cache_seed": 1234,
        "temperature": 0,
        "seed": 12345
      }
    },
    "helper_agent":  {
      "model_name": "gemini-2.5-flash",
      "model_api_key": "sfasdfsadgbw",
      "model_base_url": "https://litellm-proxydeployment",
      "llm_config_params": {
        "cache_seed": 1234,
        "temperature": 0,
        "seed": 12345
      }
    }
  }
}

执行流程（Execution Flow）

运行命令后：

• Hercules 将启动并尝试打开一个网页浏览器（默认为 Chromium）。
• 它将根据提供的 feature 文件中的步骤制定执行计划。
• 该计划会将 feature 文件中简略的步骤扩展为更详细的版本。
• Hercules 会检测 feature 文件中的断言（assertions），并在测试运行期间规划对预期结果的验证。
• 所有扩展后的步骤将根据其执行需求类型传递给不同的工具。例如，如果某一步骤需要点击按钮并捕获反馈，则会传递给 click_using_selector 工具。

输出与日志（Output and Logs）

执行完成后：

• 会生成描述事件顺序的日志。
• 最佳查看位置是 output-path 目录，其中包含 JUnit XML 结果文件以及关于测试用例执行情况的 HTML 报告。
• 您还可以在 proofs 文件夹中找到执行证据，例如视频录制、每个事件的截图和网络日志。
• 若要深入了解代理的思考链（chain of thoughts），请参考 log_files 中的 chat_messages.json 文件，其中包含代理实际规划的详细步骤。

示例 Feature 文件（Sample Feature File）

以下是一个示例 feature 文件：

Feature: 在 Salesforce 中创建账户

 Scenario: 成功创建新账户

   Given 我位于 Salesforce 登录页面
   When 我输入用户名 "user@example.com" 和密码 "securePassword"
   And 我点击 "Log In" 按钮
   And 我导航至 "Accounts" 标签页
   And 我点击 "New" 按钮
   And 我在 "Account Name" 字段中填入 "Test Account"
   And 我将 "Account Type" 选择为 "Customer"
   And 我在 "Website" 字段中填入 "www.testaccount.com"
   And 我在 "Phone" 字段中填入 "123-456-7890"
   And 我点击 "Save" 按钮
   Then 我应看到确认消息 "Account Test Account created successfully"
   And 我应在账户记录中看到 "Test Account"

示例结果截图（Sample Result Screenshot）

HTML 结果示例截图

XML 结果示例截图

---

方法 2：使用 Docker

对于所有追求可扩展性的用户，Hercules 也提供了 Docker 镜像。

拉取 Docker 镜像

docker pull testzeus/hercules:latest

在 Docker 中运行 Hercules

使用以下命令运行容器：

docker run --env-file=.env \
  -v ./agents_llm_config.json:/testzeus-hercules/agents_llm_config.json \
  -v ./opt:/testzeus-hercules/opt \
  --rm -it testzeus/hercules:latest

• 环境变量（Environment Variables）：所有必需的环境变量都可以通过在 docker run 命令中传入 .env 文件来设置。
• LLM 配置（LLM Configuration）：如果你希望完全控制 Hercules 所使用的 LLM（大语言模型，Large Language Model），而不仅限于 OpenAI 提供的选项，可以将 agents_llm_config.json 文件挂载到容器中。这适用于高级用例，初学者无需配置。详情请参考示例文件 .env-example 和 agents_llm_config-example.json。
• 目录挂载（Mounting Directories）：将 opt 文件夹挂载到 Docker 容器中，以便将所有输入传递给容器内运行的 Hercules，并将输出提取出来进行后续处理。代码仓库中已包含一个可直接挂载的示例 opt 文件夹。
• 简化参数（Simplified Parameters）：在 Docker 模式下，无需使用 --input-file、--output-path、--test-data-path 或 --project-base 参数，因为这些功能已通过在 docker run 命令中挂载 opt 文件夹自动处理。

Docker 中的浏览器访问

• 在 Docker 模式下运行时，请注意 Hercules 只能访问无头（headless）网页浏览器。
• 如果你希望 Hercules 连接到可见的网页浏览器，可以在环境文件中尝试使用 CDP URL（Chrome DevTools Protocol URL）选项。该选项可帮助你将运行在本地基础设施中的 Hercules 连接到远程浏览器（如 BrowserBase）或自托管的浏览器网格（browser grid）。
• 使用 CDP_ENDPOINT_URL 来设置需要连接到代理（agent）的 Chrome 实例的 CDP URL。

Docker 与远程浏览器支持

在 Docker 中运行 Hercules 时，你可以通过多种平台连接到远程浏览器实例：

1. BrowserStack 集成：

export BROWSERSTACK_USERNAME=your_username
export BROWSERSTACK_ACCESS_KEY=your_access_key
export CDP_ENDPOINT_URL=$(python helper_scripts/browser_stack_generate_cdp_url.py)

2. LambdaTest 集成：

export LAMBDATEST_USERNAME=your_username
export LAMBDATEST_ACCESS_KEY=your_access_key
export CDP_ENDPOINT_URL=$(python helper_scripts/lambda_test_generate_cdp_url.py)

3. BrowserBase 集成：

export CDP_ENDPOINT_URL=wss://connect.browserbase.com?apiKey=your_api_key

4. AnchorBrowser 集成：

export CDP_ENDPOINT_URL=wss://connect.anchorbrowser.io?apiKey=your_api_key

注意：视频录制仅在使用 connect_over_cdp 的平台（BrowserBase、AnchorBrowser）上支持。使用 connect API 的平台（BrowserStack、LambdaTest）不支持视频录制。

输出与日志

命令执行完成后：

• 容器会终止，输出内容将写入挂载的 opt 文件夹中，其结构与前述目录结构一致。
• 你可以在相应子文件夹中找到 JUnit XML 结果文件、HTML 报告、执行证明（proofs of execution）以及日志。

---

方法 3：从源代码构建并运行

对于硬核爱好者，你可以通过源代码使用 Hercules，以获得完整的自定义体验，并扩展 Hercules 以集成更多工具。

先决条件

• 确保你的系统已安装 Python 3.11。

从源代码运行的步骤

1. 克隆仓库

   git clone git@github.com:test-zeus-ai/testzeus-hercules.git
   

2. 进入目录

   cd testzeus-hercules
   

3. 使用 Make 命令

   本仓库提供了便捷的 make 命令。

   • 使用 make help 查看可用选项。

4. 安装 UV

   make setup-uv
   

5. 安装依赖

   make install
   

6. 运行 Hercules

   make run
   

   • 此命令会从 opt 文件夹中读取相关的 feature 文件并执行，将输出结果保存在同一文件夹中。

   • opt 文件夹的结构如下：

     opt/
     ├── input/
     │   └── test.feature
     ├── output/
     │   ├── test.feature_result.html
     │   └── test.feature_result.xml
     ├── log_files/
     ├── proofs/
     │   └── User_opens_Google_homepage/
     │       ├── network_logs.json
     │       ├── screenshots/
     │       └── videos/
     └── test_data/
         └── test_data.txt
     

7. 交互模式

   你也可以以交互模式运行 Hercules，将其作为指令执行代理（instruction execution agent）。这种方式在开发新工具、扩展代理功能，或在新环境中调试测试用例和 Hercules 行为时尤为有用。

   make run-interactive
   

   • 这将触发一个输入提示符，你可以与 Hercules 对话，它将根据你的指令执行相应操作。

方法 4：通过 helper_script_custom.sh 进行设置

对于希望在 Linux/macOS 环境中获得全自动设置体验的用户，我们提供了一个 helper_script.sh 脚本。该脚本会（如需要）安装 Python 3.11，创建虚拟环境，安装 TestZeus Hercules，并在 opt 文件夹中设置基础项目目录。

先决条件

• 确保系统中已安装 Python 3.11。

通过 helper_script_custom.sh 运行的步骤

1. 下载或创建脚本 您可以将以下脚本复制到名为 helper_script_custom.sh 的文件中：

#!/bin/bash
# set -ex

# curl -sS https://bootstrap.pypa.io/get-pip.py | python3.11

# 创建名为 'test' 的新 Python 虚拟环境
python3.11 -m venv test

# 激活虚拟环境
source test/bin/activate

# 升级 'testzeus-hercules' 包
pip install --upgrade testzeus-hercules
playwright install --with-deps

# 创建名为 'opt' 的新目录
mkdir -p opt/input opt/output opt/test_data

# 下载 https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/refs/heads/main/agents_llm_config-example.json
curl -sS https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/main/agents_llm_config-example.json > agents_llm_config-example.json
mv agents_llm_config-example.json agents_llm_config.json

# 提示用户需要编辑 'agents_llm_config.json' 文件，暂停脚本并打开该文件进行编辑
echo "请编辑 'agents_llm_config.json' 文件以添加您的 API 密钥和其他配置。"

# 暂停脚本，并显示 agents_llm_config.json 文件的绝对路径，以便用户在编辑器中打开
echo "文件 'agents_llm_config.json' 位于 $(pwd)/agents_llm_config.json"
read -p "如果文件已更新，请按 Enter 键继续"

# 下载 https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/blob/main/.env-example
curl -sS https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/main/.env-example > .env-example
mv .env-example .env

# 提示用户需要编辑 .env 文件，暂停脚本并打开该文件进行编辑
echo "文件 '.env' 位于 $(pwd)/.env"
read -p "如果文件已更新，请按 Enter 键继续"

# 创建 input/test.feature 文件
# 下载 https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/refs/heads/main/opt/input/test.feature 并保存为 opt/input/test.feature
curl -sS https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/main/opt/input/test.feature > opt/input/test.feature

# 下载 https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/refs/heads/main/opt/test_data/test_data.json 并保存为 opt/test_data/test_data.json
curl -sS https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/main/opt/test_data/test_data.json > opt/test_data/test_data.json

# 使用指定参数运行 'testzeus-hercules' 命令
testzeus-hercules --project-base=opt

2. 赋予脚本执行权限并运行

chmod +x helper_script.sh
./helper_script.sh

• 该脚本将： • 创建一个名为 test 的 Python 3.11 虚拟环境。 • 安装 testzeus-hercules 和 Playwright（浏览器自动化工具）依赖项。 • 创建 opt 文件夹结构（用于输入/输出/测试数据）。 • 下载示例配置文件：agents_llm_config.json、.env 以及示例 feature/测试数据文件。 • 重要提示：您将被要求编辑 agents_llm_config.json 和 .env 文件。在您添加了 API 密钥及其他自定义配置后，请按 Enter 键继续。

3. 脚本输出
   • 完成后，脚本将自动运行 testzeus-hercules --project-base=opt。
   • 您的日志和结果将出现在 opt/output、opt/log_files 和 opt/proofs 目录中。

---

📝 配置详情

有关 TestZeus Hercules 中所有可用环境变量和配置选项的完整指南，请参阅我们的 环境变量与配置指南。该文档详细介绍了核心环境变量、LLM（大语言模型）配置、浏览器设置、测试配置、设备配置、日志选项等内容。

禁用遥测（Telemetry）

要禁用遥测功能，请将 TELEMETRY_ENABLED 环境变量设为 0：

export TELEMETRY_ENABLED=0

自动模式（Auto Mode）

如果将 AUTO_MODE 设为 1，Hercules 在运行期间将不会请求输入邮箱地址：

export AUTO_MODE=1

理解环境文件（.env）

要详细配置 Hercules：

• 复制基础环境文件：

  cp .env-example .env
  

🔌 MCP 支持

Hercules 内置了一个 MCP（Model Context Protocol）导航代理，可通过 stdio、sse 和 streamable-http 与 MCP 服务器连接。它可直接与 Composio 生成的 MCP 服务器配合使用。

• 快速入门指南：参见 docs/MCP_Usage.md
• Composio 文档：https://docs.composio.dev/docs/mcp-developers

最小化设置步骤：

1. 在仓库根目录创建 mcp_servers.json：

{
  "mcpServers": {
    "server_name": {
      "transport": "streamable-http",
      "url": "https://mcp.composio.dev/composio/server/<SERVER_UUID>/mcp?user_id=<USER_EMAIL>"
    }
  }
}

2. 在 .env 中配置：

MCP_ENABLED=true
MCP_SERVERS=mcp_servers.json
MCP_TIMEOUT=30

然后像往常一样运行 Hercules；MCP 代理将自动初始化，并暴露所配置服务器中的工具。

示例测试用例（简单版）

Feature: 从 Gmail 读取邮件

  Scenario: 使用 MCP 从 Gmail 获取 OTP
    Given Gmail 已通过 MCP 配置完成
    When 我连接到 Gmail
    And 我读取包含 OTP 的邮件

更多测试用例请参阅 MCP-Docs

---

• Hercules 支持以下两种配置方式：

  1. 使用单一 LLM（大语言模型，Large Language Model）处理所有任务

     • 对于代理（agent）内的所有活动，请初始化 LLM_MODEL_NAME 和 LLM_MODEL_API_KEY。
     • 如果使用的是非 OpenAI 托管但兼容 OpenAI 接口的 LLM（例如通过 Groq 提供的 OpenAI 模型），还需额外提供 LLM_MODEL_BASE_URL。

  2. 为不同任务配置自定义 LLM 或使用托管 LLM

     • 如果你计划配置本地 LLM 或非 OpenAI 的 LLM，请使用其他参数，如 AGENTS_LLM_CONFIG_FILE 和 AGENTS_LLM_CONFIG_FILE_REF_KEY。
     • 这些是高级选项，可能会影响 Hercules 输出的质量。

• Hercules 默认以 ./opt 作为基础目录，但可通过环境变量 PROJECT_SOURCE_ROOT 进行更改。

• 连接到现有 Chrome 实例

  • 当你在 Docker 中运行 Hercules 以实现规模化时，此功能非常有用。
  • 你可以将运行在你基础设施中的 Hercules 连接到远程浏览器（如 BrowserBase 或你自建的浏览器网格）。
  • 使用 CDP_ENDPOINT_URL 设置要连接的 Chrome 实例的 CDP（Chrome DevTools Protocol）URL。

• 控制其他行为

  你可以通过以下环境变量控制 Hercules 的其他行为：

  • HEADLESS=true
  • RECORD_VIDEO=false
  • TAKE_SCREENSHOTS=false
  • BROWSER_TYPE=chromium（可选值：firefox, chromium）
  • CAPTURE_NETWORK=false

例如：如果你想以“有头”（Headful）模式运行浏览器，可在启动 Hercules 前设置环境变量：export HEADLESS=false。

• 如何在 Playwright 中使用追踪（Tracing）

  Playwright 中的追踪功能可帮助你有效分析测试执行过程并调试问题。要启用 Playwright 测试中的追踪功能，请按以下步骤操作：

  1. 确保在配置中启用了追踪。
  2. 追踪文件将保存到指定路径：{proof_path}/traces/trace.zip。

  启用追踪

  要启用追踪，请设置以下环境变量：

  export ENABLE_PLAYWRIGHT_TRACING=true
  

理解 agents_llm_config-example.json

• 该文件用于定义你希望提供给代理的一组 LLM 配置。

• 示例：

  {
    "anthropic": {
        "planner_agent": {
            "model_name": "claude-3-5-haiku-latest",
            "model_api_key": "",
            "model_api_type": "anthropic",
            "llm_config_params": {
                "cache_seed": null,
                "temperature": 0.0,
                "seed":12345
            }
        },
        "nav_agent": {
            "model_name": "claude-3-5-haiku-latest",
            "model_api_key": "",
            "model_api_type": "anthropic",
            "llm_config_params": {
                "cache_seed": null,
                "temperature": 0.0,
                "seed":12345
            }
        }
    }
  }
  

• 外层键（如 "anthropic"）对应通过 AGENTS_LLM_CONFIG_FILE_REF_KEY 传入的配置标识名，而 Hercules 相关信息则包含在子字典 planner_agent 和 nav_agent 中。

• 注意：除非你明确知道自己在做什么，否则应忽略此选项。在 Slack 社区中尝试这些选项前，请先与我们沟通。欢迎加入我们的 Slack

---

⚡️ 功能特性

Hercules 已可用于生产环境，并具备强大功能：

Gherkin 输入，结果输出

Hercules 让测试变得像“Gherkin 输入，结果输出”一样简单。只需提供 Gherkin 格式的端到端测试用例，Hercules 就会自动执行测试，并以整洁的 JUnit 格式呈现结果。无需手动操作，无需繁琐步骤——只有高效、无缝的测试体验。

免费且开源

Hercules 完全免费开源，无任何许可费用。你可以自由查看源码、贡献代码，或按需定制。Hercules 不仅强大，而且完全开放，为你提供所需的灵活性和控制力。

Salesforce 就绪

专为应对最复杂的用户界面而设计，Hercules 能轻松驾驭 Salesforce 及其他复杂平台。无论是复杂的 DOM 结构，还是执行 SOQL 或 Apex 代码，Hercules 都已准备就绪且高度可配置。

无需编码

告别复杂的脚本和难以维护的定位器。Hercules 采用无代码（No Code）方法，自动处理 Gherkin 特性的自动化执行，让你专注于最重要的事情——构建高质量软件。

多语言支持

开箱即用的多语言支持，让 Hercules 能与全球团队无缝协作。它致力于弥合语言障碍，赋能多元化团队在统一的测试平台上高效合作。

精准可靠

Hercules 会录制执行过程的视频并捕获网络日志，彻底解决“在我电脑上能跑”的难题。

无需维护

Hercules 具备自主性和自愈能力，能够自动适应变化。你无需再进行繁琐的维护工作——Hercules 会持续聚焦于实现你的测试目标。

UI 断言

基于强大的 TestZeus 底层架构，Hercules 对 UI 断言保持高度专注，确保每个断言都被验证，每个缺陷都不被遗漏。它严谨、敏锐，随时准备行动。

CI/CD 就绪

你可以在本地运行 Hercules，也可以将其无缝集成到 CI/CD 流水线中。Hercules 原生支持 Docker，一条命令即可部署，轻松融入你的发布流程，让测试快速、一致且无忧。

有了 Hercules，测试不再只是开发流程中的一个步骤——而是一种强大、流畅的体验，将质量置于核心位置。

移动设备模拟（Mobile Device Emulation）

Hercules 支持以多种设备类型的“移动模式”运行浏览器。Playwright 在此处提供了大量设备描述符列表：
支持的移动设备列表

启用移动模式

在 .env 文件中（或直接作为环境变量）设置 RUN_DEVICE 环境变量：

RUN_DEVICE="iPhone 15 Pro Max"

当 Hercules 运行时，它将使用所选设备对应的视口（viewport）和用户代理（user-agent）启动浏览器，从而模拟真实的移动环境。
以下是一个快速演示：

集成高级工具

Hercules 可通过更强大的工具进行扩展，以应对高级场景。通过设置以下选项启用：

LOAD_EXTRA_TOOLS=true

启用 LOAD_EXTRA_TOOLS 后，Hercules 会查找额外的工具模块，以扩展其能力（例如地理位置处理）。

对于基于位置的测试，请配置如下（支持的地理服务提供商为 maps.co 和 Google）：

GEO_API_KEY=somekey
GEO_PROVIDER=maps_co

这使得 Hercules 能够在测试执行期间更改或模拟用户位置，从而扩大对依赖用户地理位置的场景的测试覆盖范围。

注意：如果您正在寻找原生应用（native app）测试自动化方案，我们也已提供初步支持，基于 Appium 的原生应用自动化功能已在此处实现。

---

🦾 架构

多智能体（Multi-Agentic）解决方案

Hercules 基于 AutoGen 框架采用多智能体架构。在 AutoGen 框架的基础上，Hercules 的架构充分利用了工具（tools）与智能体（agents）之间的协同作用。每个工具代表一个原子操作（atomic action），即一个基本构建单元，执行后会返回对其结果的自然语言描述。这种细粒度设计使 Hercules 能够灵活组合这些工具，以应对复杂的网页自动化工作流。

系统视图

上图展示了我们在 AutoGen 架构之上选择的配置。工具可以有不同的划分方式，但这是我们目前采用的方案。我们选择使用与人类学习浏览器操作方式相匹配的工具，而不是允许大语言模型（LLM）随意生成代码。我们认为使用预配置的工具更加安全且结果更具可预测性。当然，它仍可能点击错误的元素，但至少不会执行恶意或未知的代码。

智能体（Agents）

目前包含两个智能体：

1. 规划智能体（Planner Agent）：负责任务的规划与分解。
2. 浏览器导航智能体（Browser Navigation Agent）：封装了所有用于与网页浏览器交互的工具。

工具库（Tools Library）

Hercules 能力的核心是工具库——一个定义明确的操作集合，目前专注于网页操作。这些工具分为两大类：

• 感知工具（Sensing Tools）：如 get_dom_with_content_type 和 geturl，帮助 Hercules 理解当前网页或浏览器的状态。
• 动作工具（Action Tools）：允许 Hercules 与网页环境交互和操作，例如 click、enter_text 和 openurl。

每个工具的设计都力求尽可能具有对话性，使与 LLM 的交互更直观且容错性更强。例如，工具不会仅返回布尔值，而是用自然语言解释执行过程中发生了什么，使 LLM 能更好地理解上下文并在必要时调整策略。

已实现的工具

• 感知工具

  • geturl：获取并返回当前 URL。
  • get_dom_with_content_type：根据指定的内容类型，获取当前页面的 HTML DOM。
    • text_only：提取 HTML DOM 的纯文本内容，并以文本形式返回。
    • input_fields：提取 DOM 中的可交互元素（如 button、input、textarea 等），并返回紧凑的 JSON 对象。
    • all_fields：提取 DOM 中的所有字段，并返回紧凑的 JSON 对象。
  • get_user_input：为协调器（orchestrator）提供一种机制，用于接收用户反馈，以消除歧义或澄清用户请求。

• 动作工具

  • click：根据提供的 DOM 查询选择器进行点击。
  • enter_text：在由 DOM 查询选择器指定的字段中输入文本。
  • enter_text_and_click：优化方法，结合了 enter_text 和 click 工具。
  • bulk_enter_text：优化方法，封装 enter_text，支持一次性执行多个文本输入操作。
  • openurl：在当前或新标签页中打开指定 URL。

DOM 蒸馏（DOM Distillation）

Hercules 采用了一种系统化的方法来应对庞大的 HTML DOM 结构，这对提升效率至关重要。我们引入了 DOM 蒸馏 技术，将 DOM 精简为仅包含与用户任务相关的元素。

在实践中，这意味着将庞大的 DOM 转换为更易处理的 JSON 快照。这不仅仅是减少数据量，更是聚焦于相关性，只为 LLM 提供完成任务所必需的信息。目前我们支持三种内容类型：

1. 纯文本（Text Only）：适用于信息检索任务，仅保留文本内容，无干扰。
2. 输入字段（Input Fields）：聚焦于需要用户交互的元素，旨在简化操作流程。
3. 全部内容（All Content）：包含蒸馏后的完整 DOM 元素，适用于需要全面理解页面结构的任务。

这是一种精细的“外科手术”，在去除冗余信息的同时，保留智能体操作所需的结构和内容。当然，任何蒸馏过程都可能造成信息损失，但我们的目标是不断优化这一过程，以尽量减少甚至消除此类损失。

由于无法依赖所有网页开发者遵循最佳实践（例如为每个 HTML 元素添加唯一 ID），我们在每个 DOM 元素中注入了自定义属性（md）。这样就可以引导 LLM 在生成 DOM 查询时优先使用 md 属性。

为了进一步降低 DOM 噪声，我们使用 DOM 可访问性树（DOM Accessibility Tree） 而非标准 HTML DOM。可访问性树本质上是为屏幕阅读器设计的，这比普通 HTML DOM 更贴近网页自动化的使命。

DOM 蒸馏过程仍在持续改进中。我们计划进一步优化该流程，压缩 DOM 规模，以实现更快、更经济且更准确的交互。

非功能性能力（Non-Functional Capabilities）

通过 Nuclei 进行安全测试

Hercules 集成了 Nuclei，可直接从 Gherkin 测试用例中自动化执行漏洞扫描，识别诸如配置错误、OWASP Top 10 漏洞以及 API 缺陷等问题。安全报告会与测试输出一同生成，便于无缝集成到 CI/CD 流程中。

可访问性测试（Accessibility Testing）

Hercules 支持 WCAG 2.0、2.1 和 2.2 标准的 A、AA 和 AAA 级别，能够执行可访问性测试，确保符合全球标准。它能在早期发现可访问性问题，帮助构建更具包容性和用户友好的应用程序。

---

🔬 测试与评估：QEvals

我们希望确保 Hercules 能以极高的精度胜任端到端测试任务。因此，我们对 Hercules 进行了广泛的测试，包括调用 API、处理复杂的 UI 场景、点击日历或 iframe 等操作。完整的评估列表请参见 tests 文件夹。

运行测试

运行完整测试套件，请使用以下命令：

make test

运行特定测试：

make test-case

Hercules 基于 WebArena 和 Agent-E 的工作成果，并在此基础上进一步优化。为解决先前方案中的问题，我们编写了面向复杂 QA 场景的自有测试用例，并将这些测试存放在 ./tests 文件夹中。

---

💡 设计理念（Opinions）

我们认为，卓越的质量源于对产品的明确观点。因此，我们在产品设计中融入了一些自己的理念。我们欢迎社区质疑、使用或在其基础上继续构建。以下是一些示例：

1. Gherkin 是适用于智能体（Agents）的足够好的格式：Gherkin 为大语言模型（LLMs）/AI 智能体提供了一种半结构化的格式，便于理解测试意图和用户指令。它提供了恰到好处的语法（如 Given、When、Then 等动词），既方便人类描述场景，也便于智能体执行指令。

2. 测试应具备原子性（Atomic in Nature）：软件测试应当是原子的，因为这能确保每个测试都聚焦、独立且可靠。原子测试只针对某一特定行为或功能，使失败的根本原因更容易被精准定位，避免歧义。

   以下是一个良好的原子测试示例：

   Feature: 用户登录
   
   Scenario: 使用有效凭据成功登录
   
     Given 用户位于登录页面
     When 用户输入有效凭据
     And 用户点击登录按钮
     Then 用户应看到仪表盘
   

   非原子测试会让测试人员和 AI 智能体都感到困惑。

3. 开放核心（Open Core）与开源（Open Source）：Hercules 采用开放核心模式（open-core model），结合了开源精神与商业公司 TestZeus 的支持与专业能力。通过以 AGPL v3 许可证发布 Hercules 开源版本，TestZeus 致力于为测试社区提供一个强大、灵活、免费且可修改的工具。开源带来了透明度、信任和协作潜力，任何人都可以深入代码、贡献改进并影响项目发展方向。

4. 遥测（Telemetry）：所有优秀的产品都建立在良好的反馈基础上。我们设置了遥测功能，以便在不打扰用户的情况下收集反馈。遥测默认启用，但我们同样坚定地秉持“信任”与“透明”的价值观，用户可随时关闭该功能。

5. 为 Hercules 编写提示（Prompting Hercules）：关于如何为 Hercules 编写测试的详细指南，请参阅我们的博客文章：此处。

---

🦾 HyperMind

:jigsaw: 概述
Hercules 现在拥有了 HyperMind 的能力——这是一个安全的多租户 Python 沙箱，允许测试人员将自定义逻辑、AI 驱动的启发式规则以及人工编写的智能直接注入测试场景中。
当自动化遇到瓶颈时，Hypermind 将接管控制——在受控权限下执行拥有完整 Playwright 访问能力的脚本。

:gear: 核心能力

能力	描述
:brain: 从 Gherkin 运行自定义脚本	将 Python 函数作为测试步骤调用
:earth_africa: 完整 Playwright 访问权限	直接控制浏览器、页面和上下文
:jigsaw: 自动注入的工具集	预加载常用工具（如 logger、asyncio、json 等）
:lock: 多租户隔离	提供 Executor、Data、API 和 Restricted 四级安全隔离
:gear: 动态权限控制	通过 CLI 或环境变量控制模块访问权限
:camera_with_flash: 执行证明	自动生成执行前后的截图和 JSON 格式执行报告
:arrows_counterclockwise: 可复用逻辑	跨特性或团队共享脚本

:toolbox: 使用示例

Gherkin：

Feature: 商品筛选
  Scenario: 使用 Hypermind 脚本应用筛选条件
    Given 用户位于 URL https://example.com
    When 执行 hypermind 脚本 "scripts/apply_filter.py"，参数 filter_type 为 "Turtle Neck"
    Then 脚本应报告筛选应用成功

Python: opt/scripts/apply_filter.py

async def apply_filter(filter_type: str) -> dict:
    """使用后备策略应用筛选条件。"""
    await page.wait_for_selector('[data-filter-section]')
    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
    count = await page.locator('.product-item').count()
    return {"status": "success", "filter": filter_type, "products": count}

:checkered_flag: 愿景
“当自动化失效时，Hypermind 觉醒。”
Hypermind 脚本代表了 AI 辅助测试的新阶段——将自主精确性与人类适应性融为一体。它不仅仅是后备逻辑，更是可执行的人类创造力。

🪙 Token 消耗

Hercules 是一款原生 AI 解决方案，依赖大语言模型（LLMs）进行推理和操作。根据我们的实验，如下所示的复杂用例在使用 OpenAI 的 gpt-4o API 时，单次运行成本最高可达 $0.20。请查看测试用例输出中打印的属性，以估算您自己用例的成本：

Feature: 在 Salesforce 中创建账户

 Scenario: 成功创建新账户

   Given 我位于 Salesforce 登录页面
   When 我输入用户名 "user@example.com" 和密码 "securePassword"
   And 我点击“Log In”按钮
   And 我导航至“Accounts”标签页
   And 我点击“New”按钮
   And 我在“Account Name”字段中填入“Test Account”
   And 我选择“Account Type”为“Customer”
   And 我在“Website”字段中填入“www.testaccount.com”
   And 我在“Phone”字段中填入“123-456-7890”
   And 我点击“Save”按钮
   Then 我应看到确认消息“Account Test Account created successfully”
   And 我应在账户记录中看到“Test Account”

⭐️ 与其他工具的区别

Hercules 不仅仅是另一个测试工具——它是一个智能体（agent）。借助能够思考、推理和响应需求的合成智能（synthetic intelligence），Hercules 超越了简单的自动化脚本。我们为软件测试领域带来了业界首创的开源智能体方法。这意味着更快、更智能、更具韧性的测试周期，尤其适用于复杂平台。

凭借业界领先的性能和完全开源的基础，Hercules 将强大的能力与社区驱动的灵活性相结合，让顶级测试对每个人而言都触手可及且具有变革性。

---

🚀 高层次路线图

• 增强的 LLM（大语言模型）支持：集成更多 LLM，并支持本地 LLM 部署。
• 高级工具集：增加更多工具以应对复杂的测试场景和环境。
• 改进的 DOM 提炼（DOM Distillation）：优化 DOM 提炼流程，提升效率与准确性。
• 社区贡献：鼓励并整合社区驱动的功能与工具。
• 详尽的文档：扩展文档内容，提升新用户入门体验和使用便利性。
• 赏金计划（Bounty Program）：推出赏金计划，激励社区贡献。

---

🤗 贡献指南

我们欢迎来自社区的贡献！

• 请先阅读 CONTRIBUTING.md 文件以开始参与。
• 赏金计划：敬请关注即将推出的机会！😀

如何回馈社区

1. 开发工具

   • 如果你正在为 Hercules 开发工具并希望贡献给社区，请确保在你的 Pull Request 中将新工具放入 additional_tools 文件夹。

2. 修复与增强

   • 如果你对系统核心的感知工具、提示词（prompts）或 DOM 提炼代码进行了修复或改进，请将更改提交到相应文件并发起 Pull Request。

扩展与附加工具

1. 创建新工具

   • 你可以通过向 Hercules 添加工具来开始扩展。
   • 参考 testzeus_hercules/core/tools/sql_calls.py 示例了解如何创建新工具。
   • 关键是在你希望 Hercules 执行的方法上使用 @tool 装饰器。
   • 工具装饰器应包含清晰的名称和描述，以便 Hercules 知道如何使用该工具。
   • 同时，在方法中应明确标注每个参数的用途，以确保 LLM 的函数调用效果最佳。

2. 添加工具

   • 创建好新工具文件后，可通过环境变量将工具所在文件夹路径传递给 Hercules，使其在启动时加载这些新工具，并在执行期间可用。
   • 使用 ADDITIONAL_TOOL_DIRS 环境变量传入新工具文件夹的路径。

3. 直接添加（不推荐）

   • 如果你选择直接添加工具，请将新工具文件放入克隆仓库中的 testzeus_hercules/core/tools 路径下。

   • 注意：此方式不推荐。我们建议优先使用 ADDITIONAL_TOOL_DIRS 方法。

---

🤙 联系我们

加入我们的 Slack，与社区互动、提问并参与贡献。

---

✍️ 示例

• Salesforce 示例：链接
• Wrangler 示例：链接

---

🙇 致谢

Hercules 的实现离不开以下项目的杰出工作：

1. Agent-E
2. Q*
3. Agent Q
4. Autogen

Hercules 项目基于 Agent-E 进行推演与增强。我们在多个方面进行了改进，使其具备执行测试的能力，尤其是在复杂 DOM 导航和 iframe 处理方面。此外，我们还为 Hercules 新增了多种工具和能力（如 Salesforce 导航），使其在所选基础框架之上表现更优。

Hercules 也从旧版 TestZeus 仓库 此处 中汲取了部分灵感。

---

有了 Hercules，测试不再只是流程中的一个步骤——而是一种强大、流畅的体验，将质量置于核心位置。

🚀 附注：关于 Python 虚拟环境及其他重要命令

如果你来自 Java 或 JavaScript 背景，初次使用 Python 可能会感觉略有不同——但别担心！Python 的简洁性结合虚拟环境等强大工具，使得依赖管理变得简单高效。

🎓 理解虚拟环境

在 Java 中，你可能会使用 Maven 或 Gradle 来管理项目依赖；在 JavaScript 中，则使用 npm 或 yarn。在 Python 中，虚拟环境（virtual environments） 扮演类似角色。它们允许你为项目创建隔离的依赖空间，避免与系统中其他 Python 项目发生冲突。

你可以将其想象成一个沙盒环境，TestZeus Hercules 及其依赖在此独立运行，与其他 Python 包互不干扰。

🏗️ 设置说明

✅ 1. 前提条件

首先，请确保已安装 Python 3.11 或更高版本。可通过以下命令验证：

python --version
# 或
python3 --version

如果尚未安装 Python，请在此下载；若使用 Windows 系统，请参考此处说明。

---

🏰 2. 创建并激活虚拟环境

为项目设置干净的 Python 环境：

# 创建名为 'venv' 的虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate

# macOS/Linux:
source venv/bin/activate

你会注意到终端提示符发生变化——这表示虚拟环境已激活。

稍后如需停用虚拟环境，只需运行：

deactivate

---

📥 3. 安装 TestZeus Hercules

激活虚拟环境后，直接从 PyPI 安装最新版 TestZeus Hercules：

pip install testzeus-hercules

---

🔄 4. 更新 TestZeus Hercules

如需升级至最新版本，请使用：

pip install --upgrade testzeus-hercules

---

❌ 5. 卸载 TestZeus Hercules

如需移除该包：

pip uninstall testzeus-hercules

---

🔍 6. 查看已安装的包

验证 TestZeus Hercules 是否已安装并查看其版本：

pip list

🔗 给 Java/JS 开发者的额外提示

• pip 类似于 npm 或 mvn——用于安装和管理 Python 包（packages）。
• Python 的简洁性意味着更少的配置文件——大多数操作都可以直接通过命令行完成。

---

💡 下一步

现在 TestZeus Hercules 已安装并准备就绪，请深入阅读 我们的文档，轻松学习如何创建并运行你的第一个测试用例！

---

Star 历史

✅ 引用

如果你在研究或项目中使用了 Hercules，请引用以下内容：

@software{testzeus_hercules2024,
  author = {Agnihotri, Shriyansh and Gupta, Robin},
  title = {Hercules: World's first open source testing agent},
  year = {2024},
  publisher = {GitHub},
  url = {https://github.com/test-zeus-ai/testzeus-hercules/}
}

TestZeus Hercules 快速上手指南

环境准备

• 操作系统：支持 Linux、macOS 和 Windows（Windows 需以管理员权限运行 PowerShell）
• Python 版本：建议使用 Python 3.10 或 3.11
• 前置依赖：
  • 安装 Playwright 浏览器依赖
  • 若使用 LLM 功能，需准备支持 function calling 的大模型 API Key（如 OpenAI GPT-4o、Anthropic Haiku 3.5+ 等）

💡 国内用户建议配置 PyPI 镜像源（如清华源）加速安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple testzeus-hercules

安装步骤

1. 安装 Hercules 包

pip install testzeus-hercules

2. 安装 Playwright 浏览器依赖

playwright install --with-deps

⚠️ Windows 用户可使用官方提供的 PowerShell 脚本一键安装：

# 以管理员身份运行 PowerShell
cd path\to\helper_scripts
.\hercules_windows_setup.ps1

基本使用

最简运行示例

假设你已有一个 Gherkin 特性文件 test.feature，并准备好测试数据目录：

testzeus-hercules \
  --input-file ./test.feature \
  --output-path ./output \
  --test-data-path ./test_data \
  --llm-model gpt-4o \
  --llm-model-api-key sk-proj-k.......

推荐项目结构（使用 --project-base）

若采用标准项目结构，只需指定根目录：

my_project/
├── input/              # 存放 .feature 文件
├── output/             # 输出报告和结果
├── test_data/          # 测试数据文件
└── proofs/             # 自动保存截图、视频、网络日志等证据

运行命令简化为：

testzeus-hercules --project-base ./my_project --llm-model gpt-4o --llm-model-api-key sk-proj-k.......

环境变量配置（可选）

常用环境变量示例（Linux/macOS）：

export BROWSER_TYPE=chromium
export HEADLESS=true
export RECORD_VIDEO=true
export TAKE_SCREENSHOTS=true

Windows（PowerShell）：

$env:BROWSER_TYPE="chromium"
$env:HEADLESS="true"

📌 提示：完整环境变量列表请参考官方文档 Environment Variables Guide。