playwright-mcp-server

dipakprajapati2703/playwright-mcp-server

3.2

If you are the rightful owner of playwright-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Playwright MCP Server is a Model Context Protocol server that integrates Claude Code with Microsoft Playwright for advanced browser automation and debugging capabilities.

Tools
5
Resources
0
Prompts
0

Playwright MCP Server - Installation & Frontend Debugging Guide [Cluade Code]

Complete guide for setting up Playwright MCP (Model Context Protocol) server with Claude Code for debugging frontend issues in Magento 2.

Table of Contents

  1. What is Playwright MCP Server?
  2. Prerequisites
  3. Installation
  4. Configuration
  5. Available Tools
  6. Debugging Frontend Issues
  7. Magento 2 Specific Examples
  8. Troubleshooting
  9. Best Practices

What is Playwright MCP Server?

Playwright MCP Server is a Model Context Protocol server that provides Claude Code with browser automation capabilities through Microsoft Playwright. It enables:

  • Browser Automation: Navigate, click, fill forms, interact with elements
  • Visual Testing: Capture screenshots and videos
  • Network Monitoring: Inspect API calls and requests
  • Console Logging: Track JavaScript errors and warnings
  • Multi-Browser Support: Test across Chromium, Firefox, and WebKit
  • Mobile Emulation: Test responsive designs

This is particularly valuable for debugging complex frontend issues in Magento 2 e-commerce platforms.

Prerequisites

Before installing Playwright MCP server, ensure you have:

  • Node.js: Version 16 or higher
  • npm: Latest version (comes with Node.js)
  • Claude Code: Installed and configured
  • MCP Configuration: .mcp.json file in your project root

Check Prerequisites

# Check Node.js version
node --version
# Expected: v16.x.x or higher

# Check npm version
npm --version
# Expected: 8.x.x or higher

# Check if .mcp.json exists
ls -la .mcp.json

Installation

Step 1: Install Playwright MCP Server

You can install the Playwright MCP server globally or use it via npx.

Option A: Global Installation (Recommended)
npm install -g @executeautomation/playwright-mcp-server

Advantages:

  • Faster startup time
  • No need to download on each use
  • Better for frequent use
Option B: Use via npx (No Installation)
# No installation needed - npx will download on first use
npx -y @executeautomation/playwright-mcp-server

Advantages:

  • Always uses latest version
  • No global package management
  • Good for occasional use

Step 2: Verify Installation

# If installed globally
which playwright-mcp-server

# Test with npx
npx @executeautomation/playwright-mcp-server --help

Configuration

Step 1: Create or Update .mcp.json

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@executeautomation/playwright-mcp-server"
      ]
    }
  }
}

If you have existing MCP servers, add Playwright alongside them:

{
  "mcpServers": {
    "magento-api-m246": {
      "command": "magento-api-mcp",
      "env": {
        "MAGENTO_API_SWAGGER_PATH": "/var/www/html/m246/swagger.json",
        "MAGENTO_API_DB_PATH": "/home/logicrays/.mcp/magento-api/m246.db"
      }
    },
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@executeautomation/playwright-mcp-server"
      ]
    }
  }
}

Step 2: Restart Claude Code

After updating .mcp.json, you must restart Claude Code:

# If running in terminal, press Ctrl+C and restart
# Or restart your IDE/terminal session

Step 3: Verify MCP Server is Loaded

After restart, check available tools in Claude Code. You should see Playwright-related tools.

Available Tools

Once configured, Playwright MCP provides these tools:

Navigation Tools

  • playwright_navigate - Navigate to URLs
  • playwright_screenshot - Capture page screenshots
  • playwright_click - Click elements
  • playwright_fill - Fill form fields
  • playwright_evaluate - Execute JavaScript on page

Inspection Tools

  • playwright_get_page_content - Get HTML content
  • playwright_wait_for_selector - Wait for elements
  • playwright_get_element_text - Extract text content
  • playwright_get_element_attribute - Get element attributes

Console & Network Tools

  • playwright_console_messages - Get console logs
  • playwright_network_requests - Monitor network activity
  • playwright_network_responses - Inspect API responses

Browser Management

  • playwright_new_browser - Launch new browser instance
  • playwright_new_page - Open new page/tab
  • playwright_close - Close browser/page
  • playwright_set_viewport - Set screen size (responsive testing)

Debugging Frontend Issues

Common Debugging Workflow

1. Start Browser and Navigate
// Claude will execute:
// 1. Launch browser
// 2. Navigate to your Magento store
// 3. Wait for page load

Example Request:

"Open a browser and navigate to http://localhost/m246/"

2. Capture Initial State
// Take screenshot of homepage
// Get console errors
// Check network requests

Example Request:

"Take a screenshot of the homepage and show me any JavaScript errors"

3. Interact with Elements
// Click buttons, fill forms, navigate
// Monitor behavior and responses

Example Request:

"Click on the 'Add to Cart' button and show me the network requests"

4. Verify Results
// Check DOM changes
// Verify API responses
// Capture final state

Example Request:

"Check if the cart counter updated and take a screenshot"

Magento 2 Specific Examples

Example 1: Debug Product Page Issues

Scenario: Product images not loading correctly

**Request to Claude:**
"Open http://localhost/m246/catalog/product/view/id/123 and:
1. Take a screenshot
2. Check console for JavaScript errors
3. Show me all network requests for images
4. Inspect the gallery element's HTML"

What Claude will do:

  1. Navigate to product page
  2. Capture screenshot showing current state
  3. Extract console errors (e.g., 404 errors, JS exceptions)
  4. List all image requests with status codes
  5. Show DOM structure of product gallery

Expected Output:

  • Screenshot showing missing images
  • Console error: "Failed to load resource: the server responded with a status of 404"
  • Network log showing failed image requests
  • HTML showing incorrect image paths

Example 2: Debug Add to Cart Functionality

Scenario: Add to Cart button not working

**Request to Claude:**
"Debug the Add to Cart functionality:
1. Navigate to product page SKU-12345
2. Click 'Add to Cart' button
3. Monitor AJAX requests
4. Check for JavaScript errors
5. Verify minicart update"

What Claude will do:

  1. Open product page
  2. Click the Add to Cart button
  3. Capture all XHR/Fetch requests to /checkout/cart/add/
  4. Show response data (success/error messages)
  5. Check if minicart counter updated
  6. Screenshot before/after states

Expected Output:

  • Network request to /customer/section/load/
  • Response showing cart data
  • Console errors if AJAX failed
  • Minicart DOM changes

Example 3: Debug Checkout Page

Scenario: Shipping method not appearing

**Request to Claude:**
"Debug checkout shipping step:
1. Open checkout page
2. Fill shipping address form
3. Wait for shipping methods to load
4. Take screenshot of shipping methods section
5. Show me the API call to get shipping rates
6. Check for JavaScript errors"

What Claude will do:

  1. Navigate to /checkout/
  2. Fill in address fields (street, city, zip, country)
  3. Monitor network for /rest/V1/guest-carts/{cartId}/estimate-shipping-methods
  4. Capture screenshot of shipping options
  5. Show API response with available methods
  6. Display any console errors

Expected Output:

  • API response showing shipping methods array
  • Screenshot showing rendered shipping options
  • Console errors if rates failed to load
  • Timing information for API calls

Example 4: Debug Bundle Product Custom Options

Scenario: Bundle options not displaying (CellularIsrael/BundleCustomOptions module)

**Request to Claude:**
"Debug bundle product custom options:
1. Open bundle product page
2. Inspect custom options HTML structure
3. Check for JavaScript errors related to options
4. Monitor AJAX calls when selecting options
5. Capture screenshots of option selections"

What Claude will do:

  1. Navigate to bundle product
  2. Show HTML of .product-custom-option elements
  3. Display RequireJS/Knockout.js errors
  4. Monitor /catalog/product/view/ AJAX calls
  5. Screenshot each step of option selection

Expected Output:

  • DOM structure of custom options
  • JavaScript errors (e.g., "Cannot read property 'push' of undefined")
  • AJAX requests for option pricing
  • Visual confirmation of options rendering

Example 5: Debug Payment Gateway Integration

Scenario: CardknoxDevelopment payment form not appearing

**Request to Claude:**
"Debug Cardknox payment integration:
1. Navigate through checkout to payment step
2. Check if Cardknox payment method is visible
3. Monitor network for Cardknox API calls
4. Inspect iframe elements (if using hosted fields)
5. Show console errors related to payment"

What Claude will do:

  1. Navigate to checkout payment step
  2. Check DOM for payment method elements
  3. Monitor network for *.cardknox.com requests
  4. Inspect iframe src and loading status
  5. Show console errors (CSP issues, loading failures)

Expected Output:

  • Payment methods HTML structure
  • Cardknox API initialization requests
  • Iframe elements and their sources
  • CSP or CORS errors if present

Example 6: Debug Responsive Design Issues

Scenario: Mobile menu not working on tablets

**Request to Claude:**
"Test mobile menu on tablet viewport:
1. Set viewport to iPad (768x1024)
2. Navigate to homepage
3. Click hamburger menu icon
4. Take screenshot of opened menu
5. Check for touch event handlers
6. Show any JavaScript errors"

What Claude will do:

  1. Set browser viewport to 768x1024
  2. Navigate to homepage
  3. Find and click .mobile-menu-toggle
  4. Screenshot showing menu state
  5. Execute JavaScript to check event listeners
  6. Display console errors

Expected Output:

  • Screenshot showing menu opened/closed state
  • Event listeners attached to menu elements
  • CSS media query information
  • Touch event compatibility issues

Example 7: Debug Search Autocomplete

Scenario: Search suggestions not appearing

**Request to Claude:**
"Debug search autocomplete:
1. Navigate to homepage
2. Click in search box
3. Type 'iphone' slowly
4. Monitor AJAX requests to search endpoint
5. Show autocomplete dropdown HTML
6. Check for JavaScript errors"

What Claude will do:

  1. Open homepage
  2. Focus on .search-field input
  3. Type characters with delays
  4. Monitor /search/ajax/suggest/ requests
  5. Show autocomplete container HTML
  6. Display timing and response data

Expected Output:

  • AJAX requests with query parameters
  • JSON response with product suggestions
  • HTML structure of dropdown
  • JavaScript errors (if autocomplete fails)

Example 8: Debug Customer Login Issues

Scenario: Login form not submitting

**Request to Claude:**
"Debug customer login:
1. Navigate to login page
2. Fill email and password fields
3. Click login button
4. Monitor POST request to /customer/account/loginPost/
5. Show response data
6. Check for validation errors
7. Capture screenshot of result"

What Claude will do:

  1. Open /customer/account/login/
  2. Fill form fields
  3. Submit form
  4. Capture POST request with form data
  5. Show response (redirect or error)
  6. Check for form validation messages
  7. Screenshot final state

Expected Output:

  • POST request with credentials (masked)
  • Response status code (302 redirect or 400 error)
  • Error messages in DOM
  • Console errors if AJAX failed

Example 9: Debug Page Performance

Scenario: Slow page load times

**Request to Claude:**
"Analyze homepage performance:
1. Navigate to homepage with network monitoring
2. Show all network requests with timing
3. Identify slowest resources
4. Check for render-blocking resources
5. Show total page load time
6. Recommend optimizations"

What Claude will do:

  1. Load homepage with performance monitoring
  2. List all requests with waterfall timing
  3. Highlight requests >1s
  4. Identify blocking CSS/JS
  5. Calculate total load time
  6. Suggest improvements

Expected Output:

  • Network waterfall chart data
  • Slow resources identified (e.g., large images, slow APIs)
  • Blocking resources list
  • Total load time: X seconds
  • Recommendations (image optimization, lazy loading, etc.)

Example 10: Debug Cookie/Session Issues

Scenario: Shopping cart losing items on refresh

**Request to Claude:**
"Debug cart session persistence:
1. Navigate to product page
2. Add product to cart
3. Check cookies set by server
4. Refresh the page
5. Verify cart still contains items
6. Show session cookie details"

What Claude will do:

  1. Open product page
  2. Add item to cart
  3. Extract all cookies (frontend, private_content_version)
  4. Refresh browser
  5. Check cart contents
  6. Show cookie values and expiration

Expected Output:

  • Cookie list: PHPSESSID, mage-cache-storage, form_key
  • Session ID before/after refresh
  • Cart persistence status
  • Cookie expiration times

Troubleshooting

Issue 1: MCP Server Not Loading

Symptoms:

  • Playwright tools not available in Claude Code
  • Error: "MCP server failed to start"

Solutions:

# 1. Verify installation
npm list -g @executeautomation/playwright-mcp-server

# 2. Test npx execution
npx @executeautomation/playwright-mcp-server --help

# 3. Check .mcp.json syntax
cat .mcp.json | jq .
# Should output valid JSON

# 4. Restart Claude Code completely
# Exit all sessions and restart

Issue 2: Browser Launch Failures

Symptoms:

  • Error: "Failed to launch browser"
  • Error: "Executable doesn't exist"

Solutions:

# 1. Install Playwright browsers manually
npx playwright install

# 2. Install specific browser
npx playwright install chromium

# 3. Install system dependencies (Linux)
npx playwright install-deps

# 4. Check browser installation
npx playwright --version

Issue 3: Timeout Errors

Symptoms:

  • Error: "Timeout waiting for selector"
  • Error: "Navigation timeout exceeded"

Solutions:

**Increase timeouts in requests:**
"Navigate to the page with a 30-second timeout"
"Wait up to 60 seconds for the element to appear"

**Use explicit waits:**
"Wait for the network to be idle before taking screenshot"
"Wait for the loading spinner to disappear"

**Check page load:**
"Check if the page is still loading"
"Show me the current page state"

Issue 4: Element Not Found

Symptoms:

  • Error: "Element not found"
  • Error: "Selector resolved to hidden element"

Solutions:

**Debug selector:**
"Show me all elements matching '.add-to-cart'"
"List all buttons on the page"
"Get the HTML of the product section"

**Use alternative selectors:**
"Click the button with text 'Add to Cart'"
"Find element by aria-label='Add to Cart'"
"Use XPath to find the submit button"

**Wait for visibility:**
"Wait for the button to become visible"
"Check if the element is hidden by CSS"

Issue 5: Network Requests Not Captured

Symptoms:

  • Missing AJAX requests in logs
  • Empty network request list

Solutions:

**Start monitoring before navigation:**
"Start browser with network monitoring enabled"
"Monitor network, then navigate to the page"

**Clear and retry:**
"Close browser and start fresh with network monitoring"
"Clear cache and reload with network capture"

**Check timing:**
"Wait 5 seconds after navigation, then show network requests"
"Monitor network for 10 seconds after clicking the button"

Best Practices

1. Always Start with Clean State

**Good Practice:**
"Open a new browser, clear cookies, and navigate to homepage"

**Why:** Ensures reproducible results without cached data

2. Use Explicit Waits

**Good Practice:**
"Wait for the product grid to load, then take screenshot"

**Why:** Avoids race conditions and timing issues

3. Capture Context for Debugging

**Good Practice:**
"Take screenshot, show console errors, and list network requests"

**Why:** Provides complete picture of issue

4. Test Across Viewports

**Good Practice:**
"Test on desktop (1920x1080), tablet (768x1024), and mobile (375x667)"

**Why:** Ensures responsive design works correctly

5. Monitor Network Performance

**Good Practice:**
"Load the page with network monitoring and show requests over 1 second"

**Why:** Identifies performance bottlenecks

6. Use Specific Selectors

**Good Practice:**
"Click button[data-role='proceed-to-checkout']"

**Better than:** "Click the checkout button"

**Why:** More reliable and specific

7. Document Test Scenarios

**Good Practice:**
Create test documentation:
1. Steps to reproduce
2. Expected behavior
3. Actual behavior
4. Screenshots/logs
5. Environment details

**Why:** Makes debugging reproducible

8. Clean Up Resources

**Good Practice:**
"After testing, close the browser to free resources"

**Why:** Prevents memory leaks and resource exhaustion

Advanced Usage

Custom Browser Configuration

If you need custom browser settings, you can create a wrapper script:

1. Create playwright-wrapper.js:

#!/usr/bin/env node

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({
    headless: false,           // Show browser window
    slowMo: 100,               // Slow down actions
    args: [
      '--disable-web-security', // Disable CORS (for testing only!)
      '--ignore-certificate-errors'
    ]
  });

  const context = await browser.newContext({
    viewport: { width: 1920, height: 1080 },
    userAgent: 'Custom User Agent',
    locale: 'en-US',
    timezoneId: 'America/New_York',
    permissions: ['geolocation']
  });

  const page = await context.newPage();
  // Your automation code here
})();

2. Update .mcp.json:

{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": ["/path/to/playwright-wrapper.js"]
    }
  }
}

Debugging with Playwright Inspector

For complex debugging, use Playwright Inspector:

# Set environment variable
export PWDEBUG=1

# Run your test
npx playwright test

# Or use inspector directly
npx playwright codegen http://localhost/m246/

This opens a GUI for:

  • Step-by-step debugging
  • Selector picker
  • Network inspection
  • Screenshot comparison

Integration with Magento 2 Development Workflow

1. Theme Development

**Testing custom theme changes:**
1. "Navigate to homepage with Custom theme"
2. "Compare screenshot with Luma theme"
3. "Check CSS overrides are applied"
4. "Test responsive breakpoints"

2. Module Testing

**Testing custom module frontend:**
1. "Enable module: bin/magento module:enable Vendor_Module"
2. "Clear cache and reload page"
3. "Test module functionality"
4. "Check for JavaScript errors"

3. Integration Testing

**Test complete user flows:**
1. "Browse products → Add to cart → Checkout → Payment"
2. "Monitor all API calls"
3. "Verify data consistency"
4. "Check error handling"

4. Regression Testing

**Verify no regressions after updates:**
1. "Take baseline screenshots before upgrade"
2. "Apply Magento patches/updates"
3. "Re-run tests and compare screenshots"
4. "Identify visual differences"

Security Considerations

1. Never Commit Sensitive Data

# Add to .gitignore
.mcp.json.local
playwright-config.json
screenshots/
videos/

2. Use Environment Variables

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"],
      "env": {
        "BASE_URL": "${MAGENTO_BASE_URL}",
        "TEST_USER": "${TEST_USER_EMAIL}",
        "TEST_PASS": "${TEST_USER_PASSWORD}"
      }
    }
  }
}

3. Sanitize Logs

Always review logs before sharing:

  • Remove passwords
  • Remove API keys
  • Remove customer data
  • Remove session tokens

Resources

Official Documentation

Magento 2 Resources

Community

Summary

Playwright MCP Server enables powerful frontend debugging capabilities for Magento 2:

  • Automated Testing: Click, fill, navigate programmatically
  • Visual Debugging: Screenshots and videos
  • Network Analysis: Monitor AJAX, API calls
  • Console Monitoring: JavaScript errors and warnings
  • Responsive Testing: Multiple viewports
  • Performance Analysis: Page load metrics

By integrating Playwright with Claude Code, you can efficiently debug complex frontend issues in your Cellular Israel Magento 2 e-commerce platform.

Last Updated: 2025-11-05 Magento Version: 2.4.6-p10 Node Version: 18.19.1 Playwright MCP Version: Latest (via npx)