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

package/src/screenplay/interactions/RightClick.ts

@@ -1,114 +0,0 @@
-import { AnswersQuestions, Interaction, Question, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-import { ElementFinder, protractor,WebElement } from 'protractor';
-
-import { BrowseTheWeb } from '../abilities';
-import { withAnswerOf } from '../withAnswerOf';
-
-/**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  perfom a right click on a given Web element.
- *
- *  This is typically used to open a [custom context menu](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event)
- *  on a given Web element, since it's not possible to interact with the standard context menu offered by your browser
- *
- * @example <caption>Example widget</caption>
- *  <form>
- *    <input type="text" id="field"
- *      oncontextmenu="showMenu(); return false;" />
- *
- *    <div id="context-menu" style="display:none">
- *      Custom context menu
- *    </div>
- *  </form>
- *
- *  <script>
- *    function showMenu() {
- *      document.getElementById("context-menu").style.display = 'block';
- *    }
- *  </script>
- *
- * @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'));
- *      static exampleContextMenu = Target.the('example context menu')
- *          .located(by.id('context-menu'));
- *  }
- *
- * @example <caption>Right-click on an element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, RightClick, isVisible } from '@serenity-js/protractor';
- *  import { Ensure } from '@serenity-js/assertions';
- *  import { protractor } from 'protractor';
- *
- *  actorCalled('Chloé')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          RightClick.on(Form.exampleInput),
- *          Ensure.that(Form.exampleContextMenu, isVisible()),
- *      );
- *
- * @see {@link BrowseTheWeb}
- * @see {@link Target}
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link isVisible}
- *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
- */
-export class RightClick extends Interaction {
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Question<ElementFinder> | ElementFinder} target
-     *  The element to be right clicked on
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     */
-    static on(target: Question<ElementFinder> | ElementFinder): Interaction {
-        return new RightClick(target);
-    }
-
-    /**
-     * @param {Question<ElementFinder> | ElementFinder} target
-     *  The element to be right 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: WebElement) =>
-            BrowseTheWeb.as(actor).actions().mouseMove(elf).perform()
-        ).then(() => BrowseTheWeb.as(actor).actions().click(protractor.Button.RIGHT).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 right clicks on ${this.target}`;
-    }
-}

package/src/screenplay/interactions/Scroll.ts

@@ -1,99 +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
- *  scroll until a given Web element comes into view.
- *
- * @example <caption>Example widget</caption>
- *  <!--
- *      an element somewhere at the bottom of the page,
- *      outside of the visible area
- *  -->
- *  <input type="submit" id="submit" />
- *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { Target } from '@serenity-js/protractor';
- *  import { by } from 'protractor';
- *
- *  class Form {
- *      static submitButton = Target.the('submit button')
- *          .located(by.id('submit'));
- *  }
- *
- * @example <caption>Scrolling to element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Ensure } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, Scroll, isVisible } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
- *
- *  actorCalled('Sara')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Scroll.to(Form.submitButton),
- *          Ensure.that(Form.submitButton, isVisible()),
- *      );
- *
- * @see {@link BrowseTheWeb}
- * @see {@link Target}
- * @see {@link isVisible}
- * @see {@link @serenity-js/assertions~Ensure}
- *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
- */
-export class Scroll extends Interaction {
-
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Question<ElementFinder> | ElementFinder} target
-     *  The element to be scroll to
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     */
-    static to(target: Question<ElementFinder> | ElementFinder): Scroll {
-        return new Scroll(target);
-    }
-
-    /**
-     * @param {Question<ElementFinder> | ElementFinder} target
-     *  The element to be scroll to
-     */
-    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) => BrowseTheWeb.as(actor).actions().mouseMove(elf).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 scrolls to ${this.target}`;
-    }
-}

package/src/screenplay/interactions/Select.ts

@@ -1,402 +0,0 @@
-import { Answerable, AnswersQuestions, Question } from '@serenity-js/core';
-import { commaSeparated, formatted } from '@serenity-js/core/lib/io';
-import { inspected } from '@serenity-js/core/lib/io/inspected';
-import { Interaction, UsesAbilities } from '@serenity-js/core/lib/screenplay';
-import { by, ElementFinder } from 'protractor';
-import { promise } from 'selenium-webdriver';
-
-import { promiseOf } from '../../promiseOf';
-import { Value } from '../questions';
-import { withAnswerOf } from '../withAnswerOf';
-import { SelectBuilder } from './SelectBuilder';
-
-/**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  select an option from a [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select),
- *  either by its display name, or by value.
- *
- * @see {@link Selected}
- */
-export class Select {
-
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  with a [`value`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option#attr-value)
-     *  of a single [`<option>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
-     *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor} to select.
-     *
-     * @example <caption>Example widget</caption>
-     *  <select data-test='countries'>
-     *      <option value='UK'>United Kingdom</option>
-     *      <option value='PL'>Poland</option>
-     *      <option value='US'>United States</option>
-     *  </select>
-     *
-     * @example <caption>Lean Page Object describing the widget</caption>
-     *  import { Target } from '@serenity-js/protractor';
-     *  import { browser, by } from 'protractor';
-     *
-     *  class Countries {
-     *      static dropdown = Target.the('countries dropdown')
-     *          .located(by.css('[data-test="countries"]'));
-     *  }
-     *
-     * @example <caption>Retrieving the selected value</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { BrowseTheWeb, Select, Selected } from '@serenity-js/protractor';
-     *  import { Ensure, equals } from '@serenity-js/assertions';
-     *  import { protractor } from 'protractor';
-     *
-     *  actorCalled('Nick')
-     *      .whoCan(BrowseTheWeb.using(protractor.browser))
-     *      .attemptsTo(
-     *          Select.value('UK').from(Countries.dropdown),
-     *          Ensure.that(Selected.valueOf(Countries.dropdown), equals('UK')),
-     *      );
-     *
-     * @param {string | Answerable<string>} value
-     *  A value of the [`option` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
-     *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor} to select
-     *
-     * @returns {SelectBuilder}
-     *
-     * @see {@link Selected.valueOf}
-     * @see {@link BrowseTheWeb}
-     * @see {@link Target}
-     * @see {@link @serenity-js/assertions~Ensure}
-     * @see {@link @serenity-js/assertions/lib/expectations~equals}
-     */
-    static value(value: string | Answerable<string>): SelectBuilder {
-        return {
-            from: (target: Question<ElementFinder> | ElementFinder): Interaction =>
-                new SelectValue(value, target)
-        };
-    }
-
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  with [`value`s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option#attr-value)
-     *  of multiple [`<option>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
-     *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor} to select.
-     *
-     * @example <caption>Example widget</caption>
-     *  <select multiple data-test='countries'>
-     *      <option value='UK'>United Kingdom</option>
-     *      <option value='PL'>Poland</option>
-     *      <option value='US'>United States</option>
-     *  </select>
-     *
-     * @example <caption>Lean Page Object describing the widget</caption>
-     *  import { Target } from '@serenity-js/protractor';
-     *  import { browser, by } from 'protractor';
-     *
-     *  class Countries {
-     *      static dropdown = Target.the('countries dropdown')
-     *          .located(by.css('[data-test="countries"]'));
-     *  }
-     *
-     * @example <caption>Retrieving the selected value</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { BrowseTheWeb, Select, Selected } from '@serenity-js/protractor';
-     *  import { Ensure, equals } from '@serenity-js/assertions';
-     *  import { protractor } from 'protractor';
-     *
-     *  actorCalled('Nick')
-     *      .whoCan(BrowseTheWeb.using(protractor.browser))
-     *      .attemptsTo(
-     *          Select.values('UK').from(Countries.dropdown),
-     *          Ensure.that(Selected.valuesOf(Countries.dropdown), equals([ 'UK' ])),
-     *      );
-     *
-     * @param {Array<Answerable<string[] | string>>} values
-     *  Values of the [`option` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
-     *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor} to select
-     *
-     * @returns {SelectBuilder}
-     *
-     * @see {@link Selected.valuesOf}
-     * @see {@link BrowseTheWeb}
-     * @see {@link Target}
-     * @see {@link @serenity-js/assertions~Ensure}
-     * @see {@link @serenity-js/assertions/lib/expectations~equals}
-     */
-    static values(...values: Array<Answerable<string[] | string>>): SelectBuilder {
-        return {
-            from: (target: Question<ElementFinder> | ElementFinder): Interaction =>
-                new SelectValues(values, target)
-        };
-    }
-
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  with a single [`option`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
-     *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor} to select.
-     *
-     * @example <caption>Example widget</caption>
-     *  <select data-test='countries'>
-     *      <option value='UK'>United Kingdom</option>
-     *      <option value='PL'>Poland</option>
-     *      <option value='US'>United States</option>
-     *  </select>
-     *
-     * @example <caption>Lean Page Object describing the widget</caption>
-     *  import { Target } from '@serenity-js/protractor';
-     *  import { browser, by } from 'protractor';
-     *
-     *  class Countries {
-     *      static dropdown = Target.the('countries dropdown')
-     *          .located(by.css('[data-test="countries"]'));
-     *  }
-     *
-     * @example <caption>Retrieving the selected value</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { BrowseTheWeb, Select, Selected } from '@serenity-js/protractor';
-     *  import { Ensure, equals } from '@serenity-js/assertions';
-     *  import { protractor } from 'protractor';
-     *
-     *  actorCalled('Nick')
-     *      .whoCan(BrowseTheWeb.using(protractor.browser))
-     *      .attemptsTo(
-     *          Select.option('Poland').from(Countries.dropdown),
-     *          Ensure.that(
-     *              Selected.optionIn(Countries.dropdown),
-     *              equals('Poland')
-     *          ),
-     *      );
-     *
-     * @param {string | Answerable<string>} value
-     *  Text of the [`option` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
-     *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor} to select
-     *
-     * @returns {SelectBuilder}
-     *
-     * @see {@link Selected.optionIn}
-     * @see {@link BrowseTheWeb}
-     * @see {@link Target}
-     * @see {@link @serenity-js/assertions~Ensure}
-     * @see {@link @serenity-js/assertions/lib/expectations~equals}
-     */
-    static option(value: string | Answerable<string>): SelectBuilder {
-        return {
-            from: (target: Question<ElementFinder> | ElementFinder): Interaction =>
-                new SelectOption(value, target)
-        };
-    }
-
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  with [`option`s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
-     *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor} to select.
-     *
-     * @example <caption>Example widget</caption>
-     *  <select multiple data-test='countries'>
-     *      <option value='UK'>United Kingdom</option>
-     *      <option value='PL'>Poland</option>
-     *      <option value='US'>United States</option>
-     *  </select>
-     *
-     * @example <caption>Lean Page Object describing the widget</caption>
-     *  import { Target } from '@serenity-js/protractor';
-     *  import { browser, by } from 'protractor';
-     *
-     *  class Countries {
-     *      static dropdown = Target.the('countries dropdown')
-     *          .located(by.css('[data-test="countries"]'));
-     *  }
-     *
-     * @example <caption>Retrieving the selected value</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { BrowseTheWeb, Select, Selected } from '@serenity-js/protractor';
-     *  import { Ensure, equals } from '@serenity-js/assertions';
-     *  import { protractor } from 'protractor';
-     *
-     *  actorCalled('Nick')
-     *      .whoCan(BrowseTheWeb.using(protractor.browser))
-     *      .attemptsTo(
-     *          Select.options('Poland', 'United States').from(Countries.dropdown),
-     *          Ensure.that(
-     *              Selected.optionsIn(Countries.dropdown),
-     *              equals([ 'Poland', 'United States' ])
-     *          ),
-     *      );
-     *
-     * @param {Array<Answerable<string[] | string>>} values
-     *  Text of the [`option` elements  ](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
-     *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor} to select
-     *
-     * @returns {SelectBuilder}
-     *
-     * @see {@link Selected.optionsIn}
-     * @see {@link BrowseTheWeb}
-     * @see {@link Target}
-     * @see {@link @serenity-js/assertions~Ensure}
-     * @see {@link @serenity-js/assertions/lib/expectations~equals}
-     */
-    static options(...values: Array<Answerable<string[] | string>>): SelectBuilder {
-        return {
-            from: (target: Question<ElementFinder> | ElementFinder): Interaction =>
-                new SelectOptions(values, target)
-        };
-    }
-}
-
-/**
- * @package
- */
-class SelectValue implements Interaction {
-
-    constructor(
-        private readonly value: string | Answerable<string>,
-        private readonly target: Question<ElementFinder> | ElementFinder
-    ) {
-    }
-
-    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
-        return actor.answer(this.value)
-            .then(value =>
-                withAnswerOf(actor, this.target, (element: ElementFinder) =>
-                    element
-                        .element(by.css(`option[value=${ value }]`)))
-                        .click()
-            );
-    }
-
-    toString () {
-        return formatted `#actor selects value ${ this.value } from ${ this.target }`;
-    }
-}
-
-/**
- * @package
- */
-class SelectValues implements Interaction {
-
-    constructor(
-        private readonly values: Array<Answerable<string[] | string>>,
-        private readonly target: Question<ElementFinder> | ElementFinder
-    ) {
-    }
-
-    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
-
-        return Promise.all(this.values.map(value => actor.answer(value)))
-            .then(flatten)
-            .then(values => {
-
-                const
-                    hasRequiredValue = (option: ElementFinder) =>
-                        Value.of(option).answeredBy(actor).then(value => !! ~values.indexOf(value));
-
-                return promiseOf(
-                    withAnswerOf(actor, this.target, (element: ElementFinder) =>
-                        element.all(by.css('option'))
-                            .filter(optionsToSelect(hasRequiredValue))
-                            .each(select)
-                    )
-                );
-            });
-    }
-
-    toString () {
-        return `#actor selects values ${ commaSeparated(flatten(this.values), inspected) } from ${ this.target }`;
-    }
-}
-
-/**
- * @package
- */
-class SelectOption implements Interaction {
-
-    constructor(
-        private readonly value: string | Answerable<string>,
-        private readonly target: Question<ElementFinder> | ElementFinder
-    ) {
-    }
-
-    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
-        return actor.answer(this.value)
-            .then(value => {
-                return promiseOf(withAnswerOf(actor, this.target, (element: ElementFinder) =>
-                    element
-                        .element(by.cssContainingText('option', value)))
-                        .click());
-            });
-    }
-
-    toString () {
-        return formatted `#actor selects ${ this.value } from ${ this.target }`;
-    }
-}
-
-/**
- * @package
- */
-class SelectOptions implements Interaction {
-
-    constructor(
-        private readonly values: Array<Answerable<string[] | string>>,
-        private readonly target: Question<ElementFinder> | ElementFinder
-    ) {
-    }
-
-    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
-        return Promise.all(this.values.map(value => actor.answer(value)))
-            .then(flatten)
-            .then(values => {
-
-                const
-                    hasRequiredText = (option: ElementFinder) =>
-                        option.getText().then(value => !! ~values.indexOf(value));
-
-                return promiseOf(
-                    withAnswerOf(actor, this.target, (element: ElementFinder) =>
-                        element.all(by.css('option'))
-                            .filter(optionsToSelect(hasRequiredText))
-                            .each(select)
-                    )
-                );
-            });
-    }
-
-    toString () {
-        return `#actor selects ${ commaSeparated(flatten(this.values), inspected) } from ${ this.target }`;
-    }
-}
-
-/** @package */
-function flatten<T>(listOfLists: Array<T[] | T>): T[] {
-    return listOfLists
-        .map(item => [].concat(item))
-        .reduce((acc: T[], list: T[]) => acc.concat(list), []);
-}
-
-/** @package */
-function optionsToSelect(criterion: (option: ElementFinder) => promise.Promise<boolean>) {
-    return (option: ElementFinder) =>
-        isAlreadySelected(option)
-            .then(alreadySelected =>
-                criterion(option).then(criterionMet =>
-                    xor(alreadySelected, criterionMet)
-                )
-            );
-}
-
-/** @package */
-function select(option: ElementFinder): promise.Promise<void> {
-    return option.click();
-}
-
-/** @package */
-function isAlreadySelected(option: ElementFinder): promise.Promise<boolean> {
-    return option.isSelected();
-}
-
-/** @package */
-function xor(first: boolean, second: boolean): boolean {
-    return first !== second;
-}

package/src/screenplay/interactions/SelectBuilder.ts

@@ -1,35 +0,0 @@
-import { Question } from '@serenity-js/core';
-import { Interaction } from '@serenity-js/core/lib/screenplay';
-import { ElementFinder } from 'protractor';
-
-/**
- * @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 {Question<ElementFinder> | ElementFinder} target
-     *
-     * @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: (target: Question<ElementFinder> | ElementFinder) => Interaction;
-}