WebQA Agent

Try Demo 🤗HuggingFace | 🚀ModelScope
Join us on 🎮Discord | 💬WeChat

🤖 WebQA Agent is an autonomous web browser agent that audits performance, functionality & UX for engineers and vibe-coding creators. ✨

🚀 Core Features

🧭 Overview

📋 Feature Highlights

🤖 AI-Powered Testing: Performs autonomous website testing—explores pages, plans actions, and executes end-to-end flows without manual scripting.
📊 Multi-Dimensional Observation: Covers functionality, performance, user experience, and basic security; evaluates load speed, design details, and links to surface issues.
🎯 Actionable Recommendations: Runs in real browsers and provides concrete suggestions for improvement.
📈 Visual Reports: Generates detailed HTML test reports with clear, multi-dimensional views for analysis and tracking.

📹 Examples

🤖 Conversational UI: Autonomously plans goals and interacts across a dynamic chat interface
🎨 Creative Page: Explores page structure, identifies elements

Try Demo: 🤗Hugging Face · 🚀ModelScope

Installation & Configuration

🚀 One-Click Docker Setup

Before starting, ensure Docker is installed. If not, please refer to the official installation guide: Docker Installation Guide.

Recommended versions: Docker >= 24.0, Docker Compose >= 2.32.

# 1. Download configuration template
mkdir -p config && curl -fsSL https://raw.githubusercontent.com/MigoXLab/webqa-agent/main/config/config.yaml.example -o config/config.yaml

# 2. Edit configuration file
# Set target.url, llm_config.api_key and other parameters

# 3. One-click start
curl -fsSL https://raw.githubusercontent.com/MigoXLab/webqa-agent/main/start.sh | bash

Source Installation

git clone https://github.com/MigoXLab/webqa-agent.git
cd webqa-agent

Install Python >= 3.10 and run the following commands:

pip install -r requirements.txt
playwright install

Performance Analysis - Lighthouse (Optional)

# Requires Node.js >= 18.0.0
npm install

Security Scanning - Nuclei (Optional)

Download from: Nuclei Releases

# MacOS
brew install nuclei

# For other systems, download the appropriate version from the link above

# Update templates and verify installation
nuclei -ut -v          # Update Nuclei templates
nuclei -version        # Verify successful installation

After configuring config/config.yaml (refer to "Usage > Test Configuration"), run:

python webqa-agent.py

Usage

Test Configuration

webqa-agent uses YAML configuration for test parameters:

target:
  url: https://example.com/                       # Website URL to test
  description: example description

test_config:                                      # Test configuration
  function_test:                                  # Functional testing
    enabled: True
    type: ai                                      # default or ai
    business_objectives: example business objectives  # Recommended to include test scope, e.g., test search functionality
  ux_test:                                        # User experience testing
    enabled: True
  performance_test:                               # Performance analysis
    enabled: False
  security_test:                                  # Security scanning
    enabled: False

llm_config:                                       # Vision model configuration, currently supports OpenAI SDK compatible format only
  model: gpt-4.1-2025-04-14                       # Recommended
  api_key: your_api_key
  base_url: https://api.example.com/v1

browser_config:
  viewport: {"width": 1280, "height": 720}
  headless: False                                 # Automatically overridden to True in Docker environment
  language: zh-CN
  cookies: []

Please note the following important considerations when configuring and running tests:

1. Functional Testing Notes

AI Mode: When specifying the number of test cases to generate in the configuration file, the system may re-plan based on actual page conditions. This may result in the final number of executed test cases differing from the initial configuration to ensure coverage and effectiveness.
Default Mode: The default mode focuses on whether UI interactions (e.g., clicks and navigations) complete successfully.

2. User Experience Testing Notes

UX (User Experience) testing focuses on usability, and user-friendliness. The model output in the results provides suggestions based on best practices to guide optimization.

🧠 Recommended Models

Based on our testing, these models work well with WebQA Agent:

Model	Key Strengths	Notes
gpt-4.1-2025-04-14 ⭐	High accuracy & reliability	Best choice
gpt-4.1-mini-2025-04-14	Cost-effective	Economical and practical
doubao-seed-1-6-vision-250815	Vision capabilities	Excellent web understanding

View Results

Test results will be generated in the reports directory. Open the HTML report within the generated folder to view results.

Roadmap

Continuous optimization of AI functional testing: Improve coverage and accuracy
Functional traversal and page validation: Verify business logic correctness and data integrity
Interaction and visualization: Test item visualization and local service real-time reasoning process display
Capability expansion: Multi-model integration and more evaluation dimensions

Acknowledgements

natbot: Drive a browser with GPT-3
Midscene.js: AI Operator for Web, Android, Automation & Testing
browser-use: AI Agent for Browser control

Open Source License

This project is licensed under the Apache 2.0 License.