What is Claude Code Playwright Mcp Test

Playwright MCP is a YAML-based automation testing framework designed for Claude Code. It innovatively uses a dynamic element identification system, which assigns unique ref_ids to web elements instead of relying on brittle CSS selectors or XPath expressions, enabling precise interaction based on natural language descriptions.

Use cases

This framework is ideal for automating web application tests in various environments such as development, testing, and production. It supports multi-environment configuration, reusable step libraries for efficiency, and is particularly suited for natural language test cases that do not require deep scripting knowledge.

How to use

To utilize Playwright MCP, you first need to install Playwright and set up environment variables in configuration files (.env.dev, .env.test, .env.prod). Write your test cases in YAML format using natural language or refer to reusable step libraries. Then execute your tests using Claude Code commands, specifying the environment and any necessary file paths.

Key features

Key features include dynamic element targeting through ref_id generation, natural language processing for test steps, multi-environment support, performance improvements through session persistence, and smart reporting capabilities with detailed execution metrics. The framework also allows for easy parameterization of test steps and environment variables.

Where to use

Playwright MCP can be used in diverse testing scenarios for web applications, particularly where dynamic content and user interactions occur. It finds application in environments like QA, continuous integration/continuous deployment (CI/CD) pipelines, and for teams looking to enhance their test automation processes in a user-friendly manner.

Claude Code + Playwright MCP YAML Testing Framework

中文文档 | English Documentation

An intelligent automation testing framework powered by Claude Code + Playwright MCP, enabling natural language YAML-based testing with dynamic element targeting, multi-environment configuration, and session persistence.

🧠 How Playwright MCP Works - The Core Innovation

🎯 Revolutionary Element Targeting System

Unlike traditional Playwright automation that relies on fragile CSS selectors or XPath expressions, Playwright MCP uses a revolutionary dynamic element identification system:

flowchart TD
    A["🌐 Web Page Loaded"] --> B["🔍 Playwright MCP Scans Page"]
    B --> C["🏷️ Assigns Unique ref_id to Each Element"]
    C --> D["📋 Creates Accessibility Snapshot"]
    D --> E["🤖 Claude Code Receives Element Map"]
    E --> F["🗣️ User Writes Natural Language Step"]
    F --> G["🎯 Claude Matches Description to ref_id"]
    G --> H["⚡ Executes Precise Action"]
    
    style A fill:#4CAF50,stroke:#2E7D32,stroke-width:3px,color:#ffffff
    style B fill:#2196F3,stroke:#1565C0,stroke-width:3px,color:#ffffff
    style C fill:#FF9800,stroke:#F57C00,stroke-width:3px,color:#ffffff
    style D fill:#9C27B0,stroke:#6A1B9A,stroke-width:3px,color:#ffffff
    style E fill:#F44336,stroke:#C62828,stroke-width:3px,color:#ffffff
    style F fill:#607D8B,stroke:#37474F,stroke-width:3px,color:#ffffff
    style G fill:#3F51B5,stroke:#283593,stroke-width:3px,color:#ffffff
    style H fill:#4CAF50,stroke:#2E7D32,stroke-width:3px,color:#ffffff

🎯 Dynamic ref_id Generation

When Playwright MCP accesses a web page, it automatically:

1. Scans all interactive elements on the page (buttons, inputs, links, etc.)
2. Assigns unique ref_id attributes to each element dynamically
3. Creates an accessibility snapshot with element descriptions and their corresponding ref_ids
4. Provides this mapping to Claude Code for intelligent element selection

🎯 Intelligent Element Selection

Instead of guessing selectors, Claude Code can:

• See exactly what elements exist on the page with human-readable descriptions
• Reference elements by their unique ref_id with 100% accuracy
• Avoid brittle selector-based failures that plague traditional automation
• Handle dynamic content without manual selector updates

🎯 Natural Language to Precise Actions

# Your YAML test step:
- "Click Add to Cart button for first product"

# What happens behind the scenes:
# 1. Playwright MCP identifies all "Add to Cart" buttons
# 2. Assigns ref_ids: button[ref_id="addcart_123"], button[ref_id="addcart_456"]
# 3. Claude Code intelligently selects the first one: ref_id="addcart_123"
# 4. Executes precise click action without guessing selectors

🎯 Benefits Over Traditional Automation

This is why our YAML-based approach is so powerful - you write in natural language, and Playwright MCP handles the complex element targeting automatically.

🎬 Demo Video

Watch the live demonstration of YAML-based Playwright testing in action:

📺 Watch Demo Video - See how to write and execute tests using natural language with Claude Code and Playwright MCP.

🌟 Key Features

• 🌍 Multi-Environment Support: Support for dev/test/prod environments with automatic configuration loading
• 📚 Reusable Step Libraries: Parameterized reusable step libraries to improve testing efficiency
• 🗣️ Natural Language: Direct use of natural language for test step descriptions, easy to read and write
• 🔧 Environment Variables: Automatic configuration loading from .env files, secure management of sensitive information
• 📊 Smart Reporting: Configurable test report generation with embedded data supporting HTML/JSON formats
• 📝 Smart Prompts: Claude Code project commands support parameter prompts
• 🚀 Session Persistence: Revolutionary cross-command session persistence - login once, test forever
• ⚡ Performance Boost: 80-95% performance improvement after first login with persistent sessions

🗺️ Development Roadmap

We’re actively working on exciting new features to make YAML-based testing even more powerful:

✅ Completed Features

✅ Cursor IDE Support - COMPLETED 🎉

• ✅ Project Rules Integration: Complete .mdc rule file for Cursor AI integration
• ✅ Command Support: Full /run-yaml-test command support in Cursor
• ✅ Session Persistence: Same 80-95% performance boost in Cursor as Claude Code
• ✅ Cross-Platform Compatibility: Unified framework works seamlessly in both IDEs

✅ Test Suites Support - COMPLETED 🎉

• ✅ Suite Organization: Group related test cases into logical suites
• ✅ Batch Execution: Run entire test suites with a single command
• ✅ Suite-level Configuration: Environment variables and settings per suite
• ✅ Suite Reporting: Aggregated reports across multiple test cases
• ✅ Pre/Post Actions: Suite-level setup and cleanup operations
• ✅ Validation Commands: Comprehensive suite validation functionality

# Example: test-suites/e-commerce.yml
name: "E-commerce Test Suite"
description: "Complete e-commerce workflow testing"
tags:
  - e-commerce
  - integration
test-cases:
  - "test-cases/order.yml"
  - "test-cases/product-details.yml"
  - "test-cases/sort-optimized.yml"

Available Suite Commands:

• /run-test-suite suite:e-commerce.yml env:test
• /validate-test-suite suite:smoke-tests.yml env:dev

📅 Release Timeline

🚀 Quick Start

Install Playwright MCP

claude mcp add playwright -- npx -y @playwright/mcp@latest \
  --user-data-dir ~/.cache/claude-playwright \
  --storage-state ~/.cache/claude-playwright/auth-state.json \
  --save-trace \
  --output-dir ~/CascadeProjects/claude-code-playwright-mcp-test/screenshots

Run Your First Test

# Execute order test
/run-yaml-test file:test-cases/order.yml env:dev

# View reports
/view-reports-index

Simple YAML Test Example

# test-cases/example.yml
tags:
  - smoke
steps:
  - include: "login"
  - "Click Add to Cart button for first product"
  - "Click shopping cart icon"
  - "Verify cart contains 1 item"

📚 Documentation

• 📖 Installation Guide - Detailed setup instructions
• 🏗️ Project Structure - Understanding the framework structure
• ⚡ Commands Reference - Complete command documentation
• 📝 YAML Format Guide - Writing test cases and step libraries
• 🔧 Environment Configuration - Multi-environment setup
• ✨ Best Practices - Tips for effective testing

📊 Latest Test Results

📈 Latest Test Report - Automatically generated after each test run, showing detailed execution results, screenshots, and performance metrics.

💡 Feature Requests

Have ideas for new features? We’d love to hear from you!

• Open an Issue with the enhancement label
• Join discussions in our community
• Contribute to the roadmap planning

🤝 Contributing

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📺 Resources

• 🎬 Demo Video - Live demonstration of the framework
• 📈 Latest Test Report - Most recent test execution results
• 📖 Medium Article - Detailed explanation and benefits
• 🛠️ Claude Code - AI-powered development environment
• 🎭 Playwright MCP - Browser automation integration

🆘 Support

If you encounter issues or have suggestions:

1. Watch the demo video for visual guidance
2. Check the documentation
3. Review Issues
4. Create a new Issue describing the problem
5. Use /help in Claude Code for more assistance

Happy Testing! 🚀