my-cypress-automation-framework v1.0.0

My Cypress Automation Framework

Overview

An advanced Cypress framework designed with scalability and maintainability in mind, utilizing the Page Object Model (POM) and Screen Object Model (SOM).

Features

• Page Object Model (POM): Organize page interactions in a clean, reusable manner.
• Screen Object Model (SOM): Combine multiple actions for complex workflows.
• Utilities: Built-in utility functions to handle common tasks.
• Custom Commands: Extend Cypress with reusable commands.

Installation

Install the framework via npm:

npm install my-cypress-automation-framework --save-dev

Project Structure

The framework is organized as follows

project-root/
│
├── cypress/
│   ├── downloads/                # Directory for downloaded files during tests
│   │   
│   ├── e2e/                      # Test files organized by feature
│   │   ├── authentication/
│   │   │   ├── loginPage.cy.ts   # Test cases for login feature
│   │   │
│   │   ├── dashboard/
│   │       ├── dashboardPage.cy.ts # Test cases for dashboard feature
│   │   
│   ├── pages/                    # Page Object Model (POM) files
│   │   ├── authentication/
│   │   │   ├── LoginPage.ts      # Login page object with element locators and actions
│   │   │
│   │   ├── dashboard/
│   │       ├── DashboardPage.ts  # Dashboard page object
│   │   
│   ├── screens/                  # Screen Object Model (SOM) files
│   │   ├── authentication/
│   │   │   ├── LoginScreen.ts    # Login screen actions combining multiple page actions
│   │   │
│   │   ├── dashboard/
│   │       ├── DashboardScreen.ts # Dashboard screen actions
│   │   
│   ├── support/                  # Cypress support files
│   │   ├── commands.ts           # Custom Cypress commands
│   │   ├── e2e.ts                # Global configurations and imports for Cypress
│   │   ├── utils.ts              # Utility functions used across tests
│   │   └── index.ts              # Main entry point for support file imports
│   │
│   ├── tsconfig.json             # TypeScript configuration file
│   └── cypress.config.ts         # Cypress configuration file
│
├── node_modules/                 # Node.js modules
├── package.json                  # Project dependencies and scripts
├── package-lock.json             # Dependency lock file
└── README.md                     # Project documentation

Usage

Writing Tests

Place your tests in the cypress/e2e/ directory. Here's an example test:

import { LoginScreen } from '../../screens/authentication/LoginScreen';
import { DashboardScreen } from '../../screens/dashboard/DashboardScreen';

describe('Login Tests', () => {
  const loginScreen = new LoginScreen();
  const dashboardScreen = new DashboardScreen();

  it('should login successfully with valid credentials', () => {
    loginScreen.login('testuser', 'testpassword');
    dashboardScreen.verifyWelcomeMessage('Welcome, testuser!');
  });
});

Page Objects

Define page objects in the cypress/pages/ directory. For example, the LoginPage.ts file:

export class LoginPage {
    private usernameInput = "//input[@id='empCode']";
    private passwordInput = 'input[name="password"]';
    private submitButton = 'button[type="submit"]';
  
    visit() {
      cy.visit('/login');
    }
  
    enterUsername(username: string) {
      cy.xpath(this.usernameInput).type(username);
    }
  
    enterPassword(password: string) {
      cy.get(this.passwordInput).type(password);
    }
  
    submit() {
      cy.get(this.submitButton).click();
    }
  }

Screen Objects

Screen objects combine actions from different page objects. Place them in the cypress/screens/ directory. For example:

import { LoginPage } from '../../pages/authentication/LoginPage';

export class LoginScreen {
  private loginPage: LoginPage = new LoginPage();

  login(username: string, password: string) {
    this.loginPage.visit();
    this.loginPage.enterUsername(username);
    this.loginPage.enterPassword(password);
    this.loginPage.submit();
  }
}

Utilities

Utility functions are stored in cypress/support/utils.ts. These functions can be reused across tests:

export const generateRandomEmail = (): string => {
  const randomStr = Math.random().toString(36).substring(7);
  return `testuser_${randomStr}@example.com`;
};

Custom Commands

You can define custom Cypress commands in cypress/support/commands.ts. For example:

Cypress.Commands.add('login', (username, password) => {
  cy.visit('/login')
    .get('input[name=username]').type(username)
    .get('input[name=password]').type(password)
    .get('button[type=submit]').click();
});

Running the Tests

To run the tests, use the following command:

npx cypress open

For headless test execution:

npx cypress run

Configuration

Modify the cypress.config.ts file to change the base URL, viewport size, or other configuration settings:

import { defineConfig } from 'cypress';
import * as fs from 'fs';

export default defineConfig({
  viewportWidth: 1600,
  viewportHeight: 1080,
  video: true,
  videoCompression: true,
  retries: 0,
  defaultCommandTimeout: 5000,
  execTimeout: 60000,
  pageLoadTimeout: 30000,
  requestTimeout: 10000,
  responseTimeout: 15000,
  watchForFileChanges: true,
  reporter: 'cypress-mochawesome-reporter',
  e2e: {
    experimentalRunAllSpecs: false,
    chromeWebSecurity: false,
    setupNodeEvents(on, config) {
      const env = 'dev'; // default to 'dev'
      const configFilePath = `./cypress/config.json`;
      // Read the config file
      const configFile = JSON.parse(fs.readFileSync(configFilePath, 'utf8'));
      // Set the config file data as environment variables
      config.env = {
        url: configFile['url'][env],
        credentials: configFile['credentials'],
        resolution: [1600, 1080]
      };      
      // Initialize the plugins
      require('cypress-mochawesome-reporter/plugin')(on);
      require('cypress-high-resolution')(on, config);
      // Return the updated config object
      return config;
    }
  }
});

Contributing

Contributions are welcome! Please submit a pull request or open an issue if you find a bug or want to add new features.

License

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

Summary of the README

• Introduction: Provides an overview of the framework and its key features.
• Installation: Explains how to install the framework.
• Project Structure: Describes the layout of the framework and where to place files.
• Usage: Guides users on how to write tests, define page objects, screen objects, utilities, and custom commands.
• Running Tests: Instructions on how to execute the tests.
• Configuration: Details how to customize the Cypress configuration.
• Contributing: Encourages contributions and explains how to contribute.
• License: Specifies the license under which the framework is distributed.

This README is designed to be comprehensive and informative, making it easy for users to get started with your Cypress framework.