Testim Documentation

Welcome to the Testim documentation. You'll find comprehensive guides to help you get started quickly, example code snippets, and tips for being more productive. You will also find details about advanced features that allow you to customize Testim to fit your environment or special testing conditions. Don't worry, we'll support you if you get stuck. Let's jump right in!

Guides    Changelog

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('https://example.com');
    await page.click('a');
    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 = Date.now().toString(); // 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 = Date.now().toString();

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"

Updated about a year ago

What's Next

Integrate with your test runner and view test results

Viewing local results / Root Cause CLI
Root Cause Jest integration
Root Cause Mocha integration

Getting started with Root Cause OSS Local

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.