# Cypress Page Object Model Framework

**Production-ready Cypress automation with TypeScript, API testing, Docker, and CI/CD support**

> **Updated:** September 2026 | **Package version:** 2.1.0 | **Current stack:** Node.js 18+ / Cypress 15.14.2 / TypeScript 5.9 / ESLint 9

[![Node.js CI](https://github.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/actions/workflows/node.js.yml/badge.svg)](https://github.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/actions/workflows/node.js.yml)
[![Docker CI](https://github.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/actions/workflows/docker.yml/badge.svg)](https://github.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/actions/workflows/docker.yml)
[![npm version](https://img.shields.io/npm/v/cypress-page-object-model.svg)](https://www.npmjs.com/package/cypress-page-object-model)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Cypress.io](https://img.shields.io/badge/tested%20with-Cypress-04C38E.svg)](https://www.cypress.io/)
[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white)](https://www.docker.com/)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/padmarajnidagundi/Cypress-POM-Ready-To-Use)

## Table of Contents

- [Overview](#overview)
- [Key Features](#key-features)
- [Quick Start Guide](#quick-start-guide)
- [Docker Setup](#docker-setup)
- [Framework Architecture](#framework-architecture)
- [Testing Capabilities](#testing-capabilities)
  - [UI Testing](#ui-testing)
  - [API Testing](#api-testing)
  - [Accessibility Testing](#accessibility-testing)
  - [Visual Regression Testing](#visual-regression-testing)
- [Chat Mode Documentation](#chat-mode-documentation)
- [AI Agents](#ai-agents)
- [Test Reporting](#test-reporting)
- [CI/CD Integration](#cicd-integration)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [Support & Community](#support--community)
- [License](#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

| 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**: 18.x or newer
- **npm**: 8.x or newer
- **Git**: for version control
- **Operating System**: Windows, macOS, or Linux
- **Docker** (optional): for containerized runs with the Compose v2 plugin

### Installation Steps

1. **Clone and Install**

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

2. **Setup Project**

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

3. **Open Cypress**

```bash
npm run cypress:open  # Open Cypress Test Runner
```

4. **Run Tests**

```bash
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:

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

2. Reinstall dependencies:

```bash
npm run presetup
```

3. Verify installation:

```bash
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)**

```bash
# 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
```

2. **Using Docker directly**

```bash
# 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
```

3. **Custom test commands**

```bash
# 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
```

4. **Access test artifacts**

```bash
# 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:

```bash
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](DOCKER.md)**

4. Test Cypress:

```bash
npm run cypress:open
```

## For QA Engineers

### Writing UI Tests

1. **Create Page Objects**

```typescript
// 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()
  }
}
```

2. **Write Tests**

```typescript
// 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

```javascript
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'
      )
    })
  })
})
```

2. **Integration Tests** - End-to-end API workflows

```javascript
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)
    })
  })
})
```

3. **Performance Tests** - Response time validation

```javascript
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)
    })
  })
})
```

4. **Security Tests** - Authentication & authorization

```javascript
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)
    })
  })
})
```

5. **Validation Tests** - Input validation checks

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

6. **Interoperability Tests** - Cross-platform compatibility

```javascript
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')
    })
  })
})
```

7. **Mock Tests** - Response stubbing & mocking

```javascript
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:

```javascript
// 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:

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

**Run accessibility tests:**

```bash
npm run test:a11y
```

### Visual Regression Testing

Automated visual comparison to catch unintended UI changes:

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

**Run visual tests:**

```bash
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:**

````javascript
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**

```bash
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
```

2. **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

3. **Report Structure**

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

4. **Reporter Configuration** Add these options to `cypress.config.js`:

```javascript
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
  }
})
```

5. **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

6. **CI/CD Integration**

```yaml
- 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:

```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:

```bash
npm run test:visual
```

### Accessibility Testing

Built-in accessibility testing with cypress-axe:

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

Run accessibility tests:

```bash
npm run test:a11y
```

### Network Stubbing

Enhanced network mocking capabilities:

```javascript
// 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:

```javascript
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:

```json
{
  "@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

3. **Interactive Debugging**

```javascript
// 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.

**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:**

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

**Permission errors:**

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

#### 2. Docker Issues

**Permission denied (Linux/Mac):**

```bash
# 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:**

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

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

**Slow Docker builds:**

```bash
# 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:**

```bash
# 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:**

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

> 📖 **For more Docker troubleshooting, see [DOCKER.md](DOCKER.md#troubleshooting)**

#### 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:**

```javascript
// 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:**

```bash
# 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:**

```bash
# 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:**

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

2. **Test Execution:**

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

3. **Bug Reporting:**
   ```bash
   # 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:

```bash
# 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:

```bash
# 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
```

3. **Custom Commands**
   - Create reusable commands for common operations
   - Use TypeScript for better type checking
   - Document command parameters

### Environment Configuration

```javascript
// 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)

```bash
npm run test:ci
```

2. **Docker in CI/CD**

```yaml
# 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'
}
```

3. **Jenkins** (sample configuration)

```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**

```bash
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
```

2. **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

3. **Report Structure**

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

4. **Reporter Configuration** Add these options to `cypress.config.js`:

```javascript
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
  }
})
```

5. **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

### Get Help

- **Documentation**: Comprehensive guides in this README and `/cypress/chatmode/`
- **GitHub Issues**:
  [Report bugs or request features](https://github.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/issues)
- **Discussions**: Join our
  [GitHub Discussions](https://github.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/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.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)

## 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:

```bash
npm run test:visual
```

### Accessibility Testing

Built-in accessibility testing with cypress-axe:

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

Run accessibility tests:

```bash
npm run test:a11y
```

### Network Stubbing

Enhanced network mocking capabilities:

```javascript
// 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:

```javascript
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:

```json
{
  "@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**

   ```bash
   # 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**

   ```bash
   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

   ```typescript
   /**
    * 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**

   ```bash
   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](https://github.com/padmarajnidagundi/Cypress-POM-Ready-To-Use/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`**

   ```javascript
   const { defineConfig } = require('cypress')
   ```

   **Solution:** Ensure proper configuration setup:

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

   ```javascript
   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:

   ```json
   {
     "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?**

   ```bash
   # 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?**

   ```bash
   # 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?**

   ```bash
   # 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              |
| ----------------------- | ------------------------ |
| `npm run presetup`      | Install all dependencies |
| `npm run cypress:open`  | Open Cypress Test Runner |
| `npm run test:ui`       | Run UI tests             |
| `npm run test:api`      | Run API tests            |
| `npm run test:ci`       | Run tests in CI mode     |
| `npm run test:parallel` | Run tests in parallel    |

### Docker Commands

| Command                             | Description                   |
| ----------------------------------- | ----------------------------- |
| `npm run docker:build`              | Build Docker image            |
| `npm run docker:run`                | Run tests in Docker           |
| `npm run docker:compose:up`         | Start with docker-compose     |
| `npm run docker:compose:reports`    | View reports (localhost:8080) |
| `docker-compose up --build cypress` | Build and run tests           |
| `docker run --rm cypress-pom-tests` | Run tests (direct)            |

### 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: padmaraj.nidagundi@gmail.com
- 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:

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

#### Usage Examples

**1. Generate Test Case:**

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

**2. Create Bug Report:**

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

**3. Access Best Practices:**

```bash
# 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**

```bash
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`):

```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

| Capability                | Description                                                        |
| ------------------------- | ------------------------------------------------------------------ |
| **Generate Tests**        | Ask Copilot to write new Cypress specs using existing page objects |
| **Fix Failing Tests**     | Paste error output and let Copilot suggest a fix                   |
| **Scaffold Page Objects** | Describe a page and Copilot produces a typed POM class             |
| **Add Custom Commands**   | Request new `cy.*` commands in `cypress/support/commands/`         |
| **Review Test Quality**   | Ask Copilot to audit selectors, waits, and assertions              |
| **Generate Fixtures**     | Produce realistic JSON test-data files under `cypress/fixtures/`   |

#### 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:

```javascript
// 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

| Template                       | Best Used When                                  |
| ------------------------------ | ----------------------------------------------- |
| `test-case-template.md`        | Asking an agent to document a new test scenario |
| `bug-report-template.md`       | Asking an agent to capture a reproduction case  |
| `test-execution-report.md`     | Asking an agent to summarise a test run         |
| `api-testing-checklist.md`     | Asking an agent to audit API test coverage      |
| `ui-testing-best-practices.md` | Asking an agent to review UI test code          |

#### 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:

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

After configuring, the agent can:

```bash
# 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.
```

4. 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:

```yaml
# .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..