Cypress Page Object Model Framework 2026 | MCP | ChatMode | Complete E2E Testing Guide

Production-Ready Cypress Automation Framework with TypeScript, API Testing & CI/CD Integration

Last Updated: February 3, 2026 | Version: 2.0.0 | Maintained by QA Professionals

Table of Contents

• Overview
• Key Features
• Quick Start Guide
• Docker Setup
• Framework Architecture
• Testing Capabilities
  • UI Testing
  • API Testing
  • Accessibility Testing
  • Visual Regression Testing
• Chat Mode Documentation
• AI Agents
• Test Reporting
• CI/CD Integration
• Best Practices
• Troubleshooting
• Contributing
• Support & Community
• License

Overview

A battle-tested, enterprise-grade Cypress automation framework built with TypeScript and the
Page Object Model design pattern. This framework provides everything you need for modern web
application testing including UI testing, API testing, accessibility validation, and comprehensive
reporting.

Perfect for: QA Engineers, Test Automation Engineers, DevOps Teams, and Development Teams
looking to implement robust end-to-end testing.

Why This Framework?

• ✅ Production-Ready: Used in real-world projects with proven reliability
• ✅ Best Practices Built-In: Follows industry standards and design patterns
• ✅ Comprehensive Documentation: Extensive guides and examples
• ✅ Active Maintenance: Regular updates and security patches
• ✅ Community Support: Growing community of contributors

Key Features

• 🐳 Docker Support: Fully containerized testing environment
• 📦 TypeScript support with type definitions
• 🤖 ChatGPT interface testing suite
• ♿ Comprehensive accessibility testing
• 🏗️ Page Object Model implementation
• 🔌 API testing capabilities with custom commands
• ⚡ Parallel test execution
• 🚀 CI/CD ready with GitHub Actions and Docker
• ⚙️ Environment-based configuration
• 📊 Comprehensive reporting with Mochawesome
• 🔄 Built-in retry mechanisms for flaky tests
• 🐋 Docker Compose for easy orchestration

Framework Comparison

Cypress Advantages & Disadvantages

When to Choose Cypress

1. Best For:

   • Modern web applications
   • Single page applications (SPAs)
   • Real-time testing feedback
   • JavaScript/TypeScript projects
   • E2E and Component testing
   • API testing

2. Not Ideal For:

   • Native mobile testing
   • Multi-tab scenarios
   • Complex iframe operations
   • Cross-browser testing at scale
   • Non-JavaScript applications
   • Limited resource environments

Quick Start Guide

Prerequisites

• Node.js: Version 18.x or higher
• npm: Version 8.x or higher
• Git: For version control
• Operating System: Windows, macOS, or Linux
• Docker (Optional): For containerized testing

Installation Steps

1. Clone and Install

git clone https://github.com/padmarajnidagundi/Cypress-POM-Ready-To-Use
cd Cypress-POM-Ready-To-Use

1. Setup Project

npm run presetup     # Install all dependencies
npm run setup       # Install Cypress
npm run verify      # Verify Cypress installation

1. Open Cypress

npm run cypress:open  # Open Cypress Test Runner

1. Run Tests

npm run test:ui          # Run UI tests
npm run test:api         # Run API tests
npm run test:parallel    # Run all tests in parallel
npm run test:ci         # Run tests in CI mode

Troubleshooting Installation

If you encounter the error 'cypress' is not recognized as an internal or external command, follow
these steps:

1. Clear npm cache and node_modules:

npm cache clean --force
rm -rf node_modules
rm -rf package-lock.json

1. Reinstall dependencies:

npm run presetup

1. Verify installation:

npm run verify

Docker Setup

This framework is fully Docker-ready for containerized testing. Run tests in isolated
environments without local Node.js or Cypress installation.

Docker Installation (Alternative)

If you prefer using Docker, you can run the entire test suite in a containerized environment:

1. Using Docker Compose (Recommended)

# Build and run tests
docker-compose up --build cypress

# Run tests in detached mode
docker-compose up -d cypress

# View test reports
docker-compose up cypress-reports
# Access reports at http://localhost:8080

1. Using Docker directly

# Build Docker image
docker build -t cypress-pom-tests .

# Run tests
docker run --rm cypress-pom-tests

# Run specific test suite
docker run --rm cypress-pom-tests npm run test:api
docker run --rm cypress-pom-tests npm run test:ui

# Mount local directory for development
docker run --rm -v ${PWD}/cypress:/e2e/cypress cypress-pom-tests

1. Custom test commands

# Run with environment variables
docker run --rm -e CYPRESS_BASE_URL=https://your-app.com cypress-pom-tests

# Run specific spec file
docker run --rm cypress-pom-tests npx cypress run --spec "cypress/e2e/ui/chatgpt.cy.js"

# Run with custom browser
docker run --rm cypress-pom-tests npm run test -- --browser chrome

1. Access test artifacts

# Copy reports from container
docker run --rm -v ${PWD}/reports:/e2e/cypress/reports cypress-pom-tests

# Or use docker-compose volumes (configured automatically)
docker-compose up cypress
# Reports will be available in ./cypress/reports and ./mochawesome-report

Docker Benefits:

• ✅ Consistent test environment across all machines
• ✅ No local Node.js or Cypress installation required
• ✅ Easy CI/CD integration
• ✅ Isolated dependencies and configurations
• ✅ Quick setup and teardown

Docker NPM Scripts

Convenient npm commands for Docker operations:

npm run docker:build              # Build Docker image
npm run docker:run                # Run all tests in Docker
npm run docker:run:api            # Run API tests only
npm run docker:run:ui             # Run UI tests only
npm run docker:compose:up         # Start with docker-compose
npm run docker:compose:reports    # View reports in browser (port 8080)
npm run docker:compose:down       # Stop and clean up containers

📖 For detailed Docker documentation, see DOCKER.md

1. Test Cypress:

npm run cypress:open

For QA Engineers

Writing UI Tests

1. Create Page Objects

// cypress/pageObjects/pages/loginPage.ts
import BasePage from '../basePage'

class LoginPage extends BasePage {
  private selectors = {
    username: '#username',
    password: '#password',
    submitBtn: '[data-testid="login-btn"]'
  }

  login(username: string, password: string) {
    this.getElement(this.selectors.username).type(username)
    this.getElement(this.selectors.password).type(password)
    this.getElement(this.selectors.submitBtn).click()
  }
}

1. Write Tests

// cypress/e2e/ui/login.cy.ts
import LoginPage from '../../pageObjects/pages/loginPage'

describe('Login Tests', () => {
  const loginPage = new LoginPage()

  beforeEach(() => {
    loginPage.visit('/login')
  })

  it('should login successfully', () => {
    loginPage.login('testuser', 'password')
    // assertions
  })
})

API Testing

Our framework supports comprehensive API testing across multiple categories:

Test Categories

1. Unit Tests - Basic API endpoint validation

describe('[Unit] User API Operations', () => {
  it('[Unit] should retrieve user with valid data structure', () => {
    cy.apiRequest('GET', '/users/1').then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body.data).to.have.all.keys(
        'id',
        'email',
        'first_name',
        'last_name',
        'avatar'
      )
    })
  })
})

1. Integration Tests - End-to-end API workflows

describe('[Integration] User Management Workflow', () => {
  it('[Integration] should perform complete user CRUD operations', () => {
    cy.apiRequest('POST', '/users', {
      body: { name: 'Test User', job: 'QA Engineer' }
    }).then((response) => {
      expect(response.status).to.eq(201)
    })
  })
})

1. Performance Tests - Response time validation

describe('[Performance] API Response Times', () => {
  it('[Performance] should meet response time SLA', () => {
    cy.apiRequest('GET', '/users').then((response) => {
      expect(response.duration).to.be.lessThan(1000)
    })
  })
})

1. Security Tests - Authentication & authorization

describe('[Security] API Authentication', () => {
  it('[Security] should enforce authentication', () => {
    cy.apiRequest('GET', '/protected', {
      headers: { Authorization: 'Bearer invalid_token' }
    }).then((response) => {
      expect(response.status).to.eq(401)
    })
  })
})

1. Validation Tests - Input validation checks

describe('[Validation] API Input Validation', () => {
  it('[Validation] should enforce required fields', () => {
    cy.apiRequest('POST', '/register', {
      body: {}
    }).then((response) => {
      expect(response.status).to.eq(400)
    })
  })
})

1. Interoperability Tests - Cross-platform compatibility

describe('[Interop] API Compatibility', () => {
  it('[Interop] should support multiple formats', () => {
    cy.apiRequest('GET', '/users', {
      headers: { Accept: 'application/json' }
    }).then((response) => {
      expect(response.headers['content-type']).to.include('application/json')
    })
  })
})

1. Mock Tests - Response stubbing & mocking

describe('[Mock] API Response Mocking', () => {
  it('[Mock] should handle mocked responses', () => {
    cy.intercept('GET', '/users', {
      fixture: 'users.json'
    }).as('getUsers')

    cy.apiRequest('GET', '/users').then((response) => {
      expect(response.status).to.eq(200)
      cy.wait('@getUsers')
    })
  })
})

API Test Organization Structure

cypress/e2e/api/
├── unit-tests/           # Basic API operations
├── integration-tests/    # End-to-end workflows
├── performance-tests/    # Response times & load
├── security-tests/      # Auth & security checks
├── validation-tests/    # Input validation
├── mock-tests/         # Response mocking & stubbing
└── interop-tests/      # Compatibility tests

Custom API Commands

Our framework provides built-in commands for API testing:

// Make API requests with default configuration
cy.apiRequest(method, path, options)

// Example usage
cy.apiRequest('POST', '/users', {
  body: { name: 'Test User' },
  headers: { Authorization: 'Bearer token' }
})

API Testing Best Practices

1. Test Structure

   • Use descriptive category prefixes: [Unit], [Integration], etc.
   • Group related tests in appropriate folders
   • Follow the single responsibility principle

2. Assertions

   • Verify status codes and response structure
   • Check response times for performance
   • Validate security headers and tokens
   • Test edge cases and error conditions

3. Data Management

   • Use fixtures for test data
   • Clean up test data after tests
   • Handle environment-specific configurations

Accessibility Testing

Built-in accessibility testing with cypress-axe ensures your application meets WCAG standards:

describe('Accessibility Tests', () => {
  it('should pass accessibility checks', () => {
    cy.visit('/')
    cy.injectAxe()
    cy.checkA11y()
  })
})

Run accessibility tests:

npm run test:a11y

Visual Regression Testing

Automated visual comparison to catch unintended UI changes:

describe('Visual Tests', () => {
  it('should match homepage screenshot', () => {
    cy.visit('/')
    cy.matchImageSnapshot('homepage')
  })
})

Run visual tests:

npm run test:visual

Chat Mode Documentation

What is Chat Mode?

The cypress/chatmode/ folder contains professional testing templates and comprehensive guides
designed to help QA engineers and teams standardize their testing documentation and follow industry
best practices.

Data Management

Test Data Generators:

import { TestDataGenerator } from '../support/helpers/testDataGenerator'

// Generate random user
const user = TestDataGenerator.genera

```groovy
pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                sh 'npm ci'
                sh 'npm run test:ci'
            }
        }
    }
}

Test Reporting

This framework uses Mochawesome for comprehensive HTML reporting. Get detailed insights with
screenshots, videos, and test execution metrics.

1. Available Report Commands

npm run report:clean     # Clean previous reports
npm run report:merge     # Merge multiple report JSONs
npm run report:generate  # Generate HTML from JSON
npm run test:report      # Full test execution with reports

1. Report Features

   • Interactive HTML dashboard
   • Test execution timeline
   • Suite and test-level statistics
   • Failure screenshots embedded in report
   • Test execution videos
   • Performance metrics
   • Filter and search capabilities
   • Responsive design for mobile viewing

2. Report Structure

cypress/reports/
├── html/               # HTML reports
│   ├── assets/        # Screenshots, videos
│   ├── report.html    # Main report
│   └── report.json    # Combined results
└── json/              # Individual test JSONs

1. Reporter Configuration Add these options to cypress.config.js:

module.exports = defineConfig({
  reporter: 'cypress-mochawesome-reporter',
  reporterOptions: {
    charts: true, // Enable charts
    reportPageTitle: 'Test Report', // Custom title
    embeddedScreenshots: true, // Inline screenshots
    inlineAssets: true, // Inline assets
    saveAllAttempts: false, // Save only failures
    reportDir: 'cypress/reports/html',
    overwrite: false,
    html: true,
    json: true
  }
})

1. Viewing Reports

   • Open cypress/reports/html/report.html in any browser
   • Reports are self-contained and can be shared
   • Support offline viewing
   • Can be hosted on any static server

2. CI/CD Integration

- name: Generate Test Report
  if: always()
  run: npm run test:report

- name: Upload Test Report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: test-report
    path: cypress/reports/html

Advanced Features

Visual Regression Testing

The framework includes visual regression testing capabilities:

// Visual regression test example
describe('Visual Tests', () => {
  it('should match homepage screenshot', () => {
    cy.visit('/')
    cy.matchImageSnapshot('homepage')
  })
})

Configuration in cypress.config.js:

• Visual regression path: cypress/snapshots
• Visual threshold: 0.1

Run visual tests:

npm run test:visual

Accessibility Testing

Built-in accessibility testing with cypress-axe:

describe('Accessibility Tests', () => {
  it('should pass accessibility checks', () => {
    cy.visit('/')
    cy.injectAxe()
    cy.checkA11y()
  })
})

Run accessibility tests:

npm run test:a11y

Network Stubbing

Enhanced network mocking capabilities:

// Mock REST API
cy.mockNetworkResponse('GET', '/api/users', { users: [] })

// Mock GraphQL
cy.mockGraphQL('GetUsers', { data: { users: [] } })

Test Data Management

Factory pattern for test data generation:

import UserFactory from '../support/factories/userFactory'

describe('User Tests', () => {
  it('should create user', () => {
    const user = UserFactory.generate()
    // Use generated user data in tests
  })

  it('should create multiple users', () => {
    const users = UserFactory.generateMany(3)
    // Use generated users data in tests
  })
})

Additional Dependencies

New testing capabilities are provided by:

{
  "cypress-image-snapshot": "^4.0.1",
  "cypress-axe": "^1.7.0",
  "@testing-library/cypress": "^10.0.2",
  "cypress-real-events": "^1.14.0"
}

Debugging Tips

1. Time Travel

   • Use Cypress Time Travel feature
   • Check screenshots in cypress/screenshots
   • Review videos in cypress/videos

2. Logging

   • Use cy.log() for debug information
   • Enable Chrome DevTools in interactive mode

3. Interactive Debugging

// Pause test execution
cy.pause()

// Debug specific command
cy.get('button').debug()

// Log variables
cy.log('User data:', user)

Contributing

We welcome contributions! This project follows industry best practices and is maintained by
experienced QA professionals.teUser()

// Generate email const email = TestDataGenerator.generateEmail()

// Generate password const password = TestDataGenerator.generatePassword(16, true)

**Assertion Helpers:**

```javascript
import AssertionHelpers from '../support/helpers/assertionHelpers'

// Assert API response
AssertionHelpers.assertApiResponse(response, 200, ['id', 'name', 'email'])

// Assert element state
AssertionHelpers.assertElementState('[data-testid="button"]', {
  visible: true,
  enabled: true,
  text: 'Submit'
})

Troubleshooting

Common Issues & Solutions

1. Installation Problems

Cypress not recognized:

# Clear cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm run presetup

Permission errors:

# Linux/Mac: Fix permissions
sudo chown -R $(id -u):$(id -g) ~/.cache/Cypress

2. Docker Issues

Permission denied (Linux/Mac):

# Fix file permissions
sudo chown -R $(id -u):$(id -g) cypress/reports
sudo chown -R $(id -u):$(id -g) node_modules

# Or run with proper user
docker run --rm --user $(id -u):$(id -g) cypress-pom-tests

Out of memory:

# Increase Docker memory
docker run --rm --memory=4g cypress-pom-tests

# Or in docker-compose.yml add:
# mem_limit: 4g

Slow Docker builds:

# Use BuildKit for faster builds
DOCKER_BUILDKIT=1 docker build -t cypress-pom-tests .

# Or use docker-compose with parallel builds
docker-compose build --parallel

Network connectivity issues:

# Check DNS resolution
docker run --rm cypress-pom-tests nslookup google.com

# Use host network (Linux only)
docker run --rm --network=host cypress-pom-tests

Video/screenshot issues:

# Disable video recording to save resources
docker run --rm -e CYPRESS_VIDEO=false cypress-pom-tests

📖 For more Docker troubleshooting, see DOCKER.md

3. Test Execution Issues

Flaky tests:

• Enable retry mechanism in cypress.config.js
• Use proper waits instead of hard-coded delays
• Check network stability

Timeout errors:

// Increase timeout in cypress.config.js
defaultCommandTimeout: 10000,
pageLoadTimeout: 60000

Chat Mode Documentation

1. Test Case Template (test-case-template.md)

A standardized template for documenting test cases including:

• Test ID and priority
• Test type classification
• Prerequisites and setup
• Detailed test steps
• Expected vs actual results
• Test data and environment info
• Status tracking

Usage:

# Copy template for new test case
cp cypress/chatmode/test-case-template.md docs/test-cases/TC-001.md

2. Bug Report Template (bug-report-template.md)

Comprehensive bug reporting format with:

• Severity and priority classification
• Environment details
• Reproduction steps
• Expected vs actual behavior
• Screenshots and console errors
• Impact assessment

Usage:

# Create new bug report
cp cypress/chatmode/bug-report-template.md docs/bugs/BUG-001.md

3. Test Execution Report (test-execution-report.md)

Professional test execution summary including:

• Test statistics and metrics
• Pass/fail breakdown by category
• Performance metrics
• Defect summary
• Risk assessment
• Recommendations

Usage: Use this template to generate weekly/sprint test reports for stakeholders.

4. API Testing Checklist (api-testing-checklist.md)

Complete API testing checklist covering:

• Functional testing
• Error handling (4xx, 5xx)
• Security testing
• Performance validation
• Data validation
• Edge cases

Usage: Reference during API test planning and execution to ensure comprehensive coverage.

5. UI Testing Best Practices (ui-testing-best-practices.md)

In-depth guide including:

• Test design principles
• Selector best practices
• Assertion strategies
• Waiting mechanisms
• Common pitfalls
• Debugging techniques

Usage: Share with team members and reference during code reviews.

How to Use Chat Mode Files

For Individual QA Engineers:

1. Test Planning Phase:

   # Review best practices
   cat cypress/chatmode/ui-testing-best-practices.md
   cat cypress/chatmode/api-testing-checklist.md
   

2. Test Execution:

   # Document your tests
   cp cypress/chatmode/test-case-template.md my-test-cases/TC-LOGIN-001.md
   

3. Bug Reporting:

   # Report issues using standard format
   cp cypress/chatmode/bug-report-template.md bugs/BUG-PAYMENT-001.md
   

For QA Teams:

1. Onboarding New Team Members:

   • Share the ui-testing-best-practices.md as training material
   • Use templates to standardize documentation
   • Reference during code reviews

2. Sprint Planning:

   • Use api-testing-checklist.md for test coverage planning
   • Estimate testing effort using templates
   • Create test cases from templates

3. Sprint Reviews:

   • Generate reports using test-execution-report.md
   • Present standardized metrics to stakeholders
   • Track quality trends over time

For Test Automation Projects:

# Set up documentation structure
mkdir -p docs/{test-cases,bugs,reports}

# Copy templates
cp cypress/chatmode/test-case-template.md docs/test-cases/
cp cypress/chatmode/bug-report-template.md docs/bugs/
cp cypress/chatmode/test-execution-report.md docs/reports/

# Create your first documented test case
cp cypress/chatmode/test-case-template.md docs/test-cases/TC-001-user-login.md

Integration with IDE/Chat Tools

The chat mode templates are designed to work with:

• AI Code Assistants: Copy templates into your AI assistant for context-aware test generation
• Documentation Tools: Import into Confluence, Notion, or other wikis
• Version Control: Track documentation changes alongside code
• Code Reviews: Reference during PR reviews for quality standards

Customization

All templates are Markdown-based and fully customizable:

# Customize for your project
vim cypress/chatmode/test-case-template.md

# Add your own templates
touch cypress/chatmode/my-custom-template.md

Test Reporting

Mochawesome HTML Reports

This framework uses Mochawesome for comprehensive HTML reporting with embedded screenshots and
videos.

1. Selectors

   • Use data-testid attributes: [data-testid="login-button"]
   • Store selectors in page objects.
   • Use meaningful selector names.

2. Test Organization

cypress/
├── e2e/
│   ├── api/           # API Tests
│   │   ├── users/
│   │   └── auth/
│   └── ui/            # UI Tests
│       ├── login/
│       └── dashboard/
├── pageObjects/
│   ├── components/    # Reusable components
│   └── pages/         # Page specific objects
└── fixtures/          # Test data

1. Custom Commands
   • Create reusable commands for common operations
   • Use TypeScript for better type checking
   • Document command parameters

Environment Configuration

// cypress.config.js
module.exports = {
  env: {
    apiUrl: 'https://api.dev.example.com',
    userRole: 'admin',
    featureFlags: {
      newUI: true
    }
  }
}

Running Tests in CI

1. GitHub Actions (pre-configured)

npm run test:ci

1. Docker in CI/CD

# GitHub Actions with Docker
- name: Run Cypress Tests in Docker
  run: |
    docker-compose up --build --abort-on-container-exit cypress

# GitLab CI with Docker
test:
  image: cypress/included:13.17.0
  script:
    - npm ci
    - npm run test:ci
  artifacts:
    paths:
      - cypress/reports
      - cypress/screenshots
      - cypress/videos

# Jenkins with Docker
docker.image('cypress/included:13.17.0').inside {
    sh 'npm ci'
    sh 'npm run test:ci'
}

1. Jenkins (sample configuration)

pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                sh 'npm ci'
                sh 'npm run test:ci'
            }
        }
    }
}

Test Reporting

This framework uses Mochawesome for comprehensive HTML reporting. Get detailed insights with
screenshots, videos, and test execution metrics.

1. Available Report Commands

npm run report:clean     # Clean previous reports
npm run report:merge     # Merge multiple report JSONs
npm run report:generate  # Generate HTML from JSON
npm run test:report      # Full test execution with reports

1. Report Features

   • Interactive HTML dashboard
   • Test execution timeline
   • Suite and test-level statistics
   • Failure screenshots embedded in report
   • Test execution videos
   • Performance metrics
   • Filter and search capabilities
   • Responsive design for mobile viewing

2. Report Structure

cypress/reports/
├── html/               # HTML reports
│   ├── assets/        # Screenshots, videos
│   ├── report.html    # Main report
│   └── report.json    # Combined results
└── json/              # Individual test JSONs

1. Reporter Configuration Add these options to cypress.config.js:

module.exports = defineConfig({
  reporter: 'cypress-mochawesome-reporter',
  reporterOptions: {
    charts: true, // Enable charts
    reportPageTitle: 'Test Report', // Custom title
    embeddedScreenshots: true, // Inline screenshots
    inlineAssets: true, // Inline assets
    saveAllAttempts: false, // Save only failures
    reportDir: 'cypress/reports/html',
    overwrite: false,
    html: true,
    json: true
  }
})

1. Viewing Reports

   • Open cypress/reports/html/report.html in any browser
   • Reports are self-contained and can be shared
   • Support offline viewing
   • Can b & Community

Get Help

• Documentation: Comprehensive guides in this README and /cypress/chatmode/
• GitHub Issues:
  Report bugs or request features
• Discussions: Join our
  GitHub Discussions

Community

• Stars: Star this repo if you find it useful
• Fork: Fork and customize for your needs
• Contribute: Submit PRs with improvements
• Share: Share with your QA community

Changelog

Version 2.0.0 (January-February 2026)

• 🐳 Added full Docker support with Dockerfile and docker-compose.yml
• 🐳 Created comprehensive Docker documentation (DOCKER.md)
• 🐳 Added Docker CI/CD workflow (.github/workflows/docker.yml)
• 🐳 Added Docker npm scripts for easy container management
• ✨ Added ESLint 9 flat config support
• ✨ Integrated Husky 9 for pre-commit hooks
• ✨ Added comprehensive test helpers (data generators, assertions, retry logic)
• ✨ Created chatmode templates for documentation
• 📝 Enhanced README with E-E-A-T guidelines and Docker sections
• 🔧 Updated dependencies (cypress-axe, cypress-mochawesome-reporter)
• 🔧 Added dependabot configuration
• 🔧 Improved GitHub Actions workflow
• 📚 Added CONTRIBUTING.md
• 📚 Added .dockerignore for optimized builds

Version 1.x

• Initial release with Page Object Model
• Basic UI and API testing support

Frequently Asked Questions (FAQ)always()

run: npm run test:report

• name: Upload Test Report if: always() uses: actions/upload-artifact@v4 with: name: test-report
  path: cypress/reports/html

## Advanced Features

### Visual Regression Testing

The framework includes visual regression testing capabilities:

```javascript
// Visual regression test example
describe('Visual Tests', () => {
  it('should match homepage screenshot', () => {
    cy.visit('/')
    cy.matchImageSnapshot('homepage')
  })
})

Configuration in cypress.config.js:

• Visual regression path: cypress/snapshots
• Visual threshold: 0.1

Run visual tests:

npm run test:visual

Accessibility Testing

Built-in accessibility testing with cypress-axe:

describe('Accessibility Tests', () => {
  it('should pass accessibility checks', () => {
    cy.visit('/')
    cy.injectAxe()
    cy.checkA11y()
  })
})

Run accessibility tests:

npm run test:a11y

Network Stubbing

Enhanced network mocking capabilities:

// Mock REST API
cy.mockNetworkResponse('GET', '/api/users', { users: [] })

// Mock GraphQL
cy.mockGraphQL('GetUsers', { data: { users: [] } })

Test Data Management

Factory pattern for test data generation:

import UserFactory from '../support/factories/userFactory'

describe('User Tests', () => {
  it('should create user', () => {
    const user = UserFactory.generate()
    // Use generated user data in tests
  })

  it('should create multiple users', () => {
    const users = UserFactory.generateMany(3)
    // Use generated users data in tests
  })
})

Additional Dependencies

New testing capabilities are provided by:

{
  "cypress-image-snapshot": "^4.0.1",
  "cypress-axe": "^1.5.0",
  "@testing-library/cypress": "^10.0.1",
  "cypress-real-events": "^1.11.0",
  "@faker-js/faker": "^8.0.0"
}

Debugging Tips

1. Time Travel

   • Use Cypress Time Travel feature
   • Check screenshots in cypress/screenshots
   • Review videos in cypress/videos

2. Logging

   • Use cy.log() for debug information
   • Enable Chrome DevTools in interactive mode

Contributing

We welcome contributions that help improve this Cypress Page Object Model framework! Here's how you
can contribute:

Types of Contributions

1. Page Objects

   • New page object implementations
   • Improvements to existing page objects
   • Utility functions for common actions

2. Test Examples

   • UI test examples
   • API test examples
   • Integration test patterns

3. Documentation

   • Usage examples
   • Best practices
   • Troubleshooting guides

How to Contribute

1. Fork and Clone

   # Fork this repository on GitHub
   git clone https://github.com/YOUR_USERNAME/Cypress-POM-Ready-To-Use.git
   cd Cypress-POM-Ready-To-Use
   npm install
   

2. Create a Branch

   git checkout -b feature/your-feature-name
   

3. Make Changes

   • Follow the existing code structure
   • Add tests for new features
   • Update documentation as needed

4. Contribution Guidelines

   • Use TypeScript for new files
   • Follow the page object pattern
   • Add JSDoc comments for methods
   • Include test cases for new features

   /**
    * Example of a well-documented page object
    */
   class ExamplePage extends BasePage {
     private selectors = {
       submitButton: '[data-testid="submit"]'
     }
   
     /**
      * Submits the form with given data
      * @param {string} data - The data to submit
      * @returns {Cypress.Chainable}
      */
     submitForm(data: string) {
       return this.getElement(this.selectors.submitButton).click()
     }
   }
   

5. Run Tests

   npm run test        # Run all tests
   npm run lint        # Check code style
   npm run build       # Ensure build passes
   

6. Submit PR

   • Create a Pull Request against the main branch
   • Provide a clear description of changes
   • Reference any related issues
   • Wait for review and address feedback

Directory Structure for Contributions

cypress/
├── e2e/                    # Add tests here
│   ├── api/               # API test examples
│   └── ui/                # UI test examples
├── pageObjects/           # Add page objects here
│   ├── components/        # Reusable components
│   └── pages/            # Page implementations
└── support/              # Add custom commands here
    └── commands/         # Custom command implementations

Code Style Guide

1. Naming Conventions

   • Use PascalCase for page objects: LoginPage.ts
   • Use camelCase for methods: submitForm()
   • Use descriptive test names: 'should successfully submit form'

2. File Organization

   • One page object per file
   • Group related tests in describe blocks
   • Keep selectors in a separate object

3. Testing Standards

   • Write atomic tests
   • Use meaningful assertions
   • Avoid hard-coded waits

Need Help?

• Check existing issues
• Join our [Discord community]
• Read our [documentation]

Support

• Documentation: See docs/ folder
• Issues: GitHub Issues
• Community: [Join our Discord]

FAQ

Common Configuration Issues

1. Error with cypress.config.js

   const { defineConfig } = require('cypress')
   

   Solution: Ensure proper configuration setup:

   • Install browserify preprocessor: npm install @cypress/browserify-preprocessor --save-dev
   • Use the complete configuration:

   const { defineConfig } = require('cypress')
   const createBundler = require('@cypress/browserify-preprocessor')
   
   module.exports = defineConfig({
     viewportWidth: 1920,
     viewportHeight: 1080,
     watchForFileChanges: false
     // ... other configurations
   })
   

2. TypeScript Support

   • Ensure these dependencies are installed:

   {
     "devDependencies": {
       "@cypress/browserify-preprocessor": "^3.0.2",
       "@types/node": "^20.11.16",
       "typescript": "^5.3.3"
     }
   }
   

3. Running Tests

   • For UI tests: npm run test:ui
   • For API tests: npm run test:api
   • For parallel execution: npm run test:parallel

4. Environment Configuration

   • Default environments are:
     • API URL: https://reqres.in
     • React App URL: https://react-redux.realworld.io
     • Example URL: https://example.cypress.io

5. Docker Questions

   Q: Do I need Docker installed to run tests?

   • No, Docker is optional. You can run tests locally with Node.js or use Docker for containerized
     testing.

   Q: How do I run tests in Docker?

   # Quick start
   docker-compose up --build cypress
   
   # Or using Docker directly
   docker build -t cypress-pom-tests .
   docker run --rm cypress-pom-tests
   

   Q: Can I access test reports from Docker?

   • Yes! Use docker-compose up cypress-reports and open http://localhost:8080

   Q: How do I debug tests in Docker?

   # Interactive shell
   docker run --rm -it cypress-pom-tests /bin/bash
   
   # Enable debug logs
   docker run --rm -e DEBUG=cypress:* cypress-pom-tests
   

   Q: Docker builds are slow, how to speed up?

   # Use BuildKit
   DOCKER_BUILDKIT=1 docker build -t cypress-pom-tests .
   
   # Use cache effectively (already configured in Dockerfile)
   

Best Practices

1. Page Object Model

   • Keep selectors in page objects
   • Use data-testid attributes
   • Implement base page for common functions

2. Test Organization

   • API tests in cypress/e2e/api/
   • UI tests in cypress/e2e/ui/
   • Integration tests in cypress/e2e/integration/

3. Performance

   • Use cy.session() for login state
   • Enable retries in CI mode
   • Implement proper timeouts

Quick Reference

Essential Commands

Docker Commands

File Structure

cypress/
├── e2e/                    # Test files
│   ├── api/               # API tests
│   ├── ui/                # UI tests
│   └── accessibility/     # A11y tests
├── pageObjects/           # Page Object Models
├── fixtures/              # Test data
├── support/               # Custom commands & helpers
└── reports/               # Test reports

License

MIT License - feel free to use in your projects

Contact

• Author: Padmaraj Nidagundi
• Email: [email protected]
• LinkedIn: https://www.linkedin.com/in/padmarajn/
• NpmJs: https://www.npmjs.com/package/cypress-page-object-model
• GitHub: https://github.com/padmarajnidagundi/Cypress-POM-Ready-To-Use

MCP (Model Context Protocol) Integration

Using ChatMode Templates with MCP

This repository provides MCP-compatible chatmode templates that can be accessed directly by AI
assistants and automation tools through the Model Context Protocol. The chatmode folder contains
professional testing templates and best practices documentation that can be used for context-aware
test generation and documentation.

Available MCP Resources

The following resources are available in the cypress/chatmode/ directory for MCP integration:

1. Test Case Template (test-case-template.md)

   • Standardized test case documentation format
   • Use for generating consistent test documentation
   • Includes: Test ID, priority, steps, expected results

2. Bug Report Template (bug-report-template.md)

   • Professional bug reporting structure
   • Severity and priority classification
   • Reproduction steps and impact assessment

3. Test Execution Report (test-execution-report.md)

   • Comprehensive test execution summary
   • Statistics, metrics, and defect tracking
   • Stakeholder-ready reporting format

4. API Testing Checklist (api-testing-checklist.md)

   • Complete API testing coverage checklist
   • Security, performance, and validation checks
   • Best practices and edge cases

5. UI Testing Best Practices (ui-testing-best-practices.md)

   • Detailed testing guidelines and patterns
   • Selector strategies and debugging techniques
   • Common pitfalls and solutions

MCP Integration Guide

For AI Assistants (Claude, ChatGPT, etc.)

AI assistants can reference these templates when helping users:

Repository: padmarajnidagundi/Cypress-POM-Ready-To-Use
Path: cypress/chatmode/
Branch: main

Available Templates:
- test-case-template.md
- bug-report-template.md
- test-execution-report.md
- api-testing-checklist.md
- ui-testing-best-practices.md

For MCP Servers

Create an MCP server configuration to expose chatmode templates:

{
  "mcpServers": {
    "cypress-chatmode": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./cypress/chatmode"],
      "env": {
        "ALLOWED_DIRECTORIES": "./cypress/chatmode"
      }
    }
  }
}

Usage Examples

1. Generate Test Case:

# AI can read template and generate test case
mcp read cypress/chatmode/test-case-template.md

2. Create Bug Report:

# Use template to structure bug reports
mcp read cypress/chatmode/bug-report-template.md

3. Access Best Practices:

# Reference guidelines during test development
mcp read cypress/chatmode/ui-testing-best-practices.md

Direct File Access via GitHub

Templates can be accessed directly via GitHub URLs for MCP tools:

https://raw.githubusercontent.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/main/cypress/chatmode/test-case-template.md
https://raw.githubusercontent.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/main/cypress/chatmode/bug-report-template.md
https://raw.githubusercontent.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/main/cypress/chatmode/test-execution-report.md
https://raw.githubusercontent.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/main/cypress/chatmode/api-testing-checklist.md
https://raw.githubusercontent.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/main/cypress/chatmode/ui-testing-best-practices.md

MCP Use Cases

1. Context-Aware Test Generation

AI assistants can use chatmode templates as context to generate:

• Structured test cases following your team's format
• Bug reports with all required information
• Test execution summaries with proper metrics

2. Documentation Automation

Automatically generate testing documentation using templates:

• Convert test code to documentation format
• Create test reports from execution results
• Generate checklists for test planning

3. Code Review & Quality Checks

Reference best practices during code review:

• Validate test structure against guidelines
• Check API testing coverage
• Ensure proper selector usage

4. Team Onboarding

Use templates for training new team members:

• Provide standardized documentation format
• Share testing best practices
• Establish consistent workflows

Setting Up MCP for This Repository

Step 1: Clone the Repository

git clone https://github.com/padmarajnidagundi/Cypress-POM-Ready-To-Use.git
cd Cypress-POM-Ready-To-Use

Step 2: Configure MCP Server (for Cline, Claude Desktop, etc.)

Add to your MCP configuration file (e.g., cline_mcp_settings.json):

{
  "mcpServers": {
    "cypress-templates": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/absolute/path/to/Cypress-POM-Ready-To-Use/cypress/chatmode"
      ]
    }
  }
}

Step 3: Use Templates in Your Workflow

Once configured, AI assistants can:

• Read templates to understand your documentation standards
• Generate new documents based on templates
• Reference best practices during test development
• Provide context-aware suggestions

Benefits of MCP Integration

1. Consistency: All generated documentation follows your templates
2. Efficiency: Faster test documentation and report generation
3. Quality: AI-generated content adheres to best practices
4. Collaboration: Team members get consistent guidance
5. Scalability: Easy to extend with more templates

Future MCP Enhancements

Planned features for enhanced MCP integration:

• Dynamic Page Objects: MCP-aware page object generation
• Test Orchestration: Cross-layer test flow automation
• Live Context Switching: Dynamic environment and context management
• CI/CD Integration: MCP endpoints for build systems
• Custom Commands: Cypress commands for MCP interaction
• Real-time Reporting: Stream test results via MCP

Contributing MCP Templates

We welcome contributions of additional templates:

1. Create new .md template in cypress/chatmode/
2. Follow existing template structure
3. Add usage examples
4. Submit pull request

Template Guidelines:

• Use clear, descriptive headers
• Include examples and placeholders
• Add usage instructions
• Keep format consistent

Status: MCP integration is ACTIVE - chatmode templates are ready to use with any
MCP-compatible tool!

AI Agents

Overview

This framework is designed to work seamlessly with AI coding agents such as GitHub Copilot (VS
Code), Cursor, Cline, Claude, and similar tools. The cypress/chatmode/ templates and the MCP
server configuration give any agent the context it needs to generate, review, and maintain your
Cypress tests automatically.

GitHub Copilot Agent (VS Code)

What the Agent Does

Quick Start — Copilot Chat

1. Open the Copilot Chat panel in VS Code (Ctrl+Alt+I / Cmd+Alt+I).
2. Open the relevant spec or page-object file so Copilot has file context.
3. Type a natural-language request:

@workspace Generate a Cypress spec for the Login page using the ReactLogin page object.

@workspace Add a custom command cy.loginAsAdmin() that calls POST /api/login and stores
the token in localStorage.

@workspace Review cypress/e2e/api/users.cy.js and suggest improvements for selector
strategy and assertion depth.

Copilot Agent Mode

Enable Agent mode (GitHub Copilot Edits) for multi-file changes:

1. Click the Copilot icon in the VS Code sidebar → Open Copilot Edits.
2. Type your intent across multiple files, e.g.:

Create a new page object for the Pricing page, add a spec that validates all plan cards,
and register a custom Cypress command `cy.checkPricingCard(planName)`.

Copilot will propose edits across pageObjects/, e2e/, and support/commands/ simultaneously.

Inline Completions in Test Files

Copilot provides real-time completions inside spec files:

// Start typing — Copilot completes the full test body
it('should display error on invalid credentials', () => {
  // Copilot auto-completes from here using context from loginPage.js
})

Using Chatmode Templates with Agents

The cypress/chatmode/ directory contains structured prompt templates. Attach them to any agent
conversation to enforce consistent output format.

Attaching a Template in Copilot Chat

# Reference the template in your prompt
@workspace Using the format defined in cypress/chatmode/test-case-template.md, write
test cases for the user registration flow.

Available Templates

Example Prompts

# Generate a structured test case document
@workspace Read cypress/chatmode/test-case-template.md then produce a test case document
for the "Add to Cart" feature.

# Let the agent audit API coverage
@workspace Use cypress/chatmode/api-testing-checklist.md as a checklist and evaluate
how well cypress/e2e/api/ covers each item.

# Ask the agent to write a bug report
@workspace A 401 error appears on POST /api/users when authenticated. Produce a bug
report following cypress/chatmode/bug-report-template.md.

Cline / Claude Desktop Agent

Expose the chatmode folder over MCP so any MCP-aware agent can read templates natively:

{
  "mcpServers": {
    "cypress-chatmode": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./cypress/chatmode"],
      "env": { "ALLOWED_DIRECTORIES": "./cypress/chatmode" }
    }
  }
}

After configuring, the agent can:

# List available templates
mcp list cypress/chatmode/

# Read a specific template
mcp read cypress/chatmode/test-case-template.md

# Generate a test case from the template
mcp read cypress/chatmode/test-case-template.md | agent generate --feature "User Login"

Cursor Agent

1. Open Cursor and point it at this repository.
2. Press Ctrl+K to open the inline agent prompt inside any .cy.js / .cy.ts file.
3. Use @file references to include page objects or fixtures:

@file cypress/pageObjects/reactLogin.js
Generate a full Cypress spec that covers successful login, invalid password, and
account-locked scenarios. Follow the POM pattern in the referenced file.

1. For project-wide changes, open Cursor Composer (Ctrl+Shift+I) and describe the full task:

Refactor all API specs under cypress/e2e/api/ to use the cy.apiRequest() custom command
defined in cypress/support/commands/api.commands.js.

Agent-Driven CI/CD

Agents can be embedded in CI pipelines to generate or update tests on every PR:

# .github/workflows/agent-test-gen.yml
name: Agent Test Generation
on:
  pull_request:
    paths:
      - 'src/**'

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm run test:ci
      # Add your preferred AI agent step here to analyse diff and
      # propose new Cypress specs for changed source files.

Tips for Effective Agent Use

1. Provide file context — open the relevant page object or spec before prompting so the agent
   inherits accurate selector and method names.
2. Reference chatmode templates — including a template path steers the agent toward consistent,
   reviewable output.
3. Break large tasks down — ask the agent to handle one page object or one test category at a
   time for more accurate results.
4. Review generated selectors — prefer data-testid attributes; ask the agent to flag any
   brittle CSS or XPath selectors it produces.
5. Commit incrementally — accept agent-generated files one at a time so each diff is easy to
   review and revert if needed.
6. Iterate with error output — when a generated test fails, paste the Cypress error output back
   into the agent chat for a precise fix.

Tip: The cypress/chatmode/ui-testing-best-practices.md file is an excellent system prompt
addition for any agent when working on UI test files in this repository.