Reporter Interface

Implement the following methods to create a reporter:

reportTaskStart
reportFixtureStart
reportTestDone
reportTaskDone
reportTestStart (optional)

You can use the helper methods and libraries within the reporter methods to output the required data.

Output Helpers
Formatting Helpers
Coloring Helper
Date-Time Helper

reportTaskStart

Fires when a test task starts.

async reportTaskStart (startTime, userAgents, testCount)

Parameter	Type	Description
`startTime`	Date	The date and time when testing started.
`userAgents`	Array of Strings	The list of browsers used for testing. Contains the formatted names and versions of the browsers and operating systems.
`testCount`	Number	The total number of tests to run.

Example

async reportTaskStart (startTime, userAgents, testCount) {
    this.startTime = startTime;
    this.testCount = testCount;

    const time = this.moment(startTime).format('M/D/YYYY h:mm:ss a');

    this.write(`Testing started: ${time}`)
        .newline()
        .write(`Running ${testCount} tests in: ${userAgents}`)
        .newline();
}

//=> Testing started: 8/12/2016 3:00:00 am
//=> Running 6 tests in: Chrome 41.0.2227 / Mac OS X 10.10.1,Firefox 47 / Mac OS X 10.10.1

reportFixtureStart

Fires each time a fixture starts.

async reportFixtureStart (name, path, meta)

Parameter	Type	Description
`name`	String	The test fixture name.
`path`	String	The path to a test fixture file.
`meta`	Object	The fixture metadata. See Specify Test Metadata for more information.

Example

async reportFixtureStart (name, path, meta) {
    this.currentFixtureName = name;
    this.currentFixtureMeta = meta;
    this.write(`Starting fixture: ${name} ${meta.fixtureID}`)
        .newline();
}

//=> Starting fixture: First fixture f-0001

reportTestStart

Fires each time a test starts. This method is optional.

async reportTestStart (name, meta)

Parameter	Type	Description
`name`	String	The test name.
`meta`	Object	The test metadata. See Specify Testing Metadata for more information.
`testStartInfo`	Object	A testStartInfo object.

Example

async reportTestStart (name, meta, testStartInfo) {
    this.write(`Starting test at ${testStartInfo.startTime.toLocaleTimeString()}: ${name} (${meta.severity})`) 
        .newline(); 
}

//=> Starting test at 4:00:00 AM: Submit data (minor)

testStartInfo Object

The testStartInfo object contains detailed information about the test start.

Property	Type	Description
`testRunIds`	Array of Strings	An array of all test identifiers.
`testId`	String	The test’s identifier.
`startTime`	Date	The start time of the test.

reportTestDone

Fires each time a test ends.

async reportTestDone (name, testRunInfo, meta)

Parameter	Type	Description
`name`	String	The test name.
`testRunInfo`	Object	The testRunInfo object.
`meta`	Object	The test metadata. See Specify Testing Metadata for more information.

Example

async reportTestDone (name, testRunInfo, meta) {
    const hasErr      = !!testRunInfo.errs.length;
    const hasWarnings = !!testRunInfo.warnings.length;
    const result      = testRunInfo.skipped ? 'skipped' : hasErr ? `failed` : `passed`;

    name = `${this.currentFixtureName} - ${name}`;

    let title = `${result} ${name}`;

    if (testRunInfo.unstable)
        title += ' (unstable)';

    if (testRunInfo.screenshotPath)
        title += ` (screenshots: ${testRunInfo.screenshotPath})`;

    if (meta.severity)
        title += ` (${meta.severity})`;

    if (hasWarnings)
        title += ' (with warnings)';

    this.write(title)
        .newline();
}

//=> failed First fixture - First test in first fixture (unstable) (screenshots: /screenshots/1445437598847) (critical)
//=> passed First fixture - Second test in first fixture (screenshots: /screenshots/1445437598847)
//=> failed First fixture - Third test in first fixture
//=> skipped First fixture - Fourth test in first fixture

testRunInfo Object

The testRunInfo object provides detailed information about the test run. The object has the following properties:

Property	Type	Description
`errs`	Array of Objects	An array of errors that occurred during the test run. Use the formatError helper to convert objects in this array to strings.
`warnings`	Array of Strings	An array of warnings that appeared during the test run.
`durationMs`	Number	The duration of the test (in milliseconds).
`unstable`	Boolean	Specifies if the test is marked as unstable.
`screenshotPath`	String	The path where screenshots are saved.
`screenshots`	Array of Objects	An array of screenshot objects.
`quarantine`	Object	A quarantine object.
`skipped`	Boolean	Specifies if the test was skipped.
`reportData`	Object	A reportData object.

screenshots Object

The screenshot object provides information about the screenshot captured during the test run. The object has the following properties:

Property	Type	Description
`screenshotPath`	String	The path where the screenshot was saved.
`thumbnailPath`	String	The path where the screenshot’s thumbnail was saved.
`userAgent`	String	The user agent string of the browser where the screenshot was captured.
`quarantineAttempt`	Number	The quarantine attempt’s number.
`takenOnFail`	Boolean	Specifies if the screenshot was captured when the test failed.

quarantine Object

The quarantine object stores information about quarantined tests in key-value format.

Key	Value
The quarantine attempt’s number.	Contains information about the attempt. The `passed` property is `true` if the attempt has been successful.

reportData Object

The reportData object stores custom data that the reporter receives from the t.report action.

Key	Value
Test Run ID (string)	Array of values (any type) from the t.report action.

reportTaskDone

Fires when the task ends.

async reportTaskDone (endTime, passed, warnings, result)

Parameter	Type	Description
`endTime`	Date	The date and time when testing completed.
`passed`	Number	The number of passed tests.
`warnings`	Array of Strings	An array of warnings that occurred during a task run.
`result`	Object	Contains information about the task results.

Example

async reportTaskDone (endTime, passed, warnings, result) {
    const time = this.moment(endTime).format('M/D/YYYY h:mm:ss a');
    const durationMs  = endTime - this.startTime;
    const durationStr = this.moment.duration(durationMs).format('h[h] mm[m] ss[s]');
    const summary = result.failedCount ?
                    `${result.failedCount}/${this.testCount} failed` :
                    `${result.passedCount} passed`;

    this.write(`Testing finished: ${time}`)
        .newline()
        .write(`Duration: ${durationStr}`)
        .newline()
        .write(summary)
        .newline();
}

//=> Testing finished: 8/12/2016 3:15:25 am
//=> Duration: 15m 25s
//=> 2/6 failed

result Object

The result object contains information about the task results. The object has the following properties:

Parameter	Type	Description
`passedCount`	Number	The number of passed tests.
`failedCount`	Number	The number of failed tests.
`skippedCount`	Number	The number of skipped tests.

Helper Methods

Helpers are methods and libraries used to format report output when implementing a reporter. TestCafe mixes these methods into the reporter.

To access helpers, use this.

Output Helpers

All output helper methods are chainable: each method returns this so that the methods can be executed one right after another. This allows you to write compact code like this.

this.setIndent(4)
    .write(testname)
    .newline()
    .write(result);

newline

Adds a new line to the report.

newline () → this

Example

async reportTaskDone (endTime, passed, warnings, result) {
    ...
    const summary = result.failedCount ?
                    `${result.failedCount}/${this.testCount} failed` :
                    `${result.passedCount} passed`;

    this.newline()
        .write(summary)
        .newline();
}

write

Writes the specified text to the report.

write (text) → this

Parameter	Type	Description
`text`	String	The text to output in the report.

Example

async reportTaskDone (endTime, passed, warnings, result) {
    ...
    const summary = result.failedCount ?
                    `${result.failedCount}/${this.testCount} failed` :
                    `${result.passedCount} passed`;

    this.write(summary)
        .newline();
}

useWordWrap

Toggles word wrapping for subsequent output.

useWordWrap (use) → this

Parameter	Type	Description
`use`	Boolean	Specify true to enable word wrapping.

Example

The following example demonstrates how to enable word wrapping when the title string is long:

async reportTestDone (name, testRunInfo, meta) {
    ...
    name = `${this.currentFixtureName} - ${name}`;

    const title = `${result} ${name}`;

    this.useWordWrap(true)
        .write(title);
}

setIndent

Specifies indentation for subsequent output.

setIndent (val) → this

Parameter	Type	Description
`val`	Integer	Specifies the number of spaces to indent a new line. To disable indentation, set the parameter to 0.

Example

The following example demonstrates how to indent summary information by four spaces:

async reportTaskDone (endTime, passed, warnings, result) {
    ...
    const summary = result.failedCount ?
                    `${result.failedCount}/${this.testCount} failed` :
                    `${result.passedCount} passed`;

    this.setIndent(4)
        .write(summary);
}
//=>    2/6 failed

Formatting Helpers

indentString

Indents each line in a string by a number of spaces.

indentString (str, indentVal) → String

Parameter	Type	Description
`str`	String	The string to indent.
`indentVal`	Number	The number of spaces to indent a new line.

Example

This example demonstrates how to indent each line in the str string by four spaces.

async reportTaskStart (startTime, userAgents, testCount) {
    let str = `Start running tests\nBrowsers used for testing: ${userAgents}`;
    str = this.indentString(str, 4);

    this.write(`${str}`)
}
//=>    Start running tests
//=>    Browsers used for testing: Chrome,Firefox

wordWrap

Breaks and wraps a string to a new line if its length exceeds the maximum allowed length.

wordWrap (str, indentVal, width) → String

Parameter	Type	Description
`str`	String	The string you want to break.
`indentVal`	Number	The number of spaces to indent a new line.
`width`	Number	The maximum number of characters each line can contain.

Example

The following example demonstrates how to break the title string to the next line if the string length is more than 50 symbols.

const LINE_WIDTH = 50;

async reportTestDone (name, testRunInfo, meta) {
    const hasErr    = !!testRunInfo.errs.length;
    const result    = hasErr ? `failed` : `passed`;

    name = `${this.currentFixtureName} - ${name}`;

    let title = `${result} ${name}`;

    title = this.wordWrap(title, 2, LINE_WIDTH);

    this.write(title)
        .newline()
        .newline();
}
//=>  failed Sample fixture - Comparing the input
//=>  value with the specified one
//=>
//=>  passed Sample fixture - Clicking an array of
//=>  labels and checking their states

escapeHtml

Encodes a string for use in HTML.

escapeHtml (str) → String

Parameter	Type	Description
`str`	String	The string to be encoded.

Example

The following example demonstrates how to encode the fixture name Tests for the “Example” page for HTML

async reportFixtureStart (name, path, meta) {
    this.currentFixtureName = this.escapeHtml(name);
    this.write(this.currentFixtureName);
}
//=>Tests for the &quot;Example&quot; page

formatError

Returns the formatted error message string for the specified error.

formatError (err, prefix = '') → String

Parameter	Type	Description
`err`	Object	The error object you need to format.
`prefix = ''`	String	The string that is prepended to the error. By default, it is empty.

Example

The following example demonstrates how to number errors:

async reportTestDone (name, testRunInfo, meta) {
    ...
    const hasErr = !!testRunInfo.errs.length;

    if (hasErr) {
        errs.forEach((err, idx) => {
            this.newline()
                .write(this.formatError(err, `${idx + 1}) `));
        });
    }
}
//=> 1) Chrome
//=>    Assertion failed at step "Step1"
//=>    ...
//=> 2) Firefox
//=>    Assertion failed at step "Step1"
//=>    ...

Coloring Helper

chalk

chalk is used for ANSI-coloring of the text.

chalk.<style>[.<style>...](string, [string...]) → this

Example

The following example demonstrates how to color test results:

async reportTestDone (name, testRunInfo, meta) {
    const hasErr = !!testRunInfo.errs.length;
    const result = hasErr ? this.chalk.red(`failed`) : this.chalk.green(`passed`);

    name = `${this.currentFixtureName} - ${name}`;

    const title = `${result} ${name}`;

    this.write(title);
}

To force disabling coloring in reports, set the reporter’s noColors property in the src/index.js file to false. For example, you may need to disable coloring for machine-readable formats (JSON or xUnit) since the colored output is not required.

export default function () {
    return {
        noColors: true,

        async reportTaskStart (startTime, userAgents, testCount) {
            ...
        },

        ...
    };
}

Date/Time Helper

moment

moment is used to deal with dates and time.

moment().format() → this

Example

async reportTaskDone (endTime, passed, warnings, result) {
    const durationMs  = endTime - this.startTime;
    const durationStr = this.moment
                            .duration(durationMs)
                            .format('h[h] mm[m] ss[s]');

    this.write(`Duration: ${durationStr}`)
    ...
}