@serenity-js/webdriverio 3.0.0-rc.9 → 3.0.1

package/src/adapter/WebdriverIOConfig.ts

@@ -2,121 +2,126 @@ import { SerenityConfig } from '@serenity-js/core';
 import type { Options } from '@wdio/types';
 
 /**
- * @desc
- *  [WebdriverIO configuration object](https://webdriver.io/docs/configurationfile/)
- *  with Serenity/JS-specific additions.
- *
- * @see {@link @serenity-js/cucumber/lib/cli~CucumberConfig}
- * @see {@link @serenity-js/jasmine/lib/adapter~JasmineConfig}
- * @see {@link @serenity-js/mocha/lib/adapter~MochaConfig}
- *
- * @see https://webdriver.io/docs/configurationfile/
- * @see {@link @wdio/types~Options.TestRunner}
- *
- * @public
- *
- * @extends {@wdio/types~Options.TestRunner}
- *
- * @example <caption>WebdriverIO with Serenity/JS and Cucumber</caption>
- *
- *  import { ConsoleReporter } from '@serenity-js/console-reporter';
- *  import { ArtifactArchiver } from '@serenity-js/core';
- *  import { SerenityBDDReporter } from '@serenity-js/serenity-bdd';
- *  import { WebdriverIOConfig } from '@serenity-js/webdriverio';
- *
- *  export const config: WebdriverIOConfig = {
- *
- *    framework: '@serenity-js/webdriverio',
- *
- *    serenity: {
- *        runner: 'cucumber',
- *        crew: [
- *            ConsoleReporter.forDarkTerminals(),
- *            new SerenityBDDReporter(),
- *            ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
- *        ]
- *    },
- *
- *    cucumberOpts: {
- *        // ...
- *    },
- *
- *    specs: [
- *        './features/*.feature',
- *    ],
- * };
- *
- * @example <caption>WebdriverIO with Serenity/JS and Mocha</caption>
- *
- *  import { ConsoleReporter } from '@serenity-js/console-reporter';
- *  import { ArtifactArchiver } from '@serenity-js/core';
- *  import { SerenityBDDReporter } from '@serenity-js/serenity-bdd';
- *  import { WebdriverIOConfig } from '@serenity-js/webdriverio';
- *
- *  export const config: WebdriverIOConfig = {
- *
- *    framework: '@serenity-js/webdriverio',
- *
- *    serenity: {
- *        runner: 'mocha',
- *        crew: [
- *            ConsoleReporter.forDarkTerminals(),
- *            new SerenityBDDReporter(),
- *            ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
- *        ]
- *    },
- *
- *    mochaOpts: {
- *        // ...
- *    },
- *
- *    specs: [
- *        './spec/*.spec.*',
- *    ],
- * };
- *
- * @example <caption>WebdriverIO with Serenity/JS and Jasmine</caption>
- *
- *  import { ConsoleReporter } from '@serenity-js/console-reporter';
- *  import { ArtifactArchiver } from '@serenity-js/core';
- *  import { SerenityBDDReporter } from '@serenity-js/serenity-bdd';
- *  import { WebdriverIOConfig } from '@serenity-js/webdriverio';
- *
- *  export const config: WebdriverIOConfig = {
- *
- *    framework: '@serenity-js/webdriverio',
- *
- *    serenity: {
- *        runner: 'jasmine',
- *        crew: [
- *            ConsoleReporter.forDarkTerminals(),
- *            new SerenityBDDReporter(),
- *            ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
- *        ]
- *    },
- *
- *    jasmineOpts: {
- *        // ...
- *    },
- *
- *    specs: [
- *        './spec/*.spec.*',
- *    ],
- * };
+ * [WebdriverIO configuration object](https://webdriver.io/docs/configurationfile/)
+ * with Serenity/JS-specific {@apilink SerenityConfig|additions}.
+ *
+ * ## Configuring WebdriverIO with Serenity/JS and Cucumber
+ *
+ * ```ts
+ * // wdio.conf.ts
+ * import { ConsoleReporter } from '@serenity-js/console-reporter'
+ * import { ArtifactArchiver } from '@serenity-js/core'
+ * import { SerenityBDDReporter } from '@serenity-js/serenity-bdd'
+ * import { WebdriverIOConfig } from '@serenity-js/webdriverio'
+ *
+ * export const config: WebdriverIOConfig = {
+ *
+ *   framework: '@serenity-js/webdriverio',
+ *
+ *   serenity: {
+ *     runner: 'cucumber',
+ *     crew: [
+ *       ConsoleReporter.forDarkTerminals(),
+ *       new SerenityBDDReporter(),
+ *       ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
+ *     ]
+ *   },
+ *
+ *   cucumberOpts: {
+ *     // ...
+ *   },
+ *
+ *   specs: [
+ *     './features/*.feature',
+ *   ],
+ * }
+ * ```
+ *
+ * ## Configuring WebdriverIO with Serenity/JS and Mocha
+ *
+ * ```ts
+ * // wdio.conf.ts
+ * import { ConsoleReporter } from '@serenity-js/console-reporter'
+ * import { ArtifactArchiver } from '@serenity-js/core'
+ * import { SerenityBDDReporter } from '@serenity-js/serenity-bdd'
+ * import { WebdriverIOConfig } from '@serenity-js/webdriverio'
+ *
+ * export const config: WebdriverIOConfig = {
+ *
+ *   framework: '@serenity-js/webdriverio',
+ *
+ *   serenity: {
+ *     runner: 'mocha',
+ *     crew: [
+ *       ConsoleReporter.forDarkTerminals(),
+ *       new SerenityBDDReporter(),
+ *       ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
+ *     ]
+ *   },
+ *
+ *   mochaOpts: {
+ *     // ...
+ *   },
+ *
+ *   specs: [
+ *     './spec/*.spec.*',
+ *   ],
+ * }
+ * ```
+ *
+ * ## Configuring WebdriverIO with Serenity/JS and Jasmine
+ *
+ * ```ts
+ * // wdio.conf.ts
+ * import { ConsoleReporter } from '@serenity-js/console-reporter'
+ * import { ArtifactArchiver } from '@serenity-js/core'
+ * import { SerenityBDDReporter } from '@serenity-js/serenity-bdd'
+ * import { WebdriverIOConfig } from '@serenity-js/webdriverio'
+ *
+ * export const config: WebdriverIOConfig = {
+ *
+ *   framework: '@serenity-js/webdriverio',
+ *
+ *   serenity: {
+ *     runner: 'jasmine',
+ *     crew: [
+ *       ConsoleReporter.forDarkTerminals(),
+ *       new SerenityBDDReporter(),
+ *       ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
+ *     ]
+ *   },
+ *
+ *   jasmineOpts: {
+ *     // ...
+ *   },
+ *
+ *   specs: [
+ *     './spec/*.spec.*',
+ *   ],
+ * }
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [WebdriverIO configuration file](https://webdriver.io/docs/configurationfile/)
+ * - {@apilink CucumberConfig}
+ * - {@apilink JasmineConfig}
+ * - {@apilink MochaConfig}
+ *
+ * @group Configuration
  */
 export interface WebdriverIOConfig extends Options.Testrunner {
 
     /**
-     * @desc
-     *  Serenity/JS configuration with an additional `runner` entry
-     *  allowing to specify the test runner, such as `cucumber`, `mocha`, or `jasmine`.
+     * Serenity/JS configuration with an additional `runner` entry
+     * allowing to specify the test runner, such as `cucumber`, `mocha`, or `jasmine`.
      *
-     * @see {@link @serenity-js/cucumber/lib/cli~CucumberConfig}
-     * @see {@link @serenity-js/jasmine/lib/adapter~JasmineConfig}
-     * @see {@link @serenity-js/mocha/lib/adapter~MochaConfig}
+     * #### Learn more
      *
-     * @type {@serenity-js/core~SerenityConfig}
-     * @public
+     * - [WebdriverIO configuration file](https://webdriver.io/docs/configurationfile/)
+     * - {@apilink CucumberConfig}
+     * - {@apilink JasmineConfig}
+     * - {@apilink MochaConfig}
      */
     serenity?: SerenityConfig & { runner?: string };
 }

package/src/adapter/WebdriverIOFrameworkAdapter.ts

@@ -1,9 +1,11 @@
-import { ArtifactArchiver, Serenity } from '@serenity-js/core';
-import { ModuleLoader, Path, TestRunnerAdapter } from '@serenity-js/core/lib/io';
+import { AnsiDiffFormatter, ArtifactArchiver, Cast, Serenity, TakeNotes } from '@serenity-js/core';
+import { TestRunnerAdapter } from '@serenity-js/core/lib/adapter';
+import { ModuleLoader, Path } from '@serenity-js/core/lib/io';
 import type { Capabilities } from '@wdio/types';
 import type { EventEmitter } from 'events';
-import { isPlainObject } from 'is-plain-object';
+import { isRecord } from 'tiny-types/lib/objects';
 
+import { BrowseTheWebWithWebdriverIO } from '../screenplay';
 import { BrowserCapabilitiesReporter, InitialisesReporters, OutputStreamBuffer, ProvidesWriteStream } from './reporter';
 import { OutputStreamBufferPrinter } from './reporter/OutputStreamBufferPrinter';
 import { TestRunnerLoader } from './TestRunnerLoader';
@@ -11,9 +13,6 @@ import { WebdriverIOConfig } from './WebdriverIOConfig';
 import { WebdriverIONotifier } from './WebdriverIONotifier';
 import deepmerge = require('deepmerge');
 
-/**
- * @package
- */
 export class WebdriverIOFrameworkAdapter {
 
     private adapter: TestRunnerAdapter;
@@ -30,9 +29,15 @@ export class WebdriverIOFrameworkAdapter {
         reporter: EventEmitter & ProvidesWriteStream & InitialisesReporters
     ) {
         const config = deepmerge<WebdriverIOConfig>(this.defaultConfig(), webdriverIOConfig, {
-            isMergeableObject: isPlainObject,
+            isMergeableObject: isRecord,
         });
 
+        // SauceLabs service serialises the config object for debugging.
+        // However, since Serenity/JS Stage is a pub/sub mechanism,
+        // it contains cyclic references which are not serialisable.
+        // We get rid of them from the config object to avoid confusing other services.
+        delete webdriverIOConfig.serenity;
+
         this.adapter = new TestRunnerLoader(this.loader, this.cwd, this.cid)
             .runnerAdapterFor(config);
 
@@ -64,7 +69,11 @@ export class WebdriverIOFrameworkAdapter {
         this.serenity.configure({
             outputStream:   outputStreamBuffer,
             cueTimeout:     config.serenity.cueTimeout,
-            actors:         config.serenity.actors,
+            actors:         config.serenity.actors || Cast.where(actor => actor.whoCan(
+                BrowseTheWebWithWebdriverIO.using(browser),
+                TakeNotes.usingAnEmptyNotepad(),
+            )),
+            diffFormatter:  config.serenity.diffFormatter ?? new AnsiDiffFormatter(),
             crew: [
                 ...config.serenity.crew,
                 this.notifier,
@@ -84,10 +93,9 @@ export class WebdriverIOFrameworkAdapter {
         return this.adapter.scenarioCount() > 0;
     }
 
-    run(): Promise<number> {
-        return this.adapter.run().then(() =>
-            this.notifier.failureCount()
-        );
+    async run(): Promise<number> {
+        await this.adapter.run();
+        return this.notifier.failureCount();
     }
 
     private defaultConfig(): Partial<WebdriverIOConfig> {

package/src/adapter/WebdriverIOFrameworkAdapterFactory.ts

@@ -8,7 +8,7 @@ import { WebdriverIOConfig } from './WebdriverIOConfig';
 import { WebdriverIOFrameworkAdapter } from './WebdriverIOFrameworkAdapter';
 
 /**
- * @package
+ * @group Test Runner Adapter
  */
 export class WebdriverIOFrameworkAdapterFactory {
     constructor(

package/src/adapter/WebdriverIONotifier.ts

@@ -8,7 +8,7 @@ import {
     ExecutionFailedWithError,
     ExecutionIgnored,
     ExecutionSkipped,
-    ImplementationPending,
+    ImplementationPending, Name,
     Outcome,
     ProblemIndication,
     TestSuiteDetails,
@@ -391,15 +391,17 @@ export class WebdriverIONotifier implements StageCrewMember {
         args: InnerArguments
     ): Promise<Array<Result | Error>> {
 
-        const hooks = ! Array.isArray(hookFunctions)
-            ? [ hookFunctions ]
-            : hookFunctions;
+        const hooks = Array.isArray(hookFunctions)
+            ? hookFunctions
+            : [ hookFunctions ];
 
         const asyncOperationId = CorrelationId.create();
 
         this.stage.announce(new AsyncOperationAttempted(
-            new Description(`[WebdriverIONotifier#invokeHooks] Invoking ${ hookName } hook`),
+            new Name(`WebdriverIONotifier#invokeHooks`),
+            new Description(`Invoking ${ hookName } hook`),
             asyncOperationId,
+            this.stage.currentTime(),
         ));
 
         return Promise.all(hooks.map((hook) => new Promise<Result | Error>((resolve) => {
@@ -426,8 +428,8 @@ export class WebdriverIONotifier implements StageCrewMember {
         then(results => {
 
             this.stage.announce(new AsyncOperationCompleted(
-                new Description(`[WebdriverIONotifier#invokeHooks] Invoking ${ hookName } hook completed`),
                 asyncOperationId,
+                this.stage.currentTime(),
             ));
 
             return results;

package/src/adapter/index.ts

@@ -1,3 +1,2 @@
-export * from './TestRunnerLoader';
 export * from './WebdriverIOConfig';
 export * from './WebdriverIOFrameworkAdapterFactory';

package/src/adapter/reporter/OutputStreamBuffer.ts

@@ -1,4 +1,4 @@
-import { OutputStream } from '@serenity-js/core/lib/io';
+import { OutputStream } from '@serenity-js/core/lib/adapter';
 
 /**
  * @package

package/src/adapter/reporter/OutputStreamBufferPrinter.ts

@@ -1,6 +1,6 @@
 import { Stage, StageCrewMember } from '@serenity-js/core';
+import { OutputStream } from '@serenity-js/core/lib/adapter';
 import { DomainEvent, SceneFinished } from '@serenity-js/core/lib/events';
-import { OutputStream } from '@serenity-js/core/lib/io';
 
 import { OutputStreamBuffer } from './OutputStreamBuffer';
 

package/src/adapter/reporter/ProvidesWriteStream.ts

@@ -1,4 +1,4 @@
-import { OutputStream } from '@serenity-js/core/lib/io';
+import { OutputStream } from '@serenity-js/core/lib/adapter';
 
 /**
  * @package