#9: Generalize extraReports into extensions

CHANGELOG.md

@@ -1,8 +1,8 @@
 ## Unreleased
 
 * Added:
-  * Support for `extraReports` in the reporters, which are printed after the
-    main report.
+  * Support for an `extensions` option in each reporter. Currently, this allows
+    printing extra reports after the main one.
 
 ## v0.7.0 (2021-10-08)
 

examples/jest/README.md

@@ -14,10 +14,12 @@
       instead of deleting it like normal. Default: false.
     * `printReportAtEnd` (boolean): Print the performance report at the end of the test run.
       Default: true.
-    * `extraReports` (array): Each item must be an object with the properties
-      `module` (passed to `require()`) and `callback` (a function name from the module).
-      The expected callback signature is `(benchmark: Benchmark) => string | void`.
-      They will be called after the main report and printed if they return something.
+    * `extensions` (array): Each item must be an object with the properties
+      `module` (passed to `require()`) and `extension` (name of an object from the module).
+      The named extension object may have these methods:
+
+      * `extraReport: (benchmark: Benchmark) => string | void` - This will be called after
+        the main report and printed if it returns something.
 * In `index.test.ts` or any other test file:
   * Call `benchmark.record()`.
 

examples/jest/extension.js

@@ -0,0 +1,16 @@
+const { Criteria } = require("kelonio");
+
+module.exports = {
+    extension: {
+        extraReport: benchmark => {
+            const fastest = benchmark.find(Criteria.Fastest);
+            if (fastest) {
+                return `
+= = Custom Report = =
+Fastest: "${fastest.description.join("/")}" (${fastest.mean} ms)
+= = = = = = = = = = =
+        `;
+            }
+        }
+    }
+};

examples/jest/jest.config.js

@@ -7,8 +7,8 @@ module.exports = {
                 keepStateAtStart: false,
                 keepStateAtEnd: false,
                 printReportAtEnd: true,
-                extraReports: [
-                    { module: `${__dirname}/kelonioExtra.js`, callback: "extraReport" },
+                extensions: [
+                    { module: `${__dirname}/extension.js`, extension: "extension" },
                 ],
             },
         ],

examples/karma/README.md

@@ -8,9 +8,14 @@
   * Enable (default) or disable browser inference. When enabled, the current
     browser name will be included in the performance report.
   * Enable (default) or disable printing the performance report at the end of the test run.
-  * Optionally configure some extra report callbacks
-    (of type `(benchmark: Benchmark) => string | void`),
-    which will be called after the main report and printed if they return something.
+  * Optionally configure some `extensions`.
+
+    Each item must be an object with the properties `module` (passed to `require()`)
+    and `extension` (name of an object from the module). The named extension object
+    may have these methods:
+
+    * `extraReport: (benchmark: Benchmark) => string | void` - This will be called after
+      the main report and printed if it returns something.
 * In `index.test.js` or any other test file:
   * Call `benchmark.record()`.
 

examples/karma/extension.js

@@ -0,0 +1,16 @@
+const { Criteria } = require("kelonio");
+
+module.exports = {
+    extension: {
+        extraReport: benchmark => {
+            const fastest = benchmark.find(Criteria.Fastest);
+            if (fastest) {
+                return `
+= = Custom Report = =
+Fastest: "${fastest.description.join("/")}" (${fastest.mean} ms)
+= = = = = = = = = = =
+        `;
+            }
+        }
+    }
+};

examples/karma/karma.conf.js

@@ -25,8 +25,8 @@ module.exports = config => {
         kelonioReporter: {
             inferBrowsers: true,
             printReportAtEnd: true,
-            extraReports: [
-                { module: `${__dirname}/kelonioExtra.js`, callback: "extraReport" },
+            extensions: [
+                { module: `${__dirname}/extension.js`, extension: "extension" },
             ],
         },
     });

examples/mocha/.mocha-multi.json

@@ -3,8 +3,8 @@
   "kelonioOutPluginMochaReporterReporterOptions": {
     "inferDescriptions": true,
     "printReportAtEnd": true,
-    "extraReports": [
-      {"module": "../examples/mocha/kelonioExtra.js", "callback": "extraReport"}
+    "extensions": [
+      {"module": "../examples/mocha/extension.js", "extension": "extension"}
     ]
   }
 }

examples/mocha/README.md

@@ -8,9 +8,14 @@
     in the performance report, in addition to any more specific descriptions
     that you pass to `benchmark.record()`.
   * Enable (default) or disable printing the performance report at the end of the test run.
-  * Optionally configure some extra report callbacks
-    (of type `(benchmark: Benchmark) => string | void`),
-    which will be called after the main report and printed if they return something.
+  * Optionally configure some `extensions`.
+
+    Each item must be an object with the properties `module` (passed to `require()`)
+    and `extension` (name of an object from the module). The named extension object
+    may have these methods:
+
+    * `extraReport: (benchmark: Benchmark) => string | void` - This will be called after
+      the main report and printed if it returns something.
 * In `index.test.ts` or any other test file:
   * Call `benchmark.record()`.
 

examples/mocha/extension.js

@@ -0,0 +1,16 @@
+const { Criteria } = require("kelonio");
+
+module.exports = {
+    extension: {
+        extraReport: benchmark => {
+            const fastest = benchmark.find(Criteria.Fastest);
+            if (fastest) {
+                return `
+= = Custom Report = =
+Fastest: "${fastest.description.join("/")}" (${fastest.mean} ms)
+= = = = = = = = = = =
+        `;
+            }
+        }
+    }
+};

src/reporters.ts

@@ -4,38 +4,38 @@ import { BenchmarkFileState } from "./etc";
 const MOCHA_EVENT_TEST_BEGIN = "test";
 const MOCHA_EVENT_RUN_END = "end";
 type KarmaLoggedRecord = { description: Array<string>, durations: Array<number> };
-type ExtraReportCallback = (benchmark: Benchmark) => string | void;
-type ExtraReports = Array<{ module: string, callback: string }>;
+type Extension = {
+    extraReport?: (benchmark: Benchmark) => string | void;
+};
+type ExtensionLookup = { module: string, extension: string };
 
 interface MochaReporterOptions {
     reporterOptions: {
         inferDescriptions?: boolean;
         printReportAtEnd?: boolean;
-        extraReports?: ExtraReports;
+        extensions?: Array<ExtensionLookup>;
     };
 }
 
 interface KarmaReporterOptions {
     inferBrowsers?: boolean;
     printReportAtEnd?: boolean;
-    extraReports?: ExtraReports;
+    extensions?: Array<ExtensionLookup>;
 }
 
 interface JestReporterOptions {
     keepStateAtStart?: boolean;
     keepStateAtEnd?: boolean;
     printReportAtEnd?: boolean;
-    extraReports?: ExtraReports;
+    extensions?: Array<ExtensionLookup>;
 }
 
-function handleExtraReports(extras: ExtraReports | undefined, benchmark: Benchmark, print: (report: string) => void): void {
-    for (const extra of (extras ?? [])) {
-        const callback: ExtraReportCallback | undefined = require(extra.module)?.[extra.callback];
-        if (callback) {
-            const report = callback(benchmark);
-            if (report) {
-                print(report);
-            }
+function handleExtraReports(lookups: Array<ExtensionLookup> | undefined, benchmark: Benchmark, print: (report: string) => void): void {
+    for (const lookup of (lookups ?? [])) {
+        const extension: Extension | undefined = require(lookup.module)?.[lookup.extension];
+        const report = extension?.extraReport?.(benchmark);
+        if (report) {
+            print(report);
         }
     }
 }
@@ -82,7 +82,7 @@ export class JestReporter implements jest.Reporter {
 
         if (this.options.printReportAtEnd) {
             console.log(`\n${b.report()}`);
-            handleExtraReports(this.options.extraReports, b, console.log);
+            handleExtraReports(this.options.extensions, b, console.log);
         }
 
         if (!this.options.keepStateAtEnd) {
@@ -117,7 +117,7 @@ export class KarmaReporter {
         this.onRunComplete = () => {
             if (activeConfig.printReportAtEnd) {
                 (<any>this).write(`${b.report()}\n`);
-                handleExtraReports(activeConfig.extraReports, b, msg => (<any>this).write(`${msg}\n`));
+                handleExtraReports(activeConfig.extensions, b, msg => (<any>this).write(`${msg}\n`));
             }
         };
     }
@@ -129,7 +129,7 @@ export class MochaReporter {
         let baseDescription: Array<string> = [];
         const inferDescriptions = options.reporterOptions.inferDescriptions ?? true;
         const printReportAtEnd = options.reporterOptions.printReportAtEnd ?? true;
-        const extraReports = options.reporterOptions.extraReports ?? [];
+        const extensions = options.reporterOptions.extensions ?? [];
 
         benchmark.events.on("record", (description, measurement) => {
             b.incorporate(baseDescription.concat(description), measurement);
@@ -142,7 +142,7 @@ export class MochaReporter {
         runner.once(MOCHA_EVENT_RUN_END, () => {
             if (printReportAtEnd) {
                 console.log(`\n${b.report()}`);
-                handleExtraReports(extraReports, b, console.log);
+                handleExtraReports(extensions, b, console.log);
             }
         });
     }

tests/extension.js

@@ -0,0 +1,12 @@
+const { Criteria } = require("kelonio");
+
+module.exports = {
+    extension: {
+        extraReport: benchmark => {
+            const fastest = benchmark.find(Criteria.Fastest);
+            if (fastest) {
+                return `Fastest: "${fastest.description.join("/")}" (${fastest.mean} ms)`;
+            }
+        },
+    },
+};

tests/reporters.test.ts

@@ -236,9 +236,9 @@ describe("JestReporter", () => {
                 expect(spy.mock.calls).toEqual([]);
             });
 
-            it("respects extraReports", () => {
+            it("handles extensions that print extra reports", () => {
                 JestReporter.initializeKelonio();
-                const reporter = new JestReporter({}, { extraReports: [{ module: `${__dirname}/kelonioExtra.js`, callback: "extraReport" }] });
+                const reporter = new JestReporter({}, { extensions: [{ module: `${__dirname}/extension.js`, extension: "extension" }] });
                 const spy = jest.spyOn(console, "log");
                 fs.writeFileSync(STATE_FILE, JSON.stringify({
                     foo: {
@@ -309,8 +309,8 @@ describe("KarmaReporter", () => {
         expect(writer.mock.calls).toEqual([]);
     });
 
-    it("prints extra reports when enabled", () => {
-        [writer, reporter] = makeKarmaReporter({ kelonioReporter: { extraReports: [{ module: `${__dirname}/kelonioExtra.js`, callback: "extraReport" }] } });
+    it("handles extensions that print extra reports", () => {
+        [writer, reporter] = makeKarmaReporter({ kelonioReporter: { extensions: [{ module: `${__dirname}/extension.js`, extension: "extension" }] } });
 
         // @ts-ignore
         reporter.onBrowserLog("any", `'{"description":["foo"],"durations":[1,2,3]}'`, "kelonio");
@@ -366,8 +366,8 @@ describe("MochaReporter", () => {
         expect(spy.mock.calls).toEqual([]);
     });
 
-    it("prints extra reports when enabled", () => {
-        const [runner, reporter] = makeMochaReporter({ extraReports: [{ module: `${__dirname}/kelonioExtra.js`, callback: "extraReport" }] });
+    it("handles extensions that print extra reports", () => {
+        const [runner, reporter] = makeMochaReporter({ extensions: [{ module: `${__dirname}/extension.js`, extension: "extension" }] });
         const spy = jest.spyOn(console, "log");
 
         runner.emit("test", { titlePath: () => ["A", "B"] });