Skip to content
Back to search

webqa-agent

Autonomous web browser agent that audits performance, functionality & UX for engineers and vibe-coding creators. 网站自主评估测试 Agent,支持 GUI/CLI 一键完成性能、功能使用与交互体验的测试评估

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/migoxlab--webqa-agent/badge.svg)](/listings/migoxlab--webqa-agent)

HTML

<a href="/listings/migoxlab--webqa-agent"><img src="/api/listings/migoxlab--webqa-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

<a id="quick-start"></a>

Choose between **🛠️ CLI Quick Start (Flash Mode)** or **🖥️ Full-stack Deployment (Web Dashboard)**.

🛠️ CLI Quick Start

Recommended: install via [uv](https://github.com/astral-sh/uv) (Python>=3.11). Flash mode drives the browser through [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp).

# 1) Create project and install
uv init my-webqa && cd my-webqa
uv add webqa-agent

# 2) Install Chrome browser & Chrome MCP pre-requisites
npm install -g chrome-devtools-mcp@latest  # Required for Flash mode

# 3) Initialize and Run (defaults to Flash mode)
uv run webqa-agent init      # Generates config.yaml (edit with your target URL & LLM API Key)
uv run webqa-agent gen       # Start testing
target:
  url: https://example.com
  max_concurrent_tests: 2
test_config:
  business_objectives:
    - >
      Search for "laptop", click the first result and confirm the detail page loads,
      then go back and switch to the "Images" tab and verify the content is related.
    - Apply a price filter and verify all displayed results fall within the selected range

**Built-in skills** (loaded on demand, no extra config needed): `plan`, `ui-audit`, `recovery`, `nuclei-scan`, `button-check`. See [docs/MODES&CLI.md](docs/MODES&CLI.md#built-in-skills) for details.

🖥️ Full-stack Deployment (Recommended for Teams)

For visual dashboard, test management, and history, start with Docker Compose:

git clone https://github.com/MigoXLab/webqa-agent.git
cd webqa-agent/deploy/docker-compose
cp .env.example .env
# Edit .env: fill in your LLM API Key
./start.sh

> Access via `http://localhost`. For other deployment methods, see [Deployment](#deployment).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 264 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!-- SEO Meta Information and Structured Data -->
  2. <div itemscope itemtype="https://schema.org/SoftwareApplication" align="center" xmlns="http://www.w3.org/1999/html">
  3. <meta itemprop="name" content="WebQA Agent: Autonomous Web Testing & Quality Assurance">
  4. <meta itemprop="description" content="AI-powered autonomous web browser agent that audits performance, functionality, UX, and security for comprehensive website testing and quality assurance">
  5. <meta itemprop="applicationCategory" content="Web Testing Software">
  6. <meta itemprop="operatingSystem" content="Cross-platform">
  7. <meta itemprop="programmingLanguage" content="Python">
  8. <meta itemprop="url" content="https://github.com/MigoXLab/webqa-agent">
  9. <meta itemprop="softwareVersion" content="latest">
  10. <meta itemprop="license" content="Apache-2.0">
  11. <meta itemprop="keywords" content="vibecoding, web evaluation, autonomous, web testing, automation, AI testing, browser automation, quality assurance, performance testing, UX testing, security testing, functional testing">
  12. <p align="center">
  13. <img src="docs/images/logo-title.svg" alt="WebQA Agent" height="80" />
  14. </p>
  15. <!-- badges -->
  16. <p align="center">
  17. <a href="https://github.com/MigoXLab/webqa-agent/blob/main/LICENSE"><img src="https://img.shields.io/github/license/MigoXLab/webqa-agent" alt="License"></a>
  18. <a href="https://github.com/MigoXLab/webqa-agent/stargazers"><img src="https://img.shields.io/github/stars/MigoXLab/webqa-agent" alt="GitHub stars"></a>
  19. <a href="https://github.com/MigoXLab/webqa-agent/network/members"><img src="https://img.shields.io/github/forks/MigoXLab/webqa-agent" alt="GitHub forks"></a>
  20. <a href="https://github.com/MigoXLab/webqa-agent/issues"><img src="https://img.shields.io/github/issues/MigoXLab/webqa-agent" alt="GitHub issues"></a>
  21. <a href="https://deepwiki.com/MigoXLab/webqa-agent"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
  22. </p>
  23. <p align="center">
  24. Join us on 🎮<a href="https://discord.gg/fG5QAxYyNr">Discord</a> | 💬<a href="https://aicarrier.feishu.cn/docx/NRNXdIirXoSQEHxhaqjchUfenzd">WeChat</a>
  25. </p>
  26. <p align="center"><a href="README.md">English</a> · <a href="README_zh-CN.md">简体中文</a></p>
  27. <p align="center">
  28. If you like WebQA Agent, please give us a ⭐ on GitHub!
  29. <br/>
  30. <a href="https://github.com/MigoXLab/webqa-agent/stargazers" target="_blank">
  31. <img src="docs/images/star.gif" alt="Click Star" width="900">
  32. </a>
  33. </p>
  34. <p align="center">🤖 <strong>WebQA Agent</strong> is a fully automated web testing agent with multimodal page understanding — no test scripts required. <strong>Powered by ⚡ WebQA Flash mode</strong> — just describe your business goal in one sentence and the agent drives the browser to complete the test in seconds. ✨ Use it via GUI / CLI directly, or integrate seamlessly with Cursor, Claude Code, and OpenClaw via MCP / Skill.</p>
  35. </div>
  36. <!-- Additional SEO Keywords and Context
  37. vibecoding, vibe coding, web evaluation, autonomous exploration, web testing automation, browser testing tool, AI-powered QA, automated web testing, website performance analysis, functional testing automation, user experience testing, UX, security vulnerability scanning, browser testing, web application testing, quality assurance automation, automated UI testing, web accessibility testing, performance monitoring, website audit tool, vibecoding testing, web development
  38. -->
  39. ## 📑 Table of Contents
  40. - [Core Features](#core-features)
  41. - [Examples](#examples)
  42. - [Quick Start](#quick-start)
  43. - [CLI Usage](#cli-usage)
  44. - [Deployment](#deployment)
  45. - [RoadMap](#roadmap)
  46. - [Acknowledgements](#acknowledgements)
  47. - [License](#license)
  48. ## 🚀 Core Features
  49. <a id="core-features"></a>
  50. ### 📋 Product Overview
  51. **WebQA Agent** offers three testing forms—from lightweight exploration to deep regression:
  52. | Capability | ⚡ **WebQA Flash** (Default · Recommended) | 🤖 **Standard Generate** | 📋 **Run Mode** |
  53. | :--------------- | :--------------------------------------------------------------------------- | :--------------------------------------------------------- | :------------------------------------------------- |
  54. | **Positioning** | Lightweight exploration engine; natural-language goals in seconds | AI discovery → dynamic generation → precise execution | Execute YAML instructions with expected verification |
  55. | **Use Cases** | Quick smoke tests, IDE inline runs, platform Flash exploration, MCP/Skill NL tests | New feature exploration, full QA; **Focused** / **Explore** planning | Repeatable and regression testing |
  56. | **User Input** | One-sentence goal (or concurrent goal list) | URL + optional objectives; platform picks **Focused** when goals are filled, **Explore** when empty | Structured natural-language steps |
  57. | **Entry Points** | CLI `gen` + `engine: flash`, web dashboard, MCP `run_test`, Skill | CLI `gen` + `engine: standard`, web dashboard | CLI `run`, web dashboard |
  58. **Usage & Deployment**: CLI (see [CLI Usage](#cli-usage)); full-stack deployment (Local / Docker / K8s) with Flash reports, API Key management, and one-click parameter backfill. See [Deployment](#deployment).
  59. For a detailed comparison and configuration guides for standard modes, see **[docs/MODES&CLI.md](docs/MODES&CLI.md)**.
  60. ### ⚡ Flash Key Advantages
  61. - **Second-scale execution, instant feedback**: No heavy offline planning, no lengthy test setup. Built on the lightweight Chrome DevTools MCP, the agent receives natural-language goals in real time and immediately drives the browser to interact and assert.
  62. - **Zero selector maintenance**: Say goodbye to CSS selectors and XPath. Multimodal AI identifies page elements directly — when the UI is redesigned or styles change, the agent looks and clicks like a human would.
  63. - **Native IDE & agent integration**: Ships with a standard MCP server. Issue test commands in natural language directly from **Cursor** or **Claude Code**, letting your AI coding assistant run the automation for you.
  64. ### 🧭 Architecture
  65. <p>
  66. <img src="docs/images/webqa2.svg" alt="WebQA Agent Architecture" />
  67. </p>
  68. ## 📹 Examples
  69. <a id="examples"></a>
  70. <p align="left">
  71. 🎬 <a href="https://pub-2c31c87660254d7bba9707e2b56fc15b.r2.dev/gen-baidu.mp4" target="_blank">Watch Demo: One-click testing of Baidu.com</a>
  72. </p>
  73. ## 🚀 Quick Start
  74. <a id="quick-start"></a>
  75. Choose between **🛠️ CLI Quick Start (Flash Mode)** or **🖥️ Full-stack Deployment (Web Dashboard)**.
  76. ### 🛠️ CLI Quick Start
  77. Recommended: install via [uv](https://github.com/astral-sh/uv) (Python>=3.11). Flash mode drives the browser through [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp).
  78. ```bash
  79. # 1) Create project and install
  80. uv init my-webqa && cd my-webqa
  81. uv add webqa-agent
  82. # 2) Install Chrome browser & Chrome MCP pre-requisites
  83. npm install -g chrome-devtools-mcp@latest # Required for Flash mode
  84. # 3) Initialize and Run (defaults to Flash mode)
  85. uv run webqa-agent init # Generates config.yaml (edit with your target URL & LLM API Key)
  86. uv run webqa-agent gen # Start testing
  87. ```
  88. ```yaml
  89. target:
  90. url: https://example.com
  91. max_concurrent_tests: 2
  92. test_config:
  93. business_objectives:
  94. - >
  95. Search for "laptop", click the first result and confirm the detail page loads,
  96. then go back and switch to the "Images" tab and verify the content is related.
  97. - Apply a price filter and verify all displayed results fall within the selected range
  98. ```
  99. **Built-in skills** (loaded on demand, no extra config needed): `plan`, `ui-audit`, `recovery`, `nuclei-scan`, `button-check`. See [docs/MODES&CLI.md](docs/MODES&CLI.md#built-in-skills) for details.
  100. ### 🖥️ Full-stack Deployment (Recommended for Teams)
  101. For visual dashboard, test management, and history, start with Docker Compose:
  102. ```bash
  103. git clone https://github.com/MigoXLab/webqa-agent.git
  104. cd webqa-agent/deploy/docker-compose
  105. cp .env.example .env
  106. # Edit .env: fill in your LLM API Key
  107. ./start.sh
  108. ```
  109. > Access via `http://localhost`. For other deployment methods, see [Deployment](#deployment).
  110. ## ⚙️ CLI Usage
  111. <a id="cli-usage"></a>
  112. ### CLI Parameter Details
  113. WebQA Agent provides a concise command-line interface for initialization, autonomous exploration, case execution, and launching the Web UI.
  114. | Command | Description | Common Arguments |
  115. | :------ | :------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
  116. | `init` | Initialize configuration file | `-m <gen/run>`: Specify mode; `-o <path>`: Output path; `--force`: Overwrite existing |
  117. | `gen` | **Generate/Flash Mode**: Autonomous test execution | `-c <path>`: Config path; `-w <n>`: Parallel workers; defaults to Flash engine (local Chrome via Chrome MCP) |
  118. | `run` | **Run Mode**: Execute YAML-defined test cases | `-c <path/dir>`: Config file or folder; `-w <n>`: Parallel workers; requires Standard engine (Playwright executor) |
  119. For details on Standard Gen and Run modes, see **[docs/MODES&CLI.md](docs/MODES&CLI.md)**.
  120. ### 📊 View Results
  121. Test reports are generated in the `reports/` directory. Open the HTML file to view detailed results.
  122. ______________________________________________________________________
  123. ### 🔌 MCP & Skill Integration
  124. #### WebQA MCP Server
  125. Expose browser testing to **Cursor**, **Claude Code**, and other IDEs via MCP. After install you get the `webqa-mcp-server` command.
  126. **1. Install**
  127. ```bash
  128. git clone https://github.com/MigoXLab/webqa-agent.git
  129. cd webqa-agent
  130. pip install -e .
  131. which webqa-mcp-server
  132. ```
  133. **2. API Key**
  134. WebQA platform → **API Keys** → create key (shown once).
  135. **3. IDE config (Cursor example)**
  136. Settings → MCP → Add Server:
  137. ```json
  138. {
  139. "mcpServers": {
  140. "webqa": {
  141. "command": "/absolute/path/to/webqa-mcp-server",
  142. "env": {
  143. "WEBQA_API_URL": "https://your-webqa-platform.com",
  144. "WEBQA_API_KEY": "wqa_xxxxxxxx..."
  145. }
  146. }
  147. }
  148. }
  149. ```
  150. Full tool reference: **[docs/MCP_SERVER.md](docs/MCP_SERVER.md)**.
  151. #### WebQA Skill
  152. The `skills/webqa/` package works with **OpenClaw** and **Claude Code** for natural-language browser tests without scripts.
  153. - **Claude Code**: Add `skills/webqa` to your project Skills path or copy to `.claude/skills/webqa`.
  154. - **OpenClaw**: Register `skills/webqa` per your OpenClaw Skill layout.
  155. Key references: `skills/webqa/SKILL.md`, `skills/webqa/references/mini-agent.md`, `skills/webqa/references/setup.md`.
  156. <a id="deployment"></a>
  157. ## 🖥️ Deployment
  158. For teams that need a **persistent web dashboard** with test management, scheduled tasks, and execution history, deploy the full-stack platform.
  159. **Platform highlights**:
  160. - **Flash exploration**: End-to-end integration with screenshots and step-level report detail
  161. - **API Key management**: Create MCP API keys for Cursor / Claude Code
  162. Deployment options:
  163. | Method | Use Case | Guide |
  164. | ----------------- | --------------------------- | ------------------------------------------------------ |
  165. | Local Development | Personal dev & debugging | [deploy/README.md](deploy/README.md#local-development) |
  166. | Docker Compose | Single-machine / Team trial | [deploy/README.md](deploy/README.md#docker-compose) |
  167. | Kubernetes | Production cluster | [deploy/k8s/README.md](deploy/k8s/README.md) |
  168. > **💡 Extending Internal Logic:** WebQA Agent supports extending internal logic based on your team's infrastructure (such as integrating internal SSO, OSS object storage, internal LLMs, etc.). You are free to customize and develop it to fit your needs. [deploy/README.md](deploy/README.md#custom-extensions)
  169. > **Note:** The web dashboard platform is currently only available in Chinese.
  170. <a id="roadmap"></a>
  171. ## 🗺️ RoadMap
  172. 1. **Interaction & Visualization**: Display the agent's reasoning chain and decision rationale in real time during test execution, so users can immediately understand why the AI took a particular path and adjust their business-goal descriptions and prompts accordingly (currently only post-hoc replay in the report).
  173. 2. **Flash multi-step cases**: Extend "one-sentence goal → single case chain" into a structured execution model with **precondition / steps / assertions**, enabling regression testing, failure localization, and cross-run reuse for complex scenarios (currently runs user input as a single case chain).
  174. 3. **Explore mode enhancement**: Persist the agent's broad-discovery findings (under no-PRD scenarios) into a structured, reusable test case library, closing the loop from discovery to regression instead of leaving one-off exploration reports (currently broad discovery, results not persisted).
  175. <a id="acknowledgements"></a>
  176. ## 🙏 Acknowledgements
  177. - [natbot](https://github.com/nat/natbot): Drive a browser with GPT-3
  178. - [Midscene.js](https://github.com/web-infra-dev/midscene/): AI Operator for Web, Android, Automation & Testing
  179. - [browser-use](https://github.com/browser-use/browser-use/): AI Agent for Browser control
  180. - [cc-mini](https://github.com/e10nMa2k/cc-mini): Ultra-light Python harness for agentic Claude Code workflows; provides the core engine, MCP client, skill registry, and cookie-management layer that powers WebQA Agent's Flash execution mode
  181. ## 📄 License
  182. <a id="license"></a>
  183. This project is licensed under the [Apache 2.0 License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.