🎭🤖 QA Agent Template

Claude + Playwright MCP — an AI tester that remembers your app

English · Español

Why?

Most AI testing setups rediscover your application from scratch on every run — burning tokens and producing inconsistent results.

This template gives the agent a persistent knowledge base (knowledge/) that it writes once during exploration and reuses on every later run. Each release, it gets faster, cheaper and more consistent.

✨ Features

• 🔍 Exploratory testing that builds an app map, user flows, business rules and UI inventory
• 💨 Smoke and 🔁 regression runs driven by that knowledge
• 🐛 Change validation from a GitHub issue URL — the agent reads the issue and tries to reproduce it
• 📄 PDF reports with executive summary, screenshots, console errors and metrics
• 🔐 Persistent login via Playwright storage state
• 🧠 Token-efficient: knowledge first, exploration only when asked

⚙️ How it works

flowchart LR
    C[project_config/*.yaml] --> A
    K[(knowledge/)] --> A
    P[prompts/*.md] --> A
    A[Claude Code<br/>+ Playwright MCP] -->|drives| B[🌐 Your web app]
    A -->|learns| K
    A --> R[📄 reports/generated<br/>HTML + PDF]

🚀 Quick start

Requirements: Node 20+, Claude Code (or Claude Desktop with MCP).

# 1. Use this template (or clone it)
git clone https://github.com/GonzaloAlarconRoldan/GUI-PlaywrightMCP-Framework.git my-qa-agent
cd my-qa-agent

# 2. Install deps + browser, create your local credentials file
npm install
npm run setup

# 3. Fill in your app
#    project_config/application.yaml   → name, base_url, login_url
#    project_config/credentials.yaml   → test user (git-ignored)
#    knowledge/testing_scope.md        → what matters

# 4. Start Claude Code — CLAUDE.md and .mcp.json are picked up automatically
claude

Then just tell the agent which job to run:

Execute prompts/exploratory.md

🧰 Jobs

Example:

Execute prompts/change_validation.md
Issue: https://github.com/acme/web-app/issues/142

📁 Project structure

.
├── CLAUDE.md                 # Entry point — Claude Code loads it automatically
├── CLAUDE_SYSTEM_PROMPT.md   # Agent role and browser rules
├── CLAUDE_CONTEXT.md         # What to read before acting
├── CLAUDE_REPORTING.md       # Report format and severity levels
├── .mcp.json                 # Playwright MCP server
├── project_config/           # Your app: URLs, environments, test data, credentials
├── knowledge/                # The agent's memory of your app (auto-maintained)
│   └── releases/             # Release notes for regression comparisons
├── prompts/                  # One prompt per testing job
├── playwright/
│   ├── playwright.config.ts
│   ├── auth/                 # Saved login session (git-ignored)
│   └── tests/                # Scripted tests + framework integrity checks
├── reports/                  # templates/, generated/, evidence/
├── screenshots/baseline/     # Visual baseline
├── generate_pdf.js           # HTML → PDF
└── docs/                     # Full guide and assets

📖 Documentation

• Full guide — every config and knowledge file explained, with examples
• Contributing · Security · Changelog

🗺️ Roadmap

• Exploratory, smoke, regression, change validation and report prompts
• PDF reports with screenshots
• CI with framework integrity tests
• Visual regression against baseline screenshots
• Accessibility audit prompt (axe-core)
• Turn discovered flows into reusable Playwright .spec.ts tests
• Example project against a public demo app

Got an idea? Open an issue.

🤝 Contributing

PRs are welcome — new prompts and report templates are the easiest place to start. See CONTRIBUTING.md.

⭐ Support

If this template saves you time, give it a star — it helps other QA engineers find it.

📝 License

MIT © Gonzalo Alarcón Roldán