@serenity-js/webdriverio 2.33.1 → 3.0.0-rc.11

package/src/adapter/WebdriverIONotifier.ts

@@ -1,7 +1,8 @@
 import { LogicError, Stage, StageCrewMember } from '@serenity-js/core';
-import { DomainEvent, SceneFinished, SceneStarts, TestSuiteFinished, TestSuiteStarts } from '@serenity-js/core/lib/events';
+import { AsyncOperationAttempted, AsyncOperationCompleted, DomainEvent, SceneFinished, SceneStarts, TestRunFinishes, TestSuiteFinished, TestSuiteStarts } from '@serenity-js/core/lib/events';
 import {
     CorrelationId,
+    Description,
     ExecutionCompromised,
     ExecutionFailedWithAssertionError,
     ExecutionFailedWithError,
@@ -12,20 +13,35 @@ import {
     ProblemIndication,
     TestSuiteDetails,
 } from '@serenity-js/core/lib/model';
-import { Suite } from '@wdio/reporter/build/stats/suite';
-import { Test } from '@wdio/reporter/build/stats/test';
+import { Suite as suiteStats } from '@wdio/reporter/build/stats/suite';
+import { Test as testStats } from '@wdio/reporter/build/stats/test';
+import { RemoteCapability } from '@wdio/types/build/Capabilities';
+import * as frameworks from '@wdio/types/build/Frameworks';
 import type { EventEmitter } from 'events';
 import { match } from 'tiny-types';
 
+import { WebdriverIOConfig } from './WebdriverIOConfig';
+
 /**
  * @package
  */
 export class WebdriverIONotifier implements StageCrewMember {
 
+    /**
+     * We don't have access to the "context" object produced by Mocha,
+     * and can't assume that other test runners have a similar concept.
+     * Since, at the time of writing, none of the WebdriverIO rely on this parameter
+     * using a dummy seems to be sufficient.
+     * @private
+     */
+    private static dummmyContext = {};
+
     private readonly events = new EventLog();
     private readonly suites: TestSuiteDetails[] = [];
 
     constructor(
+        private readonly config: WebdriverIOConfig,
+        private readonly capabilities: RemoteCapability,
         private readonly reporter: EventEmitter,
         private readonly successThreshold: Outcome | { Code: number },
         private readonly cid: string,
@@ -46,28 +62,42 @@ export class WebdriverIONotifier implements StageCrewMember {
             .when(TestSuiteFinished,        WebdriverIONotifier.prototype.onTestSuiteFinished.bind(this))
             .when(SceneStarts,              WebdriverIONotifier.prototype.onSceneStarts.bind(this))
             .when(SceneFinished,            WebdriverIONotifier.prototype.onSceneFinished.bind(this))
+            .when(TestRunFinishes,          WebdriverIONotifier.prototype.onTestRunFinishes.bind(this))
             .else(() => void 0);
     }
 
+    private onTestRunFinishes(): Promise<any> {
+        return this.invokeHooks('after', this.config.after, [this.failures, this.capabilities, this.specs]);
+    }
+
     failureCount(): number {
         return this.failures;
     }
 
-    private onTestSuiteStarts(started: TestSuiteStarts) {
+    private onTestSuiteStarts(started: TestSuiteStarts): Promise<any> {
         this.events.record(started.details.correlationId, started);
-        this.reporter.emit('suite:start', this.suiteStartEventFrom(started));
+
+        const suite = this.suiteStartEventFrom(started);
+
+        this.reporter.emit('suite:start', suite);
 
         this.suites.push(started.details);
+
+        return this.invokeHooks('beforeSuite', this.config.beforeSuite, [suite as any]);    // todo: correct types
     }
 
-    private onTestSuiteFinished(finished: TestSuiteFinished) {
+    private onTestSuiteFinished(finished: TestSuiteFinished): Promise<any> {
         this.suites.pop();
 
         const started = this.events.getByCorrelationId<TestSuiteStarts>(finished.details.correlationId);
-        this.reporter.emit('suite:end', this.suiteEndEventFrom(started, finished));
+        const suite = this.suiteEndEventFrom(started, finished);
+
+        this.reporter.emit('suite:end', suite);
+
+        return this.invokeHooks('afterSuite', this.config.afterSuite, [suite as any]);  // todo: correct types
     }
 
-    private suiteStartEventFrom(started: TestSuiteStarts): Suite {
+    private suiteStartEventFrom(started: TestSuiteStarts): suiteStats & frameworks.Suite {
         return {
             type:       'suite:start',
             uid:        started.details.correlationId.value,
@@ -85,7 +115,7 @@ export class WebdriverIONotifier implements StageCrewMember {
         return this.suites.map(suite => suite.name.value).concat(name).join(' ');
     }
 
-    private suiteEndEventFrom(started: TestSuiteStarts, finished: TestSuiteFinished): Suite {
+    private suiteEndEventFrom(started: TestSuiteStarts, finished: TestSuiteFinished): suiteStats & frameworks.Suite {
         return {
             ...this.suiteStartEventFrom(started),
             type:       'suite:end',
@@ -99,6 +129,8 @@ export class WebdriverIONotifier implements StageCrewMember {
         this.events.record(started.sceneId, started);
 
         this.reporter.emit(test.type, test);
+
+        return this.invokeHooks('beforeTest', this.config.beforeTest, [ this.testFrom(started), WebdriverIONotifier.dummmyContext ]);
     }
 
     private onSceneFinished(finished: SceneFinished) {
@@ -108,37 +140,59 @@ export class WebdriverIONotifier implements StageCrewMember {
         }
 
         const started     = this.events.getByCorrelationId<SceneStarts>(finished.sceneId);
+        let testEnd: testStats;
 
         if (this.willBeRetried(finished.outcome)) {
-            const testResult  = this.testEndEventFrom(started, finished);
+            testEnd  = this.testEndEventFrom(started, finished);
 
             const type = 'test:retry';
 
             this.reporter.emit(type, {
-                ...testResult,
+                ...testEnd,
                 type,
                 error:  this.errorFrom(finished.outcome),
             });
 
         } else {
 
-            const testResult  = this.testResultEventFrom(started, finished);
-            this.reporter.emit(testResult.type, testResult);
+            const testResultEvent  = this.testResultEventFrom(started, finished);
+            this.reporter.emit(testResultEvent.type, testResultEvent);
 
-            const testEnd     = this.testEndEventFrom(started, finished);
+            testEnd     = this.testEndEventFrom(started, finished);
             this.reporter.emit(testEnd.type, testEnd);
         }
+
+        return this.invokeHooks('afterTest', this.config.afterTest, [ this.testFrom(started), WebdriverIONotifier.dummmyContext, this.testResultFrom(started, finished) ]);
     }
 
     private willBeRetried(outcome: Outcome): outcome is ExecutionIgnored {
         return outcome instanceof ExecutionIgnored;
     }
 
-    private testStartEventFrom(started: SceneStarts): Test {
-        const title = started.details.name.value
+    private testShortTitleFrom(started: SceneStarts): string {
+        return started.details.name.value
             .replace(new RegExp(`^.*?(${ this.parentSuiteName() })`), '')
             .trim();
+    }
+
+    private testFrom(started: SceneStarts): frameworks.Test {
+        const
+            title           = this.testShortTitleFrom(started);
 
+        return {
+            ctx:        WebdriverIONotifier.dummmyContext,
+            file:       started.details.location.path.value,
+            fullName:   this.suiteNamesConcatenatedWith(title),
+            fullTitle:  this.suiteNamesConcatenatedWith(title),
+            parent:     this.parentSuiteName(),
+            pending:    false,
+            title,
+            type:       'test'  // I _think_ it's either 'test' or 'hook' - https://github.com/mochajs/mocha/blob/0ea732c1169c678ef116c3eb452cc94758fff150/lib/test.js#L31
+        }
+    }
+
+    private testStartEventFrom(started: SceneStarts): testStats {
+        const title = this.testShortTitleFrom(started);
         return {
             type:       'test:start',
             title,
@@ -156,7 +210,95 @@ export class WebdriverIONotifier implements StageCrewMember {
         return this.suites[this.suites.length - 1]?.name.value || '';
     }
 
-    private testEndEventFrom(started: SceneStarts, finished: SceneFinished): Test {
+    /**
+     * test status is 'passed' | 'pending' | 'skipped' | 'failed' | 'broken' | 'canceled'
+     * Since this is not documented, we're mimicking other WebdriverIO reporters, for example:
+     *   https://github.com/webdriverio/webdriverio/blob/7415f3126e15a733b51721492e4995ceafae6046/packages/wdio-allure-reporter/src/constants.ts#L3-L9
+     *
+     * @param started
+     * @param finished
+     * @private
+     */
+    private testResultFrom(started: SceneStarts, finished: SceneFinished): frameworks.TestResult {
+        const duration = finished.timestamp.diff(started.timestamp).inMilliseconds();
+        const defaultRetries = { attempts: 0, limit: 0 };
+
+        const passedOrFailed = (outcome: Outcome): boolean =>
+            this.whenSuccessful<boolean>(outcome, true, false);
+
+        return match<Outcome, frameworks.TestResult>(finished.outcome)
+            .when(ExecutionCompromised, (outcome: ExecutionCompromised) => {
+                const error = this.errorFrom(outcome);
+                return {
+                    duration,
+                    error,
+                    exception: error.message,
+                    passed: passedOrFailed(outcome),
+                    status: 'broken',
+                    retries: defaultRetries
+                }
+            })
+            .when(ExecutionFailedWithError, (outcome: ExecutionFailedWithError) => {
+                const error = this.errorFrom(outcome);
+                return {
+                    duration,
+                    error,
+                    exception: error.message,
+                    passed: passedOrFailed(outcome),
+                    status: 'broken',
+                    retries: defaultRetries
+                }
+            })
+            .when(ExecutionFailedWithAssertionError, (outcome: ExecutionFailedWithAssertionError) => {
+                const error = this.errorFrom(outcome);
+                return {
+                    duration,
+                    error,
+                    exception: error.message,
+                    passed: passedOrFailed(outcome),
+                    status: 'failed',
+                    retries: defaultRetries
+                }
+            })
+            .when(ImplementationPending, (outcome: ImplementationPending) => {
+                const error = this.errorFrom(outcome);
+                return {
+                    duration,
+                    error,
+                    exception: error.message,
+                    passed: passedOrFailed(outcome),
+                    status: 'pending',
+                    retries: defaultRetries
+                }
+            })
+            .when(ExecutionIgnored, (outcome: ExecutionIgnored) => {
+                const error = this.errorFrom(outcome);
+                return {
+                    duration,
+                    error,
+                    exception: error.message,
+                    passed: passedOrFailed(outcome),
+                    status: 'canceled',         // fixme: mark as canceled for now for the lack of a better alternative;
+                    retries: defaultRetries     //  consider capturing info about retries from Mocha and putting it on the ExecutionIgnored event so we can pass it on
+                }
+            })
+            .when(ExecutionSkipped, (outcome: ExecutionSkipped) => ({
+                duration,
+                exception: '',
+                passed: passedOrFailed(outcome),
+                status: 'skipped',
+                retries: defaultRetries
+            }))
+            .else(() => ({
+                duration,
+                exception: '',
+                passed: true,
+                status: 'passed',
+                retries: defaultRetries
+            }));
+    }
+
+    private testEndEventFrom(started: SceneStarts, finished: SceneFinished): testStats {
         const duration = finished.timestamp.diff(started.timestamp).inMilliseconds();
         return {
             ...this.testStartEventFrom(started),
@@ -165,15 +307,19 @@ export class WebdriverIONotifier implements StageCrewMember {
         };
     }
 
-    private testResultEventFrom(started: SceneStarts, finished: SceneFinished): Test {
+    private whenSuccessful<O>(outcome: Outcome, resultWhenSuccessful: O, resultWhenNotSuccessful: O): O {
+        return ! outcome.isWorseThan(this.successThreshold) && (outcome instanceof ProblemIndication)
+            ? resultWhenSuccessful
+            : resultWhenNotSuccessful
+    }
+
+    private testResultEventFrom(started: SceneStarts, finished: SceneFinished): testStats {
         const test = this.testEndEventFrom(started, finished)
 
-        const unlessSuccessful = (outcome: Outcome, type: Test['type']) =>
-            ! outcome.isWorseThan(this.successThreshold) && (outcome instanceof ProblemIndication)
-                ? 'test:pass'
-                : type;
+        const unlessSuccessful = (outcome: Outcome, type: testStats['type']) =>
+            this.whenSuccessful<testStats['type']>(outcome, 'test:pass', type);
 
-        return match<Outcome, Test>(finished.outcome)
+        return match<Outcome, testStats>(finished.outcome)
             .when(ExecutionCompromised, (outcome: ExecutionCompromised) => ({
                 ...test,
                 type:   unlessSuccessful(outcome, 'test:fail'),
@@ -231,6 +377,62 @@ export class WebdriverIONotifier implements StageCrewMember {
             actual:     error.actual
         }
     }
+
+    /**
+     * @see https://github.com/webdriverio/webdriverio/blob/main/packages/wdio-utils/src/shim.ts
+     * @param hookName
+     * @param hookFunctions
+     * @param args
+     * @private
+     */
+    private invokeHooks<Result, InnerArguments extends any[]>(
+        hookName: string,
+        hookFunctions: ((...parameters: InnerArguments) => Promise<Result> | Result) | Array<((...parameters: InnerArguments) => Result)>,
+        args: InnerArguments
+    ): Promise<Array<Result | Error>> {
+
+        const hooks = ! Array.isArray(hookFunctions)
+            ? [ hookFunctions ]
+            : hookFunctions;
+
+        const asyncOperationId = CorrelationId.create();
+
+        this.stage.announce(new AsyncOperationAttempted(
+            new Description(`[WebdriverIONotifier#invokeHooks] Invoking ${ hookName } hook`),
+            asyncOperationId,
+        ));
+
+        return Promise.all(hooks.map((hook) => new Promise<Result | Error>((resolve) => {
+            let result
+
+            try {
+                result = hook(...args);
+            } catch (error) {
+                return resolve(error);
+            }
+
+            /**
+             * if a promise is returned make sure we don't have a catch handler
+             * so in case of a rejection it won't cause the hook to fail
+             */
+            if (result && typeof result.then === 'function') {
+                return result.then(resolve, (error: Error) => {
+                    resolve(error);
+                })
+            }
+
+            resolve(result);
+        }))).
+        then(results => {
+
+            this.stage.announce(new AsyncOperationCompleted(
+                new Description(`[WebdriverIONotifier#invokeHooks] Invoking ${ hookName } hook completed`),
+                asyncOperationId,
+            ));
+
+            return results;
+        });
+    }
 }
 
 class EventLog {

package/src/index.ts

@@ -12,7 +12,4 @@ const adapterFactory = new WebdriverIOFrameworkAdapterFactory(
 export default adapterFactory;
 
 export { WebdriverIOConfig } from './adapter';
-export * from './expectations';
-export * from './input';
 export * from './screenplay';
-export * from './stage';

package/src/screenplay/abilities/{BrowseTheWeb.ts → BrowseTheWebWithWebdriverIO.ts}

@@ -1,7 +1,9 @@
-import { Ability, LogicError, UsesAbilities } from '@serenity-js/core';
-import type { Browser } from 'webdriverio';
+import { Duration, LogicError } from '@serenity-js/core';
+import { BrowserCapabilities, BrowseTheWeb, ByCss, ByCssContainingText, ById, ByTagName, ByXPath, Cookie, CookieData, Frame, Key, ModalDialog, Page, Selector } from '@serenity-js/web';
+import type * as wdio from 'webdriverio';
 
-import { Key } from '../../input';
+import { WebdriverIOCookie, WebdriverIOFrame, WebdriverIOModalDialog, WebdriverIOPage, WebdriverIOPageElement } from '../models';
+import { WebdriverIOLocator, WebdriverIONativeElementRoot } from '../models/locators';
 
 /**
  * @desc
@@ -12,8 +14,6 @@ import { Key } from '../../input';
  *  This means that its interface can change without affecting the major version of Serenity/JS itself.
  *  In particular, please don't rely on the `browser` field to remain `public` in future releases.
  *
- * @experimental
- *
  * @example <caption>Using the WebdriverIO browser</caption>
  *  import { Actor } from '@serenity-js/core';
  *  import { BrowseTheWeb, by, Navigate, Target } from '@serenity-js/webdriverio'
@@ -38,7 +38,15 @@ import { Key } from '../../input';
  * @implements {@serenity-js/core/lib/screenplay~Ability}
  * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
  */
-export class BrowseTheWeb implements Ability {
+export class BrowseTheWebWithWebdriverIO extends BrowseTheWeb<wdio.Element<'async'>, WebdriverIONativeElementRoot> {
+
+    /**
+     * @param {@wdio/types~Browser} browserInstance
+     * @returns {BrowseTheWebWithWebdriverIO}
+     */
+    static using(browserInstance: wdio.Browser<'async'>): BrowseTheWebWithWebdriverIO {
+        return new BrowseTheWebWithWebdriverIO(browserInstance);
+    }
 
     /**
      * @private
@@ -46,42 +54,106 @@ export class BrowseTheWeb implements Ability {
     private lastScriptExecutionSummary: LastScriptExecutionSummary;
 
     /**
-     * @param {@wdio/types~Browser} browserInstance
-     * @returns {BrowseTheWeb}
+     * @param {@wdio/types~Browser} browser
      */
-    static using(browserInstance: Browser<'async'>): BrowseTheWeb {
-        return new BrowseTheWeb(browserInstance);
+    constructor(protected readonly browser: wdio.Browser<'async'>) {
+        super(new Map()
+            .set(ByCss,                 (selector: ByCss)               => WebdriverIOLocator.createRootLocator(this.browser, selector, selector.value))
+            .set(ByCssContainingText,   (selector: ByCssContainingText) => WebdriverIOLocator.createRootLocator(this.browser, selector, `${ selector.value }*=${ selector.text }`))
+            .set(ById,                  (selector: ById)                => WebdriverIOLocator.createRootLocator(this.browser, selector, `#${ selector.value }`))
+            .set(ByTagName,             (selector: ByTagName)           => WebdriverIOLocator.createRootLocator(this.browser, selector, `<${ selector.value } />`))
+            .set(ByXPath,               (selector: ByXPath)             => WebdriverIOLocator.createRootLocator(this.browser, selector, selector.value))
+        );
+
+        if (! this.browser.$ || ! this.browser.$$) {
+            throw new LogicError(`WebdriverIO browser object is not initialised yet, so can't be assigned to an actor. Are you trying to instantiate an actor outside of a test or a test hook?`)
+        }
+    }
+
+    browserCapabilities(): Promise<BrowserCapabilities> {
+        return Promise.resolve(this.browser.capabilities as BrowserCapabilities);
+    }
+
+    async cookie(name: string): Promise<Cookie> {
+        return new WebdriverIOCookie(this.browser, name);
+    }
+
+    async setCookie(cookieData: CookieData): Promise<void> {
+        return this.browser.setCookies({
+            name:       cookieData.name,
+            value:      cookieData.value,
+            path:       cookieData.path,
+            domain:     cookieData.domain,
+            secure:     cookieData.secure,
+            httpOnly:   cookieData.httpOnly,
+            expiry:     cookieData.expiry
+                ? cookieData.expiry.toSeconds()
+                : undefined,
+            sameSite:   cookieData.sameSite,
+        });
+    }
+
+    deleteAllCookies(): Promise<void> {
+        return this.browser.deleteCookies() as Promise<void>;
     }
 
     /**
      * @desc
-     *  Used to access the Actor's ability to {@link BrowseTheWeb}
-     *  from within the {@link @serenity-js/core/lib/screenplay~Interaction} classes,
-     *  such as {@link Navigate}.
+     *  Navigate to a given destination, specified as an absolute URL
+     *  or a path relative to WebdriverIO `baseUrl`.
      *
-     * @param {@serenity-js/core/lib/screenplay/actor~UsesAbilities} actor
-     * @return {BrowseTheWeb}
+     * @param {string} destination
+     * @returns {Promise<void>}
      */
-    static as(actor: UsesAbilities): BrowseTheWeb {
-        return actor.abilityTo(BrowseTheWeb);
+    navigateTo(destination: string): Promise<void> {
+        return this.browser.url(destination) as any;  // todo: check if this returns a string or is mistyped
+    }
+
+    navigateBack(): Promise<void> {
+        return this.browser.back();
+    }
+
+    navigateForward(): Promise<void> {
+        return this.browser.forward();
+    }
+
+    reloadPage(): Promise<void> {
+        return this.browser.refresh();
     }
 
     /**
-     * @param {@wdio/types~Browser} browser
+     * @desc
+     *  Returns a {@link Page} representing the currently active top-level browsing context.
+     *
+     * @returns {Promise<Page>}
      */
-    constructor(public readonly browser: Browser<'async'>) {
+    async currentPage(): Promise<Page> {
+
+        const windowHandle = await this.browser.getWindowHandle();
+
+        return new WebdriverIOPage(this.browser, windowHandle);
     }
 
     /**
      * @desc
-     *  Navigate to a given destination, specified as an absolute URL
-     *  or a path relative to WebdriverIO `baseUrl`.
+     *  Returns an array of {@link Page} objects representing all the available
+     *  top-level browsing context, e.g. all the open browser tabs.
      *
-     * @param {string} destination
-     * @returns {Promise<void>}
+     * @returns {Promise<Array<Page>>}
      */
-    get(destination: string): Promise<void> {
-        return this.browser.url(destination) as any;  // todo: check if this returns a string or is mistyped
+    async allPages(): Promise<Array<Page>> {
+        const windowHandles = await this.browser.getWindowHandles();
+
+        return windowHandles.map(windowHandle => new WebdriverIOPage(this.browser, windowHandle));
+    }
+
+    async frame(bySelector: Selector): Promise<Frame<any>> {
+        const locator = this.locate(bySelector);
+        return new WebdriverIOFrame(this.browser, locator);
+    }
+
+    async modalDialog(): Promise<ModalDialog> {
+        return new WebdriverIOModalDialog(this.browser);
     }
 
     /**
@@ -101,7 +173,7 @@ export class BrowseTheWeb implements Ability {
                 return key;
             }
 
-            if (browser.isDevTools) {
+            if (this.browser.isDevTools) {
                 return key.devtoolsName;
             }
 
@@ -162,12 +234,13 @@ export class BrowseTheWeb implements Ability {
      *
      * @see {@link BrowseTheWeb#getLastScriptExecutionResult}
      */
-    executeScript<Result, InnerArguments extends any[]>(
+    async executeScript<Result, InnerArguments extends any[]>(
         script: string | ((...parameters: InnerArguments) => Result),
         ...args: InnerArguments
     ): Promise<Result> {
+        const nativeArguments = await Promise.all(args.map(arg => arg instanceof WebdriverIOPageElement ? arg.nativeElement() : arg)) as InnerArguments;
 
-        return this.browser.execute(script, ...args)
+        return this.browser.execute(script, ...nativeArguments)
             .then(result => {
                 this.lastScriptExecutionSummary = new LastScriptExecutionSummary(
                     result,
@@ -188,7 +261,7 @@ export class BrowseTheWeb implements Ability {
      *  Arrays and objects may also be used as script arguments as long as each item adheres
      *  to the types previously mentioned.
      *
-     *  Unlike executing synchronous JavaScript with {@link BrowseTheWeb#executeScript},
+     *  Unlike executing synchronous JavaScript with {@link BrowseTheWebWithWebdriverIO#executeScript},
      *  scripts executed with this function must explicitly signal they are finished by invoking the provided callback.
      *
      *  This callback will always be injected into the executed function as the last argument,
@@ -227,11 +300,13 @@ export class BrowseTheWeb implements Ability {
      *
      * @see {@link BrowseTheWeb#getLastScriptExecutionResult}
      */
-    executeAsyncScript<Result, Parameters extends any[]>(
+    async executeAsyncScript<Result, Parameters extends any[]>(
         script: string | ((...args: [...parameters: Parameters, callback: (result: Result) => void]) => void),
         ...args: Parameters
     ): Promise<Result> {
-        return this.browser.executeAsync<Result, Parameters>(script, ...args)
+        const nativeArguments = await Promise.all(args.map(arg => arg instanceof WebdriverIOPageElement ? arg.nativeElement() : arg)) as Parameters;
+
+        return this.browser.executeAsync<Result, Parameters>(script, ...nativeArguments)
             .then(result => {
                 this.lastScriptExecutionSummary = new LastScriptExecutionSummary<Result>(
                     result,
@@ -242,17 +317,32 @@ export class BrowseTheWeb implements Ability {
 
     /**
      * @desc
-     *  Returns the last result of calling {@link BrowseTheWeb#executeAsyncScript}
-     *  or {@link BrowseTheWeb#executeScript}
+     *  Returns the last result of calling {@link BrowseTheWebWithWebdriverIO#executeAsyncScript}
+     *  or {@link BrowseTheWebWithWebdriverIO#executeScript}
      *
      * @returns {any}
      */
-    getLastScriptExecutionResult<Result = any>(): Result {
+    lastScriptExecutionResult<Result = any>(): Result {
         if (! this.lastScriptExecutionSummary) {
             throw new LogicError(`Make sure to execute a script before checking on the result`);
         }
 
-        return this.lastScriptExecutionSummary.result as Result;
+        // Selenium returns `null` when the script it executed returns `undefined`
+        // so we're mapping the result back.
+        return this.lastScriptExecutionSummary.result !== null
+            ? this.lastScriptExecutionSummary.result as Result
+            : undefined;
+    }
+
+    waitFor(duration: Duration): Promise<void> {
+        return this.browser.pause(duration.inMilliseconds()) as Promise<void>;
+    }
+
+    waitUntil(condition: () => boolean | Promise<boolean>, timeout: Duration): Promise<void>  {
+        return this.browser.waitUntil(condition, {
+            timeout:    timeout.inMilliseconds(),
+            timeoutMsg: `Wait timed out after ${ timeout }`,
+        }) as Promise<void>;
     }
 }
 

package/src/screenplay/abilities/index.ts

@@ -1 +1 @@
-export * from './BrowseTheWeb';
+export * from './BrowseTheWebWithWebdriverIO';

package/src/screenplay/index.ts

@@ -1,3 +1,2 @@
 export * from './abilities';
-export * from './interactions';
-export * from './questions';
+export * from './models';

package/src/screenplay/models/WebdriverIOCookie.ts

@@ -0,0 +1,44 @@
+import { Timestamp } from '@serenity-js/core';
+import { Cookie, CookieData, CookieMissingError } from '@serenity-js/web';
+import { ensure, isDefined } from 'tiny-types';
+import * as wdio from 'webdriverio';
+
+export class WebdriverIOCookie extends Cookie {
+
+    constructor(
+        private readonly browser: wdio.Browser<'async'>,
+        cookieName: string,
+    ) {
+        super(cookieName);
+        ensure('browser', browser, isDefined());
+    }
+
+    async delete(): Promise<void> {
+        return this.browser.deleteCookies(this.cookieName) as Promise<void>;
+    }
+
+    protected async read(): Promise<CookieData> {
+        const [ cookie ] = await this.browser.getCookies(this.cookieName);
+
+        if (! cookie) {
+            throw new CookieMissingError(`Cookie '${ this.cookieName }' not set`);
+        }
+
+        // There _might_ be a bug in WDIO where the expiry date is set on "expires" rather than the "expiry" key
+        // and possibly another one around deserialising the timestamp, since WDIO seems to add several hundred milliseconds
+        // to the original expiry date
+        const expiry: number | undefined = cookie.expiry || (cookie as any).expires;
+
+        return {
+            name:       cookie.name,
+            value:      cookie.value,
+            domain:     cookie.domain,
+            path:       cookie.path,
+            expiry:     expiry !== undefined
+                ? Timestamp.fromTimestampInSeconds(Math.round(expiry))
+                : undefined,
+            httpOnly:   cookie.httpOnly,
+            secure:     cookie.secure,
+        }
+    }
+}