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)

1export class ExampleComLoginPage {
2  // Private elements
3  #elements = {
4    button_login: () => cy.get('#login-button'),
5    input_username: () => cy.get('input[name="username"]'),
6    link_home: () => cy.contains('a', 'Home')
7  }
8
9  // Public getters
10  get ButtonLogin() { return this.#elements.button_login() }
11  get InputUsername() { return this.#elements.input_username() }
12  get LinkHome() { return this.#elements.link_home() }
13
14  // Interaction methods
15  clickButtonLogin() { return this.#elements.button_login().click() }
16  typeInputUsername(text: string) { return this.#elements.input_username().type(text) }
17  clickLinkHome() { return this.#elements.link_home().click() }
18
19  // Workflow methods
20  login(username: string, password: string) {
21    this.typeInputUsername(username)
22    this.typeInputPassword(password)
23    this.clickButtonLogin()
24    return this
25  }
26}

2. Test Suite ({ClassName}.cy.ts)

1import { ExampleComLoginPage } from './ExampleComLoginPage'
2
3describe('ExampleComLoginPage Tests', () => {
4  let page: ExampleComLoginPage
5  
6  beforeEach(() => {
7    cy.visit('https://example.com/login')
8    page = new ExampleComLoginPage()
9  })
10  
11  describe('Element Interactions', () => {
12    it('should click button_login', () => {
13      page.clickButtonLogin()
14    })
15    
16    it('should type in input_username', () => {
17      page.typeInputUsername('test input')
18      page.getInputUsername().should('have.value', 'test input')
19    })
20  })
21  
22  describe('Login Workflow', () => {
23    it('should login with valid credentials', () => {
24      page.login('validuser@example.com', 'validpassword')
25      cy.url().should('not.include', '/login')
26    })
27    
28    it('should show error with invalid credentials', () => {
29      page.login('invalid@example.com', 'wrongpassword')
30      cy.contains('Invalid credentials').should('be.visible')
31    })
32  })
33  
34  describe('Error Handling', () => {
35    it('should handle network errors gracefully', () => {
36      cy.intercept('GET', '**', { forceNetworkError: true })
37      cy.visit('https://example.com/login')
38    })
39  })
40})

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

1npm install

Usage

1. Start the server:

   1npx tsx main.ts

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

   Example tool call:

   1{
   2  "method": "tools/call",
   3  "params": {
   4    "name": "generateLocator",
   5    "arguments": {
   6      "url": "https://example.com/login"
   7    }
   8  }
   9}

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

1// Use the generated Page Object
2import { ExampleComLoginPage } from './ExampleComLoginPage'
3
4describe('Login Page', () => {
5  const page = new ExampleComLoginPage()
6  
7  it('should login successfully', () => {
8    page.login('username', 'password')
9    page.verifyPageLoaded()
10  })
11})
12
13// Run the generated test suite
14// 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.