testzeus-hercules

环境要求

• Python 环境（可 pip 安装包）
• 已配置可访问的 LLM 模型服务（如 OpenAI 兼容接口）
• 磁盘可容纳 Playwright 浏览器及依赖
• Windows 用户需以管理员身份运行 PowerShell

安装与启动步骤

1. 1安装 Hercules

   从 PyPI 安装 Hercules 包，它会同时装好命令行入口 testzeus-hercules。

   pip install testzeus-hercules

   复制

2. 2安装 Playwright

   Hercules 用 Playwright 操作网页，必须安装浏览器本体及系统依赖。

   playwright install --with-deps

   复制

3. 3配置模型变量

   导出模型名称、API Key 和 Base URL；把 replace-me 换成你的真实 Key。

   export LLM_MODEL_NAME=gpt-4o
   export LLM_MODEL_API_KEY=sk-xxxxxxxx
   export LLM_MODEL_BASE_URL=https://api.openai.com/v1

   复制

4. 4准备测试文件

   按 opt/input/test.feature、opt/output、opt/test_data 的结构放好 Gherkin 用例文件。

5. 5运行 Hercules

   指定输入用例、输出目录与测试数据目录执行，测试结果写入 output-path。

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

   复制

6. 6Docker 方式运行

   拉取镜像后用 .env 传环境变量，挂载 opt 目录即可，无需再传路径参数。

   docker pull testzeus/hercules:latest
   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

   复制

关键配置

如何确认成功

运行结束后查看 opt/output 下新生成的 run_ 目录，内有 test.feature_result.html 和 .xml 结果报告。

常见问题

注意事项

• Colab 中安装依赖后可能提示重启会话，需重启后继续执行。
• Docker 连接远程浏览器时，需先导出对应平台的 USERNAME/ACCESS_KEY 再生成 CDP 地址。
• 源码运行方式需先 clone 仓库并执行 make setup-uv、make install，再用 make run。
• 项目结构与更多运行细节见 docs/run_guide.md。