🎭 Playwright Flow Tester

The Ultimate UI/UX Testing Suite with MCP Integration

Transform your testing workflow with AI-powered automation, comprehensive logging, and seamless MCP integration.

---

✨ Why Choose Playwright Flow Tester?

Feature	Traditional Testing	Our Solution
Screenshots	Last 3 steps only	🎯 20+ configurable buffers
Debug Info	Basic logs	🔍 Performance metrics + Network analysis
Integration	Manual setup	🤖 MCP-native with Claude Code/Cursor
Artifacts	File system only	📦 Streaming + Export + Caching
Dependencies	Multiple APIs	🚫 Zero external dependencies

---

🚀 Quick Start (2 minutes)

# 1. Clone & Build
git clone https://github.com/sadiuysal/flow-tester.git
cd flow-tester
docker build -t flow-tester-agent:latest flow_tester_agent/

# 2. Configure MCP (copy templates)
cp .cursor/mcp.json.template .cursor/mcp.json
cp .mcp.json.template .mcp.json
cp .claude/settings.local.json.template .claude/settings.local.json

# 3. Test Integration
./test-mcp.sh

🎉 That's it! Restart your editor and access 12 powerful MCP tools.

---

🛠️ 12 Powerful MCP Tools at Your Fingertips

🧪 Core Testing

• execute_enhanced_ui_flow - Run comprehensive UI flows with 20+ screenshot buffers
• create_flow_template - Generate templates for login, ecommerce, forms
• validate_flow_definition - Validate flows before execution

📊 Artifact Management

• get_artifacts - Retrieve traces, videos, screenshots with metadata
• list_artifacts - Filter and paginate through artifacts
• export_artifacts - Export in ZIP, JSON, HTML formats
• stream_artifact - Efficient streaming for large files

🔍 Debug & Analysis

• get_execution_logs - Detailed step-by-step execution logs
• get_debug_context - Performance metrics, element states, network data
• get_cache_stats - Monitor caching performance
• cleanup_artifacts - Intelligent retention policies

---

🎯 Perfect For

👨‍�� Developers	🧪 QA Engineers	🚀 DevOps Teams	🤖 AI Enthusiasts
Automated testing in CI/CD	Complex user flow validation	Infrastructure testing	MCP integration
Performance monitoring	Visual regression testing	Cross-browser testing	AI-powered workflows
Debug information	Artifact management	Scalable testing	Claude Code integration

---

🔥 Key Features That Set Us Apart

📸 Enhanced Screenshot Buffers

// Traditional: Only last 3 screenshots
// Our Solution: Configurable 20+ screenshots with metadata
const { snap } = withScreenRing(25); // Customize buffer size
await snap(page, 'user-login-attempt');
await snap(page, 'form-validation-error');
await snap(page, 'success-state');
// ... 22 more screenshots available!

📊 Comprehensive Debug Context

• Performance Metrics: Core Web Vitals, load times, memory usage
• Element States: Visibility, attributes, dimensions, position tracking
• Network Analysis: Request/response patterns, error detection
• Memory Monitoring: Usage patterns and optimization insights

🤖 MCP-Native Integration

• Zero Setup: Works immediately with Claude Code, Cursor, VS Code
• Real-time Access: Direct artifact access without file system mounting
• Streaming Support: Efficient handling of large artifacts
• Intelligent Caching: Configurable retention and compression

---

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    MCP Client (Claude/Cursor)              │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│              Playwright Flow Tester Agent                  │
│  ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │
│  │   Enhanced      │ │   Artifact      │ │   MCP        │ │
│  │   Logging       │ │   Manager       │ │   Server     │ │
│  │   (20+ buffers) │ │   (Streaming)   │ │   (12 tools) │ │
│  └─────────────────┘ └─────────────────┘ └──────────────┘ │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                    Playwright Engine                        │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │
│  │  Chromium  │ │   Firefox   │ │      WebKit         │   │
│  └─────────────┘ └─────────────┘ └─────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

📚 Documentation & Resources

Resource	Description	Link
🚀 Quick Start	Get running in 2 minutes	SETUP.md
📖 Usage Guide	Comprehensive API reference	USAGE.md
🔒 Security Audit	Complete security analysis	SECURITY_AUDIT.md
👨‍💻 Development	Contributing guidelines	CLAUDE.md

---

🌟 Real-World Use Cases

E-commerce Testing

// Test complete purchase flow with enhanced logging
await execute_enhanced_ui_flow({
  name: "purchase-flow",
  actions: [
    { type: "navigate", url: "/products" },
    { type: "click", selector: "[data-testid='add-to-cart']" },
    { type: "navigate", url: "/checkout" },
    { type: "fill", selector: "#email", value: "test@example.com" },
    { type: "click", selector: "[data-testid='complete-purchase']" }
  ],
  enhanced_logging: { screenshot_buffer_size: 25 }
});

Form Validation Testing

// Comprehensive form testing with debug context
await execute_enhanced_ui_flow({
  name: "registration-form",
  actions: [
    { type: "navigate", url: "/register" },
    { type: "fill", selector: "#username", value: "testuser" },
    { type: "fill", selector: "#email", value: "invalid-email" },
    { type: "click", selector: "#submit" }
  ],
  enhanced_logging: { 
    collect_performance_metrics: true,
    collect_element_states: true 
  }
});

---

🚀 Performance & Scalability

• ⚡ Fast Execution: Optimized Playwright workflows
• 🔄 Parallel Testing: Support for multiple concurrent flows
• 💾 Smart Caching: Configurable artifact retention
• 🌐 Cross-Platform: Works on Windows, macOS, Linux
• 🐳 Docker Ready: Consistent environment across deployments

---

�� Community & Support

• 📖 Comprehensive Docs: Setup guides, examples, troubleshooting
• 🔧 Active Development: Regular updates and improvements
• 🐛 Issue Tracking: GitHub issues for bug reports and feature requests
• 💡 Examples: Real-world use cases and templates
• 🔒 Security Focus: Regular security audits and updates

---

📊 Project Stats & Metrics

Metric	Value	Status
MCP Tools	12	✅ Complete
Screenshot Buffers	20+	✅ Configurable
Browser Support	3	✅ Chromium, Firefox, WebKit
Artifact Formats	4	✅ ZIP, JSON, HTML, Streaming
Dependencies	0	✅ Zero external APIs

---

🎯 Getting Started Today

1. 🚀 Quick Start Guide - Get running in 2 minutes
2. 📖 Usage Examples - Learn the API
3. 🔧 Configuration - Set up MCP integration
4. 🧪 Test Examples - See real-world usage

---

�� Star This Repository

If Playwright Flow Tester helps you build better software, please give us a ⭐ star! It helps with visibility and motivates us to keep improving.

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

• Playwright - The amazing browser automation framework
• Model Context Protocol - Seamless AI integration
• FastMCP - Python MCP server framework
• Community Contributors - Your feedback and contributions

---

🎭 Built with ❤️ for developers who demand excellence in testing

Get Started Now →