[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-test-zeus-ai--testzeus-hercules":3,"tool-test-zeus-ai--testzeus-hercules":64},[4,17,27,35,43,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",138956,2,"2026-04-05T11:33:21",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,26],{"id":44,"name":45,"github_repo":46,"description_zh":47,"stars":48,"difficulty_score":23,"last_commit_at":49,"category_tags":50,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,51,52,53,15,54,26,13,55],"数据工具","视频","插件","其他","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,54],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":69,"readme_en":70,"readme_zh":71,"quickstart_zh":72,"use_case_zh":73,"hero_image_url":74,"owner_login":75,"owner_name":76,"owner_avatar_url":77,"owner_bio":78,"owner_company":79,"owner_location":79,"owner_email":80,"owner_twitter":81,"owner_website":82,"owner_url":83,"languages":84,"stars":119,"forks":120,"last_commit_at":121,"license":122,"difficulty_score":10,"env_os":123,"env_gpu":124,"env_ram":124,"env_deps":125,"category_tags":135,"github_topics":136,"view_count":10,"oss_zip_url":79,"oss_zip_packed_at":79,"status":16,"created_at":154,"updated_at":155,"faqs":156,"releases":185},408,"test-zeus-ai\u002Ftestzeus-hercules","testzeus-hercules","Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡","Hercules 是全球首个开源的自动化测试智能体，专为现代 Web 应用设计，支持 UI、API、安全、无障碍和视觉验证等多种测试类型。它最大的特点是无需编写代码，用户只需用自然语言或简单的 Gherkin 语法描述测试步骤，Hercules 就能自动执行端到端测试，并适应频繁变化的界面和复杂业务逻辑（如 Salesforce 等平台）。这解决了传统自动化测试维护成本高、技术门槛高的痛点，让测试更稳定、高效且易于上手。\n\nHercules 特别适合 QA 工程师、产品经理、前端开发者以及希望快速开展自动化测试但缺乏编程经验的团队使用。其独特之处在于融合了多种测试能力于统一框架中，并通过视觉识别、多语言支持和 CI\u002FCD 集成，实现真正“低维护”的智能测试。作为 TestZeus 推出的开源项目，Hercules 强调透明性与社区共建，致力于让高质量测试能力普惠更多团队。","\n\u003Cimg width=\"100\" height=\"100\" alt=\"2\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_e86b35709617.png\" \u002F>\n\n# 💪 Hercules\n\n[![PyPI Total Downloads](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_67b3ed9b5254.png)](https:\u002F\u002Fpepy.tech\u002Fprojects\u002Ftestzeus-hercules)\n![Docker Pulls](https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fpulls\u002Ftestzeus\u002Fhercules)\n[![CI Test](https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Factions\u002Fworkflows\u002Fmain-test.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Factions\u002Fworkflows\u002Fmain-test.yml)\n[![Slack](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fslack-TestZeus-brightgreen.svg?logo=slack)](https:\u002F\u002Fjoin.slack.com\u002Ft\u002Ftestzeuscommunityhq\u002Fshared_invite\u002Fzt-376oeo99x-3RAWe_C0H7x9zP0rtACcPA)\n\nTesting 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\u002FCD 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):\n\n![HerculesUsage](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_2a1c8ad1acf5.gif)\n\n\n\nAs you saw, using Hercules is as simple as feeding in your Gherkin features, and getting the results:\n![HerculesUsage](statics\u002Fassets\u002Fhercules.svg)\n\nAt [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.\n\nOur 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!\n\n### Video Tutorials: [@TestZeus](https:\u002F\u002Fwww.youtube.com\u002F@TestZeus)\n---\n\n#### 🚀 **Getting Started with TestZeus Hercules**\n- **Introduction to TestZeus Hercules**  \n  Learn about the core features of TestZeus Hercules and how it can streamline end-to-end testing for your projects. \n   [![Autonomous execution with Hercules](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_2922fc71778a.png)](https:\u002F\u002Fyoutu.be\u002F_m_NDjM6aZ0?si=ArtVKz8uSgGWTcAK)\n\n- **Installation and Setup Guide**  \n  Step-by-step instructions for installing and configuring TestZeus Hercules in your environment.  \n  _[Watch now](https:\u002F\u002Fyoutu.be\u002F9D-SZGoDrfc?si=GL0IArWkB1ZgBdx5)_\n\n---\n\n#### 🧪 **Writing and Executing Test Cases**\n- **Creating BDD Test Cases**  \n  Learn how to write Behavior-Driven Development (BDD) test cases for Hercules and use dynamic testdata.  \n  _[Watch now](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=yJD0cZ7Bx6Q&t)_\n\n---\n\n#### 🌐 **Integrations and Advanced Features**\n- **Testing Multilingual content**  \n  Learn how Hercules interacts with web browsers to perform Testing on Multilingual content via Multilingual testcase.  \n  _[Watch now](https:\u002F\u002Fyoutu.be\u002FvI9iGSqKpGA?si=6NGAvKnwFboSyHT2)_\n---\n\n#### 🛠️ **Customization and Community Tools**\n- **Enhancing Hercules with Community-Driven Tools**  \n  Discover how to customize Hercules and incorporate additional tools provided by the community.  \n  _[Watch now](https:\u002F\u002Fyoutu.be\u002FC8hUy5leRF0?si=yVMpZ7WFcI01BoI3)_\n---\n\n#### 🛠️ **API Testing**\n- **API testing all the way, new ways to do end to end**  \n  _[Watch now](https:\u002F\u002Fyoutu.be\u002FqMt89DQH6LQ?si=lcSJbKOCaqqUGeQ8)_\n---\n\n#### 🛠️ **Security Testing**\n- **Security Testing done end to end**  \n  _[Watch now](https:\u002F\u002Fyoutu.be\u002Fo6MmfTakIh4?si=JL8iu4e3i85SWrxU)_\n\n#### 🛠️ **Visual validations and assertions**\n- **Using vision capabilities to check snapshots and components on the application**  \n  _[Watch now](https:\u002F\u002Fyoutu.be\u002FEKzllLEguhw)_\n\n#### 🐍 **Python Sandbox Execution**\n- **Execute custom Python scripts directly from Gherkin tests**  \n  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\u002Fpython_sandbox_execution.md)\n\n**Quick Example:**\n```gherkin\n# In your feature file\nAnd execute the apply_filter function from script at \"scripts\u002Fapply_filter.py\" with filter_type as \"Turtle Neck\"\n```\n\n```python\n# In opt\u002Fscripts\u002Fapply_filter.py\nasync def apply_filter(filter_type: str) -> dict:\n    \"\"\"Apply filter with multiple fallback strategies.\"\"\"\n    # page, logger, and other tools automatically available!\n    await page.wait_for_selector('[data-filter-section]')\n    \n    # Try multiple selector strategies\n    for selector in [f'input[value=\"{filter_type}\"]', \n                     f'label:has-text(\"{filter_type}\") input']:\n        if await page.locator(selector).count() > 0:\n            await page.locator(selector).click()\n            break\n    \n    return {\"status\": \"success\", \"filter\": filter_type}\n```\n\n**Features:**\n- 🎯 Full Playwright API access\n- 🔒 Multi-tenant security (executor, data, API, restricted modes)\n- 📦 Auto-injected modules (page, browser, logger, asyncio, etc.)\n- 🔄 Reusable across multiple tests\n- ⚙️ Configurable via environment variables\n\n**Configuration:**\n```bash\n# Set tenant for module access\nexport SANDBOX_TENANT_ID=\"executor_agent\"  # Full access: requests, pandas, numpy, BeautifulSoup\n\n# Or use CLI\nhercules --sandbox-tenant-id executor_agent --input-file test.feature\n```\n\n---\n\n## ⚙️ Installation and Usage\n\nHercules offers multiple ways to get started, catering to different user preferences and requirements.\nIf you are new to the Python ecosystem and don't know where to begin, dont worry and read the footnotes on understanding the basics.\n\n\nFor a quick taste of the solution, you can try the notebook here: \n[![Open In Colab](https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg)](https:\u002F\u002Fcolab.research.google.com\u002Fdrive\u002F1YiZsXem1POTwkcr17QqflXnihhuSqwM2?usp=sharing)\n- **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. \n\n### Approach 1: Using PyPI Package\n\n#### Installation\n\nInstall Hercules from PyPI:\n\n```bash\npip install testzeus-hercules\n```\n\nHercules uses Playwright to interact with web pages, so you need to install Playwright and its dependencies:\n\n```bash\nplaywright install --with-deps\n```\n\nFor detailed information about project structure and running tests, please refer to our [Run Guide](docs\u002Frun_guide.md).\n\n#### Basic Parameters\n\nOnce installed, you will need to provide some basic parameters to run Hercules:\n\n- `--input-file INPUT_FILE`: Path to the input Gherkin feature file to be tested.\n- `--output-path OUTPUT_PATH`: Path to the output directory. The path of JUnit XML result and HTML report for the test run.\n- `--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.\n- `--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:\n\n```\nPROJECT_BASE\u002F\n├── gherkin_files\u002F\n├── input\u002F\n│   └── test.feature\n├── log_files\u002F\n├── output\u002F\n│   ├── test.feature_result.html\n│   └── test.feature_result.xml\n├── proofs\u002F\n│   └── User_opens_Google_homepage\u002F\n│       ├── network_logs.json\n│       ├── screenshots\u002F\n│       └── videos\u002F\n└── test_data\u002F\n    └── test_data.txt\n```\n\n- `--llm-model LLM_MODEL`: Name of the LLM model to be used by the agent (recommended is `gpt-4o`, but it can take others).\n- `--llm-model-api-key LLM_MODEL_API_KEY`: API key for the LLM model, something like `sk-proj-k.......`.\n\n#### Environment Variables\n\nIn addition to command-line parameters, Hercules supports various environment variables for configuration:\n\n- `BROWSER_TYPE`: Type of browser to use (`chromium`, `firefox`, `webkit`). Default: `chromium`\n- `HEADLESS`: Run browser in headless mode (`true`, `false`). Default: `true`\n- `BROWSER_RESOLUTION`: Browser window resolution (format: `width,height`). Example: `1920,1080`\n- `BROWSER_COOKIES`: Set cookies for the browser context. Format: JSON array of cookie objects. Example: `[{\"name\": \"session\", \"value\": \"123456\", \"domain\": \"example.com\", \"path\": \"\u002F\"}]`\n- `RECORD_VIDEO`: Record test execution videos (`true`, `false`). Default: `true`\n- `TAKE_SCREENSHOTS`: Take screenshots during test (`true`, `false`). Default: `true`\n\nFor a complete list of environment variables, see our [Environment Variables Guide](docs\u002Fenvironment_variables.md).\n\n#### Running Hercules\n\nAfter passing all the required parameters, the command to run Hercules should look like this:\n\n```bash\ntestzeus-hercules --input-file opt\u002Finput\u002Ftest.feature --output-path opt\u002Foutput --test-data-path opt\u002Ftest_data --llm-model gpt-4o --llm-model-api-key sk-proj-k.......\n```\n\n\n## ⚙️ Running Hercules on a Windows Machine\n\nTo set up and run Hercules on a Windows machine:\n\n1. **Open PowerShell in Administrator Mode:**\n   - Click on the **Start Menu**, search for **PowerShell**, and right-click on **Windows PowerShell**.\n   - Select **Run as Administrator** to open PowerShell in administrator mode.\n\n2. **Navigate to the Helper Scripts Folder:**\n   - Use the `cd` command to navigate to the folder containing the `hercules_windows_setup.ps1` script. For example:\n     ```powershell\n     cd path\\to\\helper_scripts\n     ```\n\n3. **Run the Setup Script:**\n   - Execute the script to install and configure Hercules:\n     ```powershell\n     .\\hercules_windows_setup.ps1\n     ```\n\n4. **Follow On-Screen Instructions:**\n   - The script will guide you through installing Python, Playwright, FFmpeg, and other required dependencies.\n\n5. **Run Hercules:**\n   - Once the setup is complete, you can run Hercules from PowerShell or Command Prompt using the following command:\n     ```bash\n     testzeus-hercules --input-file opt\u002Finput\u002Ftest.feature --output-path opt\u002Foutput --test-data-path opt\u002Ftest_data --llm-model gpt-4o --llm-model-api-key sk-proj-k.......\n     ```\n\n---\n\n\n#### Supported AI Models for TestZeus-Hercules\n- Anthropic: Compatible with Haiku 3.5 and above.\n- Groq: Supports any version with function calling and coding capabilities.\n- Mistral: Supports any version with function calling and coding capabilities. Mistral-large, Mistral-medium. Only heavey models.\n- OpenAI: Fully compatible with GPT-4o\u002Fo3-mini and above. Note: OpenAI GPT-4o-mini is only supported for sub-agents, for planner it is still recommended to use GPT-4o.\n- Ollama: Supported with medium models and function calling. Heavy models only 70b and above.\n- Gemini: Can be used. Preferred with LiteLLM as below.\n- Deepseek: only deepseek-chat v3 support.\n- Hosting: supported on AWS bedrock, GCP VertexAI, AzureAI. [tested models, OpenAI, Anthropic Sonet and Haiku, Llamma 60b above with function calling]\nNote: Kindly ensure that the model you are using can handle agentic activities like function calling. For example larger models like OpenAI GPT 4O, Llama >70B, Mistral large etc. You can use agent_config file as below to fill LiteLLM details [https:\u002F\u002Fdocs.litellm.ai\u002Fdocs\u002Fsimple_proxy] :\n```JSON\n{\n  \"litellm-flash\": {\n    \"planner_agent\": {\n      \"model_name\": \"gemini-2.5-flash\",\n      \"model_api_key\": \"sfasdfsadgbw\",\n      \"model_base_url\": \"https:\u002F\u002Flitellm-proxydeployment\",\n      \"llm_config_params\": {\n        \"cache_seed\": 1234,\n        \"temperature\": 0,\n        \"seed\": 12345\n      }\n    },\n    \"nav_agent\":  {\n      \"model_name\": \"gemini-2.5-flash\",\n      \"model_api_key\": \"sfasdfsadgbw\",\n      \"model_base_url\": \"https:\u002F\u002Flitellm-proxydeployment\",\n      \"llm_config_params\": {\n        \"cache_seed\": 1234,\n        \"temperature\": 0,\n        \"seed\": 12345\n      }\n    },\n    \"mem_agent\":  {\n      \"model_name\": \"gemini-2.5-flash\",\n      \"model_api_key\": \"sfasdfsadgbw\",\n      \"model_base_url\": \"https:\u002F\u002Flitellm-proxydeployment\",\n      \"llm_config_params\": {\n        \"cache_seed\": 1234,\n        \"temperature\": 0,\n        \"seed\": 12345\n      }\n    },\n    \"helper_agent\":  {\n      \"model_name\": \"gemini-2.5-flash\",\n      \"model_api_key\": \"sfasdfsadgbw\",\n      \"model_base_url\": \"https:\u002F\u002Flitellm-proxydeployment\",\n      \"llm_config_params\": {\n        \"cache_seed\": 1234,\n        \"temperature\": 0,\n        \"seed\": 12345\n      }\n    }\n  }\n}\n```\n\n#### Execution Flow\n\nUpon running the command:\n\n- Hercules will start and attempt to open a web browser (default is Chromium).\n- It will prepare a plan of execution based on the feature file steps provided.\n- The plan internally expands the brief steps mentioned in the feature file into a more elaborated version.\n- Hercules detects assertions in the feature file and plans the validation of expected results with the execution happening during the test run.\n- All the steps, once elaborated, are passed to different tools based on the type of execution requirement of the step. For example, if a step wants to click on a button and capture the feedback, it will be passed to the `click_using_selector` tool.\n\n#### Output and Logs\n\nOnce the execution is completed:\n\n- Logs explaining the sequence of events are generated.\n- The best place to start is the `output-path`, which will have the JUnit XML result file as well as an HTML report regarding the test case execution.\n- You can also find proofs of execution such as video recordings, screenshots per event, and network logs in the `proofs` folder.\n- To delve deeper and understand the chain of thoughts, refer to the `chat_messages.json` in the `log_files`. This will have exact steps that were planned by the agent.\n\n#### Sample Feature File\n\nHere's a sample feature file:\n\n```gherkin\nFeature: Account Creation in Salesforce\n\n Scenario: Successfully create a new account\n\n   Given I am on the Salesforce login page\n   When I enter my username \"user@example.com\" and password \"securePassword\"\n   And I click on the \"Log In\" button\n   And I navigate to the \"Accounts\" tab\n   And I click on the \"New\" button\n   And I fill in the \"Account Name\" field with \"Test Account\"\n   And I select the \"Account Type\" as \"Customer\"\n   And I fill in the \"Website\" field with \"www.testaccount.com\"\n   And I fill in the \"Phone\" field with \"123-456-7890\"\n   And I click on the \"Save\" button\n   Then I should see a confirmation message \"Account Test Account created successfully\"\n   And I should see \"Test Account\" listed in the account records\n```\n\n#### Sample Result Screenshot\n\n##### Sample HTML Result Screenshot\n![Sample HTML Result](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_1f58199e18a4.png)\n##### Sample XML Result Screenshot\n![Sample XML Result](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_766d64f4936f.png)\n\n---\n\n### Approach 2: Using Docker\n\nFor all the scale lovers, Hercules is also available as a Docker image.\n\n#### Pull the Docker Image\n\n```bash\ndocker pull testzeus\u002Fhercules:latest\n```\n\n#### Running Hercules in Docker\n\nRun the container using:\n\n```bash\ndocker run --env-file=.env \\\n  -v .\u002Fagents_llm_config.json:\u002Ftestzeus-hercules\u002Fagents_llm_config.json \\\n  -v .\u002Fopt:\u002Ftestzeus-hercules\u002Fopt \\\n  --rm -it testzeus\u002Fhercules:latest\n```\n\n- **Environment Variables**: All the required environment variables can be set by passing an `.env` file to the `docker run` command.\n- **LLM Configuration**: If you plan to have complete control over Hercules and which LLM to use beyond the ones provided by OpenAI, you can pass `agents_llm_config.json` as a mount to the container. This is for advanced use cases and is not required for beginners. Refer to sample files `.env-example` and `agents_llm_config-example.json` for details and reference.\n- **Mounting Directories**: Mount the `opt` folder to the Docker container so that all the inputs can be passed to Hercules running inside the container, and the output can be pulled out for further processing. The repository has a sample `opt` folder that can be mounted easily.\n- **Simplified Parameters**: In the Docker case, there is no need for using `--input-file`, `--output-path`, `--test-data-path`, or `--project-base` as they are already handled by mounting the `opt` folder in the `docker run` command.\n\n#### Browser Access in Docker\n\n- While running in Docker mode, understand that Hercules has access only to a headless web browser.\n- If you want Hercules to connect to a visible web browser, try the CDP URL option in the environment file. This option can help you connect Hercules running in your infrastructure to a remote browser like BrowserBase or your self-hosted grid.\n- Use `CDP_ENDPOINT_URL` to set the CDP URL of the Chrome instance that has to be connected to the agent.\n\n### Docker and Remote Browser Support\n\nWhen running Hercules in Docker, you can connect to remote browser instances using various platforms:\n\n1. **BrowserStack Integration**:\n```bash\nexport BROWSERSTACK_USERNAME=your_username\nexport BROWSERSTACK_ACCESS_KEY=your_access_key\nexport CDP_ENDPOINT_URL=$(python helper_scripts\u002Fbrowser_stack_generate_cdp_url.py)\n```\n\n2. **LambdaTest Integration**:\n```bash\nexport LAMBDATEST_USERNAME=your_username\nexport LAMBDATEST_ACCESS_KEY=your_access_key\nexport CDP_ENDPOINT_URL=$(python helper_scripts\u002Flambda_test_generate_cdp_url.py)\n```\n\n3. **BrowserBase Integration**:\n```bash\nexport CDP_ENDPOINT_URL=wss:\u002F\u002Fconnect.browserbase.com?apiKey=your_api_key\n```\n\n4. **AnchorBrowser Integration**:\n```bash\nexport CDP_ENDPOINT_URL=wss:\u002F\u002Fconnect.anchorbrowser.io?apiKey=your_api_key\n```\n\nNote: Video recording is only supported on platforms that use connect_over_cdp (BrowserBase, AnchorBrowser). Platforms using the connect API (BrowserStack, LambdaTest) do not support video recording.\n\n#### Output and Logs\n\nAfter the command completion:\n\n- The container terminates, and output is written in the mounted `opt` folder, in the same way as described in the directory structure.\n- You will find the JUnit XML result file, HTML reports, proofs of execution, and logs in the respective folders.\n\n---\n\n### Approach 3: Building and running from Source Code\n\nFor the hardcore enthusiasts, you can use Hercules via the source code to get a complete experience of customization and extending Hercules with more tools.\n\n#### Prerequisites\n\n- Ensure you have **Python 3.11** installed on your system.\n\n#### Steps to Run from Source\n\n1. **Clone the Repository**\n\n   ```bash\n   git clone git@github.com:test-zeus-ai\u002Ftestzeus-hercules.git\n   ```\n\n2. **Navigate to the Directory**\n\n   ```bash\n   cd testzeus-hercules\n   ```\n\n3. **Use Make Commands**\n\n   The repository provides handy `make` commands.\n\n   - Use `make help` to check out possible options.\n\n4. **Install UV**\n\n   ```bash\n   make setup-uv\n   ```\n\n5. **Install Dependencies**\n\n   ```bash\n   make install\n   ```\n\n6. **Run Hercules**\n\n   ```bash\n   make run\n   ```\n\n   - This command reads the relevant feature files from the `opt` folder and executes them, putting the output in the same folder.\n   - The `opt` folder has the following format:\n\n     ```\n     opt\u002F\n     ├── input\u002F\n     │   └── test.feature\n     ├── output\u002F\n     │   ├── test.feature_result.html\n     │   └── test.feature_result.xml\n     ├── log_files\u002F\n     ├── proofs\u002F\n     │   └── User_opens_Google_homepage\u002F\n     │       ├── network_logs.json\n     │       ├── screenshots\u002F\n     │       └── videos\u002F\n     └── test_data\u002F\n         └── test_data.txt\n     ```\n\n7. **Interactive Mode**\n\n   You can also run Hercules in interactive mode as an instruction execution agent, which is more useful for RPA and debugging test cases and Hercules's behavior on new environments while building new tooling and extending the agents.\n\n   ```bash\n   make run-interactive\n   ```\n\n   - This will trigger an input prompt where you can chat with Hercules, and it will perform actions based on your commands.\n\n### Approach 4: Setting Up via helper_script_custom.sh\n\nFor those who want a fully automated setup experience on Linux\u002FmacOS environments, we provide a helper_script.sh. This script installs Python 3.11 (if needed), creates a virtual environment, installs TestZeus Hercules, and sets up the base project directories in an opt folder.\n\n#### Prerequisites\n\n- Ensure you have **Python 3.11** installed on your system.\n\n#### Steps to Run from helper_script_custom.sh\n1. **Download or Create the Script**\n  You can copy the script below into a file named helper_script_custom.sh:\n  ```bash\n  #!\u002Fbin\u002Fbash\n  # set -ex\n\n  # curl -sS https:\u002F\u002Fbootstrap.pypa.io\u002Fget-pip.py | python3.11\n\n  # Create a new Python virtual environment named 'test'\n  python3.11 -m venv test\n\n  # Activate the virtual environment\n  source test\u002Fbin\u002Factivate\n\n  # Upgrade the 'testzeus-hercules' package\n  pip install --upgrade testzeus-hercules\n  playwright install --with-deps\n\n  # create a new directory named 'opt'\n  mkdir -p opt\u002Finput opt\u002Foutput opt\u002Ftest_data\n\n  # download https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Frefs\u002Fheads\u002Fmain\u002Fagents_llm_config-example.json\n  curl -sS https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fmain\u002Fagents_llm_config-example.json > agents_llm_config-example.json\n  mv agents_llm_config-example.json agents_llm_config.json\n\n  # prompt user that they need to edit the 'agents_llm_config.json' file, halt the script and open the file in an editor\n  echo \"Please edit the 'agents_llm_config.json' file to add your API key and other configurations.\"\n\n  # halt the script and mention the absolute path of the agents_llm_config.json file so that user can edit it in the editor\n  echo \"The 'agents_llm_config.json' file is located at $(pwd)\u002Fagents_llm_config.json\"\n  read -p \"Press Enter if file is updated\"\n\n  # download https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fblob\u002Fmain\u002F.env-example\n  curl -sS https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fmain\u002F.env-example > .env-example\n  mv .env-example .env\n\n  # prompt user that they need to edit the .env file, halt the script and open the file in an editor\n  echo \"The '.env' file is located at $(pwd)\u002F.env\"\n  read -p \"Press Enter if file is updated\"\n\n  # create an input\u002Ftest.feature file\n  # download https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Frefs\u002Fheads\u002Fmain\u002Fopt\u002Finput\u002Ftest.feature and save in opt\u002Finput\u002Ftest.feature\n  curl -sS https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fmain\u002Fopt\u002Finput\u002Ftest.feature > opt\u002Finput\u002Ftest.feature\n\n  # download https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Frefs\u002Fheads\u002Fmain\u002Fopt\u002Ftest_data\u002Ftest_data.json and save in opt\u002Ftest_data\u002Ftest_data.json\n  curl -sS https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fmain\u002Fopt\u002Ftest_data\u002Ftest_data.json > opt\u002Ftest_data\u002Ftest_data.json\n\n  # Run the 'testzeus-hercules' command with the specified parameters\n  testzeus-hercules --project-base=opt\n  ```\n2. **Make the Script Executable and Run**\n```bash\nchmod +x helper_script.sh\n.\u002Fhelper_script.sh\n```\n-\tThe script will:\n\t•\tCreate a Python 3.11 virtual environment named test.\n\t•\tInstall testzeus-hercules and Playwright dependencies.\n\t•\tCreate the opt folder structure (for input\u002Foutput\u002Ftest data).\n\t•\tDownload sample config files: agents_llm_config.json, .env, and example feature\u002Ftest data files.\n\t•\tImportant: You will be prompted to edit both agents_llm_config.json and .env files. After you've added your API keys and other custom configurations, press Enter to continue.\n\n3. **Script Output**\n\t-\tAfter completion, the script automatically runs testzeus-hercules --project-base=opt.\n\t-\tYour logs and results will appear in opt\u002Foutput, opt\u002Flog_files, and opt\u002Fproofs.\n---\n\n## 📝 Configuration Details\n\nFor a comprehensive guide to all environment variables and configuration options available in TestZeus Hercules, please refer to our [Environment Variables and Configuration Guide](docs\u002Fenvironment_variables.md). This document provides detailed information about core environment variables, LLM configuration, browser settings, testing configuration, device configuration, logging options, and more.\n\n### Disabling Telemetry\n\nTo disable telemetry, set the `TELEMETRY_ENABLED` environment variable to `0`:\n\n```bash\nexport TELEMETRY_ENABLED=0\n```\n\n### Auto Mode\n\nIf `AUTO_MODE` is set to `1`, Hercules will not request an email during the run:\n\n```bash\nexport AUTO_MODE=1\n```\n\n### Understanding the Environment File (`.env`)\n\nTo configure Hercules in detail:\n\n- Copy the base environment file:\n\n  ```bash\n  cp .env-example .env\n  ```\n\n## 🔌 MCP Support\n\nHercules includes an MCP Navigation Agent that can connect to MCP servers over `stdio`, `sse`, and `streamable-http`. It works out of the box with Composio-generated MCP servers.\n\n- Quick start guide: see `docs\u002FMCP_Usage.md`\n- Composio docs: https:\u002F\u002Fdocs.composio.dev\u002Fdocs\u002Fmcp-developers\n\nMinimal setup:\n\n1) Create `mcp_servers.json` at the repo root:\n\n```\n{\n  \"mcpServers\": {\n    \"server_name\": {\n      \"transport\": \"streamable-http\",\n      \"url\": \"https:\u002F\u002Fmcp.composio.dev\u002Fcomposio\u002Fserver\u002F\u003CSERVER_UUID>\u002Fmcp?user_id=\u003CUSER_EMAIL>\"\n    }\n  }\n}\n```\n\n2) In `.env`:\n\n```\nMCP_ENABLED=true\nMCP_SERVERS=mcp_servers.json\nMCP_TIMEOUT=30\n```\n\nThen, run Hercules as usual; the MCP agent will initialize and expose tools from the configured server.\n\n### Example Testcase (Simple)\n```\nFeature: Read emails from Gmail\n\n  Scenario: Retrieve OTP from Gmail using MCP\n    Given Gmail is configured using MCP\n    When I connect to Gmail\n    And I read the email with OTP\n```\nFor more testcases visit [MCP-Docs](\u002Fdocs\u002FMCP_Usage.md)\n\n---\n- Hercules is capable of running in two configuration forms:\n\n  1. **Using single LLM for all work**\n\n     - For all the activities within the agent, initialize `LLM_MODEL_NAME` and `LLM_MODEL_API_KEY`.\n     - If using a non-OpenAI hosted solution but still OpenAI LLMs (something like OpenAI via Groq), then pass the `LLM_MODEL_BASE_URL` URL as well.\n\n  2. **Custom LLMs for different work or using hosted LLMs**\n\n     - If you plan to configure local LLMs or non-OpenAI LLMs, use the other parameters like `AGENTS_LLM_CONFIG_FILE` and `AGENTS_LLM_CONFIG_FILE_REF_KEY`.\n     - These are powerful options and can affect the quality of Hercules outputs.\n\n- Hercules considers a base folder that is by default `.\u002Fopt` but can be changed by the environment variable `PROJECT_SOURCE_ROOT`.\n\n- **Connecting to an Existing Chrome Instance**\n\n  - This is extremely useful when you are running Hercules in Docker for scale.\n  - You can connect Hercules running in your infrastructure to a remote browser like BrowserBase or your self-hosted grid.\n  - Use `CDP_ENDPOINT_URL` to set the CDP URL of the Chrome instance that has to be connected to the agent.\n\n- **Controlling Other Behaviors**\n\n  You can control other behaviors of Hercules based on the following environment variables:\n\n  - `HEADLESS=true`\n  - `RECORD_VIDEO=false`\n  - `TAKE_SCREENSHOTS=false`\n  - `BROWSER_TYPE=chromium` (options: `firefox`, `chromium`)\n  - `CAPTURE_NETWORK=false`\n \nFor example: If you would like to run with a \"Headful\" browser, you can set the environment variable with ```export HEADLESS=false``` before triggering Hercules.\n\n- **How to Use Tracing in Playwright**\n\n  Tracing in Playwright allows you to analyze test executions and debug issues effectively. To enable tracing in your Playwright tests, follow these steps:\n\n  1. Ensure that tracing is enabled in the configuration.\n  2. Traces will be saved to the specified path: `{proof_path}\u002Ftraces\u002Ftrace.zip`.\n\n  #### Enabling Tracing\n\n  To enable tracing, set the following environment variable:\n\n  ```bash\n  export ENABLE_PLAYWRIGHT_TRACING=true\n  ```\n\n### Understanding `agents_llm_config-example.json`\n\n- It's a list of configurations of LLMs that you want to provide to the agent.\n\n- Example:\n\n  ```json\n  {\n    \"anthropic\": {\n\t\t\"planner_agent\": {\n\t\t\t\"model_name\": \"claude-3-5-haiku-latest\",\n\t\t\t\"model_api_key\": \"\",\n\t\t\t\"model_api_type\": \"anthropic\",\n            \"llm_config_params\": {\n                \"cache_seed\": null,\n                \"temperature\": 0.0,\n                \"seed\":12345\n            }\n\t\t},\n\t\t\"nav_agent\": {\n\t\t\t\"model_name\": \"claude-3-5-haiku-latest\",\n\t\t\t\"model_api_key\": \"\",\n\t\t\t\"model_api_type\": \"anthropic\",\n            \"llm_config_params\": {\n                \"cache_seed\": null,\n                \"temperature\": 0.0,\n                \"seed\":12345\n            }\n\t\t}\n    }\n  }\n  ```\n\n- The key is the name of the spec that is passed in `AGENTS_LLM_CONFIG_FILE_REF_KEY`, whereas the Hercules information is passed in sub-dicts `planner_agent` and `nav_agent`.\n\n- **Note**: This option should be ignored until you are sure what you are doing. Discuss with us while playing around with these options in our Slack communication. Join us at our [Slack](https:\u002F\u002Fjoin.slack.com\u002Ft\u002Ftestzeuscommunityhq\u002Fshared_invite\u002Fzt-376oeo99x-3RAWe_C0H7x9zP0rtACcPA)\n\n---\n\n\n## ⚡️ Features\n\nHercules is production ready, and packs a punch with features:\n\n### Gherkin In, Results Out\n\nHercules makes testing as simple as Gherkin in, results out. Just feed your end-to-end tests in Gherkin format, and watch Hercules spring into action. It takes care of the heavy lifting by running your tests automatically and presenting results in a neat JUnit format. No manual steps, no fuss—just efficient, seamless testing.\n\n### Free and Open Source\n\nWith Hercules, you're harnessing the power of open source with zero licensing fees. Feel free to dive into the code, contribute, or customize it to your heart's content. Hercules is as free as it is mighty, giving you the flexibility and control you need.\n\n### Salesforce Ready\n\nBuilt to handle the most intricate UIs, Hercules conquers Salesforce and other complex platforms with ease. Whether it's complicated DOM or running your SOQL or Apex, Hercules is ready and configurable.\n\n### No Code Required\n\nSay goodbye to complex scripts and elusive locators. Hercules is here to make your life easier with its no-code approach, taking care of the automation of Gherkin features so you can focus on what matters most—building quality software.\n\n### Multilingual\n\nWith multilingual support right out of the box, Hercules is ready to work with teams across the globe. Built to bridge language gaps, it empowers diverse teams to collaborate effortlessly on a unified testing platform.\n\n### Precisely Accurate\n\nHercules records video of the execution, and captures network logs as well, so that you dont have to deal with \"It works on my computer\".\n\n\n### No Maintenance\n\nAutonomous and adaptive, Hercules takes care of itself with auto-healing capabilities. Forget about tedious maintenance—Hercules adjusts to changes and stays focused on achieving your testing goals.\n\n### UI Assertions\n\nGrounded in the powerful foundations of TestZeus, Hercules tackles UI assertions with unwavering focus, ensuring that no assertion goes unchecked and no bug goes unnoticed. It's thorough, it's sharp, and it's ready for action.\n\n### CI\u002FCD Ready\n\nRun Hercules locally or integrate it seamlessly into your CI\u002FCD pipeline. Docker-native and one-command ready, Hercules fits smoothly into your deployment workflows, keeping testing quick, consistent, and hassle-free.\n\nWith Hercules, testing is no longer just a step in the process—it's a powerful, streamlined experience that brings quality to the forefront.\n\n### Mobile Device Emulation\n\nHercules supports running the browser in \"mobile mode\" for a variety of device types. Playwright provides a large list of device descriptors here:\n[List of mobile devices supported](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fplaywright\u002Fblob\u002Fmain\u002Fpackages\u002Fplaywright-core\u002Fsrc\u002Fserver\u002FdeviceDescriptorsSource.json)\n\n#### Enabling Mobile Mode\nSet the RUN_DEVICE environment variable in your .env (or directly as an environment variable):\n```bash\nRUN_DEVICE=\"iPhone 15 Pro Max\"\n```\nWhen Hercules runs, it will now launch the browser with the corresponding viewport and user-agent for the chosen device, simulating a real mobile environment.\nHere's a quick demo:\n![MobileDemo](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_45f8d1ae1c3d.gif)\n\n#### Attaching Advanced Tools\nHercules can be extended with more powerful tools for advanced scenarios. Enable it by setting:\n```bash\nLOAD_EXTRA_TOOLS=true\n```\nWith LOAD_EXTRA_TOOLS enabled, Hercules looks for additional tool modules that can expand capabilities (e.g., geolocation handling).\n\nFor location-based tests, configure:\nsupported geo providers are maps.co and google\n```bash\nGEO_API_KEY=somekey\nGEO_PROVIDER=maps_co\n```\nThis allows Hercules to alter or simulate user location during test execution, broadening your test coverage for scenarios that rely on user geography.\n\nNote: If you are looking for native app test automation, we've got you covered, as we've built out early support for Appium powered native app automation [here](https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fpull\u002F41)\n\n---\n\n\n## 🦾 Architecture\n\n### Multi-Agentic Solution\n\nHercules leverages a multi-agent architecture based on the AutoGen framework. Building on the foundation provided by the AutoGen framework, Hercules's architecture leverages the interplay between tools and agents. Each tool embodies an atomic action, a fundamental building block that, when executed, returns a natural language description of its outcome. This granularity allows Hercules to flexibly assemble these tools to tackle complex web automation workflows.\n\n#### System View\n\n![Architecture Diagram](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_eab183f14023.jpg)\n\nThe diagram above shows the configuration chosen on top of AutoGen architecture. The tools can be partitioned differently, but this is the one that we chose for the time being. We chose to use tools that map to what humans learn about the web browser rather than allow the LLM to write code as it pleases. We see the use of configured tools to be safer and more predictable in its outcomes. Certainly, it can click on the wrong things, but at least it is not going to execute malicious unknown code.\n\n\n#### Agents\n\nAt the moment, there are two agents:\n\n1. **Planner Agent**: Executes the planning and decomposition of tasks.\n2. **Browser Navigation Agent**: Embodies all the tools for interacting with the web browser.\n\n#### Tools Library\n\nAt the core of Hercules's capabilities is the Tools Library, a repository of well-defined actions that Hercules can perform; for now, web actions. These tools are grouped into two main categories:\n\n- **Sensing Tools**: Tools like `get_dom_with_content_type` and `geturl` that help Hercules understand the current state of the webpage or the browser.\n- **Action Tools**: Tools that allow Hercules to interact with and manipulate the web environment, such as `click`, `enter_text`, and `openurl`.\n\nEach tool is created with the intention to be as conversational as possible, making the interactions with LLMs more intuitive and error-tolerant. For instance, rather than simply returning a boolean value, a tool might explain in natural language what happened during its execution, enabling the LLM to better understand the context and correct course if necessary.\n\n##### Implemented Tools\n\n- **Sensing Tools**\n\n  - `geturl`: Fetches and returns the current URL.\n  - `get_dom_with_content_type`: Retrieves the HTML DOM of the active page based on the specified content type.\n    - `text_only`: Extracts the inner text of the HTML DOM. Responds with text output.\n    - `input_fields`: Extracts the interactive elements in the DOM (button, input, textarea, etc.) and responds with a compact JSON object.\n    - `all_fields`: Extracts all the fields in the DOM and responds with a compact JSON object.\n  - `get_user_input`: Provides the orchestrator with a mechanism to receive user feedback to disambiguate or seek clarity on fulfilling their request.\n\n- **Action Tools**\n\n  - `click`: Given a DOM query selector, this will click on it.\n  - `enter_text`: Enters text in a field specified by the provided DOM query selector.\n  - `enter_text_and_click`: Optimized method that combines `enter_text` and `click` tools.\n  - `bulk_enter_text`: Optimized method that wraps `enter_text` method so that multiple text entries can be performed in one shot.\n  - `openurl`: Opens the given URL in the current or new tab.\n\n#### DOM Distillation\n\nHercules's approach to managing the vast landscape of HTML DOM is methodical and essential for efficiency. We've introduced **DOM Distillation** to pare down the DOM to just the elements pertinent to the user's task.\n\nIn practice, this means taking the expansive DOM and delivering a more digestible JSON snapshot. This isn't about just reducing size; it's about honing in on relevance, serving the LLMs only what's necessary to fulfill a request. So far, we have three content types:\n\n1. **Text Only**: For when the mission is information retrieval, and the text is the target. No distractions.\n2. **Input Fields**: Zeroing in on elements that call for user interaction. It's about streamlining actions.\n3. **All Content**: The full scope of distilled DOM, encompassing all elements when the task demands a comprehensive understanding.\n\nIt's a surgical procedure, carefully removing extraneous information while preserving the structure and content needed for the agent's operation. Of course, with any distillation, there could be casualties, but the idea is to refine this over time to limit\u002Feliminate them.\n\nSince we can't rely on all web page authors to use best practices, such as adding unique IDs to each HTML element, we had to inject our own attribute (`md`) in every DOM element. We can then guide the LLM to rely on using `md` in the generated DOM queries.\n\nTo cut down on some of the DOM noise, we use the **DOM Accessibility Tree** rather than the regular HTML DOM. The accessibility tree, by nature, is geared towards helping screen readers, which is closer to the mission of web automation than plain old HTML DOM.\n\nThe distillation process is a work in progress. We look to refine this process and condense the DOM further, aiming to make interactions faster, cost-effective, and more accurate.\n\n---\n### Non-Functional Capabilities\n\n#### Security Testing via Nuclei  \nHercules integrates with **Nuclei** to automate vulnerability scanning directly from Gherkin test cases, identifying issues like **misconfigurations, OWASP Top 10 vulnerabilities**, and API flaws. Security reports are generated alongside testing outputs for seamless CI\u002FCD integration.\n\n#### Accessibility Testing  \nHercules supports **WCAG 2.0, 2.1, and 2.2** at **A, AA, and AAA levels**, enabling accessibility testing to ensure compliance with global standards. It identifies accessibility issues early, helping build inclusive and user-friendly applications.\n\n---\n\n## 🔬 Testing and Evaluation: QEvals\n\nWe wanted to ensure that Hercules stands up to the task of end-to-end testing with immense precision. So, we have run Hercules through a wide range of tests such as running APIs, interacting with complex UI scenarios, clicking through calendars, or iframes. A full list of evaluations can be found in the [tests folder](\u003CLink to tests folder>).\n\n### Running Tests\n\nTo run the full test suite, use the following command:\n\n```bash\nmake test\n```\n\nTo run a specific test:\n\n```bash\nmake test-case\n```\n\nHercules builds on the work done by WebArena and Agent-E, and beyond that, to iron out the issues in the previous, we have written our own test cases catering to complex QA scenarios and have created tests in the `.\u002Ftests` folder.\n\n---\n\n## 💡 Opinions\n\nWe believe that great quality comes from opinions about a product. So we have incorporated a few of our opinions into the product design. We welcome the community to question them, use them, or build on top of them. Here are some examples:\n\n1. **Gherkin is a Good Enough Format for Agents**: Gherkin provides a semi-structured format for the LLMs\u002FAI Agents to follow test intent and user instructions. It provides the right amount of grammar (verbs like Given, When, Then) for humans to frame a scenario and agents to follow the instructions.\n\n2. **Tests Should Be Atomic in Nature**: Software tests should be atomic because it ensures that each test is **focused, independent, and reliable**. Atomic tests target one specific behavior or functionality, making it easier to pinpoint the root cause of failures without ambiguity.\n\n   **Here's a good example (Atomic Test)**:\n\n   ```gherkin\n   Feature: User Login\n\n   Scenario: Successful login with valid credentials\n\n     Given the user is on the login page\n     When the user enters valid credentials\n     And the user clicks the login button\n     Then the user should see the dashboard\n   ```\n\n   A non-atomic test confuses both the tester and the AI agent.\n\n3. **Open Core and Open Source**: Hercules is built on an **open-core model**, combining the spirit of open source with the support and expertise of a commercial company, **TestZeus**. By providing Hercules as open source (licensed under AGPL v3), TestZeus is committed to empowering the testing community with a robust, adaptable tool that's freely accessible and modifiable. Open source offers transparency, trust, and collaborative potential, allowing anyone to dive into the code, contribute, and shape the project's direction.\n\n4. **Telemetry** : All great products are built on good feedback. We have setup telemetry so that we can take feedback, without disturbing the user. Telemetry is enabled by default, but we also believe strongly in the values of \"Trust\" and \"Transparency\" so it can be turned off by the users.\n5. **Prompting Hercules** : A detailed guide to write tests for Hercules can be found on our blog [here](https:\u002F\u002Ftestzeus.com\u002Fblog\u002Fmastering-ai-driven-testing-writing-effective-tests-for-hercules) .\n\n---\n\n## 🦾 HyperMind\n\n:jigsaw: Summary\nHercules now gains the power of the Hypermind — a secure, multi-tenant Python sandbox that lets testers inject custom logic, AI-powered heuristics, and human-crafted intelligence directly into test scenarios.\nWhen automation hits a wall, the Hypermind takes over — executing scripts with full Playwright access and controlled permissions.\n\n\n\n:gear: Core Capabilities\nCapability\tDescription\n:brain: Run custom scripts from Gherkin\tInvoke Python functions as test steps.\n:earth_africa: Full Playwright access\tDirect control over browser, page, and context.\n:jigsaw: Auto-injected utilities\tCommon tools (logger, asyncio, json, etc.) preloaded.\n:lock: Multi-tenant isolation\tExecutor, Data, API, and Restricted levels for safety.\n:gear: Dynamic permissions\tControl module access via CLI or environment.\n:camera_with_flash: Execution proofs\tPre\u002Fpost screenshots and JSON execution reports.\n:arrows_counterclockwise: Reusable logic\tUse scripts across features or teams.\n\n\n:toolbox: Usage Example\n**Gherkin**:\n    Feature: Product Filtering\n      Scenario: Apply filter using Hypermind Script\n        Given a user is on the URL as https:\u002F\u002Fexample.com\n        When execute the hypermind script \"scripts\u002Fapply_filter.py\" with filter_type as \"Turtle Neck\"\n        Then the script should report successful filter application\n\n\n\n**Python**: opt\u002Fscripts\u002Fapply_filter.py\n\n    async def apply_filter(filter_type: str) -> dict:\n        \"\"\"Apply filter with fallback strategies.\"\"\"\n        await page.wait_for_selector('[data-filter-section]')\n        for selector in [f'input[value=\"{filter_type}\"]', f'label:has-text(\"{filter_type}\") input']:\n            if await page.locator(selector).count() > 0:\n                await page.locator(selector).click()\n                break\n        count = await page.locator('.product-item').count()\n        return {\"status\": \"success\", \"filter\": filter_type, \"products\": count}\n\n\t\n:checkered_flag: Vision\n“When automation falters, Hypermind awakens.”\nHypermind Scripts represent the next phase of AI-assisted testing — uniting autonomous precision with human adaptability. It’s not just fallback logic; it’s human creativity made executable.\n\n## 🪙 Token Usage\n\nHercules is an AI-native solution and relies on LLMs to perform reasoning and actions. Based on our experiments, we have found that a complex use case as below could cost up to **$0.20** using OpenAI's APIs gpt-4o, check the properties printed in testcase output to calculate for your testcase:\n\n```gherkin\nFeature: Account Creation in Salesforce\n\n Scenario: Successfully create a new account\n\n   Given I am on the Salesforce login page\n   When I enter my username \"user@example.com\" and password \"securePassword\"\n   And I click on the \"Log In\" button\n   And I navigate to the \"Accounts\" tab\n   And I click on the \"New\" button\n   And I fill in the \"Account Name\" field with \"Test Account\"\n   And I select the \"Account Type\" as \"Customer\"\n   And I fill in the \"Website\" field with \"www.testaccount.com\"\n   And I fill in the \"Phone\" field with \"123-456-7890\"\n   And I click on the \"Save\" button\n   Then I should see a confirmation message \"Account Test Account created successfully\"\n   And I should see \"Test Account\" listed in the account records\n```\n\n---\n\n## ⭐️ Difference from Other Tools\n\nHercules isn't just another testing tool—it's an **agent**. Powered by synthetic intelligence that can **think, reason, and react** based on requirements, Hercules goes beyond simple automation scripts. We bring an industry-first approach to open-source agents for **software testing**. This means faster, smarter, and more resilient testing cycles, especially for complex platforms.\n\nWith **industry-leading performance** and a fully open-source foundation, Hercules combines powerful capabilities with community-driven flexibility, making top-tier testing accessible and transformative for everyone.\n\n---\n\n## 🚀 High-Level Roadmap\n\n- **Enhanced LLM Support**: Integration with more LLMs and support for local LLM deployments.\n- **Advanced Tooling**: Addition of more tools to handle complex testing scenarios and environments.\n- **Improved DOM Distillation**: Refinements to the DOM distillation process for better efficiency and accuracy.\n- **Community Contributions**: Encourage and integrate community-driven features and tools.\n- **Extensive Documentation**: Expand documentation for better onboarding and usage.\n- **Bounty Program**: Launch a bounty program to incentivize contributions.\n\n---\n\n## 🤗 Contribution\n\nWe welcome contributions from the community!\n\n- **Read the [CONTRIBUTING.md](CONTRIBUTING.md) file** to get started.\n- **Bounty Program**: Stay tuned for upcoming opportunities! 😀\n\n### How to Contribute Back\n\n1. **Developing Tools**\n\n   - If you are developing tools for Hercules and want to contribute to the community, make sure you place the new tools in the `additional_tools` folder in your Pull Request.\n\n2. **Fixes and Enhancements**\n\n   - If you have a fix on sensing tools that are fundamental to the system or something in prompts or something in the DOM distillation code, then put the changes in the relevant file and share the Pull Request.\n\n### Extending and Attaching Tools\n\n1. **Creating a New Tool**\n\n   - You can start extending by adding tools to Hercules.\n   - Refer to `testzeus_hercules\u002Fcore\u002Ftools\u002Fsql_calls.py` as an example of how to create a new tool.\n   - The key is the decorator `@tool` over the method that you want Hercules to execute.\n   - The tool decorator should have a very clear description and name so that Hercules knows how to use the tool.\n   - Also, in the method, you should be clear with annotations on what parameter is used for what purpose so that function calling in the LLM works best.\n\n2. **Adding the Tool**\n\n   - Once you have created the new tools files in some folder path, you can pass the folder path to Hercules in the environment variable so that Hercules can read the new tools during the boot time and make sure that they are available during the execution.\n   - Use `ADDITIONAL_TOOL_DIRS` to pass the path of the new tools folder where you have kept the new files.\n\n3. **Direct Addition (Not Recommended)**\n\n   - In case you opt for adding the tools directly, then just put your new tools in the `testzeus_hercules\u002Fcore\u002Ftools` path of the cloned repository.\n\n   - **Note**: This way is not recommended. We prefer you try to use the `ADDITIONAL_TOOL_DIRS` approach.\n\n---\n\n## 🤙 Contact Us\n\nJoin us at our [Slack](https:\u002F\u002Fjoin.slack.com\u002Ft\u002Ftestzeuscommunityhq\u002Fshared_invite\u002Fzt-376oeo99x-3RAWe_C0H7x9zP0rtACcPA) to connect with the community, ask questions, and contribute.\n\n---\n\n## ✍️ Examples\n\n- **Salesforce Examples**: [Link](tests\u002Ftest_not_for_ci\u002Febikes\u002Febikes.feature)\n- **Wrangler Example**: [Link](tests\u002Ffuture_test_features\u002FproductSearch\u002FproductSearch.feature)\n\n---\n\n## 🙇 Credits\n\nHercules would not have been possible without the great work from the following sources:\n\n1. [Agent-E](https:\u002F\u002Farxiv.org\u002Fabs\u002F2407.13032)\n2. [Q*](https:\u002F\u002Farxiv.org\u002Fabs\u002F2312.10868)\n3. [Agent Q](https:\u002F\u002Farxiv.org\u002Fabs\u002F2408.07199)\n4. [Autogen](https:\u002F\u002Farxiv.org\u002Fpdf\u002F2308.08155)\n\nThe Hercules project is inferred and enhanced over the existing project of [Agent-E](https:\u002F\u002Fgithub.com\u002FEmergenceAI\u002FAgent-E). We have improved lots of cases to make it capable of doing testing, especially in the area of complex DOM navigation and iframes. We have also added new tools and abilities (like Salesforce navigation) to Hercules so that it can perform better work over the base framework we had picked.\n\nHercules also picks some inspiration from the legacy TestZeus repo [here](https:\u002F\u002Fwww.testzeus.org).\n\n\n---\n\nWith Hercules, testing is no longer just a step in the process—it's a powerful, streamlined experience that brings quality to the forefront.\n\n\n## 🚀 Footnotes: On virtual environments and other important commands in Python\n\nIf you're coming from a **Java** or **JavaScript** background, working with Python might feel a bit different at first—but don't worry! Python's simplicity, combined with powerful tools like virtual environments, makes managing dependencies easy and efficient.\n\n### 🎓 **Understanding Virtual Environments**\n\nIn Java, you might use tools like Maven or Gradle to manage project dependencies, or in JavaScript, you'd use `npm` or `yarn`. In Python, **virtual environments** serve a similar purpose. They allow you to create isolated spaces for your project's dependencies, avoiding conflicts with other Python projects on your system.\n\nThink of it like a sandboxed environment where TestZeus Hercules and its dependencies live independently from other Python packages.\n\n\n### 🏗️ **Setup Instructions**\n\n#### ✅ **1. Prerequisites**\n\nFirst, ensure Python 3.11 or higher is installed. You can verify this by running:\n\n```bash\npython --version\n# or\npython3 --version\n```\n\nIf Python isn't installed, [download it here](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F) or if you are on Windows, just follow the instructions [here](https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002F#%EF%B8%8F-running-hercules-on-a-windows-machine).\n\n---\n\n#### 🏰 **2. Creating and Activating a Virtual Environment**\n\nTo set up a clean Python environment for your project:\n\n```bash\n# Create a virtual environment named 'venv'\npython -m venv venv\n\n# Activate the virtual environment\n# On Windows:\nvenv\\Scripts\\activate\n\n# On macOS\u002FLinux:\nsource venv\u002Fbin\u002Factivate\n```\n\nYou'll notice your terminal prompt changes—this indicates the virtual environment is active.\n\nTo **deactivate** the virtual environment later, simply run:\n```bash\ndeactivate\n```\n\n---\n\n#### 📥 **3. Installing TestZeus Hercules**\n\nOnce your virtual environment is activated, install the latest version of TestZeus Hercules directly from PyPI:\n\n```bash\npip install testzeus-hercules\n```\n\n---\n\n#### 🔄 **4. Updating TestZeus Hercules**\n\nTo update to the latest version, use:\n\n```bash\npip install --upgrade testzeus-hercules\n```\n\n---\n\n#### ❌ **5. Uninstalling TestZeus Hercules**\n\nIf you need to remove the package:\n\n```bash\npip uninstall testzeus-hercules\n```\n\n---\n\n#### 🔍 **6. Checking Installed Packages**\n\nTo verify that TestZeus Hercules is installed and check its version:\n\n```bash\npip list\n```\n\n---\n\n### 🔗 **Additional Tips for Java\u002FJS Developers**\n\n- **`pip`** is like `npm` or `mvn`—it's used for installing and managing Python packages.\n- Python's simplicity means fewer configuration files—most things can be done directly from the command line.\n\n---\n\n### 💡 **Next Steps**\n\nNow that TestZeus Hercules is installed and ready to go, dive into [our documentation](https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002F) to learn how to create and run your first test cases with ease!\n\n---\n\n## Star History\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_d965aae7f5e9.png)](https:\u002F\u002Fstar-history.com\u002F#test-zeus-ai\u002Ftestzeus-hercules&Date)\n\n## ✅ Citation\nIf you use Hercules in your research or project, please cite:\n\n```\n@software{testzeus_hercules2024,\n  author = {Agnihotri, Shriyansh and Gupta, Robin},\n  title = {Hercules: World's first open source testing agent},\n  year = {2024},\n  publisher = {GitHub},\n  url = {https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002F}\n}\n```\n","\u003Cimg width=\"100\" height=\"100\" alt=\"2\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_e86b35709617.png\" \u002F>\n\n# 💪 Hercules\n\n[![PyPI Total Downloads](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_67b3ed9b5254.png)](https:\u002F\u002Fpepy.tech\u002Fprojects\u002Ftestzeus-hercules)\n![Docker Pulls](https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fpulls\u002Ftestzeus\u002Fhercules)\n[![CI Test](https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Factions\u002Fworkflows\u002Fmain-test.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Factions\u002Fworkflows\u002Fmain-test.yml)\n[![Slack](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fslack-TestZeus-brightgreen.svg?logo=slack)](https:\u002F\u002Fjoin.slack.com\u002Ft\u002Ftestzeuscommunityhq\u002Fshared_invite\u002Fzt-376oeo99x-3RAWe_C0H7x9zP0rtACcPA)\n\n测试现代 Web 应用程序可能非常困难，频繁的变更和复杂的功能让人难以跟上节奏。这就是 **Hercules** 的用武之地。Hercules 是全球首个开源测试智能体（testing agent），专为应对最棘手的测试任务而构建，让你无需亲自动手。它能将简单易写的 Gherkin 步骤自动转换为完整的 **端到端（end to end）** 测试——无需任何编码技能。无论你是在处理像 Salesforce 这样复杂的平台，还是在 CI\u002FCD 流水线中运行测试，Hercules 都能灵活适配你的需求并处理所有细节。借助 Hercules，测试变得简单、可靠且高效，帮助全球团队交付更优质的软件。以下是一个使用自然语言编写的测试用例（无需代码）创建潜在客户（lead）的快速演示：\n\n![HerculesUsage](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_2a1c8ad1acf5.gif)\n\n\n\n如你所见，使用 Hercules 就像输入你的 Gherkin 特性文件并获取结果一样简单：\n![HerculesUsage](statics\u002Fassets\u002Fhercules.svg)\n\n在 [TestZeus](www.testzeus.com)，我们坚信 **可信赖且开源的代码** 是创新的基石。因此，我们打造了 Hercules，使其具备透明性、可靠性，并由社区驱动。\n\n我们的使命？**让测试自动化民主化并颠覆传统**，使顶级测试能力不再仅为少数精英所享有，而是人人皆可使用。不再有技术壁垒——每个测试团队都值得拥有一位英雄！\n\n### 视频教程：[@TestZeus](https:\u002F\u002Fwww.youtube.com\u002F@TestZeus)\n---\n\n#### 🚀 **TestZeus Hercules 快速入门**\n- **TestZeus Hercules 简介**  \n  了解 TestZeus Hercules 的核心功能，以及它如何为你的项目简化端到端测试。  \n  [![Autonomous execution with Hercules](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_2922fc71778a.png)](https:\u002F\u002Fyoutu.be\u002F_m_NDjM6aZ0?si=ArtVKz8uSgGWTcAK)\n\n- **安装与设置指南**  \n  分步指导如何在你的环境中安装和配置 TestZeus Hercules。  \n  _[立即观看](https:\u002F\u002Fyoutu.be\u002F9D-SZGoDrfc?si=GL0IArWkB1ZgBdx5)_\n\n---\n\n#### 🧪 **编写与执行测试用例**\n- **创建 BDD 测试用例**  \n  学习如何为 Hercules 编写行为驱动开发（Behavior-Driven Development, BDD）测试用例，并使用动态测试数据。  \n  _[立即观看](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=yJD0cZ7Bx6Q&t)_\n\n---\n\n#### 🌐 **集成与高级功能**\n- **多语言内容测试**  \n  了解 Hercules 如何通过多语言测试用例与 Web 浏览器交互，执行多语言内容的测试。  \n  _[立即观看](https:\u002F\u002Fyoutu.be\u002FvI9iGSqKpGA?si=6NGAvKnwFboSyHT2)_\n---\n\n#### 🛠️ **自定义与社区工具**\n- **使用社区驱动的工具增强 Hercules**  \n  探索如何自定义 Hercules 并集成社区提供的额外工具。  \n  _[立即观看](https:\u002F\u002Fyoutu.be\u002FC8hUy5leRF0?si=yVMpZ7WFcI01BoI3)_\n---\n\n#### 🛠️ **API 测试**\n- **全方位 API 测试，端到端的新方式**  \n  _[立即观看](https:\u002F\u002Fyoutu.be\u002FqMt89DQH6LQ?si=lcSJbKOCaqqUGeQ8)_\n---\n\n#### 🛠️ **安全测试**\n- **端到端的安全测试**  \n  _[立即观看](https:\u002F\u002Fyoutu.be\u002Fo6MmfTakIh4?si=JL8iu4e3i85SWrxU)_\n\n#### 🛠️ **视觉验证与断言**\n- **利用视觉能力检查应用中的快照和组件**  \n  _[立即观看](https:\u002F\u002Fyoutu.be\u002FEKzllLEguhw)_\n\n#### 🐍 **Python 沙箱执行（Python Sandbox Execution）**\n- **直接从 Gherkin 测试中执行自定义 Python 脚本**  \n  运行复杂的自动化工作流、自定义业务逻辑和可复用组件，并拥有完整的 Playwright 访问权限。非常适合需要高级选择器策略、条件逻辑或数据处理的场景。[阅读文档](docs\u002Fpython_sandbox_execution.md)\n\n**快速示例：**\n```gherkin\n# 在你的 feature 文件中\nAnd execute the apply_filter function from script at \"scripts\u002Fapply_filter.py\" with filter_type as \"Turtle Neck\"\n```\n\n```python\n# 在 opt\u002Fscripts\u002Fapply_filter.py 中\nasync def apply_filter(filter_type: str) -> dict:\n    \"\"\"Apply filter with multiple fallback strategies.\"\"\"\n    # page, logger 和其他工具自动可用！\n    await page.wait_for_selector('[data-filter-section]')\n    \n    # 尝试多种选择器策略\n    for selector in [f'input[value=\"{filter_type}\"]', \n                     f'label:has-text(\"{filter_type}\") input']:\n        if await page.locator(selector).count() > 0:\n            await page.locator(selector).click()\n            break\n    \n    return {\"status\": \"success\", \"filter\": filter_type}\n```\n\n**特性：**\n- 🎯 完整的 Playwright API 访问权限\n- 🔒 多租户安全机制（执行器、数据、API、受限模式）\n- 📦 自动注入模块（page、browser、logger、asyncio 等）\n- 🔄 可在多个测试中复用\n- ⚙️ 可通过环境变量配置\n\n**配置方式：**\n```bash\n# 设置租户以控制模块访问权限\nexport SANDBOX_TENANT_ID=\"executor_agent\"  # 完全访问权限：requests、pandas、numpy、BeautifulSoup\n\n# 或通过 CLI 使用\nhercules --sandbox-tenant-id executor_agent --input-file test.feature\n```\n\n---\n\n## ⚙️ 安装与使用\n\nHercules 提供多种入门方式，以满足不同用户的偏好和需求。  \n如果你刚接触 Python 生态系统，不知道从何开始，别担心，请阅读文末关于基础知识的说明。\n\n若想快速体验该解决方案，你可以尝试以下 Notebook：  \n[![Open In Colab](https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg)](https:\u002F\u002Fcolab.research.google.com\u002Fdrive\u002F1YiZsXem1POTwkcr17QqflXnihhuSqwM2?usp=sharing)\n- **注意**：Colab 可能会提示你重启会话，因为在安装 testzeus-hercules 时会安装 python3.11 和部分依赖库。如有需要，请重启会话后继续执行。此外，我们建议采用以下方法之一，以获得完整的解决方案体验。\n\n### 方法一：使用 PyPI 包\n\n#### 安装\n\n从 PyPI 安装 Hercules：\n\n```bash\npip install testzeus-hercules\n```\n\nHercules 使用 Playwright（一个用于与网页交互的自动化工具）来操作网页，因此你需要安装 Playwright 及其依赖项：\n\n```bash\nplaywright install --with-deps\n```\n\n有关项目结构和运行测试的详细信息，请参阅我们的 [运行指南](docs\u002Frun_guide.md)。\n\n#### 基本参数\n\n安装完成后，你需要提供一些基本参数来运行 Hercules：\n\n- `--input-file INPUT_FILE`：待测试的 Gherkin feature 文件路径。\n- `--output-path OUTPUT_PATH`：输出目录路径。测试运行生成的 JUnit XML 结果和 HTML 报告将保存在此路径下。\n- `--test-data-path TEST_DATA_PATH`：测试数据目录路径。Hercules 期望测试数据位于此路径下；所有在 feature 测试中使用的测试数据都应存放于此。\n- `--project-base PROJECT_BASE`：项目根目录路径。这是一个可选参数；如果提供了该参数，则无需再指定 `--input-file`、`--output-path` 和 `--test-data-path`，Hercules 会假定这三个文件夹以如下格式存在于项目根目录中：\n\n```\nPROJECT_BASE\u002F\n├── gherkin_files\u002F\n├── input\u002F\n│   └── test.feature\n├── log_files\u002F\n├── output\u002F\n│   ├── test.feature_result.html\n│   └── test.feature_result.xml\n├── proofs\u002F\n│   └── User_opens_Google_homepage\u002F\n│       ├── network_logs.json\n│       ├── screenshots\u002F\n│       └── videos\u002F\n└── test_data\u002F\n    └── test_data.txt\n```\n\n- `--llm-model LLM_MODEL`：Agent 使用的 LLM（大语言模型，Large Language Model）名称（推荐使用 `gpt-4o`，但也支持其他模型）。\n- `--llm-model-api-key LLM_MODEL_API_KEY`：LLM 模型的 API 密钥，例如 `sk-proj-k.......`。\n\n#### 环境变量\n\n除了命令行参数外，Hercules 还支持通过多种环境变量进行配置：\n\n- `BROWSER_TYPE`：使用的浏览器类型（`chromium`、`firefox`、`webkit`）。默认值：`chromium`\n- `HEADLESS`：是否以无头模式（headless mode）运行浏览器（`true`、`false`）。默认值：`true`\n- `BROWSER_RESOLUTION`：浏览器窗口分辨率（格式：`宽度,高度`）。示例：`1920,1080`\n- `BROWSER_COOKIES`：为浏览器上下文设置 Cookie。格式：Cookie 对象的 JSON 数组。示例：`[{\"name\": \"session\", \"value\": \"123456\", \"domain\": \"example.com\", \"path\": \"\u002F\"}]`\n- `RECORD_VIDEO`：是否录制测试执行视频（`true`、`false`）。默认值：`true`\n- `TAKE_SCREENSHOTS`：测试过程中是否截取屏幕截图（`true`、`false`）。默认值：`true`\n\n完整的环境变量列表请参见我们的 [环境变量指南](docs\u002Fenvironment_variables.md)。\n\n#### 运行 Hercules\n\n在传入所有必需参数后，运行 Hercules 的命令应如下所示：\n\n```bash\ntestzeus-hercules --input-file opt\u002Finput\u002Ftest.feature --output-path opt\u002Foutput --test-data-path opt\u002Ftest_data --llm-model gpt-4o --llm-model-api-key sk-proj-k.......\n```\n\n## ⚙️ 在 Windows 机器上运行 Hercules\n\n要在 Windows 机器上设置并运行 Hercules，请按以下步骤操作：\n\n1. **以管理员模式打开 PowerShell：**\n   - 点击**开始菜单**，搜索 **PowerShell**，然后右键点击 **Windows PowerShell**。\n   - 选择 **以管理员身份运行**，以管理员模式打开 PowerShell。\n\n2. **导航到辅助脚本文件夹：**\n   - 使用 `cd` 命令进入包含 `hercules_windows_setup.ps1` 脚本的文件夹。例如：\n     ```powershell\n     cd path\\to\\helper_scripts\n     ```\n\n3. **运行设置脚本：**\n   - 执行脚本来安装和配置 Hercules：\n     ```powershell\n     .\\hercules_windows_setup.ps1\n     ```\n\n4. **按照屏幕提示操作：**\n   - 脚本将引导您安装 Python、Playwright、FFmpeg 以及其他必需的依赖项。\n\n5. **运行 Hercules：**\n   - 设置完成后，您可以使用以下命令在 PowerShell 或命令提示符中运行 Hercules：\n     ```bash\n     testzeus-hercules --input-file opt\u002Finput\u002Ftest.feature --output-path opt\u002Foutput --test-data-path opt\u002Ftest_data --llm-model gpt-4o --llm-model-api-key sk-proj-k.......\n     ```\n\n---\n\n\n#### TestZeus-Hercules 支持的 AI 模型（AI Models）\n- Anthropic：兼容 Haiku 3.5 及以上版本。\n- Groq：支持任何具备函数调用（function calling）和代码生成能力的版本。\n- Mistral：支持任何具备函数调用和代码生成能力的版本，如 Mistral-large、Mistral-medium。仅限重型模型（heavy models）。\n- OpenAI：完全兼容 GPT-4o\u002Fo3-mini 及以上版本。注意：OpenAI GPT-4o-mini 仅支持用于子代理（sub-agents），对于规划器（planner）仍建议使用 GPT-4o。\n- Ollama：支持具备函数调用能力的中型模型；重型模型仅支持 70b 及以上版本。\n- Gemini：可以使用，推荐通过 LiteLLM（如下所示）方式接入。\n- Deepseek：仅支持 deepseek-chat v3。\n- 托管平台（Hosting）：支持 AWS Bedrock、GCP VertexAI、AzureAI。[已测试模型包括 OpenAI、Anthropic Sonnet 和 Haiku、具备函数调用能力的 Llama 60b 以上模型]\n\n注意：请确保您使用的模型能够处理代理类任务（agentic activities），例如函数调用。例如较大的模型如 OpenAI GPT-4o、Llama >70B、Mistral large 等。您可以使用如下 agent_config 文件填写 LiteLLM 的详细信息 [https:\u002F\u002Fdocs.litellm.ai\u002Fdocs\u002Fsimple_proxy]：\n```JSON\n{\n  \"litellm-flash\": {\n    \"planner_agent\": {\n      \"model_name\": \"gemini-2.5-flash\",\n      \"model_api_key\": \"sfasdfsadgbw\",\n      \"model_base_url\": \"https:\u002F\u002Flitellm-proxydeployment\",\n      \"llm_config_params\": {\n        \"cache_seed\": 1234,\n        \"temperature\": 0,\n        \"seed\": 12345\n      }\n    },\n    \"nav_agent\":  {\n      \"model_name\": \"gemini-2.5-flash\",\n      \"model_api_key\": \"sfasdfsadgbw\",\n      \"model_base_url\": \"https:\u002F\u002Flitellm-proxydeployment\",\n      \"llm_config_params\": {\n        \"cache_seed\": 1234,\n        \"temperature\": 0,\n        \"seed\": 12345\n      }\n    },\n    \"mem_agent\":  {\n      \"model_name\": \"gemini-2.5-flash\",\n      \"model_api_key\": \"sfasdfsadgbw\",\n      \"model_base_url\": \"https:\u002F\u002Flitellm-proxydeployment\",\n      \"llm_config_params\": {\n        \"cache_seed\": 1234,\n        \"temperature\": 0,\n        \"seed\": 12345\n      }\n    },\n    \"helper_agent\":  {\n      \"model_name\": \"gemini-2.5-flash\",\n      \"model_api_key\": \"sfasdfsadgbw\",\n      \"model_base_url\": \"https:\u002F\u002Flitellm-proxydeployment\",\n      \"llm_config_params\": {\n        \"cache_seed\": 1234,\n        \"temperature\": 0,\n        \"seed\": 12345\n      }\n    }\n  }\n}\n```\n\n#### 执行流程（Execution Flow）\n\n运行命令后：\n\n- Hercules 将启动并尝试打开一个网页浏览器（默认为 Chromium）。\n- 它将根据提供的 feature 文件中的步骤制定执行计划。\n- 该计划会将 feature 文件中简略的步骤扩展为更详细的版本。\n- Hercules 会检测 feature 文件中的断言（assertions），并在测试运行期间规划对预期结果的验证。\n- 所有扩展后的步骤将根据其执行需求类型传递给不同的工具。例如，如果某一步骤需要点击按钮并捕获反馈，则会传递给 `click_using_selector` 工具。\n\n#### 输出与日志（Output and Logs）\n\n执行完成后：\n\n- 会生成描述事件顺序的日志。\n- 最佳查看位置是 `output-path` 目录，其中包含 JUnit XML 结果文件以及关于测试用例执行情况的 HTML 报告。\n- 您还可以在 `proofs` 文件夹中找到执行证据，例如视频录制、每个事件的截图和网络日志。\n- 若要深入了解代理的思考链（chain of thoughts），请参考 `log_files` 中的 `chat_messages.json` 文件，其中包含代理实际规划的详细步骤。\n\n#### 示例 Feature 文件（Sample Feature File）\n\n以下是一个示例 feature 文件：\n\n```gherkin\nFeature: 在 Salesforce 中创建账户\n\n Scenario: 成功创建新账户\n\n   Given 我位于 Salesforce 登录页面\n   When 我输入用户名 \"user@example.com\" 和密码 \"securePassword\"\n   And 我点击 \"Log In\" 按钮\n   And 我导航至 \"Accounts\" 标签页\n   And 我点击 \"New\" 按钮\n   And 我在 \"Account Name\" 字段中填入 \"Test Account\"\n   And 我将 \"Account Type\" 选择为 \"Customer\"\n   And 我在 \"Website\" 字段中填入 \"www.testaccount.com\"\n   And 我在 \"Phone\" 字段中填入 \"123-456-7890\"\n   And 我点击 \"Save\" 按钮\n   Then 我应看到确认消息 \"Account Test Account created successfully\"\n   And 我应在账户记录中看到 \"Test Account\"\n```\n\n#### 示例结果截图（Sample Result Screenshot）\n\n##### HTML 结果示例截图\n![Sample HTML Result](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_1f58199e18a4.png)\n##### XML 结果示例截图\n![Sample XML Result](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_766d64f4936f.png)\n\n---\n\n### 方法 2：使用 Docker\n\n对于所有追求可扩展性的用户，Hercules 也提供了 Docker 镜像。\n\n#### 拉取 Docker 镜像\n\n```bash\ndocker pull testzeus\u002Fhercules:latest\n```\n\n#### 在 Docker 中运行 Hercules\n\n使用以下命令运行容器：\n\n```bash\ndocker run --env-file=.env \\\n  -v .\u002Fagents_llm_config.json:\u002Ftestzeus-hercules\u002Fagents_llm_config.json \\\n  -v .\u002Fopt:\u002Ftestzeus-hercules\u002Fopt \\\n  --rm -it testzeus\u002Fhercules:latest\n```\n\n- **环境变量（Environment Variables）**：所有必需的环境变量都可以通过在 `docker run` 命令中传入 `.env` 文件来设置。\n- **LLM 配置（LLM Configuration）**：如果你希望完全控制 Hercules 所使用的 LLM（大语言模型，Large Language Model），而不仅限于 OpenAI 提供的选项，可以将 `agents_llm_config.json` 文件挂载到容器中。这适用于高级用例，初学者无需配置。详情请参考示例文件 `.env-example` 和 `agents_llm_config-example.json`。\n- **目录挂载（Mounting Directories）**：将 `opt` 文件夹挂载到 Docker 容器中，以便将所有输入传递给容器内运行的 Hercules，并将输出提取出来进行后续处理。代码仓库中已包含一个可直接挂载的示例 `opt` 文件夹。\n- **简化参数（Simplified Parameters）**：在 Docker 模式下，无需使用 `--input-file`、`--output-path`、`--test-data-path` 或 `--project-base` 参数，因为这些功能已通过在 `docker run` 命令中挂载 `opt` 文件夹自动处理。\n\n#### Docker 中的浏览器访问\n\n- 在 Docker 模式下运行时，请注意 Hercules 只能访问无头（headless）网页浏览器。\n- 如果你希望 Hercules 连接到可见的网页浏览器，可以在环境文件中尝试使用 CDP URL（Chrome DevTools Protocol URL）选项。该选项可帮助你将运行在本地基础设施中的 Hercules 连接到远程浏览器（如 BrowserBase）或自托管的浏览器网格（browser grid）。\n- 使用 `CDP_ENDPOINT_URL` 来设置需要连接到代理（agent）的 Chrome 实例的 CDP URL。\n\n### Docker 与远程浏览器支持\n\n在 Docker 中运行 Hercules 时，你可以通过多种平台连接到远程浏览器实例：\n\n1. **BrowserStack 集成**：\n```bash\nexport BROWSERSTACK_USERNAME=your_username\nexport BROWSERSTACK_ACCESS_KEY=your_access_key\nexport CDP_ENDPOINT_URL=$(python helper_scripts\u002Fbrowser_stack_generate_cdp_url.py)\n```\n\n2. **LambdaTest 集成**：\n```bash\nexport LAMBDATEST_USERNAME=your_username\nexport LAMBDATEST_ACCESS_KEY=your_access_key\nexport CDP_ENDPOINT_URL=$(python helper_scripts\u002Flambda_test_generate_cdp_url.py)\n```\n\n3. **BrowserBase 集成**：\n```bash\nexport CDP_ENDPOINT_URL=wss:\u002F\u002Fconnect.browserbase.com?apiKey=your_api_key\n```\n\n4. **AnchorBrowser 集成**：\n```bash\nexport CDP_ENDPOINT_URL=wss:\u002F\u002Fconnect.anchorbrowser.io?apiKey=your_api_key\n```\n\n注意：视频录制仅在使用 `connect_over_cdp` 的平台（BrowserBase、AnchorBrowser）上支持。使用 connect API 的平台（BrowserStack、LambdaTest）不支持视频录制。\n\n#### 输出与日志\n\n命令执行完成后：\n\n- 容器会终止，输出内容将写入挂载的 `opt` 文件夹中，其结构与前述目录结构一致。\n- 你可以在相应子文件夹中找到 JUnit XML 结果文件、HTML 报告、执行证明（proofs of execution）以及日志。\n\n---\n\n### 方法 3：从源代码构建并运行\n\n对于硬核爱好者，你可以通过源代码使用 Hercules，以获得完整的自定义体验，并扩展 Hercules 以集成更多工具。\n\n#### 先决条件\n\n- 确保你的系统已安装 **Python 3.11**。\n\n#### 从源代码运行的步骤\n\n1. **克隆仓库**\n\n   ```bash\n   git clone git@github.com:test-zeus-ai\u002Ftestzeus-hercules.git\n   ```\n\n2. **进入目录**\n\n   ```bash\n   cd testzeus-hercules\n   ```\n\n3. **使用 Make 命令**\n\n   本仓库提供了便捷的 `make` 命令。\n\n   - 使用 `make help` 查看可用选项。\n\n4. **安装 UV**\n\n   ```bash\n   make setup-uv\n   ```\n\n5. **安装依赖**\n\n   ```bash\n   make install\n   ```\n\n6. **运行 Hercules**\n\n   ```bash\n   make run\n   ```\n\n   - 此命令会从 `opt` 文件夹中读取相关的 feature 文件并执行，将输出结果保存在同一文件夹中。\n   - `opt` 文件夹的结构如下：\n\n     ```\n     opt\u002F\n     ├── input\u002F\n     │   └── test.feature\n     ├── output\u002F\n     │   ├── test.feature_result.html\n     │   └── test.feature_result.xml\n     ├── log_files\u002F\n     ├── proofs\u002F\n     │   └── User_opens_Google_homepage\u002F\n     │       ├── network_logs.json\n     │       ├── screenshots\u002F\n     │       └── videos\u002F\n     └── test_data\u002F\n         └── test_data.txt\n     ```\n\n7. **交互模式**\n\n   你也可以以交互模式运行 Hercules，将其作为指令执行代理（instruction execution agent）。这种方式在开发新工具、扩展代理功能，或在新环境中调试测试用例和 Hercules 行为时尤为有用。\n\n   ```bash\n   make run-interactive\n   ```\n\n   - 这将触发一个输入提示符，你可以与 Hercules 对话，它将根据你的指令执行相应操作。\n\n### 方法 4：通过 helper_script_custom.sh 进行设置\n\n对于希望在 Linux\u002FmacOS 环境中获得全自动设置体验的用户，我们提供了一个 helper_script.sh 脚本。该脚本会（如需要）安装 Python 3.11，创建虚拟环境，安装 TestZeus Hercules，并在 opt 文件夹中设置基础项目目录。\n\n#### 先决条件\n\n- 确保系统中已安装 **Python 3.11**。\n\n#### 通过 helper_script_custom.sh 运行的步骤\n1. **下载或创建脚本**\n  您可以将以下脚本复制到名为 helper_script_custom.sh 的文件中：\n  ```bash\n  #!\u002Fbin\u002Fbash\n  # set -ex\n\n  # curl -sS https:\u002F\u002Fbootstrap.pypa.io\u002Fget-pip.py | python3.11\n\n  # 创建名为 'test' 的新 Python 虚拟环境\n  python3.11 -m venv test\n\n  # 激活虚拟环境\n  source test\u002Fbin\u002Factivate\n\n  # 升级 'testzeus-hercules' 包\n  pip install --upgrade testzeus-hercules\n  playwright install --with-deps\n\n  # 创建名为 'opt' 的新目录\n  mkdir -p opt\u002Finput opt\u002Foutput opt\u002Ftest_data\n\n  # 下载 https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Frefs\u002Fheads\u002Fmain\u002Fagents_llm_config-example.json\n  curl -sS https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fmain\u002Fagents_llm_config-example.json > agents_llm_config-example.json\n  mv agents_llm_config-example.json agents_llm_config.json\n\n  # 提示用户需要编辑 'agents_llm_config.json' 文件，暂停脚本并打开该文件进行编辑\n  echo \"请编辑 'agents_llm_config.json' 文件以添加您的 API 密钥和其他配置。\"\n\n  # 暂停脚本，并显示 agents_llm_config.json 文件的绝对路径，以便用户在编辑器中打开\n  echo \"文件 'agents_llm_config.json' 位于 $(pwd)\u002Fagents_llm_config.json\"\n  read -p \"如果文件已更新，请按 Enter 键继续\"\n\n  # 下载 https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fblob\u002Fmain\u002F.env-example\n  curl -sS https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fmain\u002F.env-example > .env-example\n  mv .env-example .env\n\n  # 提示用户需要编辑 .env 文件，暂停脚本并打开该文件进行编辑\n  echo \"文件 '.env' 位于 $(pwd)\u002F.env\"\n  read -p \"如果文件已更新，请按 Enter 键继续\"\n\n  # 创建 input\u002Ftest.feature 文件\n  # 下载 https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Frefs\u002Fheads\u002Fmain\u002Fopt\u002Finput\u002Ftest.feature 并保存为 opt\u002Finput\u002Ftest.feature\n  curl -sS https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fmain\u002Fopt\u002Finput\u002Ftest.feature > opt\u002Finput\u002Ftest.feature\n\n  # 下载 https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Frefs\u002Fheads\u002Fmain\u002Fopt\u002Ftest_data\u002Ftest_data.json 并保存为 opt\u002Ftest_data\u002Ftest_data.json\n  curl -sS https:\u002F\u002Fraw.githubusercontent.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fmain\u002Fopt\u002Ftest_data\u002Ftest_data.json > opt\u002Ftest_data\u002Ftest_data.json\n\n  # 使用指定参数运行 'testzeus-hercules' 命令\n  testzeus-hercules --project-base=opt\n  ```\n2. **赋予脚本执行权限并运行**\n```bash\nchmod +x helper_script.sh\n.\u002Fhelper_script.sh\n```\n-\t该脚本将：\n\t•\t创建一个名为 test 的 Python 3.11 虚拟环境。\n\t•\t安装 testzeus-hercules 和 Playwright（浏览器自动化工具）依赖项。\n\t•\t创建 opt 文件夹结构（用于输入\u002F输出\u002F测试数据）。\n\t•\t下载示例配置文件：agents_llm_config.json、.env 以及示例 feature\u002F测试数据文件。\n\t•\t重要提示：您将被要求编辑 agents_llm_config.json 和 .env 文件。在您添加了 API 密钥及其他自定义配置后，请按 Enter 键继续。\n\n3. **脚本输出**\n\t-\t完成后，脚本将自动运行 testzeus-hercules --project-base=opt。\n\t-\t您的日志和结果将出现在 opt\u002Foutput、opt\u002Flog_files 和 opt\u002Fproofs 目录中。\n---\n\n## 📝 配置详情\n\n有关 TestZeus Hercules 中所有可用环境变量和配置选项的完整指南，请参阅我们的 [环境变量与配置指南](docs\u002Fenvironment_variables.md)。该文档详细介绍了核心环境变量、LLM（大语言模型）配置、浏览器设置、测试配置、设备配置、日志选项等内容。\n\n### 禁用遥测（Telemetry）\n\n要禁用遥测功能，请将 `TELEMETRY_ENABLED` 环境变量设为 `0`：\n\n```bash\nexport TELEMETRY_ENABLED=0\n```\n\n### 自动模式（Auto Mode）\n\n如果将 `AUTO_MODE` 设为 `1`，Hercules 在运行期间将不会请求输入邮箱地址：\n\n```bash\nexport AUTO_MODE=1\n```\n\n### 理解环境文件（`.env`）\n\n要详细配置 Hercules：\n\n- 复制基础环境文件：\n\n  ```bash\n  cp .env-example .env\n  ```\n\n## 🔌 MCP 支持\n\nHercules 内置了一个 MCP（Model Context Protocol）导航代理，可通过 `stdio`、`sse` 和 `streamable-http` 与 MCP 服务器连接。它可直接与 Composio 生成的 MCP 服务器配合使用。\n\n- 快速入门指南：参见 `docs\u002FMCP_Usage.md`\n- Composio 文档：https:\u002F\u002Fdocs.composio.dev\u002Fdocs\u002Fmcp-developers\n\n最小化设置步骤：\n\n1) 在仓库根目录创建 `mcp_servers.json`：\n\n```\n{\n  \"mcpServers\": {\n    \"server_name\": {\n      \"transport\": \"streamable-http\",\n      \"url\": \"https:\u002F\u002Fmcp.composio.dev\u002Fcomposio\u002Fserver\u002F\u003CSERVER_UUID>\u002Fmcp?user_id=\u003CUSER_EMAIL>\"\n    }\n  }\n}\n```\n\n2) 在 `.env` 中配置：\n\n```\nMCP_ENABLED=true\nMCP_SERVERS=mcp_servers.json\nMCP_TIMEOUT=30\n```\n\n然后像往常一样运行 Hercules；MCP 代理将自动初始化，并暴露所配置服务器中的工具。\n\n### 示例测试用例（简单版）\n```\nFeature: 从 Gmail 读取邮件\n\n  Scenario: 使用 MCP 从 Gmail 获取 OTP\n    Given Gmail 已通过 MCP 配置完成\n    When 我连接到 Gmail\n    And 我读取包含 OTP 的邮件\n```\n更多测试用例请参阅 [MCP-Docs](\u002Fdocs\u002FMCP_Usage.md)\n\n---\n- Hercules 支持以下两种配置方式：\n\n  1. **使用单一 LLM（大语言模型，Large Language Model）处理所有任务**\n\n     - 对于代理（agent）内的所有活动，请初始化 `LLM_MODEL_NAME` 和 `LLM_MODEL_API_KEY`。\n     - 如果使用的是非 OpenAI 托管但兼容 OpenAI 接口的 LLM（例如通过 Groq 提供的 OpenAI 模型），还需额外提供 `LLM_MODEL_BASE_URL`。\n\n  2. **为不同任务配置自定义 LLM 或使用托管 LLM**\n\n     - 如果你计划配置本地 LLM 或非 OpenAI 的 LLM，请使用其他参数，如 `AGENTS_LLM_CONFIG_FILE` 和 `AGENTS_LLM_CONFIG_FILE_REF_KEY`。\n     - 这些是高级选项，可能会影响 Hercules 输出的质量。\n\n- Hercules 默认以 `.\u002Fopt` 作为基础目录，但可通过环境变量 `PROJECT_SOURCE_ROOT` 进行更改。\n\n- **连接到现有 Chrome 实例**\n\n  - 当你在 Docker 中运行 Hercules 以实现规模化时，此功能非常有用。\n  - 你可以将运行在你基础设施中的 Hercules 连接到远程浏览器（如 BrowserBase 或你自建的浏览器网格）。\n  - 使用 `CDP_ENDPOINT_URL` 设置要连接的 Chrome 实例的 CDP（Chrome DevTools Protocol）URL。\n\n- **控制其他行为**\n\n  你可以通过以下环境变量控制 Hercules 的其他行为：\n\n  - `HEADLESS=true`\n  - `RECORD_VIDEO=false`\n  - `TAKE_SCREENSHOTS=false`\n  - `BROWSER_TYPE=chromium`（可选值：`firefox`, `chromium`）\n  - `CAPTURE_NETWORK=false`\n \n例如：如果你想以“有头”（Headful）模式运行浏览器，可在启动 Hercules 前设置环境变量：```export HEADLESS=false```。\n\n- **如何在 Playwright 中使用追踪（Tracing）**\n\n  Playwright 中的追踪功能可帮助你有效分析测试执行过程并调试问题。要启用 Playwright 测试中的追踪功能，请按以下步骤操作：\n\n  1. 确保在配置中启用了追踪。\n  2. 追踪文件将保存到指定路径：`{proof_path}\u002Ftraces\u002Ftrace.zip`。\n\n  #### 启用追踪\n\n  要启用追踪，请设置以下环境变量：\n\n  ```bash\n  export ENABLE_PLAYWRIGHT_TRACING=true\n  ```\n\n### 理解 `agents_llm_config-example.json`\n\n- 该文件用于定义你希望提供给代理的一组 LLM 配置。\n\n- 示例：\n\n  ```json\n  {\n    \"anthropic\": {\n\t\t\"planner_agent\": {\n\t\t\t\"model_name\": \"claude-3-5-haiku-latest\",\n\t\t\t\"model_api_key\": \"\",\n\t\t\t\"model_api_type\": \"anthropic\",\n            \"llm_config_params\": {\n                \"cache_seed\": null,\n                \"temperature\": 0.0,\n                \"seed\":12345\n            }\n\t\t},\n\t\t\"nav_agent\": {\n\t\t\t\"model_name\": \"claude-3-5-haiku-latest\",\n\t\t\t\"model_api_key\": \"\",\n\t\t\t\"model_api_type\": \"anthropic\",\n            \"llm_config_params\": {\n                \"cache_seed\": null,\n                \"temperature\": 0.0,\n                \"seed\":12345\n            }\n\t\t}\n    }\n  }\n  ```\n\n- 外层键（如 `\"anthropic\"`）对应通过 `AGENTS_LLM_CONFIG_FILE_REF_KEY` 传入的配置标识名，而 Hercules 相关信息则包含在子字典 `planner_agent` 和 `nav_agent` 中。\n\n- **注意**：除非你明确知道自己在做什么，否则应忽略此选项。在 Slack 社区中尝试这些选项前，请先与我们沟通。欢迎加入我们的 [Slack](https:\u002F\u002Fjoin.slack.com\u002Ft\u002Ftestzeuscommunityhq\u002Fshared_invite\u002Fzt-376oeo99x-3RAWe_C0H7x9zP0rtACcPA)\n\n---\n\n\n## ⚡️ 功能特性\n\nHercules 已可用于生产环境，并具备强大功能：\n\n### Gherkin 输入，结果输出\n\nHercules 让测试变得像“Gherkin 输入，结果输出”一样简单。只需提供 Gherkin 格式的端到端测试用例，Hercules 就会自动执行测试，并以整洁的 JUnit 格式呈现结果。无需手动操作，无需繁琐步骤——只有高效、无缝的测试体验。\n\n### 免费且开源\n\nHercules 完全免费开源，无任何许可费用。你可以自由查看源码、贡献代码，或按需定制。Hercules 不仅强大，而且完全开放，为你提供所需的灵活性和控制力。\n\n### Salesforce 就绪\n\n专为应对最复杂的用户界面而设计，Hercules 能轻松驾驭 Salesforce 及其他复杂平台。无论是复杂的 DOM 结构，还是执行 SOQL 或 Apex 代码，Hercules 都已准备就绪且高度可配置。\n\n### 无需编码\n\n告别复杂的脚本和难以维护的定位器。Hercules 采用无代码（No Code）方法，自动处理 Gherkin 特性的自动化执行，让你专注于最重要的事情——构建高质量软件。\n\n### 多语言支持\n\n开箱即用的多语言支持，让 Hercules 能与全球团队无缝协作。它致力于弥合语言障碍，赋能多元化团队在统一的测试平台上高效合作。\n\n### 精准可靠\n\nHercules 会录制执行过程的视频并捕获网络日志，彻底解决“在我电脑上能跑”的难题。\n\n### 无需维护\n\nHercules 具备自主性和自愈能力，能够自动适应变化。你无需再进行繁琐的维护工作——Hercules 会持续聚焦于实现你的测试目标。\n\n### UI 断言\n\n基于强大的 TestZeus 底层架构，Hercules 对 UI 断言保持高度专注，确保每个断言都被验证，每个缺陷都不被遗漏。它严谨、敏锐，随时准备行动。\n\n### CI\u002FCD 就绪\n\n你可以在本地运行 Hercules，也可以将其无缝集成到 CI\u002FCD 流水线中。Hercules 原生支持 Docker，一条命令即可部署，轻松融入你的发布流程，让测试快速、一致且无忧。\n\n有了 Hercules，测试不再只是开发流程中的一个步骤——而是一种强大、流畅的体验，将质量置于核心位置。\n\n### 移动设备模拟（Mobile Device Emulation）\n\nHercules 支持以多种设备类型的“移动模式”运行浏览器。Playwright 在此处提供了大量设备描述符列表：  \n[支持的移动设备列表](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fplaywright\u002Fblob\u002Fmain\u002Fpackages\u002Fplaywright-core\u002Fsrc\u002Fserver\u002FdeviceDescriptorsSource.json)\n\n#### 启用移动模式\n在 `.env` 文件中（或直接作为环境变量）设置 `RUN_DEVICE` 环境变量：\n```bash\nRUN_DEVICE=\"iPhone 15 Pro Max\"\n```\n当 Hercules 运行时，它将使用所选设备对应的视口（viewport）和用户代理（user-agent）启动浏览器，从而模拟真实的移动环境。  \n以下是一个快速演示：  \n![MobileDemo](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_45f8d1ae1c3d.gif)\n\n#### 集成高级工具\nHercules 可通过更强大的工具进行扩展，以应对高级场景。通过设置以下选项启用：\n```bash\nLOAD_EXTRA_TOOLS=true\n```\n启用 `LOAD_EXTRA_TOOLS` 后，Hercules 会查找额外的工具模块，以扩展其能力（例如地理位置处理）。\n\n对于基于位置的测试，请配置如下（支持的地理服务提供商为 maps.co 和 Google）：\n```bash\nGEO_API_KEY=somekey\nGEO_PROVIDER=maps_co\n```\n这使得 Hercules 能够在测试执行期间更改或模拟用户位置，从而扩大对依赖用户地理位置的场景的测试覆盖范围。\n\n注意：如果您正在寻找原生应用（native app）测试自动化方案，我们也已提供初步支持，基于 Appium 的原生应用自动化功能已在[此处](https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fpull\u002F41)实现。\n\n---\n\n## 🦾 架构\n\n### 多智能体（Multi-Agentic）解决方案\n\nHercules 基于 AutoGen 框架采用多智能体架构。在 AutoGen 框架的基础上，Hercules 的架构充分利用了工具（tools）与智能体（agents）之间的协同作用。每个工具代表一个原子操作（atomic action），即一个基本构建单元，执行后会返回对其结果的自然语言描述。这种细粒度设计使 Hercules 能够灵活组合这些工具，以应对复杂的网页自动化工作流。\n\n#### 系统视图\n\n![Architecture Diagram](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_eab183f14023.jpg)\n\n上图展示了我们在 AutoGen 架构之上选择的配置。工具可以有不同的划分方式，但这是我们目前采用的方案。我们选择使用与人类学习浏览器操作方式相匹配的工具，而不是允许大语言模型（LLM）随意生成代码。我们认为使用预配置的工具更加安全且结果更具可预测性。当然，它仍可能点击错误的元素，但至少不会执行恶意或未知的代码。\n\n#### 智能体（Agents）\n\n目前包含两个智能体：\n\n1. **规划智能体（Planner Agent）**：负责任务的规划与分解。\n2. **浏览器导航智能体（Browser Navigation Agent）**：封装了所有用于与网页浏览器交互的工具。\n\n#### 工具库（Tools Library）\n\nHercules 能力的核心是工具库——一个定义明确的操作集合，目前专注于网页操作。这些工具分为两大类：\n\n- **感知工具（Sensing Tools）**：如 `get_dom_with_content_type` 和 `geturl`，帮助 Hercules 理解当前网页或浏览器的状态。\n- **动作工具（Action Tools）**：允许 Hercules 与网页环境交互和操作，例如 `click`、`enter_text` 和 `openurl`。\n\n每个工具的设计都力求尽可能具有对话性，使与 LLM 的交互更直观且容错性更强。例如，工具不会仅返回布尔值，而是用自然语言解释执行过程中发生了什么，使 LLM 能更好地理解上下文并在必要时调整策略。\n\n##### 已实现的工具\n\n- **感知工具**\n\n  - `geturl`：获取并返回当前 URL。\n  - `get_dom_with_content_type`：根据指定的内容类型，获取当前页面的 HTML DOM。\n    - `text_only`：提取 HTML DOM 的纯文本内容，并以文本形式返回。\n    - `input_fields`：提取 DOM 中的可交互元素（如 button、input、textarea 等），并返回紧凑的 JSON 对象。\n    - `all_fields`：提取 DOM 中的所有字段，并返回紧凑的 JSON 对象。\n  - `get_user_input`：为协调器（orchestrator）提供一种机制，用于接收用户反馈，以消除歧义或澄清用户请求。\n\n- **动作工具**\n\n  - `click`：根据提供的 DOM 查询选择器进行点击。\n  - `enter_text`：在由 DOM 查询选择器指定的字段中输入文本。\n  - `enter_text_and_click`：优化方法，结合了 `enter_text` 和 `click` 工具。\n  - `bulk_enter_text`：优化方法，封装 `enter_text`，支持一次性执行多个文本输入操作。\n  - `openurl`：在当前或新标签页中打开指定 URL。\n\n#### DOM 蒸馏（DOM Distillation）\n\nHercules 采用了一种系统化的方法来应对庞大的 HTML DOM 结构，这对提升效率至关重要。我们引入了 **DOM 蒸馏** 技术，将 DOM 精简为仅包含与用户任务相关的元素。\n\n在实践中，这意味着将庞大的 DOM 转换为更易处理的 JSON 快照。这不仅仅是减少数据量，更是聚焦于相关性，只为 LLM 提供完成任务所必需的信息。目前我们支持三种内容类型：\n\n1. **纯文本（Text Only）**：适用于信息检索任务，仅保留文本内容，无干扰。\n2. **输入字段（Input Fields）**：聚焦于需要用户交互的元素，旨在简化操作流程。\n3. **全部内容（All Content）**：包含蒸馏后的完整 DOM 元素，适用于需要全面理解页面结构的任务。\n\n这是一种精细的“外科手术”，在去除冗余信息的同时，保留智能体操作所需的结构和内容。当然，任何蒸馏过程都可能造成信息损失，但我们的目标是不断优化这一过程，以尽量减少甚至消除此类损失。\n\n由于无法依赖所有网页开发者遵循最佳实践（例如为每个 HTML 元素添加唯一 ID），我们在每个 DOM 元素中注入了自定义属性（`md`）。这样就可以引导 LLM 在生成 DOM 查询时优先使用 `md` 属性。\n\n为了进一步降低 DOM 噪声，我们使用 **DOM 可访问性树（DOM Accessibility Tree）** 而非标准 HTML DOM。可访问性树本质上是为屏幕阅读器设计的，这比普通 HTML DOM 更贴近网页自动化的使命。\n\nDOM 蒸馏过程仍在持续改进中。我们计划进一步优化该流程，压缩 DOM 规模，以实现更快、更经济且更准确的交互。\n\n### 非功能性能力（Non-Functional Capabilities）\n\n#### 通过 Nuclei 进行安全测试  \nHercules 集成了 **Nuclei**，可直接从 Gherkin 测试用例中自动化执行漏洞扫描，识别诸如**配置错误、OWASP Top 10 漏洞**以及 API 缺陷等问题。安全报告会与测试输出一同生成，便于无缝集成到 CI\u002FCD 流程中。\n\n#### 可访问性测试（Accessibility Testing）  \nHercules 支持 **WCAG 2.0、2.1 和 2.2** 标准的 **A、AA 和 AAA 级别**，能够执行可访问性测试，确保符合全球标准。它能在早期发现可访问性问题，帮助构建更具包容性和用户友好的应用程序。\n\n---\n\n## 🔬 测试与评估：QEvals\n\n我们希望确保 Hercules 能以极高的精度胜任端到端测试任务。因此，我们对 Hercules 进行了广泛的测试，包括调用 API、处理复杂的 UI 场景、点击日历或 iframe 等操作。完整的评估列表请参见 [tests 文件夹](\u003CLink to tests folder>)。\n\n### 运行测试\n\n运行完整测试套件，请使用以下命令：\n\n```bash\nmake test\n```\n\n运行特定测试：\n\n```bash\nmake test-case\n```\n\nHercules 基于 WebArena 和 Agent-E 的工作成果，并在此基础上进一步优化。为解决先前方案中的问题，我们编写了面向复杂 QA 场景的自有测试用例，并将这些测试存放在 `.\u002Ftests` 文件夹中。\n\n---\n\n## 💡 设计理念（Opinions）\n\n我们认为，卓越的质量源于对产品的明确观点。因此，我们在产品设计中融入了一些自己的理念。我们欢迎社区质疑、使用或在其基础上继续构建。以下是一些示例：\n\n1. **Gherkin 是适用于智能体（Agents）的足够好的格式**：Gherkin 为大语言模型（LLMs）\u002FAI 智能体提供了一种半结构化的格式，便于理解测试意图和用户指令。它提供了恰到好处的语法（如 Given、When、Then 等动词），既方便人类描述场景，也便于智能体执行指令。\n\n2. **测试应具备原子性（Atomic in Nature）**：软件测试应当是原子的，因为这能确保每个测试都**聚焦、独立且可靠**。原子测试只针对某一特定行为或功能，使失败的根本原因更容易被精准定位，避免歧义。\n\n   **以下是一个良好的原子测试示例**：\n\n   ```gherkin\n   Feature: 用户登录\n\n   Scenario: 使用有效凭据成功登录\n\n     Given 用户位于登录页面\n     When 用户输入有效凭据\n     And 用户点击登录按钮\n     Then 用户应看到仪表盘\n   ```\n\n   非原子测试会让测试人员和 AI 智能体都感到困惑。\n\n3. **开放核心（Open Core）与开源（Open Source）**：Hercules 采用**开放核心模式（open-core model）**，结合了开源精神与商业公司 **TestZeus** 的支持与专业能力。通过以 AGPL v3 许可证发布 Hercules 开源版本，TestZeus 致力于为测试社区提供一个强大、灵活、免费且可修改的工具。开源带来了透明度、信任和协作潜力，任何人都可以深入代码、贡献改进并影响项目发展方向。\n\n4. **遥测（Telemetry）**：所有优秀的产品都建立在良好的反馈基础上。我们设置了遥测功能，以便在不打扰用户的情况下收集反馈。遥测默认启用，但我们同样坚定地秉持“信任”与“透明”的价值观，用户可随时关闭该功能。\n\n5. **为 Hercules 编写提示（Prompting Hercules）**：关于如何为 Hercules 编写测试的详细指南，请参阅我们的博客文章：[此处](https:\u002F\u002Ftestzeus.com\u002Fblog\u002Fmastering-ai-driven-testing-writing-effective-tests-for-hercules)。\n\n---\n\n## 🦾 HyperMind\n\n:jigsaw: 概述  \nHercules 现在拥有了 HyperMind 的能力——这是一个安全的多租户 Python 沙箱，允许测试人员将自定义逻辑、AI 驱动的启发式规则以及人工编写的智能直接注入测试场景中。  \n当自动化遇到瓶颈时，Hypermind 将接管控制——在受控权限下执行拥有完整 Playwright 访问能力的脚本。\n\n:gear: 核心能力  \n\n| 能力 | 描述 |\n|------|------|\n| :brain: 从 Gherkin 运行自定义脚本 | 将 Python 函数作为测试步骤调用 |\n| :earth_africa: 完整 Playwright 访问权限 | 直接控制浏览器、页面和上下文 |\n| :jigsaw: 自动注入的工具集 | 预加载常用工具（如 logger、asyncio、json 等） |\n| :lock: 多租户隔离 | 提供 Executor、Data、API 和 Restricted 四级安全隔离 |\n| :gear: 动态权限控制 | 通过 CLI 或环境变量控制模块访问权限 |\n| :camera_with_flash: 执行证明 | 自动生成执行前后的截图和 JSON 格式执行报告 |\n| :arrows_counterclockwise: 可复用逻辑 | 跨特性或团队共享脚本 |\n\n:toolbox: 使用示例  \n\n**Gherkin**：\n```gherkin\nFeature: 商品筛选\n  Scenario: 使用 Hypermind 脚本应用筛选条件\n    Given 用户位于 URL https:\u002F\u002Fexample.com\n    When 执行 hypermind 脚本 \"scripts\u002Fapply_filter.py\"，参数 filter_type 为 \"Turtle Neck\"\n    Then 脚本应报告筛选应用成功\n```\n\n**Python**: opt\u002Fscripts\u002Fapply_filter.py\n```python\nasync def apply_filter(filter_type: str) -> dict:\n    \"\"\"使用后备策略应用筛选条件。\"\"\"\n    await page.wait_for_selector('[data-filter-section]')\n    for selector in [f'input[value=\"{filter_type}\"]', f'label:has-text(\"{filter_type}\") input']:\n        if await page.locator(selector).count() > 0:\n            await page.locator(selector).click()\n            break\n    count = await page.locator('.product-item').count()\n    return {\"status\": \"success\", \"filter\": filter_type, \"products\": count}\n```\n\n:checkered_flag: 愿景  \n“当自动化失效时，Hypermind 觉醒。”  \nHypermind 脚本代表了 AI 辅助测试的新阶段——将自主精确性与人类适应性融为一体。它不仅仅是后备逻辑，更是可执行的人类创造力。\n\n## 🪙 Token 消耗\n\nHercules 是一款原生 AI 解决方案，依赖大语言模型（LLMs）进行推理和操作。根据我们的实验，如下所示的复杂用例在使用 OpenAI 的 gpt-4o API 时，单次运行成本最高可达 **$0.20**。请查看测试用例输出中打印的属性，以估算您自己用例的成本：\n\n```gherkin\nFeature: 在 Salesforce 中创建账户\n\n Scenario: 成功创建新账户\n\n   Given 我位于 Salesforce 登录页面\n   When 我输入用户名 \"user@example.com\" 和密码 \"securePassword\"\n   And 我点击“Log In”按钮\n   And 我导航至“Accounts”标签页\n   And 我点击“New”按钮\n   And 我在“Account Name”字段中填入“Test Account”\n   And 我选择“Account Type”为“Customer”\n   And 我在“Website”字段中填入“www.testaccount.com”\n   And 我在“Phone”字段中填入“123-456-7890”\n   And 我点击“Save”按钮\n   Then 我应看到确认消息“Account Test Account created successfully”\n   And 我应在账户记录中看到“Test Account”\n```\n\n## ⭐️ 与其他工具的区别\n\nHercules 不仅仅是另一个测试工具——它是一个**智能体（agent）**。借助能够**思考、推理和响应**需求的合成智能（synthetic intelligence），Hercules 超越了简单的自动化脚本。我们为**软件测试**领域带来了业界首创的开源智能体方法。这意味着更快、更智能、更具韧性的测试周期，尤其适用于复杂平台。\n\n凭借**业界领先的性能**和完全开源的基础，Hercules 将强大的能力与社区驱动的灵活性相结合，让顶级测试对每个人而言都触手可及且具有变革性。\n\n---\n\n## 🚀 高层次路线图\n\n- **增强的 LLM（大语言模型）支持**：集成更多 LLM，并支持本地 LLM 部署。\n- **高级工具集**：增加更多工具以应对复杂的测试场景和环境。\n- **改进的 DOM 提炼（DOM Distillation）**：优化 DOM 提炼流程，提升效率与准确性。\n- **社区贡献**：鼓励并整合社区驱动的功能与工具。\n- **详尽的文档**：扩展文档内容，提升新用户入门体验和使用便利性。\n- **赏金计划（Bounty Program）**：推出赏金计划，激励社区贡献。\n\n---\n\n## 🤗 贡献指南\n\n我们欢迎来自社区的贡献！\n\n- **请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 文件**以开始参与。\n- **赏金计划**：敬请关注即将推出的机会！😀\n\n### 如何回馈社区\n\n1. **开发工具**\n\n   - 如果你正在为 Hercules 开发工具并希望贡献给社区，请确保在你的 Pull Request 中将新工具放入 `additional_tools` 文件夹。\n\n2. **修复与增强**\n\n   - 如果你对系统核心的感知工具、提示词（prompts）或 DOM 提炼代码进行了修复或改进，请将更改提交到相应文件并发起 Pull Request。\n\n### 扩展与附加工具\n\n1. **创建新工具**\n\n   - 你可以通过向 Hercules 添加工具来开始扩展。\n   - 参考 `testzeus_hercules\u002Fcore\u002Ftools\u002Fsql_calls.py` 示例了解如何创建新工具。\n   - 关键是在你希望 Hercules 执行的方法上使用 `@tool` 装饰器。\n   - 工具装饰器应包含清晰的名称和描述，以便 Hercules 知道如何使用该工具。\n   - 同时，在方法中应明确标注每个参数的用途，以确保 LLM 的函数调用效果最佳。\n\n2. **添加工具**\n\n   - 创建好新工具文件后，可通过环境变量将工具所在文件夹路径传递给 Hercules，使其在启动时加载这些新工具，并在执行期间可用。\n   - 使用 `ADDITIONAL_TOOL_DIRS` 环境变量传入新工具文件夹的路径。\n\n3. **直接添加（不推荐）**\n\n   - 如果你选择直接添加工具，请将新工具文件放入克隆仓库中的 `testzeus_hercules\u002Fcore\u002Ftools` 路径下。\n\n   - **注意**：此方式不推荐。我们建议优先使用 `ADDITIONAL_TOOL_DIRS` 方法。\n\n---\n\n## 🤙 联系我们\n\n加入我们的 [Slack](https:\u002F\u002Fjoin.slack.com\u002Ft\u002Ftestzeuscommunityhq\u002Fshared_invite\u002Fzt-376oeo99x-3RAWe_C0H7x9zP0rtACcPA)，与社区互动、提问并参与贡献。\n\n---\n\n## ✍️ 示例\n\n- **Salesforce 示例**：[链接](tests\u002Ftest_not_for_ci\u002Febikes\u002Febikes.feature)\n- **Wrangler 示例**：[链接](tests\u002Ffuture_test_features\u002FproductSearch\u002FproductSearch.feature)\n\n---\n\n## 🙇 致谢\n\nHercules 的实现离不开以下项目的杰出工作：\n\n1. [Agent-E](https:\u002F\u002Farxiv.org\u002Fabs\u002F2407.13032)\n2. [Q*](https:\u002F\u002Farxiv.org\u002Fabs\u002F2312.10868)\n3. [Agent Q](https:\u002F\u002Farxiv.org\u002Fabs\u002F2408.07199)\n4. [Autogen](https:\u002F\u002Farxiv.org\u002Fpdf\u002F2308.08155)\n\nHercules 项目基于 [Agent-E](https:\u002F\u002Fgithub.com\u002FEmergenceAI\u002FAgent-E) 进行推演与增强。我们在多个方面进行了改进，使其具备执行测试的能力，尤其是在复杂 DOM 导航和 iframe 处理方面。此外，我们还为 Hercules 新增了多种工具和能力（如 Salesforce 导航），使其在所选基础框架之上表现更优。\n\nHercules 也从旧版 TestZeus 仓库 [此处](https:\u002F\u002Fwww.testzeus.org) 中汲取了部分灵感。\n\n---\n\n有了 Hercules，测试不再只是流程中的一个步骤——而是一种强大、流畅的体验，将质量置于核心位置。\n\n## 🚀 附注：关于 Python 虚拟环境及其他重要命令\n\n如果你来自 **Java** 或 **JavaScript** 背景，初次使用 Python 可能会感觉略有不同——但别担心！Python 的简洁性结合虚拟环境等强大工具，使得依赖管理变得简单高效。\n\n### 🎓 **理解虚拟环境**\n\n在 Java 中，你可能会使用 Maven 或 Gradle 来管理项目依赖；在 JavaScript 中，则使用 `npm` 或 `yarn`。在 Python 中，**虚拟环境（virtual environments）** 扮演类似角色。它们允许你为项目创建隔离的依赖空间，避免与系统中其他 Python 项目发生冲突。\n\n你可以将其想象成一个沙盒环境，TestZeus Hercules 及其依赖在此独立运行，与其他 Python 包互不干扰。\n\n### 🏗️ **设置说明**\n\n#### ✅ **1. 前提条件**\n\n首先，请确保已安装 Python 3.11 或更高版本。可通过以下命令验证：\n\n```bash\npython --version\n# 或\npython3 --version\n```\n\n如果尚未安装 Python，请[在此下载](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)；若使用 Windows 系统，请参考[此处说明](https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002F#%EF%B8%8F-running-hercules-on-a-windows-machine)。\n\n---\n\n#### 🏰 **2. 创建并激活虚拟环境**\n\n为项目设置干净的 Python 环境：\n\n```bash\n# 创建名为 'venv' 的虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n\n# macOS\u002FLinux:\nsource venv\u002Fbin\u002Factivate\n```\n\n你会注意到终端提示符发生变化——这表示虚拟环境已激活。\n\n稍后如需**停用**虚拟环境，只需运行：\n```bash\ndeactivate\n```\n\n---\n\n#### 📥 **3. 安装 TestZeus Hercules**\n\n激活虚拟环境后，直接从 PyPI 安装最新版 TestZeus Hercules：\n\n```bash\npip install testzeus-hercules\n```\n\n---\n\n#### 🔄 **4. 更新 TestZeus Hercules**\n\n如需升级至最新版本，请使用：\n\n```bash\npip install --upgrade testzeus-hercules\n```\n\n---\n\n#### ❌ **5. 卸载 TestZeus Hercules**\n\n如需移除该包：\n\n```bash\npip uninstall testzeus-hercules\n```\n\n---\n\n#### 🔍 **6. 查看已安装的包**\n\n验证 TestZeus Hercules 是否已安装并查看其版本：\n\n```bash\npip list\n```\n\n### 🔗 **给 Java\u002FJS 开发者的额外提示**\n\n- **`pip`** 类似于 `npm` 或 `mvn`——用于安装和管理 Python 包（packages）。\n- Python 的简洁性意味着更少的配置文件——大多数操作都可以直接通过命令行完成。\n\n---\n\n### 💡 **下一步**\n\n现在 TestZeus Hercules 已安装并准备就绪，请深入阅读 [我们的文档](https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002F)，轻松学习如何创建并运行你的第一个测试用例！\n\n---\n\n## Star 历史\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_readme_d965aae7f5e9.png)](https:\u002F\u002Fstar-history.com\u002F#test-zeus-ai\u002Ftestzeus-hercules&Date)\n\n## ✅ 引用\n\n如果你在研究或项目中使用了 Hercules，请引用以下内容：\n\n```\n@software{testzeus_hercules2024,\n  author = {Agnihotri, Shriyansh and Gupta, Robin},\n  title = {Hercules: World's first open source testing agent},\n  year = {2024},\n  publisher = {GitHub},\n  url = {https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002F}\n}\n```","# TestZeus Hercules 快速上手指南\n\n## 环境准备\n\n- **操作系统**：支持 Linux、macOS 和 Windows（Windows 需以管理员权限运行 PowerShell）\n- **Python 版本**：建议使用 Python 3.10 或 3.11\n- **前置依赖**：\n  - 安装 Playwright 浏览器依赖\n  - 若使用 LLM 功能，需准备支持 function calling 的大模型 API Key（如 OpenAI GPT-4o、Anthropic Haiku 3.5+ 等）\n\n> 💡 国内用户建议配置 PyPI 镜像源（如清华源）加速安装：\n> ```bash\n> pip install -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple testzeus-hercules\n> ```\n\n## 安装步骤\n\n### 1. 安装 Hercules 包\n```bash\npip install testzeus-hercules\n```\n\n### 2. 安装 Playwright 浏览器依赖\n```bash\nplaywright install --with-deps\n```\n\n> ⚠️ Windows 用户可使用官方提供的 PowerShell 脚本一键安装：\n> ```powershell\n> # 以管理员身份运行 PowerShell\n> cd path\\to\\helper_scripts\n> .\\hercules_windows_setup.ps1\n> ```\n\n## 基本使用\n\n### 最简运行示例\n\n假设你已有一个 Gherkin 特性文件 `test.feature`，并准备好测试数据目录：\n\n```bash\ntestzeus-hercules \\\n  --input-file .\u002Ftest.feature \\\n  --output-path .\u002Foutput \\\n  --test-data-path .\u002Ftest_data \\\n  --llm-model gpt-4o \\\n  --llm-model-api-key sk-proj-k.......\n```\n\n### 推荐项目结构（使用 `--project-base`）\n\n若采用标准项目结构，只需指定根目录：\n\n```\nmy_project\u002F\n├── input\u002F              # 存放 .feature 文件\n├── output\u002F             # 输出报告和结果\n├── test_data\u002F          # 测试数据文件\n└── proofs\u002F             # 自动保存截图、视频、网络日志等证据\n```\n\n运行命令简化为：\n```bash\ntestzeus-hercules --project-base .\u002Fmy_project --llm-model gpt-4o --llm-model-api-key sk-proj-k.......\n```\n\n### 环境变量配置（可选）\n\n常用环境变量示例（Linux\u002FmacOS）：\n```bash\nexport BROWSER_TYPE=chromium\nexport HEADLESS=true\nexport RECORD_VIDEO=true\nexport TAKE_SCREENSHOTS=true\n```\n\nWindows（PowerShell）：\n```powershell\n$env:BROWSER_TYPE=\"chromium\"\n$env:HEADLESS=\"true\"\n```\n\n> 📌 提示：完整环境变量列表请参考官方文档 [Environment Variables Guide](docs\u002Fenvironment_variables.md)。","某跨境电商团队每周需对后台订单管理系统进行回归测试，覆盖 UI 操作、API 数据一致性、安全漏洞扫描及多语言界面校验。\n\n### 没有 testzeus-hercules 时\n- 测试脚本由 QA 工程师用 Selenium + Postman + OWASP ZAP 多工具组合编写，维护成本高，每次前端改版都要重写大量选择器。\n- 安全与可访问性测试依赖手动检查或独立工具，难以集成到每日 CI 流程中。\n- 多语言界面（如英文、西班牙文、日文）的文本显示和布局差异需人工截图比对，效率低下且易遗漏。\n- 非技术产品经理无法参与测试用例设计，需求变更后测试覆盖滞后。\n- 视觉回归靠肉眼判断，组件错位或样式异常经常漏测。\n\n### 使用 testzeus-hercules 后\n- 团队直接用自然语言编写的 Gherkin 步骤（如“当用户切换至西班牙语，订单状态应显示为‘Enviado’”）自动驱动 UI、API 和视觉验证，无需编码。\n- 安全扫描、无障碍检测和视觉快照比对内置于同一测试流程，一键触发并输出统一报告。\n- 多语言测试通过内置国际化支持自动切换语言环境，并结合视觉识别验证文案与布局正确性。\n- 产品经理可直接编写或评审测试场景，实现测试左移，确保需求与验证同步。\n- 视觉差异自动高亮标记，组件偏移超过阈值即告警，大幅提升 UI 质量保障能力。\n\ntestzeus-hercules 让复杂系统的端到端测试从“高门槛、高维护”的负担，转变为“人人可写、自动覆盖”的高效实践。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftest-zeus-ai_testzeus-hercules_e143ca90.png","test-zeus-ai","TestZeus","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Ftest-zeus-ai_ff8b30dc.png","Software Quality at Godly speed",null,"shriyansh@testzeus.com","TestZeusAI","www.testzeus.com","https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai",[85,89,93,97,101,105,109,112,116],{"name":86,"color":87,"percentage":88},"Python","#3572A5",92.3,{"name":90,"color":91,"percentage":92},"Gherkin","#5B2063",2.6,{"name":94,"color":95,"percentage":96},"PowerShell","#012456",1.3,{"name":98,"color":99,"percentage":100},"Shell","#89e051",1.2,{"name":102,"color":103,"percentage":104},"JavaScript","#f1e05a",1,{"name":106,"color":107,"percentage":108},"Jupyter Notebook","#DA5B0B",0.6,{"name":110,"color":111,"percentage":108},"Makefile","#427819",{"name":113,"color":114,"percentage":115},"Dockerfile","#384d54",0.2,{"name":117,"color":118,"percentage":115},"HTML","#e34c26",968,149,"2026-04-05T10:27:39","AGPL-3.0","Linux, macOS, Windows","未说明",{"notes":126,"python":127,"dependencies":128},"需安装 Playwright 浏览器依赖（playwright install --with-deps）；支持通过 Docker、PyPI 或 Windows PowerShell 脚本安装；需要配置 LLM API 密钥（如 OpenAI GPT-4o）；推荐使用 Chromium 浏览器，支持无头模式运行；Colab 环境可能需要重启会话以适配 Python 3.11。","3.11",[129,67,130,131,132,133,134],"playwright","asyncio","requests","pandas","numpy","beautifulsoup4",[15,13,53,14],[137,138,139,140,141,142,143,129,144,145,146,147,148,149,150,151,152,153],"ai","autogen","automation","browser","end-to-end-testing","hercules","large-action-model","rpa","testing","testzeus","agents","qa-automation","software-testing","test-automation","testing-tools","agent","agentic-ai","2026-03-27T02:49:30.150509","2026-04-06T07:16:05.964872",[157,162,167,172,177,181],{"id":158,"question_zh":159,"answer_zh":160,"source_url":161},1526,"为什么在 Windows 上安装 testzeus-hercules 时出现 “RuntimeError: uvloop does not support Windows at the moment” 错误？","这是因为项目早期版本错误地包含了仅支持 Linux\u002FmacOS 的 uvloop 依赖。维护者已在 v0.0.10 及后续版本中移除了该依赖。请升级到最新版本（如 v0.0.12）以解决此问题。如果仍遇到问题，可手动确认 poetry 或 requirements 中是否已移除 uvloop。","https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fissues\u002F6",{"id":163,"question_zh":164,"answer_zh":165,"source_url":166},1527,"testzeus-hercules 是否支持 Windows 系统？如何正确在 Windows 上运行？","支持，但需注意几点：1）使用 v0.0.12 或更高版本；2）通过 Windows Store 安装 Python 3.11 并配置环境变量；3）安装 ffmpeg（用于录屏）；4）禁用浏览器广告拦截插件；5）官方提供了 PowerShell 辅助脚本帮助配置环境。详细步骤见 README 中的「Running Hercules on a Windows Machine」部分。","https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fissues\u002F11",{"id":168,"question_zh":169,"answer_zh":170,"source_url":171},1528,"为什么工具列表（tools）没有传递给 LLM？日志显示 functions 为 none。","OSS（开源）版本的 testzeus-hercules 并未内置 Salesforce 对象感知或自动解析 Gherkin 步骤为工具调用的能力。工具是通过 AutoGen (ag2) 在内部 LLM 调用中附加的，不会直接出现在主提示词中。若需查看实际发送给 LLM 的工具信息，可启用运行时日志记录（参考 ag2.ai 文档），或检查 core\u002Ftools 目录下的可用工具列表。Salesforce 深度集成功能仅在付费 SaaS 版本中提供。","https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fissues\u002F86",{"id":173,"question_zh":174,"answer_zh":175,"source_url":176},1529,"执行 testzeus-hercules 命令时报错，无法正常运行，怎么办？","该问题通常由 AutoGen (AG2) 库的向后兼容性问题引起。解决方案是卸载当前版本并重新安装最新 release（如 v0.0.12+），因为维护者已将 AG2 版本固定以避免冲突。请运行：`pip uninstall testzeus-hercules && pip install testzeus-hercules --upgrade`，确保使用最新 PyPI 或 GitHub release 版本。","https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fissues\u002F50",{"id":178,"question_zh":179,"answer_zh":180,"source_url":166},1530,"在 Windows 上运行时出现文件名或日志路径错误，如何解决？","Windows 对文件路径和命名规则较严格，旧版本中内部日志文件名可能包含非法字符导致失败。该问题已在 v0.0.12 版本修复。请确保使用最新版本，并避免在项目路径中使用特殊字符或过长目录名。",{"id":182,"question_zh":183,"answer_zh":184,"source_url":171},1531,"如何查看 testzeus-hercules 实际发送给 LLM 的请求（包括工具定义）？","可通过两种方式：1）使用 litellm 或 Portkey 作为 LLM 代理，拦截并记录所有 API 调用；2）启用 AutoGen 的运行时日志功能，生成 SQLite 文件记录完整的请求与响应。具体方法参考：https:\u002F\u002Fdocs.ag2.ai\u002Flatest\u002Fdocs\u002Fuse-cases\u002Fnotebooks\u002Fnotebooks\u002Fagentchat_logging\u002F。此外，启动时控制台会打印已加载的工具名称，也可从 core\u002Ftools 目录查看可用工具列表。",[186,191,196,201,206,211,216,221,226,231,236,241,246,251,256,261,266,271,276,281],{"id":187,"version":188,"summary_zh":189,"released_at":190},110711,"0.2.0","Lawrence Sinclair (1):\r\n          Add MseeP.ai badge (#77)\r\n\r\n    Shriyansh Agnihotri (2):\r\n          Adding script execution in the testcase (#83)\r\n          release: version 0.2.0 🚀\r\n\r\n    dependabot[bot] (1):\r\n          Bump actions\u002Fsetup-python from 5 to 6 (#78)\r\n\r\n## What's Changed\r\n* Adding script execution in the testcase by @shriyanshagnihotri in https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fpull\u002F83\r\n* Add MseeP.ai badge by @lwsinclair in https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fpull\u002F77\r\n* Bump actions\u002Fsetup-python from 5 to 6 by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fpull\u002F78\r\n\r\n## New Contributors\r\n* @lwsinclair made their first contribution in https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fpull\u002F77\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fcompare\u002F0.1.6...0.2.0","2025-11-01T07:13:02",{"id":192,"version":193,"summary_zh":194,"released_at":195},110712,"0.1.6","    Eli Cohen (1):\n          fix(tools): add support for composite combobox elements (#82)\n\n    Shriyansh Agnihotri (1):\n          release: version 0.1.6 🚀\n\n","2025-10-22T12:00:20",{"id":197,"version":198,"summary_zh":199,"released_at":200},110713,"0.1.5","    Emmanuel Ferdman (1):\n          Update Wrangler example (#73)\n\n    Shahal Thayyil (2):\n          Feature\u002Fmcp support (#74)\n          Feature\u002Fmcp support (#79)\n\n    Shriyansh Agnihotri (1):\n          release: version 0.1.5 🚀\n\n","2025-09-16T10:22:03",{"id":202,"version":203,"summary_zh":204,"released_at":205},110714,"0.1.4","    AntaraTestZeus (1):\n          feat: Add GPT-5 support with max_completion_tokens (#70)\n\n    Shriyansh Agnihotri (2):\n          lint fixes\n          release: version 0.1.4 🚀\n\n    dependabot[bot] (1):\n          Bump actions\u002Fcheckout from 4 to 5 (#69)\n\n","2025-08-18T16:58:18",{"id":207,"version":208,"summary_zh":209,"released_at":210},110715,"0.1.3","    Akhil Cherian (1):\n          feat: add IGNORE_CERTIFICATE_ERRORS env flag (#65)\n\n    Shriyansh Agnihotri (4):\n          removing old test, as website changed\n          Updating Slack group\n          moving salesforce testcase out of CI as primary org is changed and testdata is irrelevant for now\n          release: version 0.1.3 🚀\n\n    generalrobin (1):\n          Added random invoice for PDF download and validation test\n\n","2025-08-07T11:04:36",{"id":212,"version":213,"summary_zh":214,"released_at":215},110716,"0.1.2","    Shriyansh Agnihotri (9):\n          adding more checks to avoid abrupt reload and triggering browser tab failure and reload\n          updating visual skills prompt\n          deepseek-chat support enabled\n          updating architecture diagram\n          fixing typo on state_handler\n          Changing API logs format to make it easy to read\n          fix related to bounding box selection\n          update ag2 package\n          release: version 0.1.2 🚀\n\n    generalrobin (1):\n          Updated visual test based on the new website homepage\n\n","2025-05-23T18:14:02",{"id":217,"version":218,"summary_zh":219,"released_at":220},110717,"0.1.1","    Shriyansh Agnihotri (6):\n          some changes regarding CDP connections\n          adding traceback logs for better debugging\n          Adding skip line feature in the feature file parsing.\n          improving prompts and javascript click skeptism\n          refactor of handling LLMs envrionment variables, updating docs, adding portkey support #49\n          release: version 0.1.1 🚀\n\n","2025-03-22T19:58:14",{"id":222,"version":223,"summary_zh":224,"released_at":225},110718,"0.1.0","    Shriyansh Agnihotri (3):\n          Adding playwright pages check in the CDP connection\n          fixing click method typo breaking save button on forms in salesforce\n          release: version 0.1.0 🚀\n\n    generalrobin (1):\n          Create salesforcefileupload.feature\n\n","2025-03-12T18:30:34",{"id":227,"version":228,"summary_zh":229,"released_at":230},110719,"0.0.40","Shriyansh Agnihotri (3):\r\n          Adding docs for Cookie inject variables\r\n          Fixing upload file and few items in prompts\r\n          release: version 0.0.40 🚀\r\n\r\n    generalrobin (1):\r\n          Create select.feature\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fcompare\u002F0.0.37...0.0.40","2025-03-05T13:50:20",{"id":232,"version":233,"summary_zh":234,"released_at":235},110720,"0.0.39","Shriyansh Agnihotri (2):\r\n          Fixing picklist work for lwc, fix of testcase pass status.\r\n          release: version 0.0.39 🚀\r\n\r\n    generalrobin (1):\r\n          Added sample salesforce interaction tests\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fcompare\u002F0.0.38...0.0.39","2025-03-05T08:16:28",{"id":237,"version":238,"summary_zh":239,"released_at":240},110721,"0.0.38","    Shriyansh Agnihotri (3):\n          Update README.md\n          Fixing checkbox clicks and combobox selection issues in SF\n          release: version 0.0.38 🚀\n\n","2025-03-01T14:15:36",{"id":242,"version":243,"summary_zh":244,"released_at":245},110722,"0.0.37","    Shriyansh Agnihotri (3):\n          Changes in prompt and making clicks and dropdown faster, prompts help to improve accuracy\n          Adding a skip for page wait in case if someone want to speed up the execution\n          release: version 0.0.37 🚀\n\n","2025-02-26T20:56:44",{"id":247,"version":248,"summary_zh":249,"released_at":250},110723,"0.0.36","    Shriyansh Agnihotri (3):\n          Adding documentation of envrionment variables and fixing few prompts to avoid redundant steps, also fixing non OpenAI llms broken support\n          Changes on README.md for adding env details\n          release: version 0.0.36 🚀\n\n","2025-02-26T04:30:06",{"id":252,"version":253,"summary_zh":254,"released_at":255},110724,"0.0.35","    Shriyansh Agnihotri (2):\n          bug fixes, interaction logs creation with trivial selectors, adding screenshots with boundingbox and helpbox (#43)\n          release: version 0.0.35 🚀\n\n    generalrobin (1):\n          Added changes around python envs\n\n","2025-02-24T18:09:25",{"id":257,"version":258,"summary_zh":259,"released_at":260},110725,"0.0.34","    Shriyansh Agnihotri (3):\n          Few bug fixes related to prompts\n          Fxing prompts for making testcase pass consistent\n          release: version 0.0.34 🚀\n\n","2025-02-23T17:05:06",{"id":262,"version":263,"summary_zh":264,"released_at":265},110726,"0.0.33","Shriyansh Agnihotri (3):\r\n          Some refactor to prevent LLM language bais, waiter was in technical terms, LLM assumes it as human :D\r\n          removing in progress status response for sub agents\r\n          release: version 0.0.33 🚀\r\n\r\n## What's Changed\r\n* Adding Dynamic LTM for learning long-term knowledge. by @shriyanshagnihotri in https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fpull\u002F42\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Ftest-zeus-ai\u002Ftestzeus-hercules\u002Fcompare\u002F0.0.31...0.0.33","2025-02-21T19:41:50",{"id":267,"version":268,"summary_zh":269,"released_at":270},110727,"0.0.32","    Shriyansh Agnihotri (3):\n          Adding Dynamic LTM for learning long-term knowledge. (#42)\n          Fixing issue of result file writer with scenario of same name\n          release: version 0.0.32 🚀\n\n    generalrobin (2):\n          Added prompting guidelines for Hercules\n          Added slack badge and notes on models\n\n","2025-02-21T09:29:45",{"id":272,"version":273,"summary_zh":274,"released_at":275},110728,"0.0.31","    Emmanuel Ferdman (1):\n          Update Salesforce examples (#39)\n\n    Shriyansh Agnihotri (3):\n          Update README.md\n          Bugfix dependency removal from llm_helper, _pydantic.model_dump not found issue\n          release: version 0.0.31 🚀\n\n    generalrobin (1):\n          Removed redundant downloads stats\n\n","2025-02-14T06:52:35",{"id":277,"version":278,"summary_zh":279,"released_at":280},110729,"0.0.30","    Ikko Eltociear Ashimine (1):\n          docs: update README.md (#36)\n\n    Shriyansh Agnihotri (8):\n          o3-mini support\n          fixing bulk inputs and some function call prompts to make it faster\n          spliting reading page and read elements as 2 different tools\n          Refactoring few prompts and tools to make it more precise\n          Controlling hallucination because of optimisation bais in browser_agents\n          fixing interactive mode some part to enable debugging\n          fixing run script for command\n          release: version 0.0.30 🚀\n\n","2025-02-04T08:11:46",{"id":282,"version":283,"summary_zh":284,"released_at":285},110730,"0.0.29","    Shriyansh Agnihotri (3):\n          Adding some validations so that gemini protobuf don't fail with parameters.entries is missing\n          Solving #35\n          release: version 0.0.29 🚀\n\n    generalrobin (2):\n          Added visual tests (#34)\n          Added block for citation\n\n","2025-01-31T13:27:20"]