@serenity-js/webdriverio-8 3.31.0

package/src/adapter/TestRunnerLoader.ts

@@ -0,0 +1,90 @@
+import { ConfigurationError } from '@serenity-js/core';
+import type { TestRunnerAdapter } from '@serenity-js/core/lib/adapter/index.js';
+import type { ModuleLoader} from '@serenity-js/core/lib/io/index.js';
+import { Config, FileFinder, FileSystem, Path } from '@serenity-js/core/lib/io/index.js';
+
+import type { WebdriverIOConfig } from '../config/index.js';
+
+// We define TestRunnerOptions to avoid importing the global WebdriverIO namespace.
+// WebdriverIO v8 doesn't offer any more precise type declarations anyway.
+interface TestRunnerOptions {
+    [key: string]: any;
+}
+
+export class TestRunnerLoader {
+    private readonly fileSystem: FileSystem;
+    private readonly finder: FileFinder;
+
+    constructor(
+        private readonly loader: ModuleLoader,
+        private readonly cwd: Path,
+        private readonly cid: string,
+    ) {
+        this.fileSystem = new FileSystem(cwd);
+        this.finder     = new FileFinder(cwd);
+    }
+
+    runnerAdapterFor(config: WebdriverIOConfig): TestRunnerAdapter {
+        switch (config?.serenity?.runner) {
+            case 'cucumber':
+                return this.cucumberAdapter(config?.cucumberOpts);
+
+            case 'jasmine':
+                return this.jasmineAdapter(config?.jasmineOpts);
+
+            case 'mocha':
+            case undefined:
+                return this.mochaAdapter(config?.mochaOpts);
+
+            default:
+                throw new ConfigurationError(`"${ config?.serenity?.runner }" is not a supported test runner. Please use "mocha", "jasmine", or "cucumber"`);
+        }
+    }
+
+    private cucumberAdapter(cucumberOptions?: TestRunnerOptions): TestRunnerAdapter {
+        const { CucumberCLIAdapter, CucumberFormat, StandardOutput, TempFileOutput } = this.loader.require('@serenity-js/cucumber/lib/adapter/index.js');
+
+        delete cucumberOptions?.timeout;   // todo: support setting a timeout via config?
+        delete cucumberOptions?.parallel;  // WebdriverIO handles that already
+
+        const cleanedCucumberOptions = new Config(cucumberOptions)
+            .where('format', values =>
+                [].concat(values).map(value => {
+                    const format = new CucumberFormat(value);
+
+                    if (format.output === '') {
+                        return format.value;
+                    }
+
+                    const basename = Path.from(format.output).basename();
+                    const filenameParts = basename.split('.');
+
+                    if (filenameParts[0] === basename) {
+                        return `${ format.formatter }:${ format.output }.${ this.cid }`;
+                    }
+
+                    filenameParts.splice(-1, 0, `${ this.cid }`);
+
+                    return `${ format.formatter }:${ format.output.replace(basename, filenameParts.join('.')) }`;
+                })
+            ).object();
+
+        // check if we need to free up stdout for any native reporters
+        const output = cleanedCucumberOptions?.format?.some(format => new CucumberFormat(format).output === '')
+            ? new TempFileOutput(this.fileSystem)
+            : new StandardOutput();
+
+        return new CucumberCLIAdapter(cleanedCucumberOptions, this.loader, this.fileSystem, output);
+    }
+
+    private jasmineAdapter(jasmineOptions: TestRunnerOptions): TestRunnerAdapter {
+        const { JasmineAdapter } = this.loader.require('@serenity-js/jasmine/adapter')
+        return new JasmineAdapter(jasmineOptions, this.loader);
+    }
+
+    private mochaAdapter(mochaOptions: TestRunnerOptions): TestRunnerAdapter {
+        // todo: update path to mocha adapter too
+        const { MochaAdapter } = this.loader.require('@serenity-js/mocha/lib/adapter/index.js')
+        return new MochaAdapter(mochaOptions, this.loader);
+    }
+}

package/src/adapter/WebdriverIOFrameworkAdapter.ts

@@ -0,0 +1,130 @@
+import 'webdriverio';
+
+import type { Serenity } from '@serenity-js/core';
+import { AnsiDiffFormatter, ArtifactArchiver, Cast, TakeNotes } from '@serenity-js/core';
+import type { TestRunnerAdapter } from '@serenity-js/core/lib/adapter/index.js';
+import type { ModuleLoader } from '@serenity-js/core/lib/io/index.js';
+import { Path } from '@serenity-js/core/lib/io/index.js';
+import { CallAnApi } from '@serenity-js/rest';
+import type { Capabilities } from '@wdio/types';
+import * as deepmerge from 'deepmerge';
+import type { EventEmitter } from 'events';
+import { isRecord } from 'tiny-types/lib/objects/isRecord.js';
+
+import type { WebdriverIOConfig } from '../config/index.js';
+import { BrowseTheWebWithWebdriverIO } from '../screenplay/index.js';
+import type { InitialisesReporters, ProvidesWriteStream } from './reporter/index.js';
+import { BrowserCapabilitiesReporter, OutputStreamBuffer } from './reporter/index.js';
+import { OutputStreamBufferPrinter } from './reporter/OutputStreamBufferPrinter.js';
+import { TestRunnerLoader } from './TestRunnerLoader.js';
+import { WebdriverIONotifier } from './WebdriverIONotifier.js';
+
+export class WebdriverIOFrameworkAdapter {
+
+    private adapter: TestRunnerAdapter;
+    private notifier: WebdriverIONotifier;
+
+    constructor(
+        private readonly serenity: Serenity,
+        private readonly loader: ModuleLoader,
+        private readonly cwd: Path,
+        private readonly cid: string,
+        webdriverIOConfig: WebdriverIOConfig,
+        private readonly specs: string[],
+        private readonly capabilities: Capabilities.RemoteCapability,
+        private readonly reporter: EventEmitter & ProvidesWriteStream & InitialisesReporters
+    ) {
+        const config = deepmerge.default<WebdriverIOConfig>(this.defaultConfig(), webdriverIOConfig, {
+            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);
+
+        this.notifier = new WebdriverIONotifier(
+            config,
+            capabilities,
+            reporter,
+            this.adapter.successThreshold(),
+            cid,
+            this.specs,
+        );
+
+        const outputStreamBuffer = new OutputStreamBuffer(
+            `[${ this.cid }]`,
+        );
+
+        const outputStreamBufferPrinter = new OutputStreamBufferPrinter(
+            outputStreamBuffer,
+            reporter.getWriteStreamObject('@serenity-js/webdriverio-8')
+        );
+
+        this.serenity.configure({
+            outputStream: outputStreamBuffer,
+            cueTimeout: config.serenity.cueTimeout,
+            interactionTimeout: config.serenity.interactionTimeout,
+
+            diffFormatter: config.serenity.diffFormatter ?? new AnsiDiffFormatter(),
+
+            actors: config.serenity.actors || Cast.where(actor => actor.whoCan(
+                BrowseTheWebWithWebdriverIO.using(global.browser as unknown as WebdriverIO.Browser),
+                TakeNotes.usingAnEmptyNotepad(),
+                CallAnApi.using({
+                    baseURL: webdriverIOConfig.baseUrl,
+                }),
+            )),
+
+            crew: [
+                ...config.serenity.crew,
+                this.notifier,
+                outputStreamBufferPrinter,
+            ]
+        });
+    }
+
+    async init(): Promise<WebdriverIOFrameworkAdapter> {
+
+        // This is the only (hacky) way to register a fake reporter programmatically (as of @wdio/reporter 7.4.2)
+        //  - https://github.com/webdriverio/webdriverio/blob/365fb0ad79fcf4471f21f23e18afa6818986dbdb/packages/wdio-runner/src/index.ts#L147-L181
+        //  - https://github.com/webdriverio/webdriverio/blob/365fb0ad79fcf4471f21f23e18afa6818986dbdb/packages/wdio-runner/src/reporter.ts#L24
+        const browserCapabilitiesReporter = await (this.reporter._loadReporter([
+            BrowserCapabilitiesReporter, {
+                serenity: this.serenity
+            },
+        ]));
+
+        (this.reporter as any)._reporters.push(browserCapabilitiesReporter);
+
+        // WebdriverIO v8 represents paths to specs as file URIs, so they need to be converted to absolute paths to avoid confusing the test runners like Cucumber
+        const absolutePaths = this.specs.map(pathToSpec => Path.from(pathToSpec).value);
+
+        await this.adapter.load(absolutePaths);
+
+        return this;
+    }
+
+    hasTests(): boolean {
+        return this.adapter.scenarioCount() > 0;
+    }
+
+    async run(): Promise<number> {
+        await this.adapter.run();
+        return this.notifier.failureCount();
+    }
+
+    private defaultConfig(): Partial<WebdriverIOConfig> {
+        return {
+            serenity: {
+                crew: [
+                    ArtifactArchiver.storingArtifactsAt(this.cwd.value, 'target/site/serenity'),
+                ]
+            }
+        }
+    }
+}

package/src/adapter/WebdriverIOFrameworkAdapterFactory.ts

@@ -0,0 +1,39 @@
+import type { Serenity } from '@serenity-js/core';
+import type { ModuleLoader, Path } from '@serenity-js/core/lib/io/index.js';
+import type { Capabilities } from '@wdio/types';
+import type { EventEmitter } from 'events';
+
+import type { WebdriverIOConfig } from '../config/index.js';
+import type { InitialisesReporters, ProvidesWriteStream } from './reporter/index.js';
+import { WebdriverIOFrameworkAdapter } from './WebdriverIOFrameworkAdapter.js';
+
+/**
+ * @group Test Runner Adapter
+ */
+export class WebdriverIOFrameworkAdapterFactory {
+    constructor(
+        private readonly serenity: Serenity,
+        private readonly loader: ModuleLoader,
+        private readonly cwd: Path,
+    ) {
+    }
+
+    public init(
+        cid: string,
+        config: WebdriverIOConfig,
+        specs: string[],
+        capabilities: Capabilities.RemoteCapability,
+        reporter: EventEmitter & ProvidesWriteStream & InitialisesReporters
+    ): Promise<WebdriverIOFrameworkAdapter> {
+        return new WebdriverIOFrameworkAdapter(
+            this.serenity,
+            this.loader,
+            this.cwd,
+            cid,
+            config,
+            specs,
+            capabilities,
+            reporter,
+        ).init()
+    }
+}