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:

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

Add the following lines to your test:

For a Puppeteer test:
For a working example, see our examples repository

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');
});

For a Playwright test
For a working example, see our examples repository

    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,
        });

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:

Use the following command to install Root Cause:

For Jest

npm install @testim/root-cause-jest

For Mocha

npm install @testim/root-cause-mocha

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
        '@testim/root-cause-jest/lib/forSetupFilesAfterEnv'
    ],
    // 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 = {
    ...playwrightPreset,
    testRunner: 'jasmine2',
    reporters: [
        ['@testim/root-cause-jest/lib/reporter/default', { runId }],
    ],
    setupFilesAfterEnv: [
        ...playwrightPreset.setupFilesAfterEnv, '@testim/root-cause-jest/lib/forSetupFilesAfterEnv'
    ],
    globals: {
        runId,
    },
};

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.
Example:

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"
    }
}