Cypress Test Generator MCP Server

A Model Context Protocol (MCP) server that automatically generates Cypress test cases and Page Object Models by scraping and analyzing web pages.

🚀 Features

• Intelligent Web Scraping: Uses Puppeteer to render pages and extract interactive elements
• Smart Element Detection: Identifies buttons, inputs, forms, navigation, and media elements
• Page Object Generation: Creates TypeScript Page Object classes with locators and methods
• Comprehensive Test Suites: Generates tests for functionality, accessibility, performance, and error handling
• Workflow Recognition: Automatically detects common patterns like login and search workflows

📦 Installation

1. Clone or create the project directory:

   mkdir cypress-test-generator-mcp
   cd cypress-test-generator-mcp

2. Initialize and install dependencies:

   npm install

3. Build the TypeScript code:

   npm run build

4. Configure your MCP client to use the server (add to your MCP configuration file):

   {
   "mcpServers": {
    "cypress-test-generator": {
      "command": "node",
      "args": ["path/to/cypress-test-generator-mcp/dist/index.js"]
    }
   }
   }

🛠️ Available Tools

1. scrape_page

Analyzes a web page and returns its structure.

Parameters:

• url (string): The URL to scrape and analyze

Example:

// Returns detailed analysis of page elements, forms, and navigation
await tools.scrape_page({ url: "https://example.com/login" })

2. generate_page_object

Creates a TypeScript Page Object class from a URL.

Parameters:

• url (string): The URL to generate Page Object for
• outputPath (string, optional): File path to save the generated class

Example:

await tools.generate_page_object({ 
  url: "https://example.com/login",
  outputPath: "./page-objects/LoginPage.ts"
})

3. generate_test_suite

Generates comprehensive Cypress tests for a page.

Parameters:

• url (string): The URL to generate tests for
• outputPath (string, optional): File path to save the test file

Example:

await tools.generate_test_suite({ 
  url: "https://example.com/login",
  outputPath: "./tests/login.spec.ts"
})

4. generate_full_test_setup

Generates both Page Object and test suite for complete test setup.

Parameters:

• url (string): The URL to generate complete setup for
• outputDir (string, optional): Directory to save all generated files

Example:

await tools.generate_full_test_setup({ 
  url: "https://example.com/login",
  outputDir: "./cypress-tests"
})

📋 Generated Code Examples

Page Object Example

export class LoginPage {
  private readonly url = 'https://example.com/login';
  private readonly emailInputSelector = '#email';
  private readonly passwordInputSelector = '#password';
  private readonly loginButtonSelector = '.login-btn';

  visit(): void {
    cy.visit(this.url);
  }

  getEmailInput(): Cypress.Chainable {
    return cy.get(this.emailInputSelector);
  }

  typeEmailInput(text: string): void {
    this.getEmailInput().should('be.visible').clear().type(text);
  }

  login(email: string, password: string): void {
    this.typeEmailInput(email);
    this.typePasswordInput(password);
    this.clickLoginButton();
  }
}

Test Suite Example

describe('Login Page', () => {
  let page: LoginPage;

  beforeEach(() => {
    page = new LoginPage();
    page.visit();
    page.waitForPageLoad();
  });

  describe('Element Interaction Tests', () => {
    it('should be able to type in email input', () => {
      const testText = 'test@example.com';
      page.typeEmailInput(testText);
      page.getEmailInput().should('have.value', testText);
    });
  });

  describe('Accessibility Tests', () => {
    it('should have proper accessibility attributes', () => {
      cy.injectAxe();
      cy.checkA11y();
    });
  });
});

🎯 Use Cases

1. Rapid Test Development

// Generate complete test setup for a new page
await tools.generate_full_test_setup({ 
  url: "https://myapp.com/dashboard",
  outputDir: "./tests/dashboard"
})

2. Page Object Maintenance

// Regenerate Page Object when UI changes
await tools.generate_page_object({ 
  url: "https://myapp.com/updated-form",
  outputPath: "./page-objects/UpdatedFormPage.ts"
})

3. Cross-browser Testing Setup

// Generate tests for multiple pages
const pages = [
  "https://myapp.com/login",
  "https://myapp.com/signup", 
  "https://myapp.com/profile"
];

for (const url of pages) {
  await tools.generate_full_test_setup({ url, outputDir: "./tests" });
}

4. Regression Testing

// Quickly generate tests for critical user journeys
await tools.generate_test_suite({ 
  url: "https://myapp.com/checkout",
  outputPath: "./tests/critical/checkout.spec.ts"
})

🔧 Configuration Options

Puppeteer Configuration

The server uses Puppeteer with these default settings:

• Headless mode enabled
• Network idle wait strategy
• 30-second timeout
• Sandbox disabled for Docker compatibility

Element Detection

The scraper identifies:

• Interactive Elements: buttons, inputs, selects, links
• Forms: with field analysis and submission detection
• Navigation: menu items and navigation links
• Media: images, videos, audio elements
• Accessibility: ARIA labels, roles, and attributes

Selector Priority

1. id attributes
2. data-testid or data-test-id attributes
3. name attributes
4. CSS classes
5. Text content (for short text)
6. nth-child selectors (fallback)

🏗️ Project Structure

cypress-test-generator-mcp/
├── src/
│   └── index.ts          # Main MCP server code
├── dist/                 # Compiled JavaScript
├── page-objects/         # Generated Page Objects
├── tests/               # Generated test suites
├── package.json
├── tsconfig.json
└── README.md

🔍 Advanced Features

Workflow Detection

The generator automatically detects common workflows:

• Login flows: email/password + submit button
• Search functionality: search input + search button
• Form submissions: form fields + submit actions

Test Categories

Generated tests include:

• Functional tests: Element interactions and workflows
• Accessibility tests: ARIA compliance and keyboard navigation
• Performance tests: Page load timing
• Responsive tests: Multiple viewport sizes
• Error handling: Network errors and validation

Smart Naming

Elements are intelligently named based on:

• ID attributes (#user-email → userEmailInput)
• Name attributes (name="password" → passwordInput)
• Placeholder text (placeholder="Search..." → searchInput)
• Button text ("Sign In" → signInButton)

🚨 Error Handling

The server includes robust error handling for:

• Invalid URLs or unreachable pages
• Timeout issues during page loading
• Puppeteer browser launch failures
• File system write errors
• Malformed HTML parsing

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details