Cypress Page Object Generator

An MCP server for automatically generating Cypress page objects from frontend components. This tool analyzes your Vue, React, or CoffeeScript components and generates well-structured page objects to use in your Cypress tests. It can also modify existing page objects to add new methods without losing your custom changes.

Features

• Automatic extraction of selectors from various component types (Vue, React, CoffeeScript)

• Support for simultaneous detection and analysis of both Vue and CoffeeScript files in auto mode

• Intelligent matching of component files with different naming conventions

• Generation of Cypress page object classes with proper methods and getters

• Ability to modify existing page objects by adding new methods without overwriting custom code

• Support for different repository structures via configuration

• Repository-agnostic design that works with any project

• Intelligent analysis of component structure

Related MCP server: cypress-mcp-server

Installation

1. Clone the repository:

git clone https://github.com/yourusername/cypress-po-generator.git
cd cypress-po-generator

2. Install dependencies and build the project:

npm install

3. Run the setup script to automatically configure Claude:

npm run setup

The setup script will:

• Locate your Claude configuration file based on your operating system

• Add the Cypress Page Object Generator to the MCP servers configuration

• Create the configuration file if it doesn't exist

If you prefer to configure manually, you can:

1. Find your Claude configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the following to the MCP servers section:

{
  "mcpServers": {
    "cypress-po-generator": {
      "command": "node",
      "args": ["/absolute/path/to/cypress-po-generator/build/index.js"],
      "disabled": false
    }
  }
}

Usage

Once installed, you can use the page object generator through the Claude interface. This tool is integrated as an MCP (Model Context Protocol) server, allowing Claude to directly interact with it.

MCP Server Integration

The Cypress Page Object Generator provides a Model Context Protocol (MCP) server that Claude can use to analyze components and generate page objects. The MCP server exposes the following tools:

• Tool name: generate_page_object

• Server name: cypress-po-generator

• Tool name: modify_page_object

• Server name: cypress-po-generator

Using the Page Object Generator

You can use the page object generator in two ways:

1. Natural language request:

I want to generate a page object for the PatientChart component in the patient category

2. Direct MCP tool usage:

<use_mcp_tool>
<server_name>cypress-po-generator</server_name>
<tool_name>generate_page_object</tool_name>
<arguments>
{
  "componentName": "PatientChart",
  "componentType": "vue",
  "category": "patient",
  "additionalContext": "This component displays patient information and medical records."
}
</arguments>
</use_mcp_tool>

Getting Claude to Use the Tools

When using natural language prompts, you may need to be more explicit to get Claude to use the right tool. Here are some tips:

For generating page objects:

Please use the cypress-po-generator MCP server's generate_page_object tool to create a page object for the PatientChart component.

For modifying page objects:

Please use the cypress-po-generator MCP server's modify_page_object tool to update the existing InboxFilterDialog page object with new methods.

Being explicit about wanting to use the MCP tool in your prompt increases the chance that Claude will use the tool directly rather than trying to write code itself.

Using the Page Object Modifier

The page object modifier allows you to update existing page objects with new methods, rather than generating them from scratch. This is useful when you want to add selectors for new elements without losing any custom code you've added to your page objects.

Important: When asking Claude to modify an existing page object, be explicit that you want to use the MCP tool:

Please use the cypress-po-generator MCP server's modify_page_object tool to update the InboxFilterDialog page object with methods for selecting read/unread options from the dropdown.

1. Natural language request:

I want to modify the existing PatientChart page object to add methods for the new filter buttons that were added to the component

2. Direct MCP tool usage:

<use_mcp_tool>
<server_name>cypress-po-generator</server_name>
<tool_name>modify_page_object</tool_name>
<arguments>
{
  "pageObjectClassName": "PatientChart",
  "componentName": "PatientChart",
  "pageObjectPath": "spec/e2e/cypress/support/page-objects/patient/patient-chart.ts",
  "componentType": "vue",
  "additionalContext": "Need to add methods for the new filter buttons"
}
</arguments>
</use_mcp_tool>

The tool will:

1. Find the existing page object file (or use the provided path)

2. Parse the file to understand its structure and existing methods

3. Analyze the component to find selectors

4. Generate new methods only for selectors that don't already have methods

5. Add the new methods to the existing page object file while preserving all existing code

Tool Parameters

Getting Claude to Use the Tools

When using natural language prompts, you may need to be more explicit to get Claude to use the right tool. Here are some tips:

For generating page objects:

Please use the cypress-po-generator MCP server's generate_page_object tool to create a page object for the PatientChart component.

For modifying page objects:

Please use the cypress-po-generator MCP server's modify_page_object tool to update the existing InboxFilterDialog page object with new methods.

Being explicit about wanting to use the MCP tool in your prompt increases the chance that Claude will use the tool directly rather than trying to write code itself.

generate_page_object

The generate_page_object tool takes the following parameters:

• componentName: The name of the component to analyze (e.g., 'Dialog', 'PatientChart')

• outputPath (optional): Path where the page object should be saved

• componentType (optional): Type of component ('vue', 'react', 'coffee', or 'auto' for auto-detect)

• category (optional): Category for organizing page objects (e.g., 'common', 'patient', 'admin')

• additionalContext (optional): Any additional context about the component to help with generation

Claude will analyze the component and generate a Cypress page object that you can use in your tests. If outputPath is provided, the tool will also save the page object to the specified file.

modify_page_object

The modify_page_object tool takes the following parameters:

• pageObjectClassName: Name of the page object class to modify

• componentName: Name of the component to analyze for new methods

• pageObjectPath (optional): Path to the page object file (will try to find it automatically if not provided)

• componentType (optional): Type of component ('vue', 'react', 'coffee', or 'auto' for auto-detect)

• additionalContext (optional): Any additional context about the component to help with generation

If pageObjectPath is not provided, the tool will attempt to find the page object file based on the class name in the default page objects directory.

Configuration

The generator can be configured to work with different repository structures by creating a .cypress-po-generator.json file in your repository root. This allows you to customize:

• The repository path (required) - absolute path to your repository root

• Where to look for components of different types

• Which file extensions to consider

• Custom selector patterns to look for

Important: You must specify the repository path in the configuration file. Page objects will be generated in the spec/e2e/cypress/support/page-objects directory within your repository by default. You can organize them into subdirectories by using the category parameter.

Configuration File Location

The tool looks for the configuration file in the following locations, in order:

1. The current working directory (.cypress-po-generator.json)

2. The directory where the Cypress Page Object Generator is installed (where the MCP server is running from)

This allows you to use the tool in different contexts:

• When working directly in a repository, place the config file in that repository's root

• When working across multiple repositories, place the config file in the Cypress Page Object Generator's directory

Configuration Error Handling

The tool now provides better error handling for configuration issues:

• If the configuration file is missing, the tool will look for a test component in the current directory

• Clear error messages are displayed when the repository path is not defined

• Guidance is provided on how to create a proper configuration file

• Test files in the current directory can be used for testing even without a full repository setup

Example Configuration

{
  "repoPath": "/Users/username/src/chr-backend",
  "paths": {
    "vue": [
      "custom/path/to/vue/components"
    ],
    "react": [
      "custom/path/to/react/components"
    ],
    "coffee": [
      "custom/path/to/coffee/components"
    ]
  },
  "extensions": {
    "vue": [".vue"],
    "react": [".jsx", ".tsx", ".js"],
    "coffee": [".coffee"]
  },
  "selectorPatterns": {
    "customAttribute": "\\[custom-attr=\\"([^\\"]*)\\"\\"\\]"
  }
}

How It Works

1. The tool recursively scans your entire repository to find component files, skipping common directories like node_modules and .git

2. It extracts selectors, IDs, data attributes, and other relevant information

3. Based on the analysis, it generates a Cypress page object class with:

   • Getters for all identified elements

   • Click methods for interactive elements

   • Verification methods

   • Proper TypeScript typing

4. When using the modify_page_object tool, it:

   • Finds the existing page object file

   • Parses the file to identify existing methods

   • Generates only new methods that don't already exist

   • Adds the new methods to the file while preserving existing code

5. If an output path is specified, it saves the generated page object to that location

   • Directory structure is automatically created if it doesn't exist

   • Output path defaults to spec/e2e/cypress/support/page-objects in your repository

The tool handles:

• Duplicate method names by adding numeric suffixes

• Special characters in attribute values

• Different component types (Vue, React, CoffeeScript)

• Auto-detection of component type if not specified (now supports detecting both Vue and CoffeeScript simultaneously)

• Intelligent matching of component files with different naming conventions (camelCase, snake_case, kebab-case)

• Files located anywhere in the repository (not just in predefined paths)

• Preserving custom code when modifying existing page objects

Example Generated Page Object

Here's an example of a page object that might be generated:

/**
 * Page object for PatientChart component
 */
export class PatientChart {
  /**
   * Gets the main component element
   * @returns {Cypress.Chainable}
   */
  get(): Cypress.Chainable {
    return cy.get('.patient-chart');
  }
  
  /**
   * Gets element with ID patient-info
   * @returns {Cypress.Chainable}
   */
  patientInfo(): Cypress.Chainable {
    return this.get().find('#patient-info');
  }

  /**
   * Gets element with data-testid="action-buttons"
   * @returns {Cypress.Chainable}
   */
  actionButtons(): Cypress.Chainable {
    return this.get().find('[data-testid="action-buttons"]');
  }

  /**
   * Clicks on the PatientChart component
   * @returns {this} - For chaining
   */
  click(): this {
    this.get().click();
    return this;
  }

  /**
   * Clicks on element with ID patient-info
   * @returns {this} - For chaining
   */
  clickPatientInfo(): this {
    this.patientInfo().click();
    return this;
  }

  /**
   * Verifies that the PatientChart component is visible
   * @returns {this} - For chaining
   */
  verifyVisible(): this {
    this.get().should('be.visible');
    return this;
  }
}

Using With Different Repositories

The tool is designed to work with various repository structures. Here's how to use it with different setups:

Vue.js Projects

For Vue.js projects, the tool looks for .vue files in common locations. If your components are in a non-standard location, configure the paths in your .cypress-po-generator.json file.

React Projects

For React projects, the tool looks for .jsx, .tsx, .js, and .ts files in common React component directories. It extracts data attributes commonly used for testing.

Ruby on Rails + CoffeeScript Projects

For Rails projects with CoffeeScript, the tool looks in standard asset directories. It understands jQuery selectors and CoffeeScript's syntax patterns. The tool now supports analyzing both Vue and CoffeeScript files simultaneously when using the "auto" detection mode.

Advanced Usage

Modifying Existing Page Objects

The modify_page_object tool is particularly useful in CI/CD pipelines or when components are frequently updated with new elements. Instead of regenerating the entire page object (and potentially losing custom methods), you can use this tool to add only what's new.

Example: Adding new methods to an existing page object

<use_mcp_tool>
<server_name>cypress-po-generator</server_name>
<tool_name>modify_page_object</tool_name>
<arguments>
{
  "pageObjectClassName": "InboxFilterDialog",
  "componentName": "InboxFilterDialog",
  "componentType": "auto",
  "additionalContext": "Need to add selectors for the new filter options in the dialog"
}
</arguments>
</use_mcp_tool>

The tool will:

1. Search for the InboxFilterDialog page object file in your page objects directory

2. Analyze the InboxFilterDialog component (looking for both Vue and CoffeeScript files)

3. Generate methods for any new elements found in the component

4. Add those methods to the existing page object file

Improved Component File Matching

The tool now has enhanced file matching capabilities to find related component files even when they use different naming conventions. For example, when looking for "InboxViewComponent", it can find files like:

• inbox_view_component.vue

• inbox-view.coffee

• inboxView.jsx

• inbox_filter_dialog_view.coffee (contextual matching)

This makes it more effective at finding all relevant files in a large repository with mixed naming conventions.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.