Features
Start a free trial

Getting started with CodeceptJS

CodeceptJS is an end-to-end testing framework which supports Selenium, Appium, Playwright, Puppeteer and more.
It offers scenario driven testing, PageObjects support, beautiful reports and much more.

Let's start with installing everything we need:

Copy code
npm i --save-dev codeceptjs @wdio/testingbot-service

Now we need to set up CodeceptJS. Please use the command below to initialize a new project:

Copy code
npx codeceptjs init

This will ask a bunch of questions, and will create a sample test at the end of the process.

Example test

Now that you have everything set up, you can create a very simple test:

Copy code
Feature('My First Test');

Scenario('test something', ({ I }) => {
  I.amOnPage('https://testingbot.com');
  I.see('TestingBot');
});

This simple test will navigate to TestingBot and verify if the name TestingBot is present on the page.

Before we can run this test, we need to configure CodeceptJS to connect and run a browser on our grid.

Configuration

You can configure CodeceptJS with a codecept.conf.js file:

Copy code
const { setHeadlessWhen } = require('@codeceptjs/configure');

// turn on headless mode when running with HEADLESS=true environment variable
// HEADLESS=true npx codecept run
setHeadlessWhen(process.env.HEADLESS);

exports.config = {
  tests: './*_test.js',
  output: './output',
  helpers: {
    WebDriver : {
      url: "hub.testingbot.com",
      browser: 'chrome',
      desiredCapabilities: {
        build: "CodeceptJS",
        platform: 'Windows 10',
        browserName: 'chrome',
        version: 'latest'
      },
      smartWait: 5000,
      restart: false,
      timeouts: {
        "script": 60000,
        "page load": 10000
      }
     }
  },
  include: {
    I: './steps_file.js'
  },
  bootstrap: null,
  mocha: {},
  name: 'codeceptjs-example',
  plugins: {
    retryFailedStep: {
      enabled: true
    },
    screenshotOnFail: {
      enabled: true
    },
    wdio: {
      enabled: true,
      services: ['testingbot'],
      user: 'YOUR KEY HERE',
      key: 'YOUR SECRET HERE'
    }
  }
}

To run the test, you can do:

Copy code
npx codeceptjs run --steps

This will start the latest Chrome browser on TestingBot and run the test on our grid.
You will see a test appear in your member dashboard on TestingBot, together with a video, log files and other assets generated by the test.

Configuring capabilities

To run your existing tests on TestingBot, your tests will need to be configured to use the TestingBot remote machines. If the test was running on your local machine or network, you can simply change your existing test like this:

Before
Copy code
// codecept.conf.js
exports.config = {
  tests: './*_test.js',
  output: './output',
  helpers: {
    WebDriver : {}
  }
};
After
Copy code
// codecept.conf.js
plugins: {
    ...
    wdio: {
      enabled: true,
      services: ['testingbot'],
      user: 'YOUR KEY HERE',
      key: 'YOUR SECRET HERE'
    }
}

Specifying the operating system, browser and version

To let TestingBot know on which browser/platform you want to run your test on, you need to specify the browsername, version, OS and other optional options in the capabilities field.

To see how to do this, please select a combination of browser, version and platform in the drop-down menus below.

1. Select a Platform
2. Select a browser
Copy code

Reporting Test Results

If you are using the wdio-testingbot-service then your tests will automatically report back meta-data to TestingBot (like test success, name, stacktrace, ...)

Testing Internal/Staged Websites

We've built TestingBot Tunnel, to provide you with a secure way to run tests against your staged/internal webapps.
Please see our TestingBot Tunnel documentation for more information about this easy to use tunneling solution.

The example below shows how to easily run a WebdriverIO test with our Tunnel:

1. Adjust your codecept.conf.js configuration to use tbTunnel: true.
The wdio-testingbot-service will automatically download and use the tunnel for your tests.

codecept.conf.js
Copy code
plugins: {
    ...
    wdio: {
      enabled: true,
      services: ['testingbot'],
      user: 'YOUR KEY HERE',
      key: 'YOUR SECRET HERE',
      tbTunnel: true
    }
}

Parallel Testing

Please see CodeceptJS parallel testing on how to run your tests in parallel.

You can specify the concurrency by specifying a number of workers:

Copy code
npx codeceptjs run-workers 2

or run multiple different browsers with:

Copy code
npx codeceptjs run-multiple --all

Queuing

Every plan we provide comes with a limit of parallel tests.
If you exceed the number of parallel tests assigned to your account, TestingBot will queue the additional tests (for up to 6 minutes) and run the tests as soon as slots become available.

Other Options

We offer many other test options, for example: disable video recording, specifying a custom Firefox Profile, loading Chrome/Firefox/Safari extensions, running an executable before your test starts, uploading files, ...
See our list of test options for a full list of options to customize your tests.

Pick a NodeJS test framework

  • WebdriverIO

    Webdriver/Selenium 2.0 JavaScript bindings for NodeJS.

  • CodeceptJS

    Run acceptance tests with CodeceptJS on TestingBot.

  • Protractor

    Protractor is an end-to-end test framework for AngularJS applications. Protractor is a nodeJS program built on top of WebDriverJS.

  • Soda

    Selenium Node Adapter. A light-weight Selenium RC client for NodeJS.

  • Nightwatch

    Nightwatch.js is an automated testing framework written in NodeJS.

  • Intern

    Intern is a nodeJS framework for testing Web sites and applications.

  • WD.js

    WD.js is a NodeJS client for WebDriver/Selenium.

  • Hermione

    Hermione is a Test Framework similar to WebDriverIO, with automatic test retries and plugins.