Getting started with Root Cause OSS Local

This guide examplains how to get started with Root Cause.

Root Cause integrates with two parts of your code:

  • The test runner (jest/mocha/whatever).
  • The automation framework (Puppeteer/Playwright).

If you want to use Root Cause in standalone mode (i.e. without a test runner), follow the instructions in the Standalone Mode Setup section. Or, if you are using a test runner (Jest/Mocha), follow the instructions in the Test Runner Mode Setup section. After running your tests, you will be able to access the results through the CLI and view the screenshots on a web browser (See Test Runner Mode Setup).

Standalone Mode Setup

Do this if you are not using a test runner like mocha/jest

To setup Root Cause in standalone mode:

  1. Use the following command to install the Root Cause Node.js package. (you may also use the yarn equivalent command):
npm install @testim/root-cause
  1. Add the following lines to your test:
const rc = require('@testim/root-cause');
rc.launch({ testName: "My Root Cause test" }, async page => {
    // use the page object normally like you regularly would
    await page.goto('');
    import playwright from 'playwright';
    import * as rc from '@testim/root-cause';
    rc.launch({ testName: __filename, automationLibrary: 'playwright' }, async (page) => {
        await page.setViewportSize({
            width: 1400,
            height: 800,
  1. Run your test command:
npm test

Test Runner Mode Setup

If you are using test runner, such as Jest or Mocha - Root Cause integrates directly with those to provide an optimal experience.

To setup Root Cause:

  1. Use the following command to install Root Cause:
  • For Jest
npm install @testim/root-cause-jest
  • For Mocha
npm install @testim/root-cause-mocha
  1. Add the root cuase reporter and setup to your jest configuration:
  • For Jest-puppeteer:
// inside your jest.config.js
const puppeteerPreset = require('jest-puppeteer-preset/jest-preset.json');

const runId =; // name the suite run somehow
module.exports = {
    // add the Root Cause Reporter
    reporters: [['@testim/root-cause-jest/lib/reporter/default', { runId }],
    // and tell Testim Root Cause to instrument
    setupFilesAfterEnv: [
        ...puppeteerPreset.setupFilesAfterEnv, // or whatever you had here before
    // Note we expect a global 'page' object, for example like in jest-puppeteer
  • For Jest-Playwright:
const playwrightPreset = require("jest-playwright-preset/jest-preset.json");

const runId =;

module.exports = {
    testRunner: 'jasmine2',
    reporters: [
        ['@testim/root-cause-jest/lib/reporter/default', { runId }],
    setupFilesAfterEnv: [
        ...playwrightPreset.setupFilesAfterEnv, '@testim/root-cause-jest/lib/forSetupFilesAfterEnv'
    globals: {
  • For Mocha:

In order to use root-cause with Mocha, please add the root-cause mocha require hook and reporter to your .mocharc file.

For a working example, see our examples repository.

Configuring Root Cause for Mocha 8

You need to load our Root Hook, and to use our reporter.
Our reporter wraps the default reporter.
Minimal Example:

mocha --require @testim/root-cause-mocha/rootHooks --reporter @testim/root-cause-mocha/reporter

Configuring the reporter

By default, the reporter will be spec reporter.
You may use --reporter-options actualReporter=REPORTERNAMEORPATH to use different reporter, as you would with --reporter.

mocha --require @testim/root-cause-mocha/rootHooks --reporter @testim/root-cause-mocha/reporter --reporter-options actualReporter=json

Configuring Root Cause for Mocha 7

For mocha 7, we will use the --file option instead of Root Hook.
Minimal Example:

mocha --file @testim/root-cause-mocha/pre-mocha8 --reporter @testim/root-cause-mocha/reporter

Configuring the reporter

Same as Mocha 8

Using mocha config file

You may apply all these cli flags using mocha config file.

Minimal example:

// .mocharc.json
    "require": "@testim/root-cause-mocha/rootHooks",
    "reporter": "@testim/root-cause-mocha/reporter",
    "reporter-option": {
        "actualReporter": "NYAN"

What’s Next

Integrate with your test runner and view test results