webqa-agent

📑 Table of Contents

• Core Features
• Examples
• Quick Start
• CLI Usage
• Deployment
• RoadMap
• Acknowledgements
• License

🚀 Core Features

📋 Product Overview

WebQA Agent offers three testing forms—from lightweight exploration to deep regression:

Capability	⚡ WebQA Flash (Default · Recommended)	🤖 Standard Generate	📋 Run Mode
Positioning	Lightweight exploration engine; natural-language goals in seconds	AI discovery → dynamic generation → precise execution	Execute YAML instructions with expected verification
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
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
Entry Points	CLI gen + engine: flash, web dashboard, MCP run_test, Skill	CLI gen + engine: standard, web dashboard	CLI run, web dashboard

Usage & Deployment: CLI (see CLI Usage); full-stack deployment (Local / Docker / K8s) with Flash reports, API Key management, and one-click parameter backfill. See Deployment.

For a detailed comparison and configuration guides for standard modes, see docs/MODES&CLI.md.

⚡ Flash Key Advantages

• 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.
• 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.
• 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.

🧭 Architecture

📹 Examples

🎬 Watch Demo: One-click testing of Baidu.com

🚀 Quick Start

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

🛠️ CLI Quick Start

Recommended: install via uv (Python>=3.11). Flash mode drives the browser through 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 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.

⚙️ CLI Usage

CLI Parameter Details

WebQA Agent provides a concise command-line interface for initialization, autonomous exploration, case execution, and launching the Web UI.

Command	Description	Common Arguments
init	Initialize configuration file	-m <gen/run>: Specify mode; -o <path>: Output path; --force: Overwrite existing
gen	Generate/Flash Mode: Autonomous test execution	-c <path>: Config path; -w <n>: Parallel workers; defaults to Flash engine (local Chrome via Chrome MCP)
run	Run Mode: Execute YAML-defined test cases	-c <path/dir>: Config file or folder; -w <n>: Parallel workers; requires Standard engine (Playwright executor)

For details on Standard Gen and Run modes, see docs/MODES&CLI.md.

📊 View Results

Test reports are generated in the reports/ directory. Open the HTML file to view detailed results.

---

🔌 MCP & Skill Integration

WebQA MCP Server

Expose browser testing to Cursor, Claude Code, and other IDEs via MCP. After install you get the webqa-mcp-server command.

1. Install

git clone https://github.com/MigoXLab/webqa-agent.git
cd webqa-agent
pip install -e .
which webqa-mcp-server

2. API Key

WebQA platform → API Keys → create key (shown once).

3. IDE config (Cursor example)

Settings → MCP → Add Server:

{
  "mcpServers": {
    "webqa": {
      "command": "/absolute/path/to/webqa-mcp-server",
      "env": {
        "WEBQA_API_URL": "https://your-webqa-platform.com",
        "WEBQA_API_KEY": "wqa_xxxxxxxx..."
      }
    }
  }
}

Full tool reference: docs/MCP_SERVER.md.

WebQA Skill

The skills/webqa/ package works with OpenClaw and Claude Code for natural-language browser tests without scripts.

• Claude Code: Add skills/webqa to your project Skills path or copy to .claude/skills/webqa.
• OpenClaw: Register skills/webqa per your OpenClaw Skill layout.

Key references: skills/webqa/SKILL.md, skills/webqa/references/mini-agent.md, skills/webqa/references/setup.md.

🖥️ Deployment

For teams that need a persistent web dashboard with test management, scheduled tasks, and execution history, deploy the full-stack platform.

Platform highlights:

• Flash exploration: End-to-end integration with screenshots and step-level report detail
• API Key management: Create MCP API keys for Cursor / Claude Code

Deployment options:

Method	Use Case	Guide
Local Development	Personal dev & debugging	deploy/README.md
Docker Compose	Single-machine / Team trial	deploy/README.md
Kubernetes	Production cluster	deploy/k8s/README.md

💡 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

Note: The web dashboard platform is currently only available in Chinese.

🗺️ RoadMap

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).
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).
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).

🙏 Acknowledgements

• natbot: Drive a browser with GPT-3
• Midscene.js: AI Operator for Web, Android, Automation & Testing
• browser-use: AI Agent for Browser control
• 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

📄 License

This project is licensed under the Apache 2.0 License.