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: May 11, 2026 | Version: 2.1.0 | Maintained by QA Professionals

Node.js CI Docker CI npm version License: MIT Cypress.io Docker code style: prettier PRs Welcome Ask DeepWiki

Table of Contents

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

Advantages Disadvantages
✅ Real-time reload and time travel debugging ❌ Single browser tab execution
✅ Automatic waiting and retry mechanisms ❌ Limited cross-domain testing
✅ Consistent and reliable tests ❌ No support for multiple browser windows
✅ Built-in screenshots and videos ❌ Limited iframe support
✅ Excellent developer experience and debugging ❌ No native mobile testing support
✅ Modern JavaScript stack and syntax ❌ Same-origin policy limitations
✅ Rich ecosystem of plugins ❌ CPU/Memory intensive for large suites
✅ Comprehensive documentation ❌ Limited support for file downloads
✅ Active community support ❌ Requires JavaScript knowledge
✅ Built-in network stubbing ❌ Browser support limited to Chrome-family
✅ Native access to browser APIs ❌ Not suitable for native mobile apps
✅ Simple setup and configuration ❌ Complex iframe handling
✅ API testing capabilities ❌ Limited parallel testing in open source
✅ TypeScript support ❌ Higher resource usage than Selenium
✅ Command chaining for better readability ❌ Learning curve for non-JS developers

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:

{
  "@simonsmith/cypress-image-snapshot": "^10.0.4",
  "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:15.14.2
  script:
    - npm ci
    - npm run test:ci
  artifacts:
    paths:
      - cypress/reports
      - cypress/screenshots
      - cypress/videos

# Jenkins with Docker
docker.image('cypress/included:15.14.2').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

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.1.0 (May 2026)

  • ⬆️ Updated Cypress from 13.17.0 to 15.14.2
  • ⬆️ Updated @typescript-eslint/eslint-plugin and parser to 8.59.2
  • ⬆️ Updated @testing-library/cypress to 10.1.3
  • ⬆️ Updated @types/node to 22.19.18
  • ⬆️ Updated cypress-real-events to 1.15.0
  • ⬆️ Updated eslint-plugin-cypress to 6.4.1
  • ⬆️ Updated mochawesome to 7.1.4
  • ⬆️ Updated mochawesome-report-generator to 6.3.2
  • ⬆️ Updated prettier to 3.8.3
  • ⬆️ Updated typescript to 5.9.3
  • ⬆️ Updated lint-staged to 15.5.2

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:

{
  "@simonsmith/cypress-image-snapshot": "^10.0.4",
  "cypress-axe": "^1.7.0",
  "@testing-library/cypress": "^10.1.3",
  "cypress-real-events": "^1.15.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": "^22.19.18",
    "typescript": "^5.9.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?

    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

Command Description