codeceptjs

What is codeceptjs?

CodeceptJS is an end-to-end testing framework for Node.js that simplifies the process of writing and running tests for web applications. It supports various testing engines like WebDriver, Puppeteer, TestCafe, and more, allowing for flexible and powerful test automation.

What are codeceptjs's main functionalities?

End-to-End Testing

CodeceptJS allows you to write end-to-end tests in a simple and readable format. This example demonstrates a basic login test where the user navigates to the login page, fills in the username and password, clicks the login button, and verifies that the welcome message is displayed.

const { I } = inject();

Feature('Login');

Scenario('test login', (I) => {
  I.amOnPage('/login');
  I.fillField('Username', 'user');
  I.fillField('Password', 'password');
  I.click('Login');
  I.see('Welcome, user');
});

Page Object Model

CodeceptJS supports the Page Object Model (POM) design pattern, which helps in organizing and maintaining test code. This example shows a LoginPage class that encapsulates the elements and actions related to the login page, making the test code more modular and reusable.

class LoginPage {
  constructor() {
    this.fields = {
      username: 'input[name="username"]',
      password: 'input[name="password"]'
    };
    this.buttons = {
      login: 'button[type="submit"]'
    };
  }

  login(username, password) {
    I.fillField(this.fields.username, username);
    I.fillField(this.fields.password, password);
    I.click(this.buttons.login);
  }
}

module.exports = new LoginPage();

Data-Driven Testing

CodeceptJS supports data-driven testing, allowing you to run the same test with different sets of data. This example demonstrates how to create a data table with multiple user credentials and run the login test for each set of credentials.

const { I } = inject();

Feature('Login');

const users = new DataTable(['username', 'password']);
users.add(['user1', 'password1']);
users.add(['user2', 'password2']);

Data(users).Scenario('test login with multiple users', (I, current) => {
  I.amOnPage('/login');
  I.fillField('Username', current.username);
  I.fillField('Password', current.password);
  I.click('Login');
  I.see('Welcome, ' + current.username);
});

Other packages similar to codeceptjs

cypress

Cypress is a popular end-to-end testing framework that provides a fast, reliable, and easy-to-use testing experience. It offers features like time travel, real-time reloads, and automatic waiting. Compared to CodeceptJS, Cypress has a more modern and user-friendly interface but is limited to running tests in a browser environment.

nightwatch

Nightwatch.js is an end-to-end testing framework that uses the W3C WebDriver API to perform browser automation. It is known for its simplicity and ease of setup. Compared to CodeceptJS, Nightwatch.js is more focused on WebDriver-based testing and may require more configuration for advanced use cases.

webdriverio

WebdriverIO is a versatile testing framework that supports both WebDriver and DevTools protocols. It offers a wide range of plugins and integrations, making it highly customizable. Compared to CodeceptJS, WebdriverIO provides more flexibility and control over the testing process but may have a steeper learning curve.

README

Build Status:

Appium Helper:

Web Helper:

CodeceptJS

Reference: Helpers API

Supercharged E2E Testing

CodeceptJS is a new testing framework for end-to-end testing with WebDriver (or others). It abstracts browser interaction to simple steps that are written from a user's perspective. A simple test that verifies the "Welcome" text is present on a main page of a site will look like:

Feature('CodeceptJS demo');

Scenario('check Welcome page on site', ({ I }) => {
  I.amOnPage('/');
  I.see('Welcome');
});

CodeceptJS tests are:

• Synchronous. You don't need to care about callbacks or promises or test scenarios which are linear. But, your tests should be linear.
• Written from user's perspective. Every action is a method of I. That makes test easy to read, write and maintain even for non-tech persons.
• Backend API agnostic. We don't know which WebDriver implementation is running this test.

CodeceptJS uses Helper modules to provide actions to I object. Currently, CodeceptJS has these helpers:

• Playwright - is a Node library to automate the Chromium, WebKit and Firefox browsers with a single API.
• Puppeteer - uses Google Chrome's Puppeteer for fast headless testing.
• WebDriver - uses webdriverio to run tests via WebDriver protocol.
• TestCafe - cheap and fast cross-browser test automation.
• Appium - for mobile testing with Appium
• Detox - This is a wrapper on top of Detox library, aimed to unify testing experience for CodeceptJS framework. Detox provides a grey box testing for mobile applications, playing especially well for React Native apps.

And more to come...

Why CodeceptJS?

CodeceptJS is a successor of Codeception, a popular full-stack testing framework for PHP. With CodeceptJS your scenario-driven functional and acceptance tests will be as simple and clean as they can be. You don't need to worry about asynchronous nature of NodeJS or about various APIs of Playwright, Selenium, Puppeteer, TestCafe, etc. as CodeceptJS unifies them and makes them work as they are synchronous.

Features

• 🪄 AI-powered with GPT features to assist and heal failing tests.
• ☕ Based on Mocha testing framework.
• 💼 Designed for scenario driven acceptance testing in BDD-style.
• 💻 Uses ES6 natively without transpiler.
• Also plays nice with TypeScript.
• </> Smart locators: use names, labels, matching text, CSS or XPath to locate elements.
• 🌐 Interactive debugging shell: pause test at any point and try different commands in a browser.
• Easily create tests, pageobjects, stepobjects with CLI generators.

Installation

npm i codeceptjs --save

Move to directory where you'd like to have your tests (and CodeceptJS config) stored, and execute:

npx codeceptjs init

to create and configure test environment. It is recommended to select WebDriver from the list of helpers, if you need to write Selenium WebDriver tests.

After that create your first test by executing:

npx codeceptjs generate:test

Now test is created and can be executed with

npx codeceptjs run

If you want to write your tests using TypeScript just generate standard Type Definitions by executing:

npx codeceptjs def .

Later you can even automagically update Type Definitions to include your own custom helpers methods.

Note:

• CodeceptJS requires Node.js version 12+ or later.

Usage

Learn CodeceptJS by examples. Let's assume we have CodeceptJS installed and WebDriver helper enabled.

Basics

Let's see how we can handle basic form testing:

Feature('CodeceptJS Demonstration');

Scenario('test some forms', ({ I }) => {
  I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
  I.fillField('Email', '[e-mail]');
  I.fillField('Password', secret('123456'));
  I.checkOption('Active');
  I.checkOption('Male');
  I.click('Create User');
  I.see('User is valid');
  I.dontSeeInCurrentUrl('/documentation');
});

All actions are performed by I object; assertions functions start with see function. In these examples all methods of I are taken from WebDriver helper, see reference to learn how to use them.

Let's execute this test with run command. Additional option --steps will show us the running process. We recommend use --steps or --debug during development.

npx codeceptjs run --steps

This will produce an output:

CodeceptJS Demonstration --
 test some forms
 • I am on page "http://simple-form-bootstrap.plataformatec.com.br/documentation"
 • I fill field "Email", "[e-mail]"
 • I fill field "Password", "****"
 • I check option "Active"
 • I check option "Male"
 • I click "Create User"
 • I see "User is valid"
 • I dont see in current url "/documentation"
 ✓ OK in 17752ms

CodeceptJS has an ultimate feature to help you develop and debug your test. You can pause execution of test in any place and use interactive shell to try different actions and locators. Just add pause() call at any place in a test and run it.

Interactive shell can be started outside test context by running:

npx codeceptjs shell

Actions

We filled form with fillField methods, which located form elements by their label. The same way you can locate element by name, CSS or XPath locators in tests:

// by name
I.fillField('user_basic[email]', '[e-mail]');
// by CSS
I.fillField('#user_basic_email', '[e-mail]');
// don't make us guess locator type, specify it
I.fillField({css: '#user_basic_email'}, '[e-mail]');

Other methods like checkOption, and click work in a similar manner. They can take labels or CSS or XPath locators to find elements to interact.

Assertions

Assertions start with see or dontSee prefix. In our case we are asserting that string 'User is valid' is somewhere in a webpage. However, we can narrow the search to particular element by providing a second parameter:

I.see('User is valid');
// better to specify context:
I.see('User is valid', '.alert-success');

In this case 'User is valid' string will be searched only inside elements located by CSS .alert-success.

Grabbers

In case you need to return a value from a webpage and use it directly in test, you should use methods with grab prefix. They are expected to be used inside async/await functions, and their results will be available in test:

Feature('CodeceptJS Demonstration');

Scenario('test page title', async ({ I }) => {
  I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
  const title = await I.grabTitle();
  I.expectEqual(title, 'Example application with SimpleForm and Twitter Bootstrap'); // Avaiable with Expect helper. -> https://codecept.io/helpers/Expect/
});

The same way you can grab text, attributes, or form values and use them in next test steps.

Before/After

Common preparation steps like opening a web page, logging in a user, can be placed in Before or Background:

const { I } = inject();

Feature('CodeceptJS Demonstration');

Before(() => { // or Background
  I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
});

Scenario('test some forms', () => {
  I.click('Create User');
  I.see('User is valid');
  I.dontSeeInCurrentUrl('/documentation');
});

Scenario('test title', () => {
  I.seeInTitle('Example application');
});

PageObjects

CodeceptJS provides the most simple way to create and use page objects in your test. You can create one by running

npx codeceptjs generate pageobject

It will create a page object file for you and add it to the config. Let's assume we created one named docsPage:

const { I } = inject();

module.exports = {
  fields: {
    email: '#user_basic_email',
    password: '#user_basic_password'
  },
  submitButton: {css: '#new_user_basic input[type=submit]'},

  sendForm(email, password) {
    I.fillField(this.fields.email, email);
    I.fillField(this.fields.password, password);
    I.click(this.submitButton);
  }
}

You can easily inject it to test by providing its name in test arguments:

Feature('CodeceptJS Demonstration');

Before(({ I }) => { // or Background
  I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
});

Scenario('test some forms', ({ I, docsPage }) => {
  docsPage.sendForm('[e-mail]','123456');
  I.see('User is valid');
  I.dontSeeInCurrentUrl('/documentation');
});

When using Typescript, replace module.exports with export for autocompletion.

Contributing

• Contributing Guide

• Code of conduct

Contributors

Thanks all to those who are and will have contributing to this awesome project!

License

MIT © CodeceptJS Team

Changelog

3.5.12

❤️ Thanks all to those who contributed to make this release! ❤️

🛩️ Features

• feat: upgrade wdio (#4123) - by @KobeNguyenT

  🛩️ With the release of WebdriverIO version v8.14.0, and onwards, all driver management hassles are now a thing of the past 🙌. Read more here. One of the significant advantages of this update is that you can now get rid of any driver services you previously had to manage, such as wdio-chromedriver-service, wdio-geckodriver-service, wdio-edgedriver-service, wdio-safaridriver-service, and even @wdio/selenium-standalone-service.

For those who require custom driver options, fear not; WebDriver Helper allows you to pass in driver options through custom WebDriver configuration. If you have a custom grid, use a cloud service, or prefer to run your own driver, there's no need to worry since WebDriver Helper will only start a driver when there are no other connection information settings like hostname or port specified.

Example:

{
   helpers: {
     WebDriver : {
       smartWait: 5000,
       browser: "chrome",
       restart: false,
       windowSize: "maximize",
       timeouts: {
         "script": 60000,
         "page load": 10000
       }
     }
   }
}

Testing Chrome locally is now more convenient than ever. You can define a browser channel, and WebDriver Helper will take care of downloading the specified browser version for you. For example:

{
   helpers: {
     WebDriver : {
       smartWait: 5000,
       browser: "chrome",
       browserVersion: '116.0.5793.0', // or 'stable', 'beta', 'dev' or 'canary'
       restart: false,
       windowSize: "maximize",
       timeouts: {
         "script": 60000,
         "page load": 10000
       }
     }
   }
}

• feat: wdio with devtools protocol (#4105) - by @KobeNguyenT

Running with devtools protocol

{
   helpers: {
     WebDriver : {
       url: "http://localhost",
       browser: "chrome",
       devtoolsProtocol: true,
       desiredCapabilities: {
         chromeOptions: {
           args: [ "--headless", "--disable-gpu", "--no-sandbox" ]
         }
       }
     }
   }
}

• feat: add a locator builder method withTextEquals() (#4100) - by @mirao

Find an element with exact text

locate('button').withTextEquals('Add');

• feat: waitForNumberOfTabs (#4124) - by @KobeNguyenT

Waits for number of tabs.

I.waitForNumberOfTabs(2);

• feat: I.say would be added to Test.steps array (#4145) - by @KobeNguyenT

Currently I.say is not added into the Test.steps array. This PR aims to add this to steps array so that we could use it to print steps in ReportPortal for instance.

🐛 Bug Fixes

• fix: reduce the package size to 2MB (#4138) - by @KobeNguyenT
• fix(webapi): see attributes on elements (#4147) - by @KobeNguyenT
• fix: some assertion methods (#4144) - by @KobeNguyenT

Improve the error message for seeElement, dontSeeElement, seeElementInDOM, dontSeeElementInDOM

The current error message doesn't really help when debugging issue also causes some problem described in #4140

Actual

      expected visible elements '[ELEMENT]' to be empty
      + expected - actual

      -[
      -  "ELEMENT"
      -]
      +[]

Updated

     Error: Element "h1" is still visible
      at seeElementError (lib/helper/errors/ElementAssertion.js:9:9)
      at Playwright.dontSeeElement (lib/helper/Playwright.js:1472:7)

• fix: css to xpath backward compatibility (#4141) - by @KobeNguyenT

• css-to-xpath: old lib, which works perfectly unless you have hyphen in locator. (https://github.com/codeceptjs/CodeceptJS/issues/3563)
• csstoxpath: new lib, to solve the issue locator with hyphen but also have some limitations

• fix: grabRecordedNetworkTraffics throws error when being called twice (#4143) - by @KobeNguyenT
• fix: missing steps of test when running with workers (#4127) - by @KobeNguyenT

Scenario('Verify getting list of users', async () => {
let res = await I.getUserPerPage(2);
res.data = []; // this line causes the issue
await I.expectEqual(res.data.data[0].id, 7);
});

at this time, res.data.data[0].id would throw undefined error and somehow the test is missing all its steps.

• fix: process.env.profile when --profile isn't set in run-multiple mode (#4131) - by @mirao

process.env.profile is the string "undefined" instead of type undefined when no --profile is specified in the mode "run-multiple"

• fix: session doesn't respect the context options (#4111) - by @KobeNguyenT

Helpers: Playwright
Plugins: screenshotOnFail, tryTo, retryFailedStep, retryTo, eachElement

Repro --
[1]  Starting recording promises
Timeouts:
› [Session] Starting singleton browser session
Reproduce issue
I am on page "https://example.com"
› [Browser:Error] Failed to load resource: the server responded with a status of 404 ()
› [New Context] {}
user1: I am on page "https://example.com"
user1: I execute script () => {
return { width: window.screen.width, height: window.screen.height };
}
sessionScreen is {"width":375,"height":667}
✔ OK in 1890ms


OK  | 1 passed   // 4s

• fix(plugin): retryTo issue (#4117) - by @KobeNguyenT

• fix(types): CustomLocator typing broken for custom strict locators (#4120) - by @KobeNguyenT

• fix: wrong output for skipped tests - by @KobeNguyenT

• fix: no retry failed step after tryto block (#4103) - by @KobeNguyenT

• fix: deprecate some JSON Wire Protocol commands (#4104) - by @KobeNguyenT

deprecate some JSON Wire Protocol commands: grabGeoLocation, setGeoLocation

• fix: cannot locate complicated locator (#4101) - by @KobeNguyenT

Locator issue due to the lib changes

The locator locate(".ps-menu-button").withText("Authoring").inside(".ps-submenu-root:nth-child(3)") is translated to
3.5.8: //*[contains(concat(' ', normalize-space(./@class), ' '), ' ps-menu-button ')][contains(., 'Authoring')][ancestor::*[(contains(concat(' ', normalize-space(./@class), ' '), ' ps-submenu-root ') and count(preceding-sibling::*) = 2)]] and works well
3.5.11: //*[contains(@class, "ps-menu-button")][contains(., 'Authoring')][ancestor::*[3][contains(@class, "ps-submenu-root")]] and doesn't work (no clickable element found). Even if you test it in browser inspector, it doesn't work.