Edit on GitHub

Setup Guide

Note: This guide assumes that your app can be started using npm start and accepts a port passed in as the PORT environment variable. Have a look at the configuration guide if that’s not the case.

Step 1: Install

Install Testium related packages & Mocha

npm install --save-dev testium-mocha testium-driver-wd mocha

If your CI provides headless Chrome and chromedriver, you should install the chromedriver package globally.

npm install -g chromedriver

otherwise locally

npm install --save-dev chromedriver


All chromedriver versions have a specific minimum required Chrome version. If your local Chrome browser updates the version, you likely have to update your chromedriver install as well.

Step 2: Configure

Create a .testiumrc file with your configuration. This example uses a JSON config file, but INI is supported as well.

  "launch": true,
  "driver": "wd", // this is not necessary with testium-mocha 5.x+
  "browser": "chrome",
  "app": {
    "command": "npm start"
  "chrome": {
    "headless": true

launch tells Testium to start your application before running the test. Testium will automatically stop your application once all tests finished.

Step 3: Write Tests

const assert = require('assert'); // node assertion 

const { browser } = require('testium-mocha');

describe('The homepage', () => {
  // by default testium will use the `wd` driver

  before('Load homepage', () => browser.loadPage('/'));

  it('shows the right title', async () => {
    const title = await browser.getPageTitle();
    assert.strictEqual(title, 'Hello');

Step 4: Run Tests

You can just run the file above using mocha and Testium will handle everything for you:

  • Launch the app and headless Chrome.
  • Wait for the app to listen.
  • Clear cookies & reset the window to a well-known size.
  • Close the webdriver session and tear down your app & headless Chrome.
npx mocha test/integration/testsuite.test.js

To run tests against an already running local server add --launch=false

npx mocha --launch=false test/integration/testsuite.test.js

Thanks to rc you can use environment variables to override options. This makes it super easy to run the same test in regular Chrome:

testium_chrome__headless=false npx mocha test/integration/testsuite.test.js

NOTE: Testium will automatically download selenium the first time it is needed.