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.

Features

• Web Scraping: Uses Puppeteer to fetch and render web pages
• HTML Parsing: Uses Cheerio to parse HTML and extract element information
• Page Object Generation: Creates complete TypeScript Page Object classes with:
  • Private element locators
  • Public getter methods
  • Interaction methods (click, type, select, etc.)
  • Workflow methods for common test scenarios
• Test Suite Generation: Creates 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('[email protected]', 'validpassword')
      cy.url().should('not.include', '/login')
    })
    
    it('should show error with invalid credentials', () => {
      page.login('[email protected]', '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

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', () => { ... }
   

Example Usage in 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"

Dependencies

• @modelcontextprotocol/sdk: MCP server implementation
• puppeteer: Web scraping and page rendering
• cheerio: HTML parsing and element selection
• zod: Schema validation
• typescript: Type safety

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.