Cypress MCP

🚀 MCP Cypress Page Object & Test Generator

This MCP (Model Context Protocol) server automatically generates complete Cypress Page Object classes AND comprehensive test suites for any web page, streamlining the testing process and enhancing efficiency.

✨ Features

• Web Scraping: Leverages Puppeteer to fetch and render web pages.
• HTML Parsing: Employs Cheerio to parse HTML and extract element information.
• Page Object Generation: Creates complete TypeScript Page Object classes featuring:
  • Private element locators.
  • Public getter methods.
  • Interaction methods (such as click, type, select, etc.).
  • Workflow methods for common test scenarios.
• Test Suite Generation: Produces comprehensive Cypress test files with:
  • Positive test cases for all elements.
  • Negative test cases for error handling.
  • Workflow tests for common scenarios.
  • Accessibility, performance, and edge - case tests.

📦 Generated Output

The server generates two files:

1. Page Object Class ({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. Test Suite ({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')
    })
  })
})

📋 Test Categories Generated

✅ Positive Test Cases

• Element Interactions: Click, type, clear, check/uncheck for all detected elements.
• Workflow Tests: Login, search, navigation workflows.
• Form Validation: Successful form submissions.
• Element Visibility: All elements are visible and accessible.

❌ Negative Test Cases

• Error Handling: Network errors, server errors, slow connections.
• Validation Errors: Empty fields, invalid formats, required field validation.
• Edge Cases: Large inputs, special characters, unicode text.
• Accessibility: ARIA labels, keyboard navigation.

🔧 Additional Test Types

• Performance Tests: Load times, rapid interactions.
• Responsive Tests: Different viewport sizes.
• Accessibility Tests: ARIA compliance, keyboard navigation.
• Security Tests: Input sanitization, XSS prevention.

📌 Element Types Supported

• Buttons: Click interactions with validation.
• Input Fields: Type, clear, check/uncheck (for checkboxes/radio).
• Links: Click interactions with navigation verification.
• Select Dropdowns: Select options with validation.
• Textareas: Type and clear with content verification.
• Forms: Submit interactions with success/error handling.

🔍 Workflow Detection

The server intelligently detects common patterns and generates appropriate tests:

• Login Forms: Username/password validation, error handling.
• Search Forms: Query validation, results verification.
• Navigation: Home links, breadcrumbs, menu items.
• Form Submissions: Success states, validation errors.

📥 Installation

npm install

💻 Usage

[Basic Usage]

1. Start the server:

   npx tsx main.ts
   

2. Use with an MCP client: The server exposes a generateLocator tool that accepts a URL parameter.

   Example tool call:

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

3. Response format: The server returns both the Page Object class and test suite:

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

[Advanced Usage]

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

📄 Dependencies

🔧 Error Handling

The server includes comprehensive error handling for:

• Invalid URLs.
• Network connectivity issues.
• Page loading failures.
• HTML parsing errors.

🌐 Browser Configuration

The server uses Puppeteer with the following settings:

• Headless mode for server environments.
• No - sandbox mode for containerized deployments.
• Network idle waiting for dynamic content.

🤝 Contributing

To add support for new element types, interaction methods, or test patterns, modify the generatePageObjectClass and generateCypressTests functions in main.ts.