QA Browser MCP Agent
by palaneelam
README.md
# QA Browser MCP Agent for ToolShop
> A practical Browser MCP Agent series for testing the ToolShop application using Python, FastMCP, Playwright, GitHub Models API, and professional HTML reporting.
## Overview
This repository demonstrates how to build a QA Browser MCP Agent for ToolShop:
```text
https://practicesoftwaretesting.com
```
The project evolves from basic browser control to autonomous AI-powered QA execution.
## Who This Is For
- Manual Testers
- QA Engineers
- Automation Testers
- SDETs
- QA Leads
- QA Architects
- Students learning MCP
- Anyone learning Agentic AI for Software Testing
## Architecture
```text
User / QA Engineer
↓
Python Main Program
↓
FastMCP Client
↓
STDIO Transport
↓
FastMCP Browser Server
↓
Playwright
↓
Chrome Browser
↓
ToolShop Website
↓
Screenshots + HTML Reports
```
For AI versions:
```text
User Goal
↓
GitHub Models API
↓
AI Test Plan / Exploratory Test Ideas
↓
Browser MCP Server
↓
Playwright Execution
↓
Professional QA Report
```
## Versions
| Version | Folder | Purpose | AI Used | HTML Report |
|---|---|---|---|---|
| V1 | `v1_browser_control` | Browser control basics | No | No |
| V2 | `v2_search_testing_agent` | Search functionality testing | No | Yes |
| V3 | `v3_cart_testing_agent` | Shopping cart testing | No | Yes |
| V4 | `v4_checkout_testing_agent` | Checkout readiness testing | No | Yes |
| V5 | `v5_ai_exploratory_testing_agent` | AI exploratory testing | Yes | Yes |
| V6 | `v6_autonomous_browser_qa_agent` | Autonomous browser QA | Yes | Yes |
## Project Structure
```text
QA_Browser_MCP_Agent/
├── README.md
├── requirements.txt
├── .gitignore
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
├── docs/
│ ├── architecture.md
│ ├── version-comparison.md
│ ├── troubleshooting.md
│ └── sample-goals.md
├── v1_browser_control/
├── v2_search_testing_agent/
├── v3_cart_testing_agent/
├── v4_checkout_testing_agent/
├── v5_ai_exploratory_testing_agent/
└── v6_autonomous_browser_qa_agent/
```
## Prerequisites
Install:
- Python 3.12+
- Git
- VS Code
- Chromium via Playwright
- GitHub Models access for V5/V6
## Setup
```powershell
cd C:\GIT\qa_mcp_series
git clone https://github.com/YOUR_USERNAME/QA_Browser_MCP_Agent.git
cd QA_Browser_MCP_Agent
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium
```
## Environment Variables
Create `.env` in the project root only if you want V5/V6 to use GitHub Models:
```env
GITHUB_TOKEN=your_github_models_token_here
```
V1 to V4 do not need this token.
V5 and V6 also include fallback logic, so they can still run if the token is missing or quota is exhausted.
## Run Commands
Run all commands from project root.
```powershell
python .\v1_browser_control\main.py
python .\v2_search_testing_agent\main.py
python .\v3_cart_testing_agent\main.py
python .\v4_checkout_testing_agent\main.py
python .\v5_ai_exploratory_testing_agent\main.py
python .\v6_autonomous_browser_qa_agent\main.py
```
## Output Locations
Each version stores its own evidence:
```text
v2_search_testing_agent/screenshots/
v2_search_testing_agent/reports/
v3_cart_testing_agent/screenshots/
v3_cart_testing_agent/reports/
v4_checkout_testing_agent/screenshots/
v4_checkout_testing_agent/reports/
v5_ai_exploratory_testing_agent/screenshots/
v5_ai_exploratory_testing_agent/reports/
v6_autonomous_browser_qa_agent/screenshots/
v6_autonomous_browser_qa_agent/reports/
```
## Version 1: Browser Control MCP
Run:
```powershell
python .\v1_browser_control\main.py
```
Menu:
```text
1. Show Available MCP Tools
2. Open ToolShop and Capture Screenshot
3. Get ToolShop Homepage Info
4. Verify ToolShop Homepage Loads
0. Exit
```
Expected output:
```text
v1_browser_control/screenshots/toolshop_homepage.png
```
## Version 2: Search Testing Agent
Run:
```powershell
python .\v2_search_testing_agent\main.py
```
Inputs:
```text
Existing product: hammer
Invalid product: xyznotfound
Report name: search_test_report.html
```
Output:
```text
v2_search_testing_agent/reports/search_test_report.html
```
## Version 3: Cart Testing Agent
Run:
```powershell
python .\v3_cart_testing_agent\main.py
```
Inputs:
```text
Product: hammer
Report name: cart_test_report.html
```
Output:
```text
v3_cart_testing_agent/reports/cart_test_report.html
```
## Version 4: Checkout Testing Agent
Run:
```powershell
python .\v4_checkout_testing_agent\main.py
```
Inputs:
```text
Product: saw
Report name: checkout_test_report.html
```
Output:
```text
v4_checkout_testing_agent/reports/checkout_test_report.html
```
## Version 5: AI Exploratory Testing Agent
Run:
```powershell
python .\v5_ai_exploratory_testing_agent\main.py
```
Example goals:
```text
Perform security-oriented exploratory testing on ToolShop search
Explore ToolShop search from a usability perspective
Perform boundary testing on ToolShop search
Test ToolShop search functionality like a functional QA engineer
```
Output:
```text
v5_ai_exploratory_testing_agent/reports/ai_exploratory_search_report.html
```
## Version 6: Autonomous Browser QA Agent
Run:
```powershell
python .\v6_autonomous_browser_qa_agent\main.py
```
Example goals:
```text
Test ToolShop search functionality like a senior QA engineer
Perform security-focused browser QA testing on ToolShop search
Perform usability-focused testing on ToolShop product search
Perform boundary and negative testing on ToolShop search
```
Output:
```text
v6_autonomous_browser_qa_agent/reports/autonomous_browser_qa_report.html
```
## Important Concept: Why Single-Flow Tools Are Used
In MCP STDIO mode, each tool call may start a new server process. Browser state may not persist across separate menu options.
That is why this project uses stable single-flow tools:
```text
open_toolshop_and_capture_screenshot()
run_search_functionality_tests()
run_cart_functionality_tests()
run_checkout_functionality_tests()
run_ai_exploratory_search_tests()
run_autonomous_browser_qa()
```
## Troubleshooting Summary
Detailed troubleshooting is available in:
```text
docs/troubleshooting.md
```
Common issues covered:
- Browser state not persisting
- Unknown tool
- MCP connection closed
- Missing GitHub token
- Same AI results for every goal
- GitHub Models rate limit
- Playwright timeout
- Checkout button not found
- Screenshot links not opening
- Browser executable missing
## Git Commands
Check status:
```powershell
git status
```
Recommended `.gitignore` should exclude:
```text
.env
.venv/
__pycache__/
screenshots/
reports/
*.html
*.png
```
Commit:
```powershell
git add README.md requirements.txt .gitignore LICENSE CHANGELOG.md CONTRIBUTING.md docs/ v1_browser_control/ v2_search_testing_agent/ v3_cart_testing_agent/ v4_checkout_testing_agent/ v5_ai_exploratory_testing_agent/ v6_autonomous_browser_qa_agent/
git commit -m "Add QA Browser MCP Agent with six progressive versions"
git push origin main
```
If your branch is master:
```powershell
git push origin master
```
## Learning Outcomes
You will learn:
- MCP client-server architecture
- Browser automation using Playwright
- How to expose browser actions as MCP tools
- Why STDIO MCP can be stateless
- How to design stable browser-agent workflows
- How to generate professional HTML reports
- How AI can generate exploratory test ideas
- How to evolve from automation scripts to autonomous QA agents
## Future Enhancements
- Excel reporting
- PDF reporting
- Console log capture
- Network log capture
- Accessibility checks
- Visual validation
- Login flow testing
- Checkout form validation
- Bug report generation
- AI root cause analysis
- GitHub Actions
- Docker support
## Author
Neelam Pal
QA Architect | AI in Testing | MCP | Agentic AI | Quality Engineering
## License
MIT License.
This server cannot be deployed
Maintenance
ActivityStale
ResponsivenessNo issues