Configuration

CodeceptJS configuration is set in codecept.conf.js file.

After running codeceptjs init it should be saved in test root.

Name	Type	Description
bootstrap?	(() => Promise<void>) | boolean | string	Execute code before tests are run. Can be either JS module file or async function: bootstrap: async () => server.launch(), or bootstrap: 'bootstrap.js',
bootstrapAll?	(() => Promise<void>) | boolean | string	Execute code before launching tests in parallel mode
gherkin?	{ features: string | string[] ; steps: string[] }	Enable BDD features. Sample configuration: gherkin: { features: "./features/*.feature", steps: ["./step_definitions/steps.js"] }
gherkin.features	string | string[]	load feature files by pattern. Multiple patterns can be specified as array
gherkin.steps	string[]	load step definitions from JS files
grep?	string	Pattern to filter tests by name. This option is useful if you plan to use multiple configs for different environments. To execute only tests with @firefox tag use grep: '@firefox'
helpers?	{}	Enable and configure helpers: helpers: { Playwright: { url: 'https://mysite.com', browser: 'firefox' } }
include?	any	Include page objects to access them via dependency injection I: "./custom_steps.js", loginPage: "./pages/Login.js", User: "./pages/User.js", Configured modules can be injected by name in a Scenario: Scenario('test', { I, loginPage, User })
mocha?	any	Mocha test runner options, additional reporters can be configured here. Example: mocha: { "mocha-junit-reporter": { stdout: "./output/console.log", options: { mochaFile: "./output/result.xml", attachments: true //add screenshot for a failed test } } }
noGlobals?	boolean	Disable registering global functions (Before, Scenario, etc). Not recommended
output	string	Where to store failure screenshots, artifacts, etc output: './output'
plugins?	any	Enable CodeceptJS plugins. Example: plugins: { autoDelay: { enabled: true } }
require?	string[]	Require additional JS modules Example: require: ["should"]
teardown?	(() => Promise<void>) | boolean | string	Execute code after tests finished. Can be either JS module file or async function: teardown: async () => server.stop(), or teardown: 'teardown.js',
teardownAll?	(() => Promise<void>) | boolean | string	Execute JS code after finishing tests in parallel mode
tests	string	Pattern to locate CodeceptJS tests. Allows to enter glob pattern or an Array of patterns to match tests / test file names. For tests in JavaScript: tests: 'tests/**.test.js' For tests in TypeScript: tests: 'tests/**.test.ts'
timeout?	number	Set default tests timeout in seconds. Tests will be killed on no response after timeout. timeout: 20,
translation?	string	Enable localized test commands
maskSensitiveData?	boolean	Enable to mask Sensitive Data in console.

Require

Requires modules before running tests. This is useful for:

• Assertion libraries: e.g., 'should' instead of manually requiring it in each test
• TypeScript loaders: Enable TypeScript test files in ESM or CommonJS projects
• Setup modules: Initialize testing environment
• Custom modules: With relative paths like "require": ["./lib/setup"]

TypeScript Support

For ESM Projects (CodeceptJS 4.x)

Use modern loaders that support ES Modules:

Using tsx (recommended - fast, zero config):

codecept.conf.ts

export const config = {
  tests: './**/*_test.ts',
  require: ['tsx/cjs'],  // ← Modern TypeScript loader
  helpers: {},
  include: {},
}

Using ts-node/esm:

codecept.conf.ts

export const config = {
  tests: './**/*_test.ts',
  require: ['ts-node/esm'],  // ← Established TypeScript loader
  helpers: {},
  include: {},
}

Note: For ts-node/esm, you need a tsconfig.json with ESM configuration. See TypeScript documentation for details.

For CommonJS Projects (CodeceptJS 3.x)

Use the CommonJS loader:

codecept.conf.js

exports.config = {
  tests: './*_test.ts',
  require: ['ts-node/register'],  // ← CommonJS TypeScript loader
  helpers: {},
  include: {},
}

Multiple Requires

You can combine multiple modules:

codecept.conf.ts

export const config = {
  tests: ['./**/*_test.ts', './smoke_test.ts'],
  require: [
    'tsx/cjs',           // TypeScript loader
    'should',            // Assertion library
    './lib/testSetup'    // Custom setup
  ],
  helpers: {},
  include: {},
}

Modules are loaded in the order specified, before any tests run.

Dynamic Configuration

By default codecept.json is used for configuration. You can override its values in runtime by using --override or -o option in command line, passing valid JSON as a value:

codeceptjs run -o '{ "helpers": {"WebDriver": {"browser": "firefox"}}}'

You can also switch to JS configuration format for more dynamic options. Create codecept.conf.js file and make it export config property.

See the config example:

export const config = {
  helpers: {
    WebDriver: {
      // load variables from the environment and provide defaults
      url: process.env.CODECEPT_URL || 'http://localhost:3000',

      user: process.env.CLOUDSERVICE_USER,
      key: process.env.CLOUDSERVICE_KEY,

      coloredLogs: true,
      waitForTimeout: 10000,
    },
  },

  // don't build monolithic configs
  mocha: require('./mocha.conf.js') || {},
  include: {
    I: './src/steps_file.js',
    loginPage: './src/pages/login_page',
    dashboardPage: new DashboardPage(),
  },

  // here goes config as it was in codecept.conf.ts
  // ....
}

(Don’t copy-paste this config, it’s just demo)

If you prefer to store your configuration files in a different location, or with a different name, you can do that with --config or `-c:

codeceptjs run --config=./path/to/my/config.js

Common Configuration Patterns

📺 Watch this material on YouTube

@codeceptjs/configure ships with CodeceptJS as a dependency and contains shared recipes for common configuration patterns. It lets you set meta-configuration that’s independent of the active helper.

Toggle headless/headed mode, change window size, etc.:

import { setHeadlessWhen, setWindowSize } from '@codeceptjs/configure'

setHeadlessWhen(process.env.CI)
setWindowSize(1600, 1200)

export const config = {
  // ...
}

For one-shot bundles use setBrowserConfig — pass any subset of { browser, show, windowSize, url, ... } and the right per-helper translation happens automatically (Puppeteer receives product for browser, WebDriver gets --headless injected, etc.). Keys whose value is undefined are skipped, so unset env vars don’t clobber existing config:

import { setBrowserConfig } from '@codeceptjs/configure'

setBrowserConfig({
  browser: process.env.BROWSER,        // optional engine override
  show: !process.env.HEADLESS,         // headed unless HEADLESS is set
  windowSize: '1280x720',
  url: process.env.URL,                // overrides helper.url when set
})

setCommonPlugins() enables a curated set of plugins and registers a few more as discoverable (so they can be activated ad-hoc via -p plugin arguments without editing config):

import { setCommonPlugins } from '@codeceptjs/configure'

setCommonPlugins()

Plugin	Default	Notes
retryFailedStep	enabled	Retry steps that fail with transient errors
screenshot	enabled	Screenshot on fail (default) / test / step / file / url
pause	registered	Pause on failure / step / file / URL — -p pause:on=fail, -p pause:on=step, -p pause:on=file:path=tests/login_test.js, -p pause:on=url:pattern=/checkout/*
browser	registered	CLI overrides for browser helpers — -p browser:show, -p browser:browser=firefox, see commands
aiTrace	registered	Capture AI traces — -p aiTrace, narrow with `on=fail
heal	registered	Self-heal failing steps — -p heal, narrow with `on=file

eachElement, tryTo, and retryTo are no longer plugins in 4.x — import them from codeceptjs/effects.

Profile

Using process.env.profile you can change the config dynamically. It provides value of --profile option passed to runner. Use its value to change config value on the fly.

For instance, with the config above we can change browser value using profile option

codeceptjs run --profile firefox

export const config = {
  helpers: {
    WebDriver: {
      url: 'http://localhost:3000',
      // load value from `profile`
      browser: process.env.profile || 'firefox',
    },
  },
}