feat: add possibility to pass additional data to the reporter plugin (closes #3584)

src/api/test-controller/index.js

@@ -57,6 +57,7 @@ import {
     SkipJsErrorsCommand,
     AddRequestHooksCommand,
     RemoveRequestHooksCommand,
+    ReportCommand,
 } from '../../test-run/commands/actions';
 
 import {
@@ -629,6 +630,10 @@ export default class TestController {
         return this.enqueueCommand(RemoveRequestHooksCommand, { hooks });
     }
 
+    [delegatedAPI(ReportCommand.methodName)] (...args) {
+        return this.enqueueCommand(ReportCommand, { args });
+    }
+
     static enableDebugForNonDebugCommands () {
         inDebug = true;
     }

src/reporter/index.ts

@@ -52,6 +52,7 @@ interface TaskInfo {
 }
 
 interface TestInfo {
+    reportData: Dictionary<any[]>;
     fixture: Fixture;
     test: Test;
     testRunIds: string[];
@@ -86,6 +87,7 @@ interface BrowserRunInfo extends Browser {
 interface TestRunInfo {
     errs: TestRunErrorFormattableAdapter[];
     warnings: string[];
+    reportData: Dictionary<any[]>;
     durationMs: number;
     unstable: boolean;
     screenshotPath: string;
@@ -123,6 +125,11 @@ interface ReportWarningEventArguments {
     actionId?: string;
 }
 
+interface ReportDataEventArgs {
+    data: any[];
+    testRun: TestRun
+}
+
 const debugLog = debug('testcafe:reporter');
 
 export default class Reporter {
@@ -194,6 +201,8 @@ export default class Reporter {
 
         messageBus.on('warning-add', async e => await this._onWarningAddHandler(e));
 
+        messageBus.on('report-data', async e => await this._onReportDataHandler(e));
+
         messageBus.once('start', async (task: Task) => await this._onceTaskStartHandler(task));
 
         messageBus.on('test-run-start', async testRun => await this._onTaskTestRunStartHandler(testRun));
@@ -299,6 +308,7 @@ export default class Reporter {
             pendingTestRunDonePromise:  Reporter._createPendingPromise(),
             pendingTestRunStartPromise: Reporter._createPendingPromise(),
             browsers:                   [],
+            reportData:                 {},
         };
     }
 
@@ -312,6 +322,7 @@ export default class Reporter {
         return {
             errs:           sortBy(reportItem.errs, ['userAgent', 'code']),
             warnings:       reportItem.warnings,
+            reportData:     reportItem.reportData,
             durationMs:     +new Date() - (reportItem.startTime as number), //eslint-disable-line  @typescript-eslint/no-extra-parens
             unstable:       reportItem.unstable,
             screenshotPath: reportItem.screenshotPath as string,
@@ -544,10 +555,12 @@ export default class Reporter {
 
         reportItem.browsers.push(browser);
 
-        reportItem.pendingRuns = isTestRunStoppedTaskExecution ? 0 : reportItem.pendingRuns - 1;
-        reportItem.unstable    = reportItem.unstable || testRun.unstable;
-        reportItem.errs        = reportItem.errs.concat(testRun.errs);
-        reportItem.warnings    = testRun.warningLog ? union(reportItem.warnings, testRun.warningLog.messages) : [];
+        reportItem.pendingRuns            = isTestRunStoppedTaskExecution ? 0 : reportItem.pendingRuns - 1;
+        reportItem.unstable               = reportItem.unstable || testRun.unstable;
+        reportItem.errs                   = reportItem.errs.concat(testRun.errs);
+        reportItem.warnings               = testRun.warningLog ? union(reportItem.warnings, testRun.warningLog.messages) : [];
+        reportItem.reportData             = reportItem.reportData || {};
+        reportItem.reportData[testRun.id] = testRun.reportDataLog ? testRun.reportDataLog.data : [];
 
         if (testRun.quarantine) {
             reportItem.quarantine = reportItem.quarantine || {};
@@ -635,4 +648,45 @@ export default class Reporter {
 
         (this.taskInfo.pendingTaskDonePromise.resolve as Function)();
     }
+
+    private _prepareReportDataEventArgs (testRun: TestRun): any {
+        const { test, browser, id } = testRun;
+        const fixture               = test.fixture;
+
+        const testInfo = {
+            name: test.name,
+            id:   test.id,
+            meta: test.meta,
+        };
+
+        const fixtureInfo = {
+            name: fixture?.name,
+            id:   fixture?.id,
+            meta: fixture?.meta,
+            path: fixture?.path,
+        };
+
+        return {
+            test:      testInfo,
+            fixture:   fixtureInfo,
+            testRunId: id,
+            browser,
+        };
+    }
+
+    private async _onReportDataHandler ({ testRun, data }: ReportDataEventArgs): Promise<void> {
+        if (!this.taskInfo)
+            return;
+
+        const testRunInfo = this._prepareReportDataEventArgs(testRun);
+
+        await this.dispatchToPlugin({
+            method:        ReporterPluginMethod.reportData as string,
+            initialObject: this.taskInfo.task,
+            args:          [
+                testRunInfo,
+                ...data,
+            ],
+        });
+    }
 }

src/reporter/interfaces.ts

@@ -10,6 +10,7 @@ export interface ReporterPlugin {
     reportTestDone(): void;
     reportTaskDone(): void;
     reportWarnings?(): void;
+    reportData? (): void
 }
 
 export interface ReporterSource {

src/reporter/plugin-host.ts

@@ -194,4 +194,8 @@ export default class ReporterPluginHost {
     // NOTE: It's an optional method
     public async reportWarnings (/* warnings */): Promise<void> { // eslint-disable-line @typescript-eslint/no-empty-function
     }
+
+    // NOTE: It's an optional method
+    public async reportData (/* testRun, ...data */): Promise<void> { // eslint-disable-line @typescript-eslint/no-empty-function
+    }
 }

src/reporter/plugin-methods.ts

@@ -11,6 +11,7 @@ const ReporterPluginMethod: EnumFromPropertiesOf<ReporterPlugin> = {
     reportTestDone:        'reportTestDone',
     reportTaskDone:        'reportTaskDone',
     reportWarnings:        'reportWarnings',
+    reportData:            'reportData',
 };
 
 export default ReporterPluginMethod;

src/reporter/report-data-log.ts

@@ -0,0 +1,32 @@
+import MessageBus from '../utils/message-bus';
+import TestRun from '../test-run';
+
+type ReportDataLogCallback = (data: any[]) => Promise<void>;
+
+export default class ReportDataLog {
+    private readonly _data: any[];
+    public callback?: ReportDataLogCallback;
+
+    public constructor (callback?: ReportDataLogCallback) {
+        this._data    = [];
+        this.callback = callback;
+    }
+
+    public get data (): any[] {
+        return this._data;
+    }
+
+    public async addData (data: any[]): Promise<void> {
+        if (this.callback)
+            await this.callback(data);
+
+        this._data.push(...data);
+    }
+
+    public static createAddDataCallback (messageBus: MessageBus | undefined, testRun: TestRun): ReportDataLogCallback {
+        return async (data: any[]) => {
+            if (messageBus)
+                await messageBus.emit('report-data', { data, testRun });
+        };
+    }
+}

src/services/serialization/replicator/transforms/command-base-trasform/command-constructors.ts

@@ -49,6 +49,7 @@ import {
     SkipJsErrorsCommand,
     AddRequestHooksCommand,
     RemoveRequestHooksCommand,
+    ReportCommand,
 } from '../../../../../test-run/commands/actions';
 
 import { AssertionCommand } from '../../../../../test-run/commands/assertion';
@@ -115,6 +116,7 @@ const COMMAND_CONSTRUCTORS = new Map<string, CommandConstructor>([
     [CommandType.skipJsErrors, SkipJsErrorsCommand],
     [CommandType.addRequestHooks, AddRequestHooksCommand],
     [CommandType.removeRequestHooks, RemoveRequestHooksCommand],
+    [CommandType.report, ReportCommand],
 ]);
 
 export default COMMAND_CONSTRUCTORS;

src/test-run/commands/actions.d.ts

@@ -285,3 +285,8 @@ export class RunCustomActionCommand extends ActionCommandBase {
     public args: any;
 }
 
+export class ReportCommand extends ActionCommandBase {
+    public constructor (obj: object, testRun: TestRun, validateProperties: boolean);
+    public args: any[];
+}
+

src/test-run/commands/actions.js

@@ -813,3 +813,16 @@ export class RemoveRequestHooksCommand extends ActionCommandBase {
     }
 }
 
+export class ReportCommand extends ActionCommandBase {
+    static methodName = camelCase(TYPE.report);
+
+    constructor (obj, testRun, validateProperties) {
+        super(obj, testRun, TYPE.report, validateProperties);
+    }
+
+    getAssignableProperties () {
+        return [
+            { name: 'args', required: true },
+        ];
+    }
+}

src/test-run/commands/type.js

@@ -72,4 +72,5 @@ export default {
     addRequestHooks:                     'add-request-hooks',
     removeRequestHooks:                  'remove-request-hooks',
     runCustomAction:                     'run-custom-action',
+    report:                              'report',
 };

src/test-run/index.ts

@@ -143,6 +143,7 @@ import {
 
 import ProxylessRequestPipeline from '../proxyless/request-pipeline';
 import Proxyless from '../proxyless';
+import ReportDataLog from '../reporter/report-data-log';
 
 const lazyRequire                 = require('import-lazy')(require);
 const ClientFunctionBuilder       = lazyRequire('../client-functions/client-function-builder');
@@ -227,6 +228,7 @@ interface OpenedWindowInformation {
 export default class TestRun extends AsyncEventEmitter {
     private [testRunMarker]: boolean;
     public readonly warningLog: WarningLog;
+    public readonly reportDataLog: ReportDataLog;
     private readonly opts: Dictionary<OptionValue>;
     public readonly test: Test;
     public readonly browserConnection: BrowserConnection;
@@ -290,6 +292,7 @@ export default class TestRun extends AsyncEventEmitter {
         this[testRunMarker]    = true;
         this._messageBus       = messageBus;
         this.warningLog        = new WarningLog(globalWarningLog, WarningLog.createAddWarningCallback(messageBus, this));
+        this.reportDataLog     = new ReportDataLog(ReportDataLog.createAddDataCallback(messageBus, this));
         this.opts              = opts;
         this.test              = test;
         this.browserConnection = browserConnection;
@@ -307,8 +310,8 @@ export default class TestRun extends AsyncEventEmitter {
         this.pageLoadTimeout      = this._getPageLoadTimeout(test, opts);
         this.testExecutionTimeout = this._getTestExecutionTimeout(opts);
 
-        this.disablePageReloads   = test.disablePageReloads || opts.disablePageReloads as boolean && test.disablePageReloads !== false;
-        this.disablePageCaching   = test.disablePageCaching || opts.disablePageCaching as boolean;
+        this.disablePageReloads = test.disablePageReloads || opts.disablePageReloads as boolean && test.disablePageReloads !== false;
+        this.disablePageCaching = test.disablePageCaching || opts.disablePageCaching as boolean;
 
         this.disableMultipleWindows = opts.disableMultipleWindows as boolean;
 
@@ -350,7 +353,7 @@ export default class TestRun extends AsyncEventEmitter {
 
         this.debugLog = new TestRunDebugLog(this.browserConnection.userAgent);
 
-        this.quarantine  = null;
+        this.quarantine = null;
 
         this.debugLogger = this.opts.debugLogger;
 
@@ -1308,6 +1311,9 @@ export default class TestRun extends AsyncEventEmitter {
             return await wrappedFn(this, args);
         }
 
+        if (command.type === COMMAND_TYPE.report)
+            return await this.reportDataLog.addData(command.args as any[]);
+
         if (command.type === COMMAND_TYPE.assertion)
             return this._executeAssertion(command as AssertionCommand, callsite as CallsiteRecord);
 

test/functional/fixtures/reporter/test.js

@@ -888,6 +888,61 @@ const experimentalDebug = !!process.env.EXPERIMENTAL_DEBUG;
         });
     });
 
+    describe('Report Data', () => {
+        let reportDataInfos = {};
+        let testDoneInfos   = {};
+        let reporter        = null;
+
+        const createReportDataReporter = () => {
+            return createReporter({
+                reportData: ({ browser }, ...data) => {
+                    const alias = browser.alias;
+
+                    if (!reportDataInfos[alias])
+                        reportDataInfos[alias] = [];
+
+                    reportDataInfos[alias].push(data);
+                },
+                reportTestDone: (name, { reportData, browsers }) => {
+                    browsers.forEach(({ testRunId, alias }) => {
+                        testDoneInfos[alias] = reportData[testRunId];
+                    });
+                },
+            });
+        };
+
+        beforeEach(() => {
+            reportDataInfos = {};
+            testDoneInfos   = {};
+
+            reporter = createReportDataReporter();
+        });
+
+        it('Should raise reportData twice with different argument count and types', async () => {
+            const expectedReportData = [1, true, 'string', { 'reportResult': 'test' }];
+
+            await runTests('testcafe-fixtures/report-data-test.js', 'Run t.report action with object val', {
+                reporter,
+            });
+
+            const reportDataBrowserInfos = Object.entries(reportDataInfos);
+            const testDoneBrowserInfos   = Object.entries(testDoneInfos);
+
+            expect(reportDataBrowserInfos.length).eql(config.browsers.length);
+            expect(testDoneBrowserInfos.length).eql(config.browsers.length);
+
+            reportDataBrowserInfos.forEach(([alias, reportData]) => {
+                expect(reportData.flat()).eql(testDoneInfos[alias]);
+            });
+
+            testDoneBrowserInfos.forEach(([, reportData]) => {
+                const [, ...rest] = reportData;
+
+                expect(rest).eql(expectedReportData);
+            });
+        });
+    });
+
     describe('Warnings', () => {
         let warningResult          = {};
         let reporter               = null;

test/functional/fixtures/reporter/testcafe-fixtures/index-test.js

@@ -25,6 +25,7 @@ async function errorCheck (t) {
 
 test('Simple test', async t => {
     await t.wait(1);
+    await t.report();
 });
 
 test('Simple command test', async t => {

test/functional/fixtures/reporter/testcafe-fixtures/report-data-test.js

@@ -0,0 +1,8 @@
+fixture`Report Data API`
+    .page('../pages/index.html');
+
+test('Run t.report action with object val', async t => {
+    await t
+        .report(t.browser.alias)
+        .report(1, true, 'string', { 'reportResult': 'test' });
+});