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 函數。