@serenity-js/playwright 3.0.0-rc.20

package/src/screenplay/models/PlaywrightBrowsingSession.ts

@@ -0,0 +1,88 @@
+import { CorrelationId } from '@serenity-js/core/lib/model';
+import { BrowsingSession, Cookie, CookieData } from '@serenity-js/web';
+import * as playwright from 'playwright-core';
+
+import { PlaywrightOptions } from '../../PlaywrightOptions';
+import { PlaywrightCookie, PlaywrightPage } from '../models';
+
+/**
+ * @desc
+ *  Playwright-specific implementation of the {@link @serenity-js/web/lib/screenplay/models~BrowsingSession}.
+ *
+ * @see {@link @serenity-js/web/lib/screenplay/models~BrowsingSession}
+ */
+export class PlaywrightBrowsingSession extends BrowsingSession<PlaywrightPage> {
+
+    private currentPlaywrightBrowserContext: playwright.BrowserContext;
+
+    constructor(
+        protected readonly browser: playwright.Browser,
+        protected readonly browserContextOptions: PlaywrightOptions,
+    ) {
+        super();
+    }
+
+    protected async registerCurrentPage(): Promise<PlaywrightPage> {
+        const context = await this.browserContext();
+
+        await context.newPage();
+
+        // calling context.newPage() triggers a callback registered via browserContext(),
+        // which wraps playwright.Page in PlaywrightPage and adds it to the list of pages
+        // returned by this.allPages()
+
+        const allPages = await this.allPages()
+
+        return allPages[allPages.length-1];
+    }
+
+    /**
+     * @override
+     */
+    async closeAllPages(): Promise<void> {
+        await super.closeAllPages();
+
+        const context = await this.browserContext();
+        await context.close();
+    }
+
+    async cookie(name: string): Promise<Cookie> {
+        const context = await this.browserContext();
+        return new PlaywrightCookie(context, name);
+    }
+
+    async setCookie(cookie: CookieData): Promise<void> {
+        const context = await this.browserContext();
+
+        await context.addCookies([ cookie ]);
+    }
+
+    async deleteAllCookies(): Promise<void> {
+        const context = await this.browserContext()
+        await context.clearCookies();
+    }
+
+    private async browserContext(): Promise<playwright.BrowserContext> {
+        if (! this.currentPlaywrightBrowserContext) {
+            this.currentPlaywrightBrowserContext = await this.browser.newContext(this.browserContextOptions);
+
+            this.currentPlaywrightBrowserContext.on('page', async page => {
+                await page.waitForLoadState();
+
+                this.register(
+                    new PlaywrightPage(this, page, this.browserContextOptions, CorrelationId.create())
+                );
+            });
+
+            if (this.browserContextOptions?.defaultNavigationTimeout) {
+                this.currentPlaywrightBrowserContext.setDefaultNavigationTimeout(this.browserContextOptions?.defaultNavigationTimeout);
+            }
+
+            if (this.browserContextOptions?.defaultTimeout) {
+                this.currentPlaywrightBrowserContext.setDefaultTimeout(this.browserContextOptions?.defaultTimeout);
+            }
+        }
+
+        return this.currentPlaywrightBrowserContext;
+    }
+}

package/src/screenplay/models/PlaywrightCookie.ts

@@ -0,0 +1,46 @@
+import { Timestamp } from '@serenity-js/core';
+import { Cookie, CookieData, CookieMissingError } from '@serenity-js/web';
+import * as playwright from 'playwright-core';
+import { ensure, isDefined } from 'tiny-types';
+
+export class PlaywrightCookie extends Cookie {
+
+    constructor(
+        private readonly context: playwright.BrowserContext,
+        cookieName: string,
+    ) {
+        super(cookieName);
+        ensure('context', context, isDefined());
+    }
+
+    async delete(): Promise<void> {
+        // see https://github.com/microsoft/playwright/issues/10143
+        const cookies = await this.context.cookies();
+        await this.context.clearCookies();
+        await this.context.addCookies(
+            cookies.filter(cookie => cookie.name !== this.cookieName)
+        );
+    }
+
+    protected async read(): Promise<CookieData> {
+        const cookies = await this.context.cookies();
+
+        const found = cookies.find(cookie => cookie.name === this.cookieName);
+
+        if (! found) {
+            throw new CookieMissingError(`Cookie '${ this.cookieName }' not set`);
+        }
+
+        return {
+            name:       found.name,
+            value:      found.value,
+            domain:     found.domain,
+            path:       found.path,
+            expiry:     found.expires !== undefined
+                ? Timestamp.fromTimestampInSeconds(Math.round(found.expires))
+                : undefined,
+            httpOnly:   found.httpOnly,
+            secure:     found.secure,
+        }
+    }
+}

package/src/screenplay/models/PlaywrightModalDialogHandler.ts

@@ -0,0 +1,53 @@
+import { AbsentModalDialog, AcceptedModalDialog, DismissedModalDialog, ModalDialog, ModalDialogHandler } from '@serenity-js/web';
+import * as playwright from 'playwright-core';
+
+export class PlaywrightModalDialogHandler extends ModalDialogHandler {
+
+    private readonly defaultHandler: (dialog: playwright.Dialog) => Promise<ModalDialog> =
+        async (dialog: playwright.Dialog) => {
+            await dialog.dismiss();
+            return new DismissedModalDialog(dialog.message());
+        }
+
+    private currentHandler: (dialog: playwright.Dialog) => Promise<ModalDialog>;
+
+    constructor(private readonly page: playwright.Page) {
+        super();
+
+        this.currentHandler = this.defaultHandler;
+
+        this.page.on('dialog', async (dialog: playwright.Dialog) => {
+            this.modalDialog = await this.currentHandler(dialog);
+        });
+    }
+
+    async acceptNext(): Promise<void> {
+        this.currentHandler = async (dialog: playwright.Dialog) => {
+            await dialog.accept(dialog.defaultValue());
+            return new AcceptedModalDialog(dialog.message());
+        }
+    }
+
+    async acceptNextWithValue(text: string | number): Promise<void> {
+        this.currentHandler = async (dialog: playwright.Dialog) => {
+            await dialog.accept(String(text));
+            return new AcceptedModalDialog(dialog.message());
+        }
+    }
+
+    async dismissNext(): Promise<void> {
+        this.currentHandler = async (dialog: playwright.Dialog) => {
+            await dialog.dismiss();
+            return new DismissedModalDialog(dialog.message());
+        }
+    }
+
+    async reset(): Promise<void> {
+        this.modalDialog = new AbsentModalDialog();
+        this.currentHandler = this.defaultHandler;
+    }
+
+    async discard(): Promise<void> {
+        this.page.off('dialog', this.currentHandler);
+    }
+}

package/src/screenplay/models/PlaywrightPage.ts

@@ -0,0 +1,258 @@
+import { LogicError } from '@serenity-js/core';
+import { CorrelationId } from '@serenity-js/core/lib/model';
+import { Cookie, CookieData, Key, Page, PageElement, PageElements, Selector } from '@serenity-js/web';
+import * as Buffer from 'buffer';
+import * as playwright from 'playwright-core';
+import * as structs from 'playwright-core/types/structs';
+import { URL } from 'url';
+
+import { PlaywrightOptions } from '../../PlaywrightOptions';
+import { PlaywrightLocator, PlaywrightRootLocator } from './locators';
+import { PlaywrightBrowsingSession } from './PlaywrightBrowsingSession';
+import { PlaywrightModalDialogHandler } from './PlaywrightModalDialogHandler';
+import { PlaywrightPageElement } from './PlaywrightPageElement';
+
+/**
+ * @desc
+ *  Playwright-specific implementation of the {@link @serenity-js/web/lib/screenplay/models~Page}.
+ *
+ * @see {@link @serenity-js/web/lib/screenplay/models~Page}
+ */
+export class PlaywrightPage extends Page<playwright.ElementHandle> {
+    /**
+     * @private
+     */
+    private lastScriptExecutionSummary: LastScriptExecutionSummary;
+
+    constructor(
+        session: PlaywrightBrowsingSession,
+        private readonly page: playwright.Page,
+        private readonly options: PlaywrightOptions,
+        pageId: CorrelationId,
+    ) {
+        super(
+            session,
+            new PlaywrightRootLocator(page),
+            new PlaywrightModalDialogHandler(page),
+            pageId
+        );
+    }
+
+    locate(selector: Selector): PageElement<playwright.ElementHandle> {
+        return new PlaywrightPageElement(
+            new PlaywrightLocator(
+                this.rootLocator,
+                selector,
+            ),
+        );
+    }
+
+    locateAll(selector: Selector): PageElements<playwright.ElementHandle> {
+        return new PageElements(
+            new PlaywrightLocator(
+                this.rootLocator,
+                selector
+            )
+        );
+    }
+
+    async navigateTo(destination: string): Promise<void> {
+        await this.page.goto(destination, { waitUntil: this.options?.defaultNavigationWaitUntil });
+        await this.resetState();
+    }
+
+    async navigateBack(): Promise<void> {
+        await this.page.goBack({ waitUntil: this.options?.defaultNavigationWaitUntil });
+        await this.resetState();
+    }
+
+    async navigateForward(): Promise<void> {
+        await this.page.goForward({ waitUntil: this.options?.defaultNavigationWaitUntil });
+        await this.resetState();
+    }
+
+    async reload(): Promise<void> {
+        await this.page.reload({ waitUntil: this.options?.defaultNavigationWaitUntil });
+        await this.resetState();
+    }
+
+    async sendKeys(keys: (string | Key)[]): Promise<void> {
+        const keySequence = keys.map(key => {
+            if (! Key.isKey(key)) {
+                return key;
+            }
+
+            return key.devtoolsName;
+        });
+
+        await this.page.keyboard.press(
+            keySequence.join('+'),
+        );
+    }
+
+    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 PlaywrightPageElement
+                    ? arg.nativeElement()
+                    : arg
+            )
+        ) as InnerArguments;
+
+        const serialisedScript = typeof script === 'function'
+            ? String(script)
+            : String(`function script() { ${ script } }`);
+
+        const result = await this.page.evaluate<Result, typeof nativeArguments>(
+            new Function(`
+                const parameters = arguments[0];
+                return (${ serialisedScript }).apply(null, parameters);
+            `) as structs.PageFunction<typeof nativeArguments, Result>,
+            nativeArguments
+        );
+
+        this.lastScriptExecutionSummary = new LastScriptExecutionSummary(
+            result,
+        );
+
+        return result;
+    }
+
+    async executeAsyncScript<Result, Parameters extends any[]>(script: string | ((...args: [...parameters: Parameters, callback: (result: Result) => void]) => void), ...args: Parameters): Promise<Result> {
+
+        const nativeArguments = await Promise.all(
+            args.map(arg =>
+                arg instanceof PlaywrightPageElement
+                    ? arg.nativeElement()
+                    : arg
+            )
+        ) as Parameters;
+
+        const serialisedScript = typeof script === 'function'
+            ? String(script)
+            : String(`function script() { ${ script } }`);
+
+        const result = await this.page.evaluate<Result, typeof nativeArguments>(
+            new Function(`
+                const parameters = arguments[0];
+                
+                return new Promise((resolve, reject) => {
+                    try {
+                        return (${ serialisedScript }).apply(null, parameters.concat(resolve));
+                    } catch (error) {
+                        return reject(error);
+                    }
+                })
+            `) as structs.PageFunction<typeof nativeArguments, Result>,
+            nativeArguments
+        );
+
+        this.lastScriptExecutionSummary = new LastScriptExecutionSummary(
+            result,
+        );
+
+        return result;
+    }
+
+    /**
+     * @desc
+     *  Returns the last result of calling {@link BrowseTheWebWithPlaywright#executeAsyncScript}
+     *  or {@link BrowseTheWebWithPlaywright#executeScript}
+     *
+     * @returns {any}
+     */
+    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;
+    }
+
+    async takeScreenshot(): Promise<string> {
+        const screenshot: Buffer = await this.page.screenshot();
+
+        return screenshot.toString('base64');
+    }
+
+    async cookie(name: string): Promise<Cookie> {
+        return (this.session as PlaywrightBrowsingSession).cookie(name);
+    }
+
+    async setCookie(cookieData: CookieData): Promise<void> {
+        const url = await this.page.url();
+
+        const cookie = {
+            name:       cookieData.name,
+            value:      cookieData.value,
+            domain:     cookieData.domain,
+            path:       cookieData.path,
+            url:        !(cookieData.domain && cookieData.path)
+                ? url
+                : undefined,
+            secure:     cookieData.secure,
+            httpOnly:   cookieData.httpOnly,
+            expires:    cookieData.expiry
+                ? cookieData.expiry.toSeconds()
+                : undefined,
+            sameSite:   cookieData.sameSite,
+        };
+
+        return (this.session as PlaywrightBrowsingSession).setCookie(cookie);
+    }
+
+    async deleteAllCookies(): Promise<void> {
+        await (this.session as PlaywrightBrowsingSession).deleteAllCookies();
+    }
+
+    title(): Promise<string> {
+        return this.page.title();
+    }
+
+    name(): Promise<string> {
+        return this.page.evaluate(
+            /* istanbul ignore next */
+            () => window.name
+        );
+    }
+
+    async url(): Promise<URL> {
+        return new URL(this.page.url());
+    }
+
+    async viewportSize(): Promise<{ width: number, height: number }> {
+        return this.page.viewportSize();
+    }
+
+    setViewportSize(size: { width: number, height: number }): Promise<void> {
+        return this.page.setViewportSize(size);
+    }
+
+    async close(): Promise<void> {
+        await this.resetState();
+        await (this.modalDialogHandler as PlaywrightModalDialogHandler).discard();
+        await this.page.close();
+    }
+
+    async closeOthers(): Promise<void> {
+        await this.session.closePagesOtherThan(this);
+    }
+
+    async isPresent(): Promise<boolean> {
+        return ! this.page.isClosed();
+    }
+
+    private async resetState() {
+        this.lastScriptExecutionSummary = undefined;
+        await this.rootLocator.switchToMainFrame()
+        await this.modalDialogHandler.reset();
+    }
+}
+
+/**
+ * @package
+ */
+class LastScriptExecutionSummary<Result = any> {
+    constructor(public readonly result: Result) {}
+}

package/src/screenplay/models/PlaywrightPageElement.ts

@@ -0,0 +1,235 @@
+import { LogicError } from '@serenity-js/core';
+import { PageElement, SelectOption, SwitchableOrigin } from '@serenity-js/web';
+import * as scripts from '@serenity-js/web/lib/scripts';
+import * as playwright from 'playwright-core';
+import { ensure, isDefined } from 'tiny-types';
+
+import { PlaywrightLocator } from './locators';
+
+export class PlaywrightPageElement extends PageElement<playwright.ElementHandle> {
+    of(parent: PageElement<playwright.ElementHandle>): PageElement<playwright.ElementHandle> {
+        return new PlaywrightPageElement(this.locator.of(parent.locator));
+    }
+
+    async enterValue(value: string | number | Array<string | number>): Promise<void> {
+        const text = [].concat(value).join('');
+
+        const element = await this.nativeElement();
+        return element.fill(text);
+    }
+
+    async clearValue(): Promise<void> {
+        try {
+            const element = await this.nativeElement();
+            await element.fill('');
+        }
+        catch(error) {
+            throw new LogicError(`The input field doesn't seem to have a 'value' attribute that could be cleared.`, error);
+        }
+    }
+
+    async click(): Promise<void> {
+        const element = await this.nativeElement();
+        return element.click();
+    }
+
+    async doubleClick(): Promise<void> {
+        const element = await this.nativeElement();
+        return element.dblclick();
+    }
+
+    async scrollIntoView(): Promise<void> {
+        const element = await this.nativeElement();
+        return element.scrollIntoViewIfNeeded();
+    }
+
+    async hoverOver(): Promise<void> {
+        const element = await this.nativeElement();
+        return element.hover();
+    }
+
+    async rightClick(): Promise<void> {
+        const element = await this.nativeElement();
+        return element.click({ button: 'right' });
+    }
+
+    async selectOptions(...options: Array<SelectOption>): Promise<void> {
+        const element = await this.nativeElement();
+
+        const optionsToSelect = options.map(option =>
+            ({
+                value: option.value,
+                label: option.label,
+            })
+        );
+
+        await element.selectOption(optionsToSelect);
+    }
+
+    async selectedOptions(): Promise<Array<SelectOption>> {
+        const element = await this.nativeElement();
+
+        const options = await element.$$eval(
+            'option',
+            /* istanbul ignore next */
+            (optionNodes: Array<HTMLOptionElement>) =>
+                optionNodes.map((optionNode: HTMLOptionElement) => {
+                    return {
+                        selected:   optionNode.selected,
+                        disabled:   optionNode.disabled,
+                        label:      optionNode.label,
+                        value:      optionNode.value,
+                    }
+                })
+        );
+
+        return options.map(option =>
+            new SelectOption(option.label, option.value, option.selected, option.disabled)
+        );
+    }
+
+    async attribute(name: string): Promise<string> {
+        const element = await this.nativeElement();
+        return element.getAttribute(name);
+    }
+
+    async text(): Promise<string> {
+        const element = await this.nativeElement();
+        return element.innerText();                     // eslint-disable-line unicorn/prefer-dom-node-text-content
+    }
+
+    async value(): Promise<string> {
+        const element = await this.nativeElement();
+        return element.inputValue();
+    }
+
+    async switchTo(): Promise<SwitchableOrigin> {
+        try {
+            const element = await this.nativeElement();
+
+            const frame = await element.contentFrame();
+
+            if (frame) {
+                const locator = (this.locator as PlaywrightLocator);
+
+                await locator.switchToFrame(element);
+
+                return {
+                    switchBack: async (): Promise<void> => {
+                        await locator.switchToParentFrame();
+                    }
+                }
+            }
+
+            const previouslyFocusedElement = await element.evaluateHandle(
+                /* istanbul ignore next */
+                (domNode: HTMLElement) => {
+                    const currentlyFocusedElement = document.activeElement;
+                    domNode.focus();
+                    return currentlyFocusedElement;
+                }
+            );
+
+            return new PreviouslyFocusedElementSwitcher(previouslyFocusedElement);
+        } catch(error) {
+            throw new LogicError(`Couldn't switch to page element located ${ this.locator }`, error);
+        }
+    }
+
+    async isActive(): Promise<boolean> {
+        try {
+            const element = await this.nativeElement();
+            return element.evaluate(
+                /* istanbul ignore next */
+                domNode => domNode === document.activeElement
+            );
+        } catch {
+            return false;
+        }
+    }
+
+    async isClickable(): Promise<boolean> {
+        try {
+            const element = await this.nativeElement();
+            await element.click({ trial: true });
+
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    async isEnabled(): Promise<boolean> {
+        try {
+            const element = await this.nativeElement();
+            return element.isEnabled();
+        } catch {
+            return false;
+        }
+    }
+
+    async isPresent(): Promise<boolean> {
+        try {
+            const element = await this.nativeElement();
+            return element !== null;
+        }
+        catch(error) {
+            if (error.name === 'TimeoutError') {
+                return false;
+            }
+            throw error;
+        }
+    }
+
+    async isSelected(): Promise<boolean> {
+
+        try {
+            const element: playwright.ElementHandle = await this.nativeElement();
+
+            // works for <option />
+            const selected = await element.getAttribute('selected');
+            if (selected !== null) {
+                return true;
+            }
+
+            // works only for checkboxes and radio buttons, throws for other elements
+            return await element.isChecked();
+        } catch {
+            return false;
+        }
+    }
+
+    async isVisible(): Promise<boolean> {
+        try {
+            const element = await this.nativeElement();
+
+            const isVisible = await element.isVisible();
+            if (! isVisible) {
+                return false;
+            }
+
+            return await element.evaluate(scripts.isVisible);
+        } catch {
+            return false;
+        }
+    }
+}
+
+/**
+ * @private
+ */
+class PreviouslyFocusedElementSwitcher implements SwitchableOrigin {
+    constructor(private readonly node: playwright.JSHandle) {
+        ensure('DOM element', node, isDefined());
+    }
+
+    async switchBack (): Promise<void> {
+        await this.node.evaluate(
+            /* istanbul ignore next */
+            (domNode: HTMLElement) => {
+                domNode.focus();
+            },
+            this.node
+        );
+    }
+}

package/src/screenplay/models/index.ts

@@ -0,0 +1,5 @@
+export * from './locators';
+export * from './PlaywrightBrowsingSession';
+export * from './PlaywrightCookie';
+export * from './PlaywrightPage';
+export * from './PlaywrightPageElement';