amazon-q-cypress-mcp

JMRMEDEV/amazon-q-cypress-mcp

3.1

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

Cypress MCP Server is an advanced Model Context Protocol server designed to enhance the execution of Cypress E2E tests with improved screenshot management, clean output formatting, and automatic file handling.

Cypress MCP Server

An enhanced Model Context Protocol (MCP) server for running Cypress E2E tests with advanced screenshot handling, clean output formatting, and automatic file management.

Features

🖼️ Enhanced Screenshot Management

  • Viewport Only Capture: Screenshots capture only the rendered application content, not the Cypress runner UI
  • Success Screenshots: Automatically captures screenshots for both failed AND successful tests
  • Clean Naming: Screenshots are copied to /tmp with predictable names: screenshot-cypress-<timestamp>-<uuid>.png
  • Automatic Cleanup: Removes temporary test files and original screenshots after execution
  • AI-Ready Output: Returns /tmp screenshot paths for easy AI processing

📊 Clean Output & Logging

  • Structured Results: Returns comprehensive test results including successes, failures, and execution summaries
  • Clean Logs: Removes ANSI escape codes and formats output for readability
  • Detailed Test Info: Provides test duration, error details, and execution statistics
  • JSON Parsing: Handles both successful JSON parsing and fallback to raw output

🔧 Advanced Configuration

  • Webpack Overlay Handling: Optional handling of webpack dev server overlays
  • Custom Browser Support: Chrome, Firefox, Edge, Electron support
  • Flexible Test Input: Accept test code as string or spec file paths
  • Base URL Configuration: Automatic base URL setup for testing

Installation

cd ~/mcp-servers/cypress
npm install

Usage

Basic Test Execution

// Run a simple test with screenshot capture
{
  "testCode": `
    describe('My Test', () => {
      it('should work', () => {
        cy.visit('/');
        cy.get('h1').should('be.visible');
      });
    });
  `,
  "baseUrl": "http://localhost:3000",
  "browser": "electron",
  "headless": true
}

Protected Route Testing

// Test protected routes with authentication
{
  "testCode": `
    describe('Protected Route Test', () => {
      it('should access admin area', () => {
        // Login first
        cy.visit('/adminLogin');
        cy.get('[data-testid="email-input"]').type('user@example.com');
        cy.get('[data-testid="password-input"]').type('password');
        cy.get('[data-testid="submit-button"]').click({force: true});
        
        // Access protected route
        cy.visit('/admin');
        cy.url().should('include', '/admin');
        cy.get('table').should('be.visible');
      });
    });
  `,
  "baseUrl": "http://localhost:3000",
  "handleWebpackOverlay": true
}

Response Format

Successful Test Response

{
  "status": "completed",
  "exitCode": 0,
  "summary": {
    "totalTests": 1,
    "passed": 1,
    "failed": 0,
    "pending": 0,
    "skipped": 0,
    "durationMs": 5000
  },
  "successes": [
    {
      "spec": "temp-abc123.cy.js",
      "test": "My Test > should work",
      "duration": 5000
    }
  ],
  "failures": [],
  "screenshots": [
    "/tmp/screenshot-cypress-1703123456789-abc12345.png"
  ],
  "logs": {
    "stdout": "Clean test execution output...",
    "stderr": ""
  }
}

Failed Test Response

{
  "status": "failed",
  "exitCode": 1,
  "summary": {
    "totalTests": 1,
    "passed": 0,
    "failed": 1,
    "pending": 0,
    "skipped": 0,
    "durationMs": 3000
  },
  "successes": [],
  "failures": [
    {
      "spec": "temp-abc123.cy.js",
      "test": "My Test > should fail",
      "error": "AssertionError: expected element to be visible..."
    }
  ],
  "screenshots": [
    "/tmp/screenshot-cypress-1703123456789-def67890.png"
  ],
  "logs": {
    "stdout": "Test execution output...",
    "stderr": "Error details..."
  }
}

Parameters

ParameterTypeDefaultDescription
testCodestring-Cypress test code as string (alternative to spec file)
specstring-Path to existing spec file (e.g., cypress/e2e/login.cy.js)
browserstringchromeBrowser to use (chrome, firefox, edge, electron)
headlessbooleantrueRun in headless mode
baseUrlstring-Base URL for tests (e.g., http://localhost:3000)
handleWebpackOverlaybooleanfalseHandle webpack dev server overlay issues
configobject{}Additional Cypress configuration options

Screenshot Configuration

The server automatically configures Cypress with optimal screenshot settings:

// Applied automatically to all tests
Cypress.Screenshot.defaults({
  capture: 'viewport',           // Only capture app content, not runner UI
  disableTimersAndAnimations: true,  // Consistent screenshots
  blackout: [],                 // No elements blacked out
  overwrite: true              // Prevent duplicate files
});

// Success screenshots added automatically
afterEach(function() {
  if (this.currentTest.state === 'passed') {
    cy.screenshot('test-success', { 
      capture: 'viewport',
      overwrite: true 
    });
  }
});

File Management

Automatic Cleanup Process

  1. During Test: Cypress generates screenshots in cypress/screenshots/
  2. After Test: Server copies screenshots to /tmp/ with clean names
  3. Cleanup: Removes temporary .cy.js files and original .png files
  4. Return: Provides /tmp screenshot paths in response

Screenshot Naming Convention

  • Format: screenshot-cypress-<timestamp>-<uuid>.png
  • Location: /tmp/ directory
  • Example: /tmp/screenshot-cypress-1703123456789-a1b2c3d4.png

Webpack Overlay Handling

When handleWebpackOverlay: true is set, the server automatically adds:

// Auto-dismisses webpack dev server overlays
Cypress.Commands.add('dismissWebpackOverlay', () => {
  cy.get('iframe[id*="webpack-dev-server-client-overlay"]', { timeout: 1000 })
    .should('exist')
    .then(($iframe) => {
      const iframeDoc = $iframe.contents();
      const closeButton = iframeDoc.find('button, [role="button"], .close');
      if (closeButton.length) {
        closeButton.click();
      }
    })
    .catch(() => {
      // Overlay not present, continue
    });
});

beforeEach(() => {
  cy.dismissWebpackOverlay();
});

Best Practices

1. Protected Route Testing

Always login before accessing protected routes:

// Login first
cy.visit('/login');
cy.get('[data-testid="email"]').type('user@example.com');
cy.get('[data-testid="password"]').type('password');
cy.get('[data-testid="submit"]').click({force: true});

// Verify login success
cy.url({ timeout: 15000 }).should('include', '/dashboard');

// Then access protected route
cy.visit('/protected-route');

2. Wait for Content

Allow time for dynamic content to load:

cy.get('table', { timeout: 15000 }).should('be.visible');
cy.wait(2000); // Allow content to fully render before screenshot

3. Use Data Test IDs

Use data-testid attributes for reliable element selection:

cy.get('[data-testid="submit-button"]').click({force: true});

Troubleshooting

No Screenshots Generated

  • Ensure tests are actually running (check logs)
  • Verify /tmp directory permissions
  • Check if Cypress is configured correctly

Test Failures

  • Review the failures array in response
  • Check logs.stderr for detailed error information
  • Verify base URL is accessible

Webpack Overlay Issues

  • Set handleWebpackOverlay: true
  • Ensure development server is running
  • Check for console errors in logs

Dependencies

  • @modelcontextprotocol/sdk: MCP server framework
  • glob: File pattern matching for screenshot cleanup
  • cypress: E2E testing framework (peer dependency)

Development

To modify the server:

  1. Edit server.js
  2. Test syntax: node -c server.js
  3. Restart MCP client to pick up changes

License

MIT