@codeceptjs/configure

What is @codeceptjs/configure?

@codeceptjs/configure is a utility package for configuring CodeceptJS, a popular end-to-end testing framework. It simplifies the process of setting up and managing configurations for CodeceptJS tests, allowing users to easily switch between different configurations and environments.

What are @codeceptjs/configure's main functionalities?

Set Configuration

This feature allows you to set configurations based on environment variables. In this example, the `setHeadlessWhen` function sets the browser to headless mode if the `HEADLESS` environment variable is true.

const { setHeadlessWhen } = require('@codeceptjs/configure');
setHeadlessWhen(process.env.HEADLESS);

Customize Configuration

This feature allows you to customize the window size for your tests. The `setWindowSize` function sets the browser window size to 1920x1080.

const { setWindowSize } = require('@codeceptjs/configure');
setWindowSize(1920, 1080);

Load Environment Variables

This feature allows you to load environment variables from a file. The `loadEnv` function loads environment variables from a `.env` file.

const { loadEnv } = require('@codeceptjs/configure');
loadEnv('.env');

Other packages similar to @codeceptjs/configure

dotenv

dotenv is a zero-dependency module that loads environment variables from a .env file into process.env. It is similar to the `loadEnv` feature of @codeceptjs/configure but does not provide other configuration utilities.

config

config is a configuration manager for Node.js applications. It allows you to define a set of default parameters and override them with environment-specific values. It provides more comprehensive configuration management compared to @codeceptjs/configure.

cross-env

cross-env allows you to set environment variables across different platforms. It is useful for setting environment variables in a way that works for both Windows and Unix-based systems. It is similar to the environment variable management features of @codeceptjs/configure.

README

CodeceptJS Configuration Hooks

Configuration hook helps you update CodeceptJS configuration at ease.

Those hooks are expected to simplify configuration for common use cases.

Requires CodeceptJS >= 2.3.3

Install it

npm i @codeceptjs/configure --save

How to use it

Better to see once.

Watch YouTube video

setHeadlessWhen

Toggle headless mode for Puppeteer, WebDriver, TestCafe, Nightmare and Playwright on condition.

Usage:

// in codecept.conf.js
const { setHeadlessWhen } = require('@codeceptjs/configure');

// enable headless when env var HEADLESS exists
// Use it like:
//
// export HEADLESS=true && npx codeceptjs run
setHeadlessWhen(process.env.HEADLESS); 

exports.config = {
  helpers: {
    // standard config goes here
    WebDriver: {} 
    // or Puppeteer
    // or TestCafe
  }
}

• For Puppeteer, TestCafe, Nigthmare, Playwright: it enables show: true.
• For WebDriver with Chrome browser: it adds --headless option to chrome options inside desiredCapabilities.

setHeadedWhen

Opposite to setHeadlessWhen. Forces window mode for running tests.

// in codecept.conf.js
const { setHeadlessWhen } = require('@codeceptjs/configure');

// enable window mode when env var DEV exists
// Use it like:
//
// export DEV=true && npx codeceptjs run
setHeadedWhen(process.env.DEV); 

setSharedCookies

Shares cookies between browser and REST/GraphQL helpers.

This hooks sets onRequest function for REST, GraphQL, ApiDataFactory, GraphQLDataFactory. This function obtains cookies from an active session in WebDriver or Puppeteer helpers.

// in codecept.conf.js
const { setSharedCookies } = require('@codeceptjs/configure');

// share cookies between browser helpers and REST/GraphQL
setSharedCookies();

exports.config = {
  helpers: {
    WebDriver: {
      // standard config goes here      
    } 
    // or Puppeteer
    // or TestCafe,
    REST: {
      // standard config goes here      
      // onRequest: <= will be set by hook
    },
    ApiDataFactory: {
      // standard config goes here
      // onRequest: <= will be set by hook
    }
  }
}

setBrowser

Changes browser in config for Playwright, Puppeteer, WebDriver, Protractor & TestCafe:

const { setBrowser } = require('@codeceptjs/configure');

setBrowser(process.env.BROWSER);

setWindowSize

Universal way to set a browser window size. For Puppeteer this launches Chrome browser with a specified width and height dimensions without changing viewport size.

Usage: setWindowSize(width, height).

// in codecept.conf.js
const { setWindowSize } = require('@codeceptjs/configure');

setWindowSize(1600, 1200);

exports.config = {
  helpers: {
    Puppeteer: {}
  }
}

Contributing

Please send your config hooks!

If you feel that codecept.conf.js becomes too complicated and you know how to make it simpler, send a pull request with a config hook to solve your case.

Good ideas for config hooks:

• Setting the same window size for all browser helpers.
• Configuring run-multiple
• Changing browser in WebDriver or Protractor depending on environment variable.

To create a custom hook follow this rules.

1. Create a file starting with prefix use in hooks directory.
2. Create a js module that exports a function.
3. Require config object from codeceptjs package.
4. Use config.addHook((config) => {}) to set a hook for configuration
5. Add a test to index_test.js
6. Run mocha index_test.js

See current hooks as examples.