Writing Tests with CodeceptJS & Nightmare

   Quality Assurance
Writing Tests with CodeceptJS & Nightmare

There are plenty of test automation tools available for a project. Most give you the ability to combine frameworks together to better suit your needs. Because there are so many different options and combinations of testing tools and libraries, it may be difficult finding something to get started with. To help with that, let’s take a look at one such combination for testing: CodeceptJS and Nightmare – a framework and integrated library that make it simple to create fast, scalable acceptance tests for any project.


Nightmare is a library for browser automation and is used as a web crawler as well as a means for UI testing. It uses Electron under the hood and can be considered as the newer, faster version of PhantomJS. Nightmare can run tests in both headless mode and in a window for debugging and because it doesn’t rely on drivers like Selenium, it’s incredibly fast.

It has a simple API and incorporates the same actions engineers are most familiar with like .goto(url[, headers]) and .check(selector). A test written with Nightmare looks like this:

Writing Tests with CodeceptJS & Nightmare, Example
*Example provided in project repo

You can also incorporate a more BDD-like structure for your tests by using Mocha and Chai assertions with the Nightmare library.

Writing Tests with CodeceptJS & Nightmare, BDD-like structure with Mocha and Chai
*Example provided in project repo

Nightmare provides a simple library for writing UI tests as it’s fast and well-documented. However, it may not offer some of the same flexibility testers are used to with Selenium as it’s just a library and not a full test framework. Thankfully, there are options to further extend your Nightmare tests.


CodeceptJS is a tool for writing acceptance tests. It focuses on test scenarios and the user’s perspective. It supports mobile testing and is built to use many of the popular libraries like Nightmare, WebdriverIO, and Protractor. CodeceptJS adds to Nightmare’s test actions and incorporates readable test scenarios.

Writing Tests with CodeceptJS & Nightmare, Example

Another feature of CodeceptJS is its ability to generate page objects, page fragments, and step objects. This makes it much easier organizing tests without a lot of extra effort.

Setting Things Up

Getting things set up is simple. First run npm install -g codeceptjs-nightmare to install all of the necessary dependencies. Next, generate the project by running codeceptjs init. You will be prompted with a few set up questions:

  1. Where are your tests located? (default location ./*_test.js)
  2. What helpers do you want to use? (Use space to select)
  3. Where should logs, screenshots, and reports to be stored?
  4. Would you like to extend I object with custom steps?
  5. Do you want to choose localization for tests?
  6. Where would you like to place custom steps?
  7. [Nightmare] Base url of site to be tested?

This will generate a codecept.json file. Now you can create your first test with codeceptjs gt.

Writing Tests with CodeceptJS & Nightmare, JSON file

You can further organize your tests with page object, step object, and page fragment generators. You can find more information in CodeceptJS’ documentation, but here are the available commands:

  • Page Object: codeceptjs gpo
  • Step Object: codeceptjs go --type step
  • Page Fragment: codeceptjs go --type fragment

CodeceptJS makes it easier for teams to begin creating automated tests because it works with some of the most popular libraries and uses simple, acceptance-based scenarios. This lets you create easy-to-read tests and scale your test suite with your project.

There is a test harness available if you want to quickly spin up CodeceptJS-Nightmare tests for your application. It includes all necessary dependencies, an option to generate an HTML report, and is set up to also run in a Docker container via docker-compose. Check it out at https://github.com/ModusCreateOrg/codeceptjs-nightmare-harness.

Wrapping Up

There are many options to choose from when designing a structure for tests. Why work with Nightmare and CodeceptJS? CodeceptJS makes it simple to create a uniform test suite across popular libraries like WebdriverIO, Appium, and Nightmare. It builds upon what these libraries already offer and allows teams to easily create new test projects. Nightmare gives you the ability to create tests that are fast and efficient – a major plus for any automation roadmap.

If you’re having trouble choosing tools for an automation suite or getting started with automation altogether, consider checking out the repo and start writing your own CodeceptJS + Nightmare tests!

Like What You See?

Got any questions?