Modify Reporter Output

Article Summary

The onBeforeWrite hook allows you to modify the output of a reporter.

If you want your reports to include custom content, you have the option to create a custom reporter from scratch. However, this approach takes time and effort. Use the onBeforeWrite hook if you want to make minor changes to the output of an existing reporter.

Define an onBeforeWrite hook in a JavaScript configuration file. The following hook adds the duration in milliseconds to every test entry in the report:

//.testcaferc.js or .testcaferc.cjs
function onBeforeWriteHook(writeInfo) { // This function will fire every time the reporter calls the "write" method.
    if (writeInfo.initiator === 'reportTestDone') { // The "initiator" property contains the name of the reporter event that triggered the hook.
         const {
            name,
            testRunInfo,
            meta
        } = writeInfo.data || {}; // If you attached this hook to a compatible reporter (such as "spec" or "list"), the hook can process data related to the event.
        const testDuration = testRunInfo.durationMs; // Save the duration of the test.
        writeInfo.formattedText = writeInfo.formattedText + ' (' + testDuration + 'ms)'; // Add test duration to the reporter output.
    };
}


module.exports = { // Attach the hook
    hooks: {
        reporter: {
            onBeforeWrite: {
                'spec': onBeforeWriteHook, // This hook will fire when you use the default "spec" reporter.
            },
        },
    },
};

Reporter hook demonstration

Attach the Hook
Create a Hook Function
Process Different Reporter Events
Limitations

Attach the Hook

Use a JavaScript configuration file to define and attach reporter hooks.

The hooks.reporter.onBeforeWrite property attaches onBeforeWrite hooks to reporters. Populate this property with key-value pairs, where the key is the name of the reporter, and the value is the corresponding hook function.

module.exports = {
    hooks: {
        reporter: {
            onBeforeWrite: {
                'spec': hookFunction,
                'list': aDifferentHookFunction
            },
        },
    },
};

Create a Hook Function

The onBeforeWrite hook function intercepts reporter output every time the reporter fires the write method.

Consider the following hook function:

function onBeforeWriteHook(writeInfo) {
    if (writeInfo.initiator === 'reportTestDone') { // Determine the reporter event
        const dateTime = new Date().toLocaleString('en-US', { timeZone: 'UTC' });
        writeInfo.formattedText = dateTime + writeInfo.formattedText; // Modify reporter output
    };
}

The function receives an object with the following properties:

Property	Type	Description
initiator	String	The name of the reporter event
data	Object	Event data (different for different events)
formattedText	String	The text that reaches `stdout`
formatOptions	Object	The formatting options of the reporter (`indent` and `wordWrap`)

Note

The following reporters share event data with onBeforeWrite hooks out of the box:

spec
list
minimal

If you want the onBeforeWrite hook to access data from a custom reporter, change the code of the target reporter.

The function uses the initiator property to find the name of the current reporter event.
The function modifies the value of the formattedText property to change the reporter output.

Process Different Reporter Events

TestCafe executes the onBeforeWrite hook every time the target reporter calls a write method. If you attach the hook to a compatible reporter (spec, list, or minimal), you can process data from the following events:

reportTaskStart
reportFixtureStart
reportTestStart
reportTestDone
reportTaskDone

Different events pass different data to the hook function.

reportTaskStart

The reporter fires the reportTaskStart event when TestCafe initializes the first browser. During this stage, the spec reporter lists browsers that the user selected for the test run. For example:

 Running tests in:
 - Chrome 112.0.0.0 / Ventura 13

Compatible reporters pass the following data to the onBeforeWrite hook during the reportTaskStart event:

property	type	definition
startTime	Date	The test run start time and date
userAgents	Array	The list of browsers that the user selected for the test run
testCount	Number	The total number of tests in the test suite

reportFixtureStart

The reporter fires the rerportFixtureStart event when TestCafe launches the first test from a fixture. During this stage, the spec reporter outputs the name of the fixture. For example:

Homepage Tests

Compatible reporters pass the following data to the onBeforeWrite hook during the reportFixtureStart event:

property	type	definition
name	String	The name of the fixture
path	String	The path to the test file
meta	Object	The fixture metadata

reportTestStart

The reporter fires the reportTestStart event when TestCafe launches a test.

Compatible reporters pass the following data to the onBeforeWrite hook during the reportTestStart event:

property	type	definition
name	String	The name of the test
meta	Object	The test metadata

reportTestDone

The reporter fires the reportTestDone event when TestCafe concludes the test. During this stage, the spec reporter displays the name and status of the test. For example:

✓ My first test

Compatible reporters pass the following data to the onBeforeWrite hook during the reportTestDone event:

property	type	definition
name	Date	The test run start time and date
testRunInfo	Object	The object with test run data (duration, status, etc.)
meta	Object	The test metadata

reportTaskDone

The reporter fires the reportTaskDone event when TestCafe concludes the final test. During this stage, the spec reporter displays the number of successful tests and the test task’s total runtime. For example:

1 passed (4s)

Compatible reporters pass the following data to the onBeforeWrite hook during the reportTaskDone event:

property	type	definition
endTime	Date	The time and date of the test run’s conclusion
passed	Number	The number of successful tests
warnings	Object	The full list of warnings the tests raised
result	Object	The number of successful, failed, and skipped tests from the test run

Limitations