@serenity-js/console-reporter 3.0.0-rc.9 → 3.0.1

package/README.md

@@ -1,14 +1,16 @@
 # Serenity/JS
 
-[Serenity/JS](https://serenity-js.org) is a framework designed to make acceptance and regression testing
-of modern full-stack applications faster, more collaborative and easier to scale.
+[![Follow Serenity/JS on LinkedIn](https://img.shields.io/badge/Follow-Serenity%2FJS%20-0077B5?logo=linkedin)](https://www.linkedin.com/company/serenity-js)
+[![Watch Serenity/JS on YouTube](https://img.shields.io/badge/Watch-@serenity--js-E62117?logo=youtube)](https://www.youtube.com/@serenity-js)
+[![Join Serenity/JS Community Chat](https://img.shields.io/badge/Chat-Serenity%2FJS%20Community-FBD30B?logo=matrix)](https://matrix.to/#/#serenity-js:gitter.im)
+[![Support Serenity/JS on GitHub](https://img.shields.io/badge/Support-@serenity--js-703EC8?logo=github)](https://github.com/sponsors/serenity-js)
 
-## Serenity/JS Console Reporter
+[Serenity/JS](https://serenity-js.org) is an innovative framework designed to make acceptance and regression testing
+of complex software systems faster, more collaborative and easier to scale.
 
-`@serenity-js/console-reporter` module reports progress of your Serenity/JS tests to the terminal.
+To get started, check out the comprehensive [Serenity/JS Handbook](https://serenity-js.org/handbook), [API documentation](https://serenity-js.org/api/core), and [Serenity/JS project templates on GitHub](https://serenity-js.org/handbook/getting-started#serenityjs-project-templates).
 
-`ConsoleReporter` supports both colour and monochromatic output, as well as simple colour themes for terminals
-with dark and light backgrounds.
+If you have any questions or just want to say hello, join the [Serenity/JS Community Chat](https://matrix.to/#/#serenity-js:gitter.im).
 
 ### Installation
 
@@ -27,41 +29,110 @@ instead of `cmd.exe` to benefit from the colour output.
 
 To allow Serenity/JS to print the progress report to standard output, assign the `ConsoleReporter` to the `Stage`.
 
-This can be done in your `protractor.conf.js` file if you're using Protractor, or programmatically.
+This can be done:
+- via `playwright.config.ts`, if you're using Serenity/JS with [Playwright Test](https://serenity-js.org/api/playwright-test)
+- via `wdio.conf.ts`, if you're using Serenity/JS with [WebdriverIO](https://serenity-js.org/api/playwright-test)
+- via `protractor.conf.js`, if you're using Serenity/JS with [Protractor](https://serenity-js.org/api/protractor)
+- or programmatically.
 
-#### Programmatic configuration
+#### Usage with Playwright Test
 
-```typescript
-import { configure } from '@serenity-js/core';
-import { ConsoleReporter } from '@serenity-js/console-reporter';
+Learn more about using [Serenity/JS with Playwright Test](https://serenity-js.org/api/playwright-test).
 
-configure({
-    crew: [
-        ConsoleReporter.withDefaultColourSupport(),
+```typescript
+// playwright.config.ts
+import type { PlaywrightTestConfig } from '@serenity-js/playwright-test';
+
+const config: PlaywrightTestConfig = {
+    reporter: [
+        [ '@serenity-js/playwright-test', {
+            crew: [
+                // console reporter with default settings
+                '@serenity-js/console-reporter',
+                
+                // console reporter with a theme for 'dark', 'light' or 'mono' terminals
+                // [ '@serenity-js/console-reporter', { theme: 'auto' } ]                
+            ]
+        }]
     ],
-});
+
+    // Other configuration omitted for brevity
+    // For details, see https://playwright.dev/docs/test-configuration    
+};
+
+export default config;
 ```
 
-#### Protractor
+#### Usage with WebdriverIO
+
+Learn more about using [Serenity/JS with WebdriverIO](https://serenity-js.org/api/webdriverio).
+
+```typescript
+// wdio.conf.ts
+
+import { WebdriverIOConfig } from '@serenity-js/webdriverio';
+
+export const config: WebdriverIOConfig = {
+
+    framework: '@serenity-js/webdriverio',
+
+    serenity: {
+        crew: [
+            // console reporter with default settings
+            '@serenity-js/console-reporter',
+
+            // console reporter with a theme for 'dark', 'light' or 'mono' terminals
+            // [ '@serenity-js/console-reporter', { theme: 'auto' } ]  
+        ]
+    },
+
+    // Other configuration omitted for brevity
+    // For details, see https://webdriver.io/docs/options
+};
+```
+
+#### Usage with Protractor
+
+Learn more about using [Serenity/JS with Protractor](https://serenity-js.org/api/protractor).
 
 ```javascript
 // protractor.conf.js
 
-const { ConsoleReporter } = require('@serenity-js/console-reporter');
-
 exports.config = {
-  framework:      'custom',
-    frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
+
+    framework:      'custom',
+    frameworkPath:  require.resolve('@serenity-js/protractor/adapter'),
+
     serenity: {
-      crew: [
-        ConsoleReporter.withDefaultColourSupport(),
-      ],
-      // other Serenity/JS config
+        crew: [
+            // console reporter with default settings
+            '@serenity-js/console-reporter',
+
+            // console reporter with a theme for 'dark', 'light' or 'mono' terminals
+            // [ '@serenity-js/console-reporter', { theme: 'auto' } ]  
+        ]
     },
-    // other Protractor config
- };
+
+    // ...
+}
+```
+
+#### Programmatic configuration
+
+Learn more about [configuring Serenity/JS programmatically](https://serenity-js.org/api/core/class/SerenityConfig).
+
+```typescript
+import { configure } from '@serenity-js/core';
+import { ConsoleReporter } from '@serenity-js/console-reporter';
+
+configure({
+    crew: [
+        ConsoleReporter.withDefaultColourSupport(),
+    ],
+});
 ```
 
 #### Colour Themes
 
-Consult the API docs of the `ConsoleReporter` class to learn more about the supported colour themes.
+Consult the API docs of the [`ConsoleReporter`](/api/console-reporter/class/ConsoleReporter) class
+to learn more about the supported colour themes.

package/lib/index.d.ts

@@ -1 +1,5 @@
+import { StageCrewMemberBuilder } from '@serenity-js/core';
+import { ConsoleReporter, ConsoleReporterConfig } from './stage';
 export * from './stage';
+export default function create(config?: ConsoleReporterConfig): StageCrewMemberBuilder<ConsoleReporter>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAEjE,cAAc,SAAS,CAAC;AAGxB,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,MAAM,GAAE,qBAAiC,GAAG,sBAAsB,CAAC,eAAe,CAAC,CAEjH"}

package/lib/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
@@ -10,5 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const stage_1 = require("./stage");
 __exportStar(require("./stage"), exports);
+// eslint-disable-next-line unicorn/no-useless-undefined
+function create(config = undefined) {
+    return stage_1.ConsoleReporter.fromJSON(config || { theme: 'auto' });
+}
+exports.default = create;
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAEA,mCAAiE;AAEjE,0CAAwB;AAExB,wDAAwD;AACxD,SAAwB,MAAM,CAAC,SAAgC,SAAS;IACpE,OAAO,uBAAe,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;AACjE,CAAC;AAFD,yBAEC"}

package/lib/stage/crew/console-reporter/ConsoleReporter.d.ts

@@ -1,25 +1,32 @@
 import { ListensToDomainEvents, Stage, StageCrewMemberBuilder } from '@serenity-js/core';
 import { DomainEvent } from '@serenity-js/core/lib/events';
+import { ConsoleReporterConfig } from './ConsoleReporterConfig';
 import { Printer } from './Printer';
 import { TerminalTheme } from './themes';
 /**
- * @desc
- *  Uses [standard output](https://en.wikipedia.org/wiki/Standard_streams)
- *  to report on progress of your Serenity/JS acceptance tests.
+ * A {@apilink StageCrewMember} that uses [standard output](https://en.wikipedia.org/wiki/Standard_streams)
+ * to report on progress of your Serenity/JS acceptance tests.
  *
- *  `ConsoleReporter` ships with colour themes for both dark and light terminals,
- *  as well as a monochromatic theme for those moments when you're in a noir mood
- *  (or have a terminal that doesn't support colours, like the good old `cmd.exe` on Windows).
+ * `ConsoleReporter` ships with colour themes for both dark and light terminals,
+ * as well as a monochromatic theme for those moments when you're in a noir mood
+ * (or have a terminal that doesn't support colours, like the good old `cmd.exe` on Windows).
  *
- * @example <caption>Registering the reporter programmatically</caption>
+ * ## Registering the reporter programmatically
+ *
+ * ```ts
  *  import { configure } from '@serenity-js/core';
  *  import { ConsoleReporter } from '@serenity-js/console-reporter';
  *
  *  configure({
- *      crew: [ ConsoleReporter.withDefaultColourSupport() ],
+ *    crew: [
+ *      ConsoleReporter.withDefaultColourSupport()
+ *    ],
  *  });
+ * ```
  *
- * @example <caption>Redirecting output to a file</caption>
+ * ## Redirecting output to a file
+ *
+ * ```ts
  *  import { configure } from '@serenity-js/core';
  *  import { ConsoleReporter } from '@serenity-js/console-reporter';
  *  import { createWriteStream } from 'fs';
@@ -28,27 +35,53 @@ import { TerminalTheme } from './themes';
  *      outputStream: createWriteStream('./output.log'),
  *      crew: [ ConsoleReporter.withDefaultColourSupport() ],
  *  });
+ *  ```
+ * ## Registering the reporter with WebdriverIO
+ *
+ * ```ts
+ * // wdio.conf.ts
+ * import { ConsoleReporter } from '@serenity-js/console-reporter';
+ * import { WebdriverIOConfig } from '@serenity-js/webdriverio';
+ *
+ * export const config: WebdriverIOConfig = {
+ *
+ *   framework: '@serenity-js/webdriverio',
+ *
+ *   serenity: {
+ *     crew: [
+ *       ConsoleReporter.forDarkTerminals(),
+ *     ]
+ *     // other Serenity/JS config
+ *   },
+ *
+ *  // other WebdriverIO config
+ * }
+ * ```
  *
- * @example <caption>Registering the reporter using Protractor configuration</caption>
- *  // protractor.conf.js
- *  const { ConsoleReporter } = require('@serenity-js/console-reporter');
+ * ## Registering the reporter with Protractor
  *
- *  exports.config = {
- *    framework:     'custom',
- *    frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
+ * ```js
+ * // protractor.conf.js
+ * const { ConsoleReporter } = require('@serenity-js/console-reporter');
  *
- *    serenity: {
- *      crew: [
- *        ConsoleReporter.withDefaultColourSupport(),
- *      ],
- *      // other Serenity/JS config
- *    },
+ * exports.config = {
+ *   framework:     'custom',
+ *   frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
  *
- *    // other Protractor config
- *  };
+ *   serenity: {
+ *     crew: [
+ *       ConsoleReporter.withDefaultColourSupport(),
+ *     ],
+ *     // other Serenity/JS config
+ *   },
+ *
+ *   // other Protractor config
+ * }
+ * ```
  *
  * @public
- * @implements {@serenity-js/core/lib/stage~ListensToDomainEvents}
+ *
+ * @group Stage
  */
 export declare class ConsoleReporter implements ListensToDomainEvents {
     private readonly printer;
@@ -57,68 +90,59 @@ export declare class ConsoleReporter implements ListensToDomainEvents {
     private startTimes;
     private artifacts;
     private summary;
-    private firstError;
+    private readonly firstErrors;
     private readonly summaryFormatter;
+    private readonly eventQueues;
+    static fromJSON(config: ConsoleReporterConfig): StageCrewMemberBuilder<ConsoleReporter>;
     /**
-     * @desc
-     *  Instantiates a `ConsoleReporter` that auto-detects
-     *  your terminal's support for colours and use a colour theme
-     *  for dark terminals if successful.
-     *
-     *  Please note that spawning your test process from another process
-     *  (by using [npm-failsafe](https://www.npmjs.com/package/npm-failsafe), for example)
-     *  causes the `ConsoleReporter` to use the monochromatic colour scheme,
-     *  as colour support can't be detected in child processes.
-     *
-     *  If the above describes your setup, use {@link ConsoleReporter#forDarkTerminals}
-     *  or {@link ConsoleReporter#forLightTerminals} to make the sub-process produce colour output.
+     * Instantiates a `ConsoleReporter` that auto-detects
+     * your terminal's support for colours and uses a colour theme
+     * for dark terminals if successful.
      *
-     * @returns {@serenity-js/core/lib/stage~StageCrewMemberBuilder}
+     * Please note that spawning your test process from another process
+     * (by using [npm-failsafe](https://www.npmjs.com/package/npm-failsafe), for example)
+     * causes the `ConsoleReporter` to use the monochromatic colour scheme,
+     * as colour support can't be detected in child processes.
      */
     static withDefaultColourSupport(): StageCrewMemberBuilder<ConsoleReporter>;
     /**
-     * @desc
-     *  Instantiates a `ConsoleReporter` with a monochromatic colour theme.
-     *  Good for terminals with no colour support (like the `cmd.exe` on Windows),
-     *  or for when you need to pipe the output to a text file and want
-     *  to avoid printing control characters.
-     *
-     * @returns {@serenity-js/core/lib/stage~StageCrewMemberBuilder}
+     * Instantiates a `ConsoleReporter` with a monochromatic colour theme.
+     * Good for terminals with no colour support (like the `cmd.exe` on Windows),
+     * or for times when you need to pipe the output to a text file and want
+     * to avoid printing control characters.
      */
     static forMonochromaticTerminals(): StageCrewMemberBuilder<ConsoleReporter>;
     /**
-     * @desc
-     *  Instantiates a `ConsoleReporter` with a colour theme optimised for terminals with dark backgrounds.
-     *
-     * @returns {@serenity-js/core/lib/stage~StageCrewMemberBuilder}
+     * Instantiates a `ConsoleReporter` with a colour theme optimised for terminals with dark backgrounds.
      */
     static forDarkTerminals(): StageCrewMemberBuilder<ConsoleReporter>;
     /**
-     * @desc
-     *  Instantiates a `ConsoleReporter` with a colour theme optimised for terminals with light backgrounds.
-     *
-     * @returns {@serenity-js/core/lib/stage~StageCrewMemberBuilder}
+     * Instantiates a `ConsoleReporter` with a colour theme optimised for terminals with light backgrounds.
      */
     static forLightTerminals(): StageCrewMemberBuilder<ConsoleReporter>;
+    private static theme;
     /**
      * @param {Printer} printer
      * @param {TerminalTheme} theme
-     * @param {@serenity-js/core/lib/stage~Stage} [stage=null]
+     * @param {Stage} [stage=undefined]
      */
     constructor(printer: Printer, theme: TerminalTheme, stage?: Stage);
     /**
-     * @desc
-     *  Handles {@link @serenity-js/core/lib/events~DomainEvent} objects emitted by the {@link @serenity-js/core/lib/stage~StageCrewMember}.
+     * Handles {@apilink DomainEvent} objects emitted by the {@apilink Stage}.
      *
-     * @see {@link @serenity-js/core/lib/stage~StageCrewMember}
+     * @see {@apilink StageCrewMember}
      *
-     * @listens {@serenity-js/core/lib/events~DomainEvent}
+     * @listens {DomainEvent}
      *
-     * @param {@serenity-js/core/lib/events~DomainEvent} event
-     * @returns {void}
+     * @param {DomainEvent} event
      */
     notifyOf(event: DomainEvent): void;
+    private printTestRunErrorOutcome;
+    private printScene;
+    private printSummary;
+    private isSceneSpecific;
     private formattedOutcome;
     private deCamelCased;
     private iconFrom;
 }
+//# sourceMappingURL=ConsoleReporter.d.ts.map

package/lib/stage/crew/console-reporter/ConsoleReporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsoleReporter.d.ts","sourceRoot":"","sources":["../../../../src/stage/crew/console-reporter/ConsoleReporter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkD,qBAAqB,EAAc,KAAK,EAAE,sBAAsB,EAAa,MAAM,mBAAmB,CAAC;AAEhK,OAAO,EAEH,WAAW,EASd,MAAM,8BAA8B,CAAC;AAkBtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,aAAa,EAAiF,MAAM,UAAU,CAAC;AAExH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,qBAAa,eAAgB,YAAW,qBAAqB;IAsErD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IAtE3B,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2B;IAEvD,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,GAAG,sBAAsB,CAAC,eAAe,CAAC;IAIvF;;;;;;;;;OASG;IACH,MAAM,CAAC,wBAAwB,IAAI,sBAAsB,CAAC,eAAe,CAAC;IAI1E;;;;;OAKG;IACH,MAAM,CAAC,yBAAyB,IAAI,sBAAsB,CAAC,eAAe,CAAC;IAI3E;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,sBAAsB,CAAC,eAAe,CAAC;IAIlE;;OAEG;IACH,MAAM,CAAC,iBAAiB,IAAI,sBAAsB,CAAC,eAAe,CAAC;IAInE,OAAO,CAAC,MAAM,CAAC,KAAK;IAapB;;;;OAIG;gBAEkB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,aAAa,EACpB,KAAK,CAAC,EAAE,KAAK;IAQlC;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IA+BlC,OAAO,CAAC,wBAAwB;IAIhC,OAAO,CAAC,UAAU;IAmIlB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,QAAQ;CAkBnB"}