CodeceptJS provides API to run custom code before and after the test and inject custom listeners into the event system.

Bootstrap & Teardown

In case you need to execute arbitrary code before or after the tests, you can use bootstrap and teardown config. Use it to start and stop webserver, Selenium, etc.

When using the Multiple Execution mode , there are two additional hooks available; bootstrapAll and teardownAll. These hooks are only called once each; before all of the test suites are run (bootstrapAll) and after all of the test suites have finished (teardownAll).

There are different ways to define bootstrap and teardown functions:

Corresponding examples provided in next sections.

Example: Async Bootstrap in a Function

Add to codecept.json:

"bootstrap": "./run_server.js"

Export a function in your bootstrap file:

// bootstrap.js
var server = require('./app_server');
module.exports = function(done) {
  // on error call done('error description') to stop
  if (!server.validateConfig()) {
    done("Can't execute server with invalid config, tests stopped");
  // call done() to continue execution

Example: Async Teardown in a Function

Stopping a server from a previous example can be done in a similar manner. Create a teardown file and add it to codecept.json:

"teardown": "./stop_server.js"

Inside stop_server.js:

var server = require('./app_server');
module.exports = function(done) {

Example: Bootstrap & Teardown Inside an Object

Examples above can be combined into one file.

Add to config (codecept.json):

  "bootstrap": "./server.js"
  "teardown": "./server.js"

server.js should export object with bootstrap and teardown functions:

// bootstrap.js
var server = require('./app_server');
module.exports = {
  bootstrap: function(done) {
  teardown: function(done) {

Example: Bootstrap & Teardown Inside Config

If you are using JavaScript-style config codecept.conf.js, bootstrap and teardown functions can be placed inside of it:

var server = require('./app_server');

exports.config = {
  tests: "./*_test.js",
  helpers: {},

  // adding bootstrap/teardown
  bootstrap: function(done) {
  teardown: function(done) {
  // ...
  // other config options

Example: BootstrapAll & TeardownAll Inside Config

Using JavaScript-style config codecept.conf.js, bootstrapAll and teardownAll functions can be placed inside of it:

const fs = require('fs');
const tempFolder = process.cwd() + '/tmpFolder';

exports.config = {
  tests: "./*_test.js",
  helpers: {},

  multiple: {
    suite1: {
      grep: '@suite1',
      browsers: [ 'chrome', 'firefox' ],
    suite2: {
      grep: '@suite2',
      browsers: [ 'chrome' ],

  // adding bootstrapAll/teardownAll
  bootstrapAll: function(done) {
    fs.mkdir(tempFolder, (err) => {
      console.log('Create a temp folder before all test suites start', err);

  bootstrap: function(done) {
    console.log('Do some pretty suite setup stuff');
    done(); // Don't forget to call done()

  teardown: function(done) {
    console.log('Cool, one of the test suites have finished');

  teardownAll: function(done) {
    console.log('All suites are now done so we should clean up the temp folder');

    fs.rmdir(tempFolder, (err) => {
      console.log('Ok, now I am done', err);

  // ...
  // other config options

Note: The bootstrapAll and teardownAll hooks are only called when using Multiple Execution.


Plugins allow to use CodeceptJS internal API to extend functionality. Use internal event dispatcher, container, output, promise recorder, to create your own reporters, test listeners, etc.

CodeceptJS includes built-in plugins which extend basic functionality and can be turned on and off on purpose. Taking them as examples you can develop your custom plugins.

A plugin is a basic JS module returning a function. Plugins can have individual configs which are passed into this function:

const defaultConfig = {
  someDefaultOption: true

module.exports = function(config) {
  config = Object.assign(defaultConfig, config);
  // do stuff

Plugin can register event listeners or hook into promise chain with recorder. See API reference.

To enable your custom plugin in config add it to plugins section. Specify path to node module using require.

"plugins": {
  "myPlugin": {
    "require": "./path/to/my/module",
    "enabled": true

If a plugin is disabled (enabled is not set or false) this plugin can be enabled from command line:

./node_modules/.bin/codeceptjs run --plugin myPlugin

Several plugins can be enabled as well:

./node_modules/.bin/codeceptjs run --plugin myPlugin,allure

Custom Hooks

(deprecated, use plugins)

Hooks are JavaScript files same as for bootstrap and teardown, which can be registered inside hooks section of config. Unlike bootstrap you can have multiple hooks registered:

"hooks": [

Inside those JS files you can use CodeceptJS API (see below) to access its internals.


Use local CodeceptJS installation to get access to codeceptjs module

CodeceptJS provides an API which can be loaded via require('codeceptjs') when CodeceptJS is installed locally. These internal objects are available:

API reference is available on GitHub. Also please check the source code of corresponding modules.

Event Listeners

CodeceptJS provides a module with event dispatcher and set of predefined events.

It can be required from codeceptjs package if it is installed locally.

const event = require('codeceptjs').event;

module.exports = function() {

  event.dispatcher.on(event.test.before, function (test) {

    console.log('--- I am before test --');


Available events:

For further reference look for currently available listeners using event system.

Test Object

Test events provide a test object with following fields:

and others

Step Object

Step events provide step objects with following fields:


To inject asynchronous functions in a test or before/after a test you can subscribe to corresponding event and register a function inside a recorder object. Recorder represents a global promises chain.

Provide a function description as a first parameter, function should return a promise:

const event = require('codeceptjs').event;
const recorder = require('codeceptjs').recorder;
module.exports = function() {

  event.dispatcher.on(event.test.before, function (test) {

    const request = require('request');

    recorder.add('create fixture data via API', function() {
      return new Promise((doneFn, errFn) => {
          baseUrl: 'http://api.site.com/',
          method: 'POST',
          url: '/users',
          json: { name: 'john', email: '[email protected]' }
        }), (err, httpResponse, body) => {
          if (err) return errFn(err);

Whenever you execute tests with --verbose option you will see registered events and promises executed by a recorder.


Output module provides 4 verbosity levels. Depending on the mode you can have different information printed using corresponding functions.

It is recommended to avoid console.log and use output.* methods for printing.

const output = require('codeceptjs').output;

output.print('This is basic information');
output.debug('This is debug information');
output.log('This is verbose logging information');


CodeceptJS has a dependency injection container with Helpers and Support objects. They can be retrieved from the container:

let container = require('codeceptjs').container;

// get object with all helpers
let helpers = container.helpers();

// get helper by name
let WebDriverIO = container.helpers('WebDriverIO');

// get support objects
let support = container.support();

// get support object by name
let UserPage = container.support('UserPage');

// get all registered plugins
let plugins = container.plugins();

New objects can also be added to container in runtime:

let container = require('codeceptjs').container;

  helpers: { // add helper
    MyHelper: new MyHelper({ config1: 'val1' });
  support: { // add page object
    UserPage: require('./pages/user');

Container also contains current Mocha instance:

let mocha = container.mocha();


CodeceptJS config can be accessed from require('codeceptjs').config.get():

let config = require('codeceptjs').config.get();

if (config.myKey == 'value') {
  // run hook

Custom Runner

CodeceptJS can be imported and used in custom runners. To initialize Codecept you need to create Config and Container objects.

let Container = require('codeceptjs').container;
let Codecept = require('codeceptjs').codecept;

let config = { helpers: { WebDriverIO: { browser: 'chrome', url: 'http://localhost' } } };
let opts = { steps: true };

// create runner
let codecept = new Codecept(config, opts);

// initialize codeceptjs in current dir

// create helpers, support files, mocha
Container.create(config, opts);

// initialize listeners

// load tests

// run tests

In this way Codecept runner class can be extended.