Amazon Q Cypress MCP

Cypress MCP服务器

一个增强的模型上下文协议（MCP）服务器，用于运行Cypress E2E测试，具有高级屏幕截图处理、干净的输出格式和自动文件管理功能。

特性

🖼️ 增强的屏幕截图管理

• 仅视口捕捉：屏幕截图仅捕获渲染的应用程序内容，而不是Cypress runner UI
• 成功截图：自动捕获失败和成功测试的屏幕截图
• 干净命名：屏幕截图被复制到 /tmp 具有可预测的名称： screenshot-cypress--.png
• 自动清理：执行后删除临时测试文件和原始屏幕截图
• AI就绪输出：退货 /tmp 截图路径，便于人工智能处理

📊 清洁输出和记录

• 结构化结果：返回全面的测试结果，包括成功、失败和执行摘要
• 清理日志：删除ANSI转义码并格式化输出以提高可读性
• 详细测试信息：提供测试持续时间、错误详细信息和执行统计信息
• JSON解析：处理成功的JSON解析和回退到原始输出

🔧 高级配置

• Webpack覆盖处理：可选处理webpack-dev服务器覆盖
• 自定义浏览器支持：Chrome、Firefox、Edge、Electron支持
• 灵活的测试输入：接受测试代码作为字符串或规范文件路径
• 基本URL配置：用于测试的自动基本URL设置

安装

cd ~/mcp-servers/cypress
npm install

用法

基本测试执行

// 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
}

受保护路由测试

// 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
}

响应格式

成功测试响应

{
  "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": ""
  }
}

测试响应失败

{
  "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..."
  }
}

参数

屏幕截图配置

服务器会自动为Cypress配置最佳屏幕截图设置：

// 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 
    });
  }
});

文件管理

自动清理过程

1. 测试期间：Cypress在中生成屏幕截图 cypress/screenshots/
2. 测试后：服务器将屏幕截图复制到 /tmp/ 名字干净
3. 清理：删除临时 .cy.js 文件和原件 .png 文件
4. 返回：提供 /tmp 响应中的截图路径

截图命名约定

• 格式: screenshot-cypress--.png
• 位置: /tmp/ 目录
• 示例: /tmp/screenshot-cypress-1703123456789-a1b2c3d4.png

Webpack覆盖处理

当 handleWebpackOverlay: true 设置后，服务器会自动添加：

// 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();
});

最佳实践

1.受保护路由测试

在访问受保护的路由之前，请务必登录：

// 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.等待内容

留出时间加载动态内容：

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

3.使用数据测试ID

使用 data-testid 可靠元素选择的属性：

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

故障排除

未生成屏幕截图

• 确保测试实际运行（检查日志）
• 验证 /tmp 目录权限
• 检查Cypress是否配置正确

测试失败

• 查看 failures 数组响应
• 检查 logs.stderr 有关详细的错误信息
• 验证基本URL是否可访问

Webpack覆盖问题

• 集 handleWebpackOverlay: true
• 确保开发服务器正在运行
• 检查日志中的控制台错误

依赖项

• @modelcontextprotocol/sdk：MCP服务器框架
• glob：用于屏幕截图清理的文件模式匹配
• cypress：E2E测试框架（对等依赖）

发展

要修改服务器，请执行以下操作：

1. 编辑 server.js
2. 测试语法： node -c server.js
3. 重新启动MCP客户端以获取更改

许可证

麻省理工学院