End to end testing with NodeJS using CodeceptJS with real world example— Part 1 : Understanding the basics

CodeceptJS is a modern end to end testing framework with a special BDD-style syntax. The tests are written as a linear scenario of the user’s action on a site.

Understanding the Architecture

CodeceptJS is a javascript wrapper around different automation frameworks for both Web & Mobile Testing.

Web Testing:

  • WebDriverIO — Next-gen browser and mobile automation test framework for Node.js.
  • Protractor — end to end testing for Angular
  • Nightmare — A high-level browser automation library for automating Electron apps.
  • Playwright — Node.js library to automate Chromium, Firefox and WebKit with a single API
  • Puppeteer — Puppeteer is a Node library which provides a high-level API to control Chrome or Chromium over the DevTools Protocol.

Mobile Testing:

  • Appium — Appium is an open source test automation framework for use with native, hybrid and mobile web apps.
  • Detox — Gray box end-to-end testing and automation framework for mobile apps (by Wix)

Hence you have access to all the above mentioned frameworks, in a single stable implementation.

Installing CodeceptJS

Please refer this link for detailed installation guide.

CodeceptJS requires Node 12+ versions to work.

Open a directory where you want to install CodeceptJS tests. If it is an empty directory — create a new NPM package with

npm init -y

Install CodeceptJS with NPM:

npx codeceptjs init
  • Please choose Puppeteer when asked for choosing the helpers. (We will explore each and every driver in the upcoming chapters).
  • Press ENTER for all the other options in the wizard.

Understanding the directory Structure


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

Here is an overview of some of the available options with their defaults:

  • tests: "./*_test.js" - pattern to locate tests. Allows to enter glob pattern
  • grep: — pattern to filter tests by name
  • include: {} - actors and page objects to be registered in DI container and included in tests. Accepts objects and module require paths
  • timeout: 10000 - default tests timeout
  • output: "./output" - where to store failure screenshots, etc
  • helpers: {} - list of enabled helpers
  • multiple: {} - multiple options, see Multiple Execution
  • bootstrap: "./bootstrap.js" - an option to run code before tests are run. See Hooks
  • require: [] - array of module names to be required before codecept starts. See Require

It’s okay. We will see most of them with their practical uses.


This is the file where you write your tests.


During initialization you were asked to create a custom steps file. If you accepted this option, you are now able to use the custom_steps.js file to extend I. See how the login method can be added to I:

module.exports = function() {
return actor({

login: function(email, password) {
this.fillField('Email', email);
this.fillField('Password', password);


This file has nothing to do with the codeceptJS Project. It helps you configure the javascript settings for your project.

The presence of jsconfig.json file in a directory indicates that the directory is the root of a JavaScript Project. The jsconfig.json file specifies the root files and the options for the features provided by the JavaScript language service like linting for example.

Refer this link for all the different kind of configurations available.

Make an observation 💡

  1. If you go to codecept.conf.js , you will see that codecept has added Puppeteer in the helpers object. This happens as we provided puppeteer as our helper during the installation wizard.

Enable IntelliSense in VS Code for CodeceptJS

To get autocompletion when working with CodeceptJS, use Visual Studio Code or another IDE that supports TypeScript Definitions.

Generate step definitions with:

npx codeceptjs def

Create a file called jsconfig.json in your project root directory, unless you already have one.

"compilerOptions": {
"allowJs": true,

Writing our first test

As we have choosen Puppeteer as our default helper, the tests will use Puppeteer as their underlying tool to automate the browser. Puppeteer by default uses chromium as the browser to automate, and if you observed, it automatically downloaded the chromium browser when setting up the project.

Nagivate to _test.js and add the following code to the file.

Feature('Google Landing Page');Scenario('Open Google', ({ I }) => {   I.amOnPage('https://google.com'); // opens google.com

Execute the test using the following command

npx codeceptjs run

This runs all tests from current directory. You should be able to see the test case execution in chromium web browser, and see the test case as passed.

To see the list of all available commands for Puppeteer, fire the following command

npx codeceptjs listTiT

Congratulations🎉🎉. You just executed your first test case using CodeceptJS & Puppeteer.

The code can be found here at this repository 🐱

See you in the next article, where we learn about different locators strategies, wait strategies, different web operations available for automation and much more.




M.S in Human Centered Computing @ UMBC

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Intro to Basic React Hooks (useState and useEffect)

Skeleton UI in jetpack compose, the lost design

Where do we use cy.wrap() command in Cypress Test

The simplest way to get started with WebAssembly

Top 10 Useful JavaScript Functions You Need to Know as a Developer

How We Boosted the Performance of Our React Native App

Imperative vs Declarative in JavaScript

How to resize the image as base64 in asp.net core

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
shivam gohel

shivam gohel

M.S in Human Centered Computing @ UMBC

More from Medium

CodeBuild: Automated tests using Cypress

The art of Cypress optimization: Boost test run time with parallelization strategy + GitLab

Git: Basic Functionalities and Its Application In PPL

Testing: A Sometimes Tedious but Crucial Part of Software Development