🎭 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: "[email protected]" },
    { 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 →