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

package/src/screenplay/interactions/Click.ts

@@ -1,96 +0,0 @@
-import { AnswersQuestions, Interaction, Question, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-import { ElementFinder } from 'protractor';
-
-import { withAnswerOf } from '../withAnswerOf';
-
-/**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  [click](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event) on a given Web element.
- *
- * @example <caption>Example widget</caption>
- *  <form>
- *    <input type="text" name="example" id="example" />
- *  </form>
- *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { Target } from '@serenity-js/protractor';
- *  import { by } from 'protractor';
- *
- *  class Form {
- *      static exampleInput = Target.the('example input')
- *          .located(by.id('example'));
- *  }
- *
- * @example <caption>Clicking on an element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Click, isSelected } from '@serenity-js/protractor';
- *  import { Ensure } from '@serenity-js/assertions';
- *  import { protractor } from 'protractor';
- *
- *  actorCalled('Chloé')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Click.on(Form.exampleInput),
- *          Ensure.that(Form.exampleInput, isSelected()),
- *      );
- *
- * @see {@link BrowseTheWeb}
- * @see {@link Target}
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link isSelected}
- *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
- */
-export class Click extends Interaction {
-
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Question<ElementFinder> | ElementFinder} target
-     *  The element to be clicked on
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     */
-    static on(target: Question<ElementFinder> | ElementFinder): Interaction {
-        return new Click(target);
-    }
-
-    /**
-     * @param {Question<ElementFinder> | ElementFinder} target
-     *  The element to be clicked on
-     */
-    constructor(private readonly target: Question<ElementFinder> | ElementFinder) {
-        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
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<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> {
-        return withAnswerOf(actor, this.target, (elf: ElementFinder) => elf.click());
-    }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return formatted `#actor clicks on ${ this.target }`;
-    }
-}

package/src/screenplay/interactions/Close.ts

@@ -1,184 +0,0 @@
-import { AnswersQuestions, Interaction, UsesAbilities } from '@serenity-js/core';
-
-import { BrowseTheWeb } from '../abilities';
-
-/**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  close browser tabs or windows.
- *
- * @example <caption>Closing a browser tab or window</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Click, Close, Switch } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
- *
- *  actorCalled('Caleb')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Click.on(someLinkThatOpensANewWindow),
- *
- *          Switch.toNewWindow().and(
- *              // perform activities in the context of the new window
- *              Close.currentWindow(),
- *          ),
- *      );
- *
- * @example <caption>Closing any new windows after a Jasmine test</caption>
- *  import 'jasmine';
- *
- *  import { actorInTheSpotlight } from '@serenity-js/core';
- *  import { Close } from '@serenity-js/protractor';
- *
- *  after(() =>
- *      actorInTheSpotlight().attemptsTo(
- *          Close.anyNewWindows(),
- *      ));
- *
- * @example <caption>Closing any new windows after a Mocha test</caption>
- *  import 'mocha';
- *
- *  import { actorInTheSpotlight } from '@serenity-js/core';
- *  import { Close } from '@serenity-js/protractor';
- *
- *  after(() =>
- *      actorInTheSpotlight().attemptsTo(
- *          Close.anyNewWindows(),
- *      ));
- *
- * @example <caption>Closing any new windows after a    Cucumber scenario</caption>
- *  import { actorInTheSpotlight } from '@serenity-js/core';
- *  import { Close } from '@serenity-js/protractor';
- *  import { After } from 'cucumber';
- *
- *  After(() =>
- *      actorInTheSpotlight().attemptsTo(
- *          Close.anyNewWindows(),
- *      ));
- *
- * @see {@link Switch}
- */
-export class Close {
-
-    /**
-     * @desc
-     *  Closes any windows other than the original one that
-     *  the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  has {@link Navigate}d to.
-     *
-     *  When the windows are closed, it switches the context
-     *  back to the original window.
-     *
-     * @static
-     * @returns {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link Switch}
-     */
-    static anyNewWindows(): Interaction {
-        return new CloseWindowsOtherThan(actor => BrowseTheWeb.as(actor).getOriginalWindowHandle(), `#actor closes any new windows`);
-    }
-
-    /**
-     * @desc
-     *  Closes the currently focused browser window.
-     *
-     *  **Please note** that this interaction should be used to close
-     *  pop-up windows or any new windows/tabs opened during the test
-     *  rather than the _main_ window, which is managed by Protractor.
-     *
-     *  See tests for usage examples.
-     *
-     * @static
-     * @returns {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link Switch}
-     */
-    static currentWindow(): Interaction {
-        return new CloseCurrentWindow();
-    }
-}
-
-/**
- * @package
- */
-class CloseWindowsOtherThan extends Interaction {
-    constructor(
-        private readonly windowToKeepBy: (actor: UsesAbilities & AnswersQuestions) => Promise<string>,
-        private readonly description: string = `#actor closes several windows`,
-    ) {
-        super();
-    }
-
-    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
-        return this.windowToKeepBy(actor)
-            .then(windowToKeep => this.windowsOtherThan(windowToKeep, actor)
-                .then(windowsToClose => this.closeAll(windowsToClose, actor))
-                .then(() => this.switchTo(windowToKeep, actor)),
-            );
-    }
-
-    toString(): string {
-        return this.description;
-    }
-
-    /**
-     * @param {string} windowToKeep
-     * @param {UsesAbilities & AnswersQuestions} actor
-     * @private
-     */
-    private windowsOtherThan(windowToKeep: string, actor: UsesAbilities & AnswersQuestions) {
-        return BrowseTheWeb.as(actor).getAllWindowHandles()
-            .then(allWindows =>
-                this.isDefined(windowToKeep) && allWindows.length > 1
-                    ? allWindows.filter(handle => handle !== windowToKeep)
-                    : []
-            )
-    }
-
-    /**
-     * @param {string[]} windows
-     * @param {UsesAbilities & AnswersQuestions} actor
-     * @private
-     */
-    private closeAll(windows: string[], actor: UsesAbilities & AnswersQuestions) {
-        return windows.reduce(
-            (previous, handle) => {
-                return previous
-                    .then(() => BrowseTheWeb.as(actor).switchToWindow(handle))
-                    .then(() => BrowseTheWeb.as(actor).closeCurrentWindow());
-            },
-            Promise.resolve()
-        );
-    }
-
-    /**
-     * @param {string} window
-     * @param {UsesAbilities & AnswersQuestions} actor
-     * @private
-     */
-    private switchTo(window: string, actor: UsesAbilities & AnswersQuestions): Promise<void> {
-        return this.isDefined(window)
-            ? BrowseTheWeb.as(actor).switchToWindow(window)
-            : Promise.resolve();
-    }
-
-    /**
-     * @param {any} value
-     * @private
-     */
-    private isDefined(value: any) {
-        return value !== undefined && value !== null;
-    }
-}
-
-/**
- * @package
- */
-class CloseCurrentWindow extends Interaction {
-    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
-        return BrowseTheWeb.as(actor).closeCurrentWindow();
-    }
-
-    toString(): string {
-        return `#actor closes current browser window`;
-    }
-}

package/src/screenplay/interactions/DeleteCookies.ts

@@ -1,154 +0,0 @@
-import { Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-
-import { promiseOf } from '../../promiseOf';
-import { BrowseTheWeb } from '../abilities';
-
-/**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  remove cookies from the browser.
- *
- * @example <caption>Removing a single cookie</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Navigate, DeleteCookies } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
- *
- *  actorCalled('Sid')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Navigate.to('/login'),
- *          DeleteCookies.called('jwt_token'),
- *          Navigate.reloadPage(),
- *      );
- *
- * @example <caption>Removing all cookies before each Jasmine test</caption>
- *  import 'jasmine';
- *
- *  import { actorInTheSpotlight } from '@serenity-js/core';
- *  import { DeleteCookies } from '@serenity-js/protractor';
- *
- *  before(() =>
- *      actorInTheSpotlight().attemptsTo(
- *          DeleteCookies.all(),
- *      ));
- *
- * @example <caption>Removing all cookies before each Mocha test</caption>
- *  import 'mocha';
- *
- *  import { actorInTheSpotlight } from '@serenity-js/core';
- *  import { DeleteCookies } from '@serenity-js/protractor';
- *
- *  before(() =>
- *      actorInTheSpotlight().attemptsTo(
- *          DeleteCookies.all(),
- *      ));
- *
- * @example <caption>Removing all cookies before each Cucumber scenario</caption>
- *  import { actorInTheSpotlight } from '@serenity-js/core';
- *  import { DeleteCookies } from '@serenity-js/protractor';
- *  import { Before } from 'cucumber';
- *
- *  Before(() =>
- *      actorInTheSpotlight().attemptsTo(
- *          DeleteCookies.all(),
- *      ));
- *
- * @see {@link Navigate}
- */
-export class DeleteCookies {
-
-    /**
-     * @desc
-     *  Removes a single cookie identified by `cookieName`.
-     *
-     * @param {Answerable<string>} cookieName
-     *  The name of the cookie to be deleted
-     *
-     * @returns {@link @serenity-js/core/lib/screenplay~Interaction}
-     */
-    static called(cookieName: Answerable<string>): Interaction {
-        return new DeleteCookieCalled(cookieName);
-    }
-
-    /**
-     * @desc
-     *  Removes any cookies set.
-     *
-     * @returns {@link @serenity-js/core/lib/screenplay~Interaction}
-     */
-    static all(): Interaction {
-        return new DeletesAllCookies();
-    }
-}
-
-/**
- * @package
- */
-class DeleteCookieCalled implements Interaction {
-    constructor(private readonly name: Answerable<string>) {
-    }
-
-    /**
-     * @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
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<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): Promise<void> {
-        return actor.answer(this.name)
-            .then(name => BrowseTheWeb.as(actor).manage().deleteCookie(name));
-    }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return formatted `#actor deletes the "${ this.name }" cookie`;
-    }
-}
-
-/**
- * @package
- */
-class DeletesAllCookies implements Interaction {
-
-    /**
-     * @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
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<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): Promise<void> {
-        return promiseOf(BrowseTheWeb.as(actor).manage().deleteAllCookies());
-    }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return `#actor deletes all cookies`;
-    }
-}

package/src/screenplay/interactions/Dismiss.ts

@@ -1,99 +0,0 @@
-import { AnswersQuestions, Interaction, Question, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-import { AlertPromise } from 'selenium-webdriver';
-
-/**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  dismiss a {@link ModalDialog}.
- *
- * @example <caption>Example widget</caption>
- *  <button
- *      data-test="trigger"
- *      onclick="alert('hello!')">Trigger Alert</button>
- *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { Target } from '@serenity-js/protractor';
- *  import { by } from 'protractor';
- *
- *  class Widget {
- *      static trigger = Target.the('trigger button')
- *          .located(by.css('[data-test="trigger"]'));
- *  }
- *
- * @example <caption>Dismissing a modal dialog window</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Click, Dismiss, ModalDialog } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
- *
- *  actorCalled('Nick')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Click.on(Widget.trigger),
- *          Dismiss.the(ModalDialog.window()),
- *      );
- *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
- *
- * @see {@link Accept}
- * @see {@link ModalDialog}
- */
-export class Dismiss extends Interaction {
-
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  with a {@link ModalDialog.window} the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  will dismiss.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Question<AlertPromise> | AlertPromise} modalDialogWindow
-     *  The modal dialog window to dismiss
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link ModalDialog.window}
-     * @see {@link @serenity-js/core/lib/screenplay~Question}
-     */
-    static the(modalDialogWindow: Question<AlertPromise> | AlertPromise): Interaction {
-        return new Dismiss(modalDialogWindow);
-    }
-
-    /**
-     * @param {@serenity-js/core/lib/screenplay~Question<AlertPromise> | AlertPromise} modalDialogWindow
-     *  The modal dialog window to dismiss
-     *
-     * @see {@link ModalDialog.window}
-     */
-    constructor(private readonly modalDialogWindow: Question<AlertPromise> | AlertPromise) {
-        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
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<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> {
-        return actor.answer(this.modalDialogWindow)
-            .then(alert => alert.dismiss());
-    }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return formatted `#actor dismisses ${ this.modalDialogWindow }`;
-    }
-}

package/src/screenplay/interactions/DoubleClick.ts

@@ -1,124 +0,0 @@
-import { AnswersQuestions, Interaction, Question, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-import { ElementFinder } from 'protractor';
-
-import { BrowseTheWeb } from '../abilities';
-import { withAnswerOf } from '../withAnswerOf';
-
-/**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  perform a double-click on a given Web element.
- *
- * @example <caption>Example widget</caption>
- *  <!--
- *      The editor shows up when the user double-clicks
- *      on one of the properties of their profile
- *      and let's them change the value of that property.
- *  -->
- *  <div id="user-profile">
- *      <ul>
- *          <li id="display-name" ondblclick="edit(this)">User12345</li>
- *          <li id="email-address" ondblclick="edit(this)">tester@example.org</li>
- *      </ul>
- *      <form id="editor" class="hidden">
- *          <input type="text" value="" />
- *      </form>
- *  </div>
- *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { Target } from '@serenity-js/protractor';
- *  import { by } from 'protractor';
- *
- *  class UserProfile {
- *      static displayName = Target.the('display name')
- *          .located(by.id('display-name'));
- *      static emailAddress = Target.the('email address')
- *          .located(by.id('email-address'));
- *      static editor = Target.the('editor')
- *          .located(by.id('editor'));
- *  }
- *
- * @example <caption>Double-clicking on an element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, DoubleClick, isVisible, Enter, Text, Wait } from '@serenity-js/protractor';
- *  import { Ensure, equals, not } from '@serenity-js/assertions';
- *  import { protractor, Key } from 'protractor';
- *
- *  actorCalled('Dorothy')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          DoubleClick.on(UserProfile.displayName),
- *          Wait.until(UserProfile.editor, isVisible()),
- *
- *          Enter.theValue('New username').into(UserProfile.editor),
- *          Press.the(Key.ENTER).in(UserProfile.editor),
- *
- *          Ensure.that(Text.of(UserProfile.displayName), equals('New username')),
- *          Ensure.that(UserProfile.editor, not(isVisible()))
- *      );
- *
- * @see {@link Target}
- *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
- */
-export class DoubleClick extends Interaction {
-
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Question<ElementFinder> | ElementFinder} target
-     *  The element to be double-clicked on
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     */
-    static on(target: Question<ElementFinder> | ElementFinder): Interaction {
-        return new DoubleClick(target);
-    }
-
-    /**
-     * @param {Question<ElementFinder> | ElementFinder} target
-     *  The element to be double-clicked on
-     */
-    constructor(private readonly target: Question<ElementFinder> | ElementFinder) {
-        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
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<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> {
-        // Since the deprecation of Webdriver's ControlFlow,
-        // Protractor's doubleClick might behave incorrectly when promises are used.
-        // The mouseMove/doubleClick combo works around that problem.
-        // See https://github.com/angular/protractor/issues/4578
-
-        return withAnswerOf(actor, this.target, (elf: ElementFinder) =>
-            BrowseTheWeb.as(actor).actions()
-                .mouseMove(elf)
-                .perform()
-                .then(() => BrowseTheWeb.as(actor).actions().doubleClick().perform()));
-    }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return formatted `#actor double-clicks on ${ this.target }`;
-    }
-}