@serenity-js/web 3.0.0-rc.0

package/src/screenplay/interactions/Wait.ts

@@ -0,0 +1,264 @@
+import { Answerable, AnswersQuestions, AssertionError, Duration, Expectation, ExpectationMet, ExpectationOutcome, Interaction, UsesAbilities } from '@serenity-js/core';
+import { formatted } from '@serenity-js/core/lib/io';
+
+import { BrowseTheWeb } from '../abilities';
+import { WaitBuilder } from './WaitBuilder';
+
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  wait before proceeding either for a set {@link @serenity-js/core/lib/model~Duration}
+ *  or until a given {@link @serenity-js/core/lib/screenplay/questions~Expectation} is met.
+ *
+ *  Under the hood, `Wait` uses WebdriverIO ["explicit waiting"](https://webdriver.io/docs/autowait/)
+ *  mechanism.
+ *
+ * @example <caption>Example widget</caption>
+ *  <!--
+ *      After about 1 second, the text will change from 'Loading...' to 'Ready!'
+ *  -->
+ *  <h1 id="status">Loading...</h1>
+ *  <script>
+ *      (function () {
+ *          setTimeout(function () {
+ *              document.getElementById('status').textContent = 'Ready!'
+ *          }, 1000);
+ *      })();
+ *  </script>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class App {
+ *      static status = Target.the('status widget')
+ *          .located(by.id('status'));
+ *  }
+ *
+ * @example <caption>Waiting for a set amount of time</caption>
+ *  import { actorCalled, Duration } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Wait } from '@serenity-js/webdriverio';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Wendy')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Wait.for(Duration.ofSeconds(1.5)),
+ *          Ensure.that(App.status, equals('Ready!')),
+ *      );
+ *
+ *  // Please note that while the above implementation works,
+ *  // this approach is inefficient because at best
+ *  // the actor might wait too long and at worst the test
+ *  // might become "flaky" if any external interference
+ *  // (like network glitches, animations taking a bit too long etc.)
+ *  // makes the actor wait not long enough.
+ *
+ * @example <caption>Waiting until a condition is met</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Wait, Text } from '@serenity-js/webdriverio';
+ *  import { equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Wendy')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Wait.until(Text.of(App.status), equals('Ready!')),
+ *          // app is ready, proceed with the scenario
+ *      );
+ *
+ *  // Wait.until makes the Actor keep asking a Question,
+ *  // in this case Text.of(App.status), until the answer meets
+ *  // the expectation, or a timeout expires (default: 5s).
+ *  //
+ *  // Please note that both Ensure and Wait can be used with
+ *  // the same expectations, like `equals`.
+ *
+ * @example <caption>Changing the default timeout</caption>
+ *  import { actorCalled, Duration } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Wait, Text } from '@serenity-js/webdriverio';
+ *  import { equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Wendy')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Wait.upTo(Duration.ofSeconds(3))
+ *              .until(Text.of(App.status), equals('Ready!')),
+ *          // app is ready, proceed with the scenario
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link Text}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ * @see {@link @serenity-js/core/lib/model~Duration}
+ *
+ * @see {@link @serenity-js/core/lib/screenplay~Interaction}
+ */
+export class Wait {
+
+    /**
+     * @desc
+     *  Default timeout of 5 seconds used with {@link Wait.until}.
+     *
+     * @type {@serenity-js/core~Duration}
+     */
+    static readonly Default_Timeout = Duration.ofSeconds(5);
+
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to wait for a set duration.
+     *
+     * @param {Answerable<Duration>} duration
+     *  A set duration the {@link @serenity-js/core/lib/screenplay/actor~Actor} should wait for
+     *  before proceeding
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static for(duration: Answerable<Duration>): Interaction {
+        return new WaitFor(duration);
+    }
+
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to wait until the answer to the question (`actual`) meets the `expectation`,
+     *  or a custom timeout expires.
+     *
+     * @param {Duration} duration
+     *  Custom timeout to override {@link Wait.Default_Timeout}
+     *
+     * @returns {WaitBuilder}
+     */
+    static upTo(duration: Duration): WaitBuilder {
+        return {
+            until: <Actual>(actual: Answerable<Actual>, expectation: Expectation<any, Actual>): Interaction =>
+                new WaitUntil(actual, expectation, duration),
+        };
+    }
+
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to wait until the answer to the question (`actual`) meets the `expectation`,
+     *  or a {@link Wait.Default_Timeout} expires.
+     *
+     * @param {Answerable<Actual>} actual
+     *  A {@link @serenity-js/core/lib/screenplay~Question}
+     *  that the {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  will keep asking until the answer meets
+     *  the {@link @serenity-js/core/lib/screenplay/questions~Expectation} provided
+     *
+     * @param {@serenity-js/core/lib/screenplay/questions~<any,Actual>} expectation
+     *  An {@link @serenity-js/core/lib/screenplay/questions~Expectation} to be met before proceeding
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static until<Actual>(actual: Answerable<Actual>, expectation: Expectation<any, Actual>): Interaction {
+        return new WaitUntil(actual, expectation, Wait.Default_Timeout);
+    }
+}
+
+/**
+ * @package
+ */
+class WaitFor extends Interaction {
+    constructor(private readonly duration: Answerable<Duration>) {
+        super();
+    }
+
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions} actor
+     * @returns {Promise<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     */
+    async performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
+        return actor.answer(this.duration)
+            .then(duration => BrowseTheWeb.as(actor).waitFor(duration));
+    }
+
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString(): string {
+        return formatted`#actor waits for ${ this.duration }`;
+    }
+}
+
+/**
+ * @package
+ */
+class WaitUntil<Actual> extends Interaction {
+    constructor(
+        private readonly actual: Answerable<Actual>,
+        private readonly expectation: Expectation<any, Actual>,
+        private readonly timeout: Duration,
+    ) {
+        super();
+    }
+
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions} actor
+     * @returns {Promise<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
+        const
+            actual      = this.actual,
+            expectation = this.expectation.answeredBy(actor);
+
+        let expectationOutcome: ExpectationOutcome<any, Actual>;
+
+        return BrowseTheWeb.as(actor)
+            .waitUntil(function () {
+                return actor.answer(actual)
+                    .then(act => expectation(act))
+                    .then(outcome => {
+                        expectationOutcome = outcome;
+
+                        return outcome instanceof ExpectationMet;
+                    });
+            },
+            this.timeout
+            )
+            .catch(error => {
+                if (expectationOutcome) {
+                    throw new AssertionError(
+                        `Waited ${ this.timeout.toString() } for ${ formatted `${ this.actual }` } to ${ this.expectation.toString() }`,
+                        expectationOutcome.expected,
+                        expectationOutcome.actual,
+                        error,
+                    );
+                }
+
+                throw error;
+            });
+    }
+
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString(): string {
+        return formatted`#actor waits up to ${ this.timeout } until ${ this.actual } does ${ this.expectation }`;
+    }
+}

package/src/screenplay/interactions/WaitBuilder.ts

@@ -0,0 +1,34 @@
+import { Answerable, Expectation, Interaction } from '@serenity-js/core';
+
+/**
+ * @desc
+ *  Fluent interface to make the instantiation of
+ *  the {@link @serenity-js/core/lib/screenplay~Interaction}
+ *  to {@link Wait} more readable.
+ *
+ * @see {@link Wait}
+ *
+ * @interface
+ */
+export interface WaitBuilder {
+
+    /**
+     * @desc
+     *  Instantiates an {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  to {@link Wait}.
+     *
+     * @param {Answerable<Actual>} actual
+     *  A {@link @serenity-js/core/lib/screenplay~Question}
+     *  that the {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  will keep asking until the answer meets
+     *  the {@link @serenity-js/core/lib/screenplay/questions~Expectation} provided
+     *
+     * @param {@serenity-js/core/lib/screenplay/questions~Expectation<any,Actual>} expectation
+     *  An {@link @serenity-js/assertions~Expectation} to be met before proceeding
+     *
+     * @returns {Interaction}
+     *
+     * @see {@link Target}
+     */
+    until: <Actual>(actual: Answerable<Actual>, expectation: Expectation<any, Actual>) => Interaction;
+}

package/src/screenplay/interactions/index.ts

@@ -0,0 +1,16 @@
+export * from './Clear';
+export * from './Click';
+export * from './DoubleClick';
+export * from './Enter';
+export * from './ExecuteScript';
+export * from './Hover';
+export * from './Navigate';
+export * from './Press';
+export * from './PressBuilder';
+export * from './RightClick';
+export * from './Scroll';
+export * from './Select';
+export * from './SelectBuilder';
+export * from './Switch';
+export * from './TakeScreenshot';
+export * from './Wait';

package/src/screenplay/models/Cookie.ts

@@ -0,0 +1,219 @@
+import { Adapter, Answerable, Interaction, Question, Timestamp } from '@serenity-js/core';
+import { formatted } from '@serenity-js/core/lib/io';
+import { ensure, isBoolean, isDefined, isInstanceOf, isOneOf, isPlainObject, isString, Predicate } from 'tiny-types';
+
+import { CookieMissingError } from '../../errors';
+import { BrowseTheWeb } from '../abilities';
+import { CookieData } from './CookieData';
+
+export abstract class Cookie {
+
+    /**
+     * @desc
+     *  Creates a {@link @serenity-js/core/lib/screenplay~Question} about a Cookie
+     *
+     * @param {Answerable<string>} name
+     * @returns {Question<Promise<Cookie>> & Adapter<Cookie>}
+     */
+    static called(name: Answerable<string>): Question<Promise<Cookie>> & Adapter<Cookie> {
+        return Question.about(`"${ name }" cookie`, async actor => {
+            const cookieName = await actor.answer(name);
+            return BrowseTheWeb.as(actor).cookie(cookieName);
+        });
+    }
+
+    /**
+     * @desc
+     *  Sets a cookie for the current page.
+     *  Make sure that the actor performing this interaction is on the page that should receive the cookie.
+     *  An actor can't set a cookie for an arbitrary page without being on that page.
+     *
+     * @param {Answerable<CookieData>} cookieData
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static set(cookieData: Answerable<CookieData>): Interaction {
+
+        return Interaction.where(formatted `#actor sets cookie: ${ cookieData }`, async actor => {
+            const cookie = ensure('cookieData', await actor.answer(cookieData), isDefined(), isPlainObject());
+
+            const sanitisedCookieData: CookieData = {
+                name:         ensure(`Cookie.set(cookieData.name)`,     cookie.name,  isDefined(), isString()),
+                value:        ensure(`Cookie.set(cookieData.value)`,    cookie.value, isDefined(), isString()),
+                path:         ensureIfPresent(cookie, 'path',       isString()),
+                domain:       ensureIfPresent(cookie, 'domain',     isString()),
+                secure:       ensureIfPresent(cookie, 'secure',     isBoolean()),
+                httpOnly:     ensureIfPresent(cookie, 'httpOnly',   isBoolean()),
+                expiry:       ensureIfPresent(cookie, 'expiry',     isInstanceOf(Timestamp)),
+                sameSite:     ensureIfPresent(cookie, 'sameSite',   isOneOf<'Lax' | 'Strict' | 'None'>('Lax', 'Strict', 'None')),
+            }
+
+            return BrowseTheWeb.as(actor).setCookie(sanitisedCookieData);
+        });
+    }
+
+    /**
+     * @desc
+     *  Creates an {@link @serenity-js/core/lib/screenplay~Interaction} to delete all cookies currently set in the browser.
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static deleteAll(): Interaction {
+        return Interaction.where(`#actor deletes all cookies`, actor => {
+            return BrowseTheWeb.as(actor).deleteAllCookies();
+        });
+    }
+
+    private cookie: CookieData;
+
+    protected constructor(protected readonly cookieName: string) {
+        ensure('browser', cookieName, isDefined());
+    }
+
+    name(): string {
+        return this.cookieName;
+    }
+
+    /**
+     * @desc
+     *  Checks if a given cookie is set.
+     *
+     * @returns {Promise<boolean>}
+     */
+    async isPresent(): Promise<boolean> {
+        try {
+            const cookie = await this.lazyLoadCookie();
+            return cookie && cookie.name === this.cookieName;
+        }
+        catch(error) {
+            if (error instanceof CookieMissingError) {
+                return false;
+            }
+
+            throw error;
+        }
+    }
+
+    /**
+     * @desc
+     *  Returns the value of a given cookie.
+     *
+     * @returns {Promise<string>}
+     */
+    async value(): Promise<string> {
+        const cookie = await this.lazyLoadCookie();
+        return cookie.value;
+    }
+
+    /**
+     * @desc
+     *  Returns the path of a given cookie, if any was set.
+     *
+     * @returns {Promise<string>}
+     */
+    async path(): Promise<string> {
+        const cookie = await this.lazyLoadCookie();
+        return cookie.path;
+    }
+
+    /**
+     * @desc
+     *  Returns the domain of a given cookie, if any was set.
+     *
+     * @returns {Promise<string>}
+     */
+    async domain(): Promise<string> {
+        const cookie = await this.lazyLoadCookie();
+        return cookie.domain;
+    }
+
+    /**
+     * @desc
+     *  Checks if a given cookie is HTTP-only.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies
+     *
+     * @returns {Promise<string>}
+     */
+    async isHttpOnly(): Promise<boolean> {
+        const cookie = await this.lazyLoadCookie();
+        return cookie.httpOnly;
+    }
+
+    /**
+     * @desc
+     *  Checks if a given cookie is secure.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies
+     *
+     * @returns {Promise<string>}
+     */
+    async isSecure(): Promise<boolean> {
+        const cookie = await this.lazyLoadCookie();
+        return cookie.secure;
+    }
+
+    /**
+     * @desc
+     *  Returns the expiry date of a given cookie
+     *
+     * @returns {Promise<Timestamp>}
+     */
+    async expiry(): Promise<Timestamp> {
+        const cookie = await this.lazyLoadCookie();
+        return cookie.expiry;
+    }
+
+    /**
+     * @desc
+     *  Deletes a given cookie.
+     *
+     * @abstract
+     *
+     * @returns {Promise<void>}
+     */
+    abstract delete(): Promise<void>;
+
+    /**
+     * @desc
+     *  Reads a given cookie from the browser.
+     *
+     *  This method is to be implemented by integration tool-specific adapters.
+     *  **Please note**: you don't need to implement any response caching here
+     *  since it is covered by {@link Cookie#lazyLoadCookie} method.
+     *
+     * @protected
+     * @abstract
+     *
+     * @returns {Promise<void>}
+     */
+    protected abstract read(): Promise<CookieData>;
+
+    /**
+     * @desc
+     *  Invokes {@link Cookie#read} and caches the result in memory.
+     *
+     * @private
+     * @returns {Promise<CookieData>}
+     */
+    private async lazyLoadCookie(): Promise<CookieData> {
+        if (! this.cookie) {
+            this.cookie = await this.read();
+        }
+
+        return this.cookie;
+    }
+}
+
+/**
+ * @ignore
+ * @private
+ *
+ * @param data
+ * @param property
+ * @param predicates
+ */
+function ensureIfPresent<K extends keyof CookieData>(data: CookieData, property: K, ...predicates: Array<Predicate<CookieData[K]>>): CookieData[K] | undefined {
+    return data[property] !== undefined
+        ? ensure(`Cookie.set(cookieData.${property})`, data[property], ...predicates)
+        : undefined;
+}

package/src/screenplay/models/CookieData.ts

@@ -0,0 +1,97 @@
+import { Timestamp } from '@serenity-js/core';
+
+/**
+ * @desc
+ *  A data structure describing a {@link Cookie} to be set or that's been read.
+ *
+ * @public
+ */
+export interface CookieData {
+    /**
+     * @desc
+     *  The name of the cookie.
+     *
+     * @type {string}
+     * @public
+     */
+    name: string;
+
+    /**
+     * @desc
+     *  The value of the cookie.
+     *
+     * @type {string}
+     * @public
+     */
+    value: string;
+
+    /**
+     * @desc
+     *  The domain the cookie is visible to.
+     *  Defaults to the current browsing context's document's URL when setting a cookie.
+     *
+     * Optional.
+     *
+     * @type {string}
+     * @public
+     */
+    domain?: string;
+
+    /**
+     * @desc
+     *  The cookie path. Defaults to "/" when adding a cookie.
+     *
+     * Optional.
+     *
+     * @type {string}
+     * @public
+     */
+    path?: string;
+
+    /**
+     * @desc
+     *  The {@link @serenity-js/core/lib/model~Timestamp} of when the cookie expires.
+     *
+     * Optional.
+     *
+     * @type {@serenity-js/core/lib/model~Timestamp}
+     * @public
+     */
+    expiry?: Timestamp;
+
+    /**
+     * @desc
+     *  Whether the cookie is an HTTP-only cookie. Defaults to false when adding a new cookie.
+     *
+     * Optional.
+     *
+     * @type {boolean}
+     * @public
+     */
+    httpOnly?: boolean;
+
+    /**
+     * @desc
+     *  Whether the cookie is a secure cookie. Defaults to false when adding a new cookie.
+     *
+     *  Optional.
+     *
+     * @type {boolean}
+     * @public
+     */
+    secure?: boolean;
+
+    /**
+     * @desc
+     *  Whether the cookie applies to a SameSite policy.
+     *  Defaults to "None" if omitted when adding a cookie.
+     *
+     *  Can be set to either "Lax" or "Strict".
+     *
+     *  Optional.
+     *
+     * @type {string}
+     * @public
+     */
+    sameSite?: 'Lax' | 'Strict' | 'None';
+}

package/src/screenplay/models/ModalDialog.ts

@@ -0,0 +1,19 @@
+import { Adapter, Question } from '@serenity-js/core';
+
+import { BrowseTheWeb } from '../abilities';
+
+export abstract class ModalDialog {
+    static window(): Question<Promise<ModalDialog>> & Adapter<ModalDialog> {
+        return Question.about<Promise<ModalDialog>>('modal dialog', actor => {
+            return BrowseTheWeb.as(actor).modalDialog();
+        });
+    }
+
+    abstract accept(): Promise<void>;
+    abstract dismiss(): Promise<void>;
+
+    abstract text(): Promise<string>;
+    abstract enterValue(value: string | number | Array<string | number>): Promise<void>;
+
+    abstract isPresent(): Promise<boolean>;
+}