e2e-codeceptjs-boilerplate

A comprehensive end-to-end testing framework using CodeceptJS and Playwright, with support for BDD, Cucumber, and Allure reporting.

View project on GitHub

🚀 Automation Framework with CodeceptJS, Playwright, and CucumberJS

Automation Framework

Under Development Playwright CodeceptJS CucumberJS Node NPM

Dependencies

Axios Chai ExcelJS Import-Export Mongoose Puppeteer-Core

Dev Dependencies

Allure-Legacy Types-Node Allure-Commandline Allure-Playwright BrowserLogs-Plugin Debug Moment ESLint

Available Scripts

  • Run Tests: npm run test:run - Run the tests with debugging.
  • Serve Allure Report: npm run test:report-serve - Serve the Allure report.
  • Debug Tests: npm run test:debug - Run tests with the @debug tag.
  • Generate Allure Report: npm run test:report-generate - Generate the Allure report.
  • Run E2E Tests: npm run test:e2e - Run end-to-end tests.
  • Run Parallel Tests: npm run test:parallel - Run tests in parallel.
  • Open Allure Report: npm run test:report-open - Open the generated Allure report.

📖 Table of Contents

Introduction

Welcome to the Automation Framework, a powerful, scalable, and customizable solution built using CodeceptJS, Playwright, and CucumberJS. This framework is designed to streamline the process of end-to-end (E2E) testing for web applications, enabling seamless integration, robust testing, and detailed reporting.

Prerequisites

Before setting up the framework, ensure you have the following installed on your local machine:

  • Node.js: Version 14.x or higher (Recommended: >= 20.16.0).
  • NPM: Version 6.x or higher (Recommended: >= 10.8.1).
  • Git: For version control and to clone the repository.

To verify that these are installed correctly, run the following commands:

node -v
npm -v
git --version

Project Setup

Cloning the Repository

Start by cloning the repository to your local machine. This will allow you to have a copy of the project that you can work on.

git clone https://github.com/hexdee606/e2e-codeceptjs-boilerplate.git
cd e2e-codeceptjs-boilerplate

Installing Dependencies

Next, install all the necessary dependencies required by the project. This includes CodeceptJS, Playwright, CucumberJS, and other supporting libraries.

npm install

Configuring Playwright

After installing the dependencies, you need to configure Playwright by installing the required browser binaries. This step ensures that Playwright can run tests across different browsers.

npx playwright install

Configuration

Overview of Configuration Files

This framework is highly configurable. Below is a brief overview of the key configuration files:

  • codecept.conf.js: Main configuration file for CodeceptJS, including helper settings and plugins.
  • playwright.conf.js: Configuration for Playwright, defining browser settings.
  • env.conf.js: Environment-specific configurations like URLs and API endpoints.
  • plugins.conf.js: Configuration for various plugins used in the framework.
  • global.variables.conf.js: Defines global variables that are accessible throughout the tests.

CodeceptJS Configuration

The central configuration file, codecept.conf.js, is where you define the test settings, helpers, plugins, and other global configurations.

exports.config = {
  output: './outputs',
  helpers: {
    Playwright: require('./config/playwright.conf'),
    REST: require('./config/rest.conf'),
    GraphQL: require('./config/graphql.conf'),
    FileSystem: {}
  },
  include: require('./config/include.conf'),
  mocha: require('./config/mocha.conf'),
  bootstrap: null,
  plugins: require('./config/plugins.conf'),
  timeout: 15000,
  gherkin: require('./config/gherkin.conf'),
  stepTimeout: 5000,
  retryFailedStep: {
    enabled: true,
    retries: 2
  },
  multiple: require('./config/multiple.conf'),
  name: 'automation-framework'
};

This file includes all the necessary configurations for CodeceptJS, such as the directories for outputs, the helpers you’re using, and plugin configurations.

Playwright Configuration

Located in config/playwright.conf.js, this file contains browser settings like headless mode, browser type, and timeouts. Playwright enables testing across Chromium, Firefox, and WebKit.

module.exports = {
  url: 'http://localhost',
  show: false, // Set to true to show the browser during testing
  browser: 'chromium', // Can be 'chromium', 'firefox', 'webkit'
  waitForTimeout: 15000, // Default wait time
  restart: true, // Restart the browser between tests
  windowSize: '1280x1024'
};

This file controls how Playwright interacts with the browsers. You can adjust settings to run tests in headless mode or with a visible browser window.

Environment Configuration

The env.conf.js file defines environment-specific configurations like URLs for different environments (e.g., development, staging, production).

const envConf = {
  'env': process.env.E2E_ENV || 'int',
  'int': {
    'web': {
      host_url: 'https://automationexercise.com'
    },
    'restApi': {
      end_point: 'https://petstore.swagger.io/v2'
    },
    'gql': {
      end_point: 'https://graphqlzero.almansi.me/api'
    }
  }
};

module.exports = envConf;

This setup allows you to easily switch environments by changing the E2E_ENV variable, making it easy to run tests against different environments without modifying the code.

Plugins Configuration

The plugins used in this framework enhance functionality like reporting, retrying failed steps, and capturing screenshots. The plugins.conf.js file configures these plugins.

module.exports = {
  allure: {
    enabled: true,
    outputDir: './outputs/allure-results',
    require: '@codeceptjs/allure-legacy'
  },
  retryFailedStep: {
    enabled: true,
    retries: 3
  },
  stepByStepReport: {
    enabled: true,
    screenshotsForAllFailures: true,
    onFail: true
  },
  screenshotOnFail: {
    enabled: true,
    path: './outputs/screenshots',
    fullPage: true,
    uniqueNames: true,
    keepSuccessfulScreenshots: false,
    quality: 80,
    format: 'png'
  },
  BrowserLogsOnFail: {
    enabled: true,
    uniqueNames: true,
    require: 'codeceptjs-browserlogs-plugin',
    path: './outputs/logs',
    includeConsoleLog: true,
    includeNetworkLog: true,
    includeErrorLog: true,
    logFormat: 'json',
    maxLogEntries: 1000,
    filterLogTypes: ['error', 'warn']
  }
};

This file allows you to configure how and when reports, screenshots, and logs are generated, and which plugins are active.

Global Variables Configuration

The global.variables.conf.js file defines global variables that can be accessed throughout your tests. This is especially useful for defining reusable constants, URLs, or utility functions that are needed across multiple test cases.

global.api_helper = require("../custom_helpers/api_helper");
global.browser_storage_utils = require("../custom_helpers/browser_storage_utils");
global.common_codeceptjs_utils = require("../custom_helpers/common_codeceptjs_utils");
global.common_utils = require("../custom_helpers/common_utils");
global.excel_utils = require("../custom_helpers/excel_utils");
global.graphql_helper = require("../custom_helpers/graphql_helper");
global.keyboard_utils = require("../custom_helpers/keyboard_utils");
global.strings_data = require("../custom_helpers/strings_data");
global.test_data = require("../custom_helpers/test_data");
global.variables = require("../custom_helpers/variables");

This configuration imports various custom helper modules, making them globally available in your test scripts. This eliminates the need for repeated imports and promotes code reusability.

Step Definitions and Support Files

The include.conf.js file is where you configure the paths to your step definitions and support files:

module.exports = {
  I: './steps_file.js',
  page: './src/pages/*_page.js',
};

This file tells CodeceptJS where to find the step definitions (steps_file.js) and page objects (*_page.js). Step definitions contain the implementation of the steps written in your Gherkin files, while page objects encapsulate page-specific actions.

Custom Helpers

Custom helpers in this framework extend CodeceptJS with additional functionalities. These helpers are located in the custom_helpers/ directory.

Example: API Helper

The api_helper.js file provides a set of functions to handle API interactions, making it easier to send GET, POST, PUT, DELETE requests from your tests.

class ApiHelper extends Helper {
  async sendGetRequest(endpoint, headers = {}) {
    const I = actor();
    return I.sendGetRequest(endpoint, headers);
  }
}

This helper centralizes all API-related methods, ensuring that your test code remains clean and focused on the logic rather than the specifics of HTTP requests.

Example: Browser Storage Utils

The browser_storage_utils.js file provides utility functions for interacting with browser storage (localStorage and sessionStorage).

class BrowserStorageUtils extends Helper {
  async getLocalStorageKeysAndValues() {
    return await I.executeScript(() => {
      const localStorageData = {};
      for (let i = 0; i < localStorage.length; i++) {
        const key = localStorage.key(i);
        const value = localStorage.getItem(key);
        localStorageData[key] = value;
      }
      return localStorageData;
    });
  }
}

This helper allows you to programmatically interact with browser storage during your tests, enabling you to verify that the correct data is being stored or retrieved.

Running Tests

Running Tests Locally

You can run all tests locally using the default command:

npm test

This will execute all test scenarios defined in your project.

Running in Headless Mode

To run tests in headless mode (without opening a browser window):

npm run test:headless

This is useful for running tests in CI/CD pipelines or when you don’t need to see the browser’s UI.

Parallel Test Execution

You can configure and run tests in parallel across multiple browsers or environments by leveraging the multiple configuration:

npm run test:parallel

This reduces test execution time significantly by running tests concurrently.

Test Reporting

Mochawesome Reports

Mochawesome generates HTML and JSON reports that provide a detailed view of test results.

  • Generate Reports: 
    npm run generate-mochawesome-report

Allure Reports

Allure offers a comprehensive and interactive reporting tool, perfect for tracking test trends and history.

  • Generate Allure Reports: 
    npm run generate-allure-report-with-history
  • View Allure Reports: 
    npm run open-allure-report

Debugging and Troubleshooting

Enabling Debug Mode

Debugging is essential for identifying issues in your tests. Enable debug mode by running:

DEBUG=* npm test

This will provide detailed logs during test execution.

Screenshots on Failure

The framework is configured to capture screenshots whenever a test fails. These are saved in the ./outputs/screenshots/ directory.

Capturing Browser Logs

Browser logs are automatically captured for failed tests, providing insights into console errors, network issues, and more. Logs are stored in ./outputs/logs/.

Contributing

We welcome contributions from the community! Please follow our Contributing Guidelines to get started. Whether it’s a bug fix, new feature, or documentation improvement, your help is appreciated.

Code of Conduct

We enforce a strict Code of Conduct to ensure a welcoming and inclusive environment for all contributors. Please familiarize yourself with it before participating in this project.

Support

For any support or inquiries, feel free to reach out via email at hexdee606@gmail.com. We strive to respond to all queries within 24-48 hours.

License

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