cypress-mcp

🚀 MCP Cypress 页面对象与测试生成器

本 MCP（模型上下文协议）服务器可自动为任意网页生成完整的 Cypress 页面对象类 以及 全面的测试套件。

✨ 主要特性

• 网页抓取：使用 Puppeteer 来获取并渲染网页。
• HTML 解析：使用 Cheerio 解析 HTML 并提取元素信息。
• 页面对象生成：创建完整的 TypeScript 页面对象类，包含：
  • 私有元素定位器。
  • 公共获取方法。
  • 交互方法（点击、输入、选择等）。
  • 常见测试场景的工作流方法。
• 测试套件生成：创建全面的 Cypress 测试文件，包含：
  • 所有元素的正向测试用例。
  • 用于错误处理的负向测试用例。
  • 常见场景的工作流测试。
  • 可访问性、性能和边界情况测试。

📦 生成的输出

服务器会生成 两个文件：

1. 页面对象类 ({ClassName}.ts)

export class ExampleComLoginPage {
  // Private elements
  #elements = {
    button_login: () => cy.get('#login-button'),
    input_username: () => cy.get('input[name="username"]'),
    link_home: () => cy.contains('a', 'Home')
  }

  // Public getters
  get ButtonLogin() { return this.#elements.button_login() }
  get InputUsername() { return this.#elements.input_username() }
  get LinkHome() { return this.#elements.link_home() }

  // Interaction methods
  clickButtonLogin() { return this.#elements.button_login().click() }
  typeInputUsername(text: string) { return this.#elements.input_username().type(text) }
  clickLinkHome() { return this.#elements.link_home().click() }

  // Workflow methods
  login(username: string, password: string) {
    this.typeInputUsername(username)
    this.typeInputPassword(password)
    this.clickButtonLogin()
    return this
  }
}

2. 测试套件 ({ClassName}.cy.ts)

import { ExampleComLoginPage } from './ExampleComLoginPage'

describe('ExampleComLoginPage Tests', () => {
  let page: ExampleComLoginPage
  
  beforeEach(() => {
    cy.visit('https://example.com/login')
    page = new ExampleComLoginPage()
  })
  
  describe('Element Interactions', () => {
    it('should click button_login', () => {
      page.clickButtonLogin()
    })
    
    it('should type in input_username', () => {
      page.typeInputUsername('test input')
      page.getInputUsername().should('have.value', 'test input')
    })
  })
  
  describe('Login Workflow', () => {
    it('should login with valid credentials', () => {
      page.login('validuser@example.com', 'validpassword')
      cy.url().should('not.include', '/login')
    })
    
    it('should show error with invalid credentials', () => {
      page.login('invalid@example.com', 'wrongpassword')
      cy.contains('Invalid credentials').should('be.visible')
    })
  })
  
  describe('Error Handling', () => {
    it('should handle network errors gracefully', () => {
      cy.intercept('GET', '**', { forceNetworkError: true })
      cy.visit('https://example.com/login')
    })
  })
})

📋 生成的测试类别

✅ 正向测试用例

• 元素交互：对所有检测到的元素进行点击、输入、清除、勾选/取消勾选操作。
• 工作流测试：登录、搜索、导航工作流。
• 表单验证：成功的表单提交。
• 元素可见性：所有元素可见且可访问。

❌ 负向测试用例

• 错误处理：网络错误、服务器错误、连接缓慢。
• 验证错误：空字段、无效格式、必填字段验证。
• 边界情况：大输入、特殊字符、Unicode 文本。
• 可访问性：ARIA 标签、键盘导航。

🔧 其他测试类型

• 性能测试：加载时间、快速交互。
• 响应式测试：不同视口大小。
• 可访问性测试：ARIA 合规性、键盘导航。
• 安全测试：输入清理、防止 XSS 攻击。

📌 支持的元素类型

• 按钮：带有验证的点击交互。
• 输入字段：输入、清除、勾选/取消勾选（复选框/单选框）。
• 链接：带有导航验证的点击交互。
• 下拉选择框：带有验证的选项选择。
• 文本区域：带有内容验证的输入和清除。
• 表单：带有成功/错误处理的提交交互。

🔍 工作流检测

服务器能够智能检测常见模式并生成相应的测试：

• 登录表单：用户名/密码验证、错误处理。
• 搜索表单：查询验证、结果验证。
• 导航：主页链接、面包屑导航、菜单项。
• 表单提交：成功状态、验证错误。

📦 安装指南

npm install

💻 使用示例

基础用法

1. 启动服务器：

   npx tsx main.ts
   

2. 与 MCP 客户端配合使用： 服务器提供了一个 generateLocator 工具，该工具接受一个 URL 参数。

   工具调用示例：

   {
     "method": "tools/call",
     "params": {
       "name": "generateLocator",
       "arguments": {
         "url": "https://example.com/login"
       }
     }
   }
   

3. 响应格式： 服务器会返回页面对象类和测试套件：

   // ===== PAGE OBJECT CLASS =====
   // Save this as: ExampleComLoginPage.ts
   export class ExampleComLoginPage { ... }
   
   // ===== CYPRESS TESTS =====
   // Save this as: ExampleComLoginPage.cy.ts
   describe('ExampleComLoginPage Tests', () => { ... }
   

高级用法

// Use the generated Page Object
import { ExampleComLoginPage } from './ExampleComLoginPage'

describe('Login Page', () => {
  const page = new ExampleComLoginPage()
  
  it('should login successfully', () => {
    page.login('username', 'password')
    page.verifyPageLoaded()
  })
})

// Run the generated test suite
// npx cypress run --spec "cypress/e2e/ExampleComLoginPage.cy.ts"

📚 详细文档

依赖项

• @modelcontextprotocol/sdk：MCP 服务器实现。
• puppeteer：网页抓取和页面渲染。
• cheerio：HTML 解析和元素选择。
• zod：模式验证。
• typescript：类型安全。

错误处理

服务器包含全面的错误处理，用于处理以下情况：

• 无效的 URL。
• 网络连接问题。
• 页面加载失败。
• HTML 解析错误。

浏览器配置

服务器使用 Puppeteer 并采用以下设置：

• 服务器环境的无头模式。
• 容器化部署的无沙箱模式。
• 等待网络空闲以处理动态内容。

🤝 贡献指南

若要添加对新元素类型、交互方法或测试模式的支持，请修改 main.ts 中的 generatePageObjectClass 和 generateCypressTests 函数。