testzeus-hercules

想象一下这个场景：凌晨两点，你负责的 SaaS 产品刚刚完成一次重大更新。测试团队早已下班，而明天一早就要上线。你是选择手动跑一遍核心流程（耗时两小时），还是让一个 AI Agent 帮你搞定这一切？

这就是 TestZeus Hercules 试图解决的问题。作为全球首个开源测试 Agent，Hercules 将自然语言编写的 Gherkin 规范自动转化为完整的端到端（E2E）自动化测试——无需写一行代码，无需维护复杂的测试框架。

一、项目起源与团队背景

Hercules 由 TestZeus 团队开发，核心作者为 Shriyansh Agnihotri（shriyansh@testzeus.com）。TestZeus 是一家专注于测试自动化的初创公司，使命是"民主化并颠覆测试自动化行业"，让顶级测试能力不再是大公司的专属。

该项目的诞生源于行业的一个普遍痛点：现代 Web 应用变化频繁（Salesforce、React 单页应用等），传统测试工具（Selenium、Cypress）需要大量代码维护工作，而 AI Agent 技术的成熟让"用自然语言驱动测试"成为可能。

GitHub 数据显示，该项目目前获得 1045 stars，被 16 个 topics 标记，涵盖 agent、autogen、playwright、rpa、end-to-end-testing 等多个技术领域，在 AI + 软件测试交叉领域具有较高的影响力。

图1：TestZeus 组织头像

作为一个成立不久的开源团队，TestZeus 已经在 Slack 社区积累了活跃的开发者生态，并配套提供了 YouTube 视频教程体系（@TestZeus 频道）和完整的在线文档（testzeus.com/hercules/docs）。

二、技术架构：多 Agent 协作的测试引擎

如果把 Hercules 比作一支"自动化测试特战队"，它的核心架构由以下角色组成：

1. 高层规划 Agent（High-Level Planner） 负责理解用户的 Gherkin 规范，将测试任务分解为可执行的子步骤。这是整个系统的"指挥官"，决定"先登录、再搜索、后下单"的执行顺序。

2. 浏览器导航 Agent（Browser Navigation Agent） 在给定页面状态下，决定下一步操作（点击、输入、悬停等），调用 Playwright 底层工具执行真实浏览器交互。Planner 给出指令，Nav Agent 负责落地。

3. 专项 Agent 矩阵

• browser_nav_agent.py：通用浏览器操作
• api_nav_agent.py：API 级别接口测试
• sec_nav_agent.py：安全漏洞检测（XSS、SQL 注入等）
• sql_nav_agent.py：数据库状态验证
• mcp_nav_agent.py：MCP（Model Context Protocol）工具集成

4. 记忆子系统（Memory） 采用两层记忆架构：

• 静态长期记忆（Static LTM）：存储项目配置、固定测试数据
• 动态长期记忆（Dynamic LTM）：记录测试执行过程中的中间状态，支持跨场景复用

5. 工具层（Tools） 23 个核心工具，覆盖浏览器操作（click、enter_text、hover）、API 调用、无障碍访问检测、PDF 解析、SQL 查询、文件上传、验证码破解等。工具通过 tool_registry.py 统一注册和管理。

图2：Hercules 系统架构图

整个系统在 AutoGen（ag2）框架下运行，支持 OpenAI、Anthropic、Gemini、Portkey 等多种 LLM 后端，并通过 Portkey 实现多模型 fallback（当主模型不可用时自动切换）。

图3：Lead Creation 自动化测试 Demo（自然语言转 Playwright 浏览器自动化）

三、核心功能详解

3.1 Gherkin 驱动的自然语言测试

用户只需编写标准 Gherkin 格式的 .feature 文件，用自然语言描述测试场景：

Feature: Lead Creation
  Scenario: Create a new lead in Salesforce
    Given I open the Salesforce login page
    When I log in with credentials "admin@test.com" and "password123"
    And I navigate to the Leads section
    And I click the "New Lead" button
    And I fill in the lead form with:
      | Field    | Value              |
      | Name     | John Doe           |
      | Company  | Acme Corp          |
      | Email    | john@acme.com      |
    Then I should see a success message

Hercules 自动解析、规划、执行，全程无需人工干预。这是 BDD（行为驱动开发）与 LLM Agent 的首次深度结合。

3.2 Playwright 驱动的真实浏览器

底层使用 Playwright（<=1.49.0），支持 Chrome、Firefox、MS Edge 等多浏览器通道。Playwright 相比 Selenium 的核心优势在于：自动等待（auto-wait）、网络拦截、iframe 处理，这些能力对现代 SPA 应用至关重要。

3.3 多维度测试类型覆盖

测试类型	对应 Agent	能力描述
UI 自动化	browser_nav_agent	真实浏览器操作、DOM 交互
API 测试	api_nav_agent	HTTP 请求构造、响应验证
安全测试	sec_nav_agent	XSS、注入等漏洞检测
无障碍测试	accessibility_calls	WCAG 合规性检查
SQL 验证	sql_nav_agent	数据库查询与断言
可视化测试	visual_skill	截图对比、布局验证

3.4 MCP 集成与扩展性

支持 MCP（Model Context Protocol）服务器扩展，允许接入第三方工具或服务。通过 mcp_servers.example.json 配置文件，可以声明式地添加 MCP 工具，由 mcp_nav_agent.py 统一调度。

3.5 测试报告生成

执行完成后，自动生成 JUnit XML + HTML 报告（通过 junit2html），可直接接入 CI/CD 系统（Jenkins、GitHub Actions、GitLab CI）。

图4：HTML 格式测试报告

图5：JUnit XML 格式测试报告

四、技术栈与依赖分析

核心依赖（Python >= 3.11）：

依赖	版本	作用
ag2[all]	0.10.x	多 Agent 协作框架（AutoGen）
playwright	<=1.49.0	浏览器自动化引擎
anthropic	0.87.x	Claude API 集成
sentence-transformers	5.0.x	向量嵌入（记忆系统）
chromadb	1.0.x	向量数据库（RAG 记忆）
transformers	5.0.x	预训练模型支持
pydantic	2.6.x	配置校验与数据模型
mcp	1.23.x	MCP 协议支持
portkey-ai	1.11.x	LLM 网关与 fallback
opentelemetry	1.27.x	链路追踪

关键架构选择：

• AutoGen（ag2）：选择 AutoGen 而非 LangChain 的原因是其原生支持多 Agent 对话协作，适合测试 Agent 这种"规划-执行-验证"多轮交互场景
• Sentence-Transformers + ChromaDB：为 Agent 提供语义记忆能力，支持 RAG 风格的信息检索
• Portkey AI：作为 LLM 网关，支持多 provider fallback，提高测试执行稳定性
• OpenTelemetry：集成 Sentry SDK 进行遥测监控，支持性能分析

开发依赖： pytest + coverage：单元测试；uv：快速的 Python 包管理工具（Dockerfile 中使用 uv sync 而非 pip）

五、部署与安装

方式一：Docker（推荐）

项目提供官方 Dockerfile，基于 python:3.11-slim，内置 uv 包管理和 Playwright 浏览器安装：

docker pull testzeus/hercules
docker run -it \
  -e LLM_MODEL_NAME=gpt-4 \
  -e LLM_MODEL_API_KEY=sk-xxx \
  -v $(pwd)/features:/testzeus-hercules/opt \
  testzeus/hercules

entrypoint.sh 脚本负责环境变量校验，确保 LLM 配置完整。

方式二：本地安装

pip install testzeus-hercules
testzeus-hercules --config config.json --features tests/lead.feature

前置要求：

• Python 3.11+（不支持 3.10 及以下）
• 至少一个 LLM API Key（OpenAI GPT-4/4o、Claude 3.5/3.7、Gemini 等）
• Docker（可选，推荐使用）

硬件需求： 无 GPU 要求，普通 4GB RAM + 5GB 磁盘即可运行。但需要稳定的互联网连接以访问 LLM API。

部署难度评估： 中等。主要门槛在于 LLM API Key 的获取与配置，以及对 Gherkin 规范的基本了解。Docker 方式可降低环境配置复杂度。

六、局限性与挑战

6.1 LLM 依赖的成本问题

每次测试执行都需要调用 LLM API。在大型测试套件中，Token 消耗可能相当可观。项目通过限制 Planner 最大对话轮数（默认 500 轮）和 Nav Agent 轮数（默认 10 轮）来控制成本，但复杂场景下 Token 消耗仍需关注。

6.2 验证码与反爬对抗

现代网站大量使用 reCAPTCHA、hCaptcha 等反自动化机制。项目依赖 playwright-recaptcha 库进行验证码破解，但其能力有限，对高级验证码仍无法保证成功率。

6.3 复杂动态页面处理

单页应用（React/Vue）和 Shadow DOM 场景下，DOM 结构动态变化，Agent 的"点击第 N 个按钮"策略可能失效。项目通过 accessibility tree 和 semantic role 匹配来增强鲁棒性，但极端场景仍需人工介入。

6.4 社区成熟度

作为新兴开源项目，核心维护者较少，社区规模有限。Issue 响应和版本迭代速度受限于资源投入。

6.5 安全考量

代码中集成了 Sentry SDK 进行遥测（默认开启），telemetry.py 中包含 ENABLE_TELEMETRY 环境变量可关闭。虽然 Sentry 已做 PII 脱敏处理，但涉及测试用例中的敏感数据时，建议在隔离环境中运行。

七、行业意义与生态定位

7.1 AI Agent 落地的绝佳场景

软件测试是 AI Agent 最自然的落地场景之一：任务边界清晰（给定输入验证输出）、反馈信号明确（测试通过/失败）、可自动化程度高。Hercules 证明了 LLM Agent 在真实 QA 场景中的可行性。

7.2 BDD 的现代化复兴

Gherkin/BDD 规范在 2010 年代初曾流行一时，但因维护成本高、维护与开发脱节而逐渐式微。Hercules 通过 AI 消除了"维护成本"这个最大障碍——测试规范即测试执行，无需翻译层。

7.3 开源 vs 商业测试工具

对比 Testim、Mabl、Functionize 等商业 AI 测试平台，Hercules 的开源特性允许企业深度定制、自托管、无用量限制。这对重视数据主权和成本控制的技术团队具有吸引力。

7.4 增长态势

GitHub 1045 stars、pip 累计下载量持续增长、活跃的 Slack 社区，表明项目正处于成长期。TestZeus 团队配套提供的文档、视频、社区运营策略较为完整，具备持续发展的基础。

---

总结： TestZeus Hercules 代表了"AI + 测试自动化"交叉领域的最新探索，通过 AutoGen 多 Agent 架构将自然语言测试规范转化为真实浏览器操作，在 Salesforce 等复杂平台上展现出独特优势。其开源、模块化、可扩展的设计为技术团队提供了商业工具之外的性价比替代方案。主要挑战在于 LLM 成本控制、验证码对抗和复杂动态页面的鲁棒性。