@serenity-js/web 3.0.0-rc.9 → 3.0.0

package/src/expectations/ElementExpectation.ts

@@ -1,108 +0,0 @@
-import { Answerable, AnswersQuestions, Expectation, ExpectationMet, ExpectationNotMet } from '@serenity-js/core';
-
-import { PageElement } from '../screenplay';
-
-/**
- * @desc
- *  A convenience method to create a custom {@link PageElement}-related {@link @serenity-js/core/lib/screenplay/questions~Expectation}
- *
- * @example <caption>Defining an expectation</caption>
- *  import { Expectation } from '@serenity-js/core';
- *  import { ElementExpectation, PageElement } from '@serenity-js/web';
- *
- *  export function isPresent(): Expectation<boolean, PageElement> {
- *      return ElementExpectation.forElementTo('become present', actual => actual.isPresent());
- *  }
- *
- * @example <caption>Using an expectation in an assertion</caption>
- *  import { Ensure } from '@serenity-js/assertions';
- *  import { actorCalled } from '@serenity-js/core';
- *  import { By, PageElement } from '@serenity-js/web';
- *
- *  const submitButton = () =>
- *      PageElement.located(By.css('.submit')).describedAs('submit button');
- *
- *  actorCalled('Izzy').attemptsTo(
- *      Ensure.that(submitButton(), isPresent())
- *  );
- *
- * @example <caption>Using an expectation in a synchronisation statement</caption>
- *  import { actorCalled, Duration } from '@serenity-js/core';
- *  import { By, PageElement, Wait } from '@serenity-js/web';
- *
- *  const submitButton = () =>
- *      PageElement.located(By.css('.submit')).describedAs('submit button');
- *
- *  actorCalled('Izzy').attemptsTo(
- *      Wait.upTo(Duration.ofSeconds(2)).until(submitButton(), isPresent())
- *  );
- *
- * @public
- * @extends {@serenity-js/core/lib/screenplay/questions~Expectation}
- */
-export class ElementExpectation extends Expectation<PageElement> {
-
-    /**
-     * @desc
-     *  Creates an {@link @serenity-js/core/lib/screenplay/questions~Expectation}
-     *
-     * @example <caption>Defining an expectation</caption>
-     *  import { Expectation } from '@serenity-js/core';
-     *  import { ElementExpectation, PageElement } from '@serenity-js/web';
-     *
-     *  export function isPresent(): Expectation<boolean, PageElement> {
-     *      return ElementExpectation.forElementTo('become present', actual => actual.isPresent());
-     *  }
-     *
-     * @param {string} description
-     *  A description of the expectation.
-     *  Please note that Serenity/JS will use it to describe your expectation in sentences like these:
-     *  - `actor ensures that <something> does <description>`
-     *  - `actor ensures that <something> does not <description>`
-     *  - `actor waits until <something> does <description>`
-     *  - `actor waits until <something> does not <description>`
-     *
-     *  To work with the above templates, the description should be similar to
-     *  - `become present`,
-     *  - `become active`,
-     *  - `equal X`,
-     *  - `has value greater than Y`.
-     *
-     *  Descriptions like "is present", "is active", "equals X", "is greater than Y" WILL NOT work well.
-     *
-     * @param {function(actual: PageElement): Promise<boolean>} fn
-     *  An asynchronous callback function that receives a {@link PageElement} and returns a {@link Promise}
-     *  that should resolve to `true` when the expectation is met, and `false` otherwise.
-     *
-     * @returns {ElementExpectation<any, PageElement>}
-     */
-    static forElementTo(description: string, fn: (actual: PageElement) => Promise<boolean>): Expectation<PageElement> {
-        return new ElementExpectation(description, fn);
-    }
-
-    /**
-     * @param {string} description
-     * @param {function(actual: PageElement): Promise<boolean>} fn
-     */
-    constructor(
-        description: string,
-        private readonly fn: (actual: PageElement) => Promise<boolean>,
-    ) {
-        super(
-            description,
-            async (actor: AnswersQuestions, actual: Answerable<PageElement>) => {
-                const pageElement = await actor.answer(actual);
-
-                try {
-                    const result = await fn(pageElement);
-
-                    return result
-                        ? new ExpectationMet(this.toString(), undefined, pageElement)
-                        : new ExpectationNotMet(this.toString(), undefined, pageElement);
-                } catch(error) {
-                    return new ExpectationNotMet(`${ description } (${ error.message })`, undefined, pageElement);
-                }
-            }
-        );
-    }
-}

package/src/input/index.ts

@@ -1 +0,0 @@
-export * from './Key';

package/src/screenplay/abilities/BrowserCapabilities.ts

@@ -1,5 +0,0 @@
-export interface BrowserCapabilities {
-    platformName?: string;
-    browserName?: string;
-    browserVersion?: string;
-}

package/src/screenplay/interactions/EnterBuilder.ts

@@ -1,28 +0,0 @@
-import { Answerable, Interaction } from '@serenity-js/core';
-
-import { PageElement } from '../models';
-
-/**
- * @desc
- *  Fluent interface to make the instantiation of
- *  the {@link @serenity-js/core/lib/screenplay~Interaction}
- *  to {@link Enter} more readable.
- *
- * @see {@link Enter}
- *
- * @interface
- */
-export interface EnterBuilder {
-
-    /**
-     * @desc
-     *  Instantiates an {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  to {@link Enter}.
-     *
-     * @param {Answerable<PageElement>} field
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link Target}
-     */
-    into: (field: Answerable<PageElement> /* | Question<AlertPromise> | AlertPromise */) => Interaction;
-}

package/src/screenplay/interactions/PressBuilder.ts

@@ -1,29 +0,0 @@
-import { Answerable } from '@serenity-js/core';
-import { Interaction } from '@serenity-js/core/lib/screenplay';
-
-import { PageElement } from '../models';
-
-/**
- * @desc
- *  Fluent interface to make the instantiation of
- *  the {@link @serenity-js/core/lib/screenplay~Interaction}
- *  to {@link Press} more readable.
- *
- * @see {@link Press}
- *
- * @interface
- */
-export interface PressBuilder {
-
-    /**
-     * @desc
-     *  Instantiates an {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  to {@link Press}.
-     *
-     * @param {Answerable<PageElement>} field
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link Target}
-     */
-    in: (field: Answerable<PageElement> /* | Question<AlertPromise> | AlertPromise */) => Interaction;
-}

package/src/screenplay/interactions/SelectBuilder.ts

@@ -1,36 +0,0 @@
-import { Answerable } from '@serenity-js/core';
-import { Interaction } from '@serenity-js/core/lib/screenplay';
-
-import { PageElement } from '../models';
-
-/**
- * @desc
- *  Configures the {@link Target} representing
- *  a [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)
- *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor}
- *  to interact with.
- *
- * @interface
- */
-export interface SelectBuilder {
-
-    /**
-     * @desc
-     *  Configures the {@link Target} representing
-     *  a [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)
-     *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  to interact with
-     *
-     * @param {Answerable<PageElement>} pageElement
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link Select}
-     * @see {@link Select.option}
-     * @see {@link Select.options}
-     * @see {@link Select.value}
-     * @see {@link Select.values}
-     * @see {@link Target}
-     */
-    from: (pageElement: Answerable<PageElement>) => Interaction;
-}

package/src/screenplay/interactions/Wait.ts

@@ -1,260 +0,0 @@
-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<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<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<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;
-
-        let expectationOutcome: ExpectationOutcome<any, Actual>;
-
-        return BrowseTheWeb.as(actor)
-            .waitUntil(
-                async function () {
-                    expectationOutcome = await actor.answer(expectation.isMetFor(actual));
-                    return expectationOutcome 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

@@ -1,34 +0,0 @@
-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<Actual>) => Interaction;
-}

package/src/screenplay/models/ModalDialog.ts

@@ -1,19 +0,0 @@
-import { Optional, Question, QuestionAdapter } from '@serenity-js/core';
-
-import { BrowseTheWeb } from '../abilities';
-
-export abstract class ModalDialog implements Optional {
-    static window(): QuestionAdapter<ModalDialog> {
-        return Question.about<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>;
-}

package/src/screenplay/questions/ElementQuestion.ts

@@ -1,58 +0,0 @@
-import { Answerable, AnswersQuestions, LogicError, Question } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-
-/**
- * @desc
- *  A base class for questions about {@link PageElement}s.
- *
- * @extends {@serenity-js/core/lib/screenplay~Question}
- */
-// todo: remove
-export abstract class ElementQuestion<T>
-    extends Question<T>
-{
-    constructor(protected subject: string) {
-        super();
-    }
-
-    /**
-     * @desc
-     *  Changes the description of this question's subject.
-     *
-     * @param {string} subject
-     * @returns {Question<T>}
-     */
-    describedAs(subject: string): this {
-        this.subject = subject;
-        return this;
-    }
-
-    toString(): string {
-        return this.subject;
-    }
-
-    /**
-     * @desc
-     *  Returns the resolved {@link PageElement}, or throws a {@link @serenity-js/core/lib/errors~LogicError}
-     *  if the element is `undefined`.
-     *
-     * @param {@serenity-js/core/lib/screenplay/actor~AnswersQuestions} actor
-     * @param {@serenity-js/core/lib/screenplay~Answerable<Element|ElementList>} element
-     *
-     * @returns {Promise<PageElement|PageElements>}
-     *
-     * @protected
-     */
-    protected async resolve<T>(
-        actor: AnswersQuestions,
-        element: Answerable<T>,
-    ): Promise<T> {
-        const resolved = await actor.answer(element);
-
-        if (! resolved) {
-            throw new LogicError(formatted `Couldn't find ${ element }`);
-        }
-
-        return resolved;
-    }
-}

package/tsconfig.eslint.json

@@ -1,10 +0,0 @@
-{
-  "extends": "./tsconfig",
-  "include": [
-    "src/**/*.ts",
-    "spec/**/*.ts"
-  ],
-  "exclude": [
-    "node_modules"
-  ]
-}