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

package/src/screenplay/questions/Selected.ts

@@ -1,268 +0,0 @@
-import { AnswersQuestions, Question, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-import { ElementFinder } from 'protractor';
-
-import { promiseOf } from '../../promiseOf';
-import { withAnswerOf } from '../withAnswerOf';
-import { Value } from './Value';
-
-/**
- * @desc
- *  Represents options and values selected in a
- *  [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).
- *
- * @see {@link Select}
- */
-export class Selected {
-
-    /**
-     * @desc
-     *  Represents the value of a single option selected in a
-     *  [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/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</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 { Accept, 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 {Question<ElementFinder> | ElementFinder} target
-     *  A {@link Target} identifying the `<select>` element of interest
-     *
-     * @returns {Question<Promise<string>>}
-     *
-     * @see {@link Select.value}
-     */
-    static valueOf(target: Question<ElementFinder> | ElementFinder): Question<Promise<string>> {
-        return new SelectedValue(target);
-    }
-
-    /**
-     * @desc
-     *  Represents values of options selected in a
-     *  [HTML `<select multiple>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
-     *
-     * @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</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 { Accept, 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 {Question<ElementFinder> | ElementFinder} target
-     *  A {@link Target} identifying the `<select>` element of interest
-     *
-     * @returns {Question<Promise<string[]>>}
-     *
-     * @see {@link Select.values}
-     */
-    static valuesOf(target: Question<ElementFinder> | ElementFinder): Question<Promise<string[]>> {
-        return new SelectedValues(target);
-    }
-
-    /**
-     * @desc
-     *  Represents a single option selected in a
-     *  [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
-     *
-     * @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</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 { Accept, 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 {Question<ElementFinder> | ElementFinder} target
-     *  A {@link Target} identifying the `<select>` element of interest
-     *
-     * @returns {Question<Promise<string>>}
-     *
-     * @see {@link Select.option}
-     */
-    static optionIn(target: Question<ElementFinder> | ElementFinder): Question<Promise<string>> {
-        return new SelectedOption(target);
-    }
-
-    /**
-     * @desc
-     *  Represents options selected in a
-     *  [HTML `<select multiple>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
-     *
-     * @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</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 { Accept, 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 {Question<ElementFinder> | ElementFinder} target
-     *  A {@link Target} identifying the `<select>` element of interest
-     *
-     * @returns {Question<Promise<string[]>>}
-     *
-     * @see {@link Select.options}
-     */
-    static optionsIn(target: Question<ElementFinder> | ElementFinder): Question<Promise<string[]>> {
-        return new SelectedOptions(target);
-    }
-}
-
-/**
- * @package
- */
-class SelectedValue extends Question<Promise<string>> {
-
-    constructor(private readonly target: Question<ElementFinder> | ElementFinder) {
-        super(formatted `value selected in ${ target }`);
-    }
-
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string> {
-        const value = withAnswerOf(actor, this.target, (element: ElementFinder) =>
-            Value.of(element.$('option:checked')).answeredBy(actor)
-        );
-
-        return promiseOf(value);
-    }
-}
-
-/**
- * @package
- */
-class SelectedValues extends Question<Promise<string[]>> {
-
-    constructor(private readonly target: Question<ElementFinder> | ElementFinder) {
-        super(formatted `values selected in ${ target }`);
-    }
-
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string[]> {
-        const options = withAnswerOf(actor, this.target, (element: ElementFinder) => element.$$('option')
-            .filter(option => option.isSelected()));
-
-        return promiseOf(options.map(option => Value.of(option).answeredBy(actor)));
-    }
-}
-
-/**
- * @package
- */
-class SelectedOption extends Question<Promise<string>> {
-
-    constructor(private target: Question<ElementFinder> | ElementFinder) {
-        super(formatted `option selected in ${ target }`);
-    }
-
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string> {
-        return promiseOf(withAnswerOf(actor, this.target, element => element.$('option:checked').getText()));
-    }
-}
-
-/**
- * @package
- */
-class SelectedOptions extends Question<Promise<string[]>> {
-
-    constructor(private target: Question<ElementFinder> | ElementFinder) {
-        super(formatted `options selected in ${ target }`);
-    }
-
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string[]> {
-        return promiseOf(withAnswerOf(actor, this.target, element => element.$$('option')
-            .filter(option => option.isSelected())
-            .map(elements => elements.getText())));
-    }
-}

package/src/screenplay/questions/Value.ts

@@ -1,73 +0,0 @@
-import { AnswersQuestions, MetaQuestion, 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';
-import { TargetNestedElement } from './targets';
-
-/**
- * @desc
- *  Resolves to the value of a given [`input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)
- *  {@link WebElement}, represented by {@link ElementFinder} or `Question<ElementFinder>`.
- *
- * @extends {@serenity-js/core/lib/screenplay~Question}
- * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
- */
-export class Value
-    extends Question<Promise<string>>
-    implements MetaQuestion<Question<ElementFinder> | ElementFinder, Promise<string>> {
-    /**
-     * @param {Question<ElementFinder> | ElementFinder} target
-     * @returns {Value}
-     */
-    static of(target: Question<ElementFinder> | ElementFinder): Value {
-        return new Value(target);
-    }
-
-    /**
-     * @param {Question<ElementFinder> | ElementFinder} target
-     */
-    constructor(private readonly target: Question<ElementFinder> | ElementFinder) {
-        super(formatted`the value of ${ target }`);
-    }
-
-    /**
-     * @desc
-     *  Resolves to the value of a given [`input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)
-     *  {@link WebElement}, located in the context of a `parent` element.
-     *
-     * @param {Question<ElementFinder> | ElementFinder} parent
-     * @returns {Question<Promise<string[]>>}
-     *
-     * @see {@link Target.all}
-     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
-     */
-    of(parent: Question<ElementFinder> | ElementFinder): Question<Promise<string>> {
-        return new Value(new TargetNestedElement(parent, this.target));
-    }
-
-    /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  answer this {@link @serenity-js/core/lib/screenplay~Question}.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     */
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string> {
-        return withAnswerOf(actor, this.target, (elf: ElementFinder) =>
-            BrowseTheWeb.as(actor).executeFunction(
-                /* istanbul ignore next */
-                function getValue(webElement) {
-                    return webElement.value;
-                },
-                elf.getWebElement(),
-            ),
-        );
-    }
-}

package/src/screenplay/questions/Website.ts

@@ -1,27 +0,0 @@
-import { Question } from '@serenity-js/core';
-
-import { BrowseTheWeb } from '../abilities';
-
-export class Website {
-    /**
-     * Retrieves the title of the current page.
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Question<Promise<string>>}
-     */
-    static title(): Question<Promise<string>> {
-        return Question.about(`the title of the current page`, actor =>
-            BrowseTheWeb.as(actor).getTitle(),
-        );
-    }
-
-    /**
-     * Retrieves the url of the current page.
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Question<Promise<string>>}
-     */
-    static url(): Question<Promise<string>> {
-        return Question.about(`the url of the current page`, actor =>
-            BrowseTheWeb.as(actor).getCurrentUrl(),
-        );
-    }
-}

package/src/screenplay/questions/Window.ts

@@ -1,29 +0,0 @@
-import { Question } from '@serenity-js/core';
-
-import { promiseOf } from '../../promiseOf';
-import { BrowseTheWeb } from '../abilities';
-
-export class Window {
-
-    /**
-     * @desc
-     *  Returns the size of the current browser window.
-     *
-     * @returns {Question<Promise<{ width: number, height: number }>>}
-     */
-    static size(): Question<Promise<{ width: number, height: number }>> {
-        return Question.about(`browser window size`, actor =>
-            promiseOf(BrowseTheWeb.as(actor).manage().window().getSize()));
-    }
-
-    /**
-     * @desc
-     *  Returns the `{ x: number, y: number }` position of the current browser window.
-     *
-     * @returns {Question<Promise<{ x: number, y: number }>>}
-     */
-    static position(): Question<Promise<{ x: number, y: number }>> {
-        return Question.about(`browser window position`, actor =>
-            promiseOf(BrowseTheWeb.as(actor).manage().window().getPosition()));
-    }
-}

package/src/screenplay/questions/lists/ElementArrayFinderListAdapter.ts

@@ -1,158 +0,0 @@
-import { AnswersQuestions, Expectation, ExpectationMet, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-import { ListAdapter } from '@serenity-js/core/lib/screenplay/questions/lists';
-import { ElementArrayFinder, ElementFinder } from 'protractor';
-
-/**
- * @desc
- *  Adapts {@link ElementArrayFinder} so that it can be used with {@link @serenity-js/core/lib/screenplay/questions~List}.
- *
- *  You most likely won't need to use this class directly. Instead, check out {@link Target} and {@link Target.all}.
- *
- * @see {@link Target}
- *
- * @implements {@serenity-js/core/lib/screenplay/questions/lists~ListAdapter}
- */
-export class ElementArrayFinderListAdapter implements ListAdapter<ElementFinder, ElementArrayFinder> {
-
-    /**
-     * @param {Question<ElementArrayFinder> | ElementArrayFinder} collection
-     */
-    constructor(private readonly collection: Question<ElementArrayFinder> | ElementArrayFinder) {
-    }
-
-    /**
-     * @desc
-     *  Returns the number of {@link ElementFinder}s that the underlying {@link ElementArrayFinder} contains,
-     *  left after applying any filters.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<number>}
-     */
-    count(actor: AnswersQuestions & UsesAbilities): Promise<number> {
-        return Promise.resolve(this.elements(actor).count());
-    }
-
-    /**
-     * @desc
-     *  Returns the first of {@link ElementFinder}s that the underlying {@link ElementArrayFinder} contains,
-     *  left after applying any filters
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {ElementFinder}
-     */
-    first(actor: AnswersQuestions & UsesAbilities): ElementFinder {
-        return this.elements(actor).first();
-    }
-
-    /**
-     * @desc
-     *  Returns the last of {@link ElementFinder}s that the underlying {@link ElementArrayFinder} contains,
-     *  left after applying any filters
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {ElementFinder}
-     */
-    last(actor: AnswersQuestions & UsesAbilities): ElementFinder {
-        return this.elements(actor).last();
-    }
-
-    /**
-     * @desc
-     *  Returns the nth of {@link ElementFinder}s that the underlying {@link ElementArrayFinder} contains,
-     *  left after applying any filters
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     *
-     * @param {number} index
-     *  Zero-based index of the item to return
-     *
-     * @returns {ElementFinder}
-     */
-    get(actor: AnswersQuestions & UsesAbilities, index: number): ElementFinder {
-        return this.elements(actor).get(index);
-    }
-
-    /**
-     * @desc
-     *  Returns the underlying {@link ElementArrayFinder},
-     *  with any filters applied.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {ElementFinder}
-     */
-    items(actor: AnswersQuestions & UsesAbilities): ElementArrayFinder {
-        return this.elements(actor);
-    }
-
-    /**
-     * @desc
-     *  Filters the underlying {@link ElementArrayFinder} so that the result contains only those {@link ElementFinder}s that meet the {@link Expectation}
-     *
-     * @param {@serenity-js/core/lib/screenplay/questions~MetaQuestion<ElementFinder, Promise<Answer_Type> | Answer_Type>} question
-     * @param {@serenity-js/core/lib/screenplay/questions~Expectation<any, Answer_Type>} expectation
-     *
-     * @returns {@serenity-js/core/lib/screenplay/questions/lists~ListAdapter<ElementFinder, ElementArrayFinder>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
-     */
-    withFilter<Answer_Type>(
-        question: MetaQuestion<ElementFinder, Promise<Answer_Type> | Answer_Type>,
-        expectation: Expectation<any, Answer_Type>
-    ): ListAdapter<ElementFinder, ElementArrayFinder> {
-        return new ElementArrayFinderListAdapter(
-            new ElementArrayFinderArrayListFilter(this.collection, question, expectation)
-        );
-    }
-
-    /**
-     * @desc
-     *  Returns a human-readable description of the underlying {@link ElementArrayFinder}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return formatted `${ this.collection }`;
-    }
-
-    private elements(actor: AnswersQuestions & UsesAbilities): ElementArrayFinder {
-        return Question.isAQuestion(this.collection)
-            ? this.collection.answeredBy(actor)
-            : this.collection;
-    }
-}
-
-/**
- * @private
- */
-class ElementArrayFinderArrayListFilter<Answer_Type>
-    extends Question<ElementArrayFinder>
-{
-    constructor(
-        private readonly collection: Question<ElementArrayFinder> | ElementArrayFinder,
-        private readonly question: MetaQuestion<ElementFinder, Promise<Answer_Type> | Answer_Type>,
-        private readonly expectation: Expectation<any, Answer_Type>
-    ) {
-        super([
-            formatted `${ collection }`,
-            collection instanceof ElementArrayFinderArrayListFilter ? 'and' : 'where',
-            formatted `${ question } does ${ expectation }`
-        ].join(' '));
-    }
-
-    answeredBy(actor: AnswersQuestions & UsesAbilities): ElementArrayFinder {
-
-        return this.finderAs(actor)
-            .filter((elementFinder: ElementFinder) =>
-                Promise.resolve(this.question.of(elementFinder).answeredBy(actor))
-                    .then(answer => this.expectation.answeredBy(actor)(answer))
-                    .then(outcome => outcome instanceof ExpectationMet)
-            );
-    }
-
-    private finderAs(actor: AnswersQuestions & UsesAbilities): ElementArrayFinder {
-        return Question.isAQuestion(this.collection)
-            ? this.collection.answeredBy(actor)
-            : this.collection;
-    }
-}

package/src/screenplay/questions/lists/index.ts

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