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

package/src/screenplay/interactions/Select.ts

@@ -1,321 +1,281 @@
-import { Answerable, q } from '@serenity-js/core';
-import { asyncMap, commaSeparated, formatted } from '@serenity-js/core/lib/io';
-import { inspected } from '@serenity-js/core/lib/io/inspected';
+import { Answerable, d } from '@serenity-js/core';
+import { asyncMap, commaSeparated } from '@serenity-js/core/lib/io';
+import { stringified } from '@serenity-js/core/lib/io/stringified';
 import { Interaction } from '@serenity-js/core/lib/screenplay';
 
-import { By, PageElement, PageElements } from '../models';
-import { SelectBuilder } from './SelectBuilder';
+import { PageElement, SelectOption } from '../models';
 
 /**
- * @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.
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * 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}
+ * ## Learn more
+ * - {@apilink Selected}
+ *
+ * @group Activities
  */
 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 {Answerable<string>} value
+     * Instantiates an {@apilink Interaction|interaction}
+     * that instructs the {@apilink Actor|actor}
+     * to select a single [`<option>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     * with a given [`value`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option#attr-value).,
+     *
+     * #### Example widget
+     *
+     * ```html
+     * <select data-test='countries'>
+     *   <option value='UK'>United Kingdom</option>
+     *   <option value='PL'>Poland</option>
+     *   <option value='US'>United States</option>
+     * </select>
+     * ```
+     *
+     * #### Lean Page Object describing the widget
+     *
+     * ```ts
+     * import { By, PageElement } from '@serenity-js/web'
+     *
+     * class Countries {
+     *   static dropdown = () =>
+     *     PageElement.located(By.css('[data-test="countries"]'))
+     *       .describedAs('countries dropdown')
+     * }
+     * ```
+     *
+     * #### Retrieving the selected value
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Select, Selected } from '@serenity-js/web';
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Nick')
+     *   .attemptsTo(
+     *     Select.value('UK').from(Countries.dropdown()),
+     *     Ensure.that(Selected.valueOf(Countries.dropdown()), equals('UK')),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink Selected.valueOf}
+     * - {@apilink PageElement}
+     *
+     * @param 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}
+     *  for the {@apilink Actor} to select
      */
-    static value(value: Answerable<string>): SelectBuilder {
+    static value(value: Answerable<string>): { from: (pageElement: Answerable<PageElement>) => Interaction } {
         return {
             from: (pageElement: Answerable<PageElement>): Interaction =>
-                Interaction.where(formatted `#actor selects value ${ value } from ${ pageElement }`, async actor => {
-                    return PageElement.located(By.css(q`option[value=${ value }]`))
-                        .of(pageElement)
-                        .click()
-                        .performAs(actor);
+                Interaction.where(d`#actor selects value ${ value } from ${ pageElement }`, async actor => {
+                    const element       = await actor.answer(pageElement);
+                    const desiredValue  = await actor.answer(value);
+
+                    await element.selectOptions(SelectOption.withValue(desiredValue));
                 }),
         };
     }
 
     /**
-     * @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
+     * Instantiates an {@apilink Interaction|interaction}
+     * that instructs the {@apilink Actor|actor}
+     * to select multiple [`<option>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     * identified by their [`value`s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option#attr-value).
+     *
+     * #### Example widget
+     *
+     * ```ts
+     * <select multiple data-test='countries'>
+     *   <option value='UK'>United Kingdom</option>
+     *   <option value='PL'>Poland</option>
+     *   <option value='US'>United States</option>
+     * </select>
+     * ```
+     *
+     * #### Lean Page Object describing the widget
+     *
+     * ```ts
+     * import { By, PageElement } from '@serenity-js/web'
      *
-     * @returns {SelectBuilder}
+     * class Countries {
+     *   static dropdown = () =>
+     *     PageElement.located(By.css('[data-test="countries"]'))
+     *       .describedAs('countries dropdown')
+     * }
+     * ```
      *
-     * @see {@link Selected.valuesOf}
-     * @see {@link BrowseTheWeb}
-     * @see {@link Target}
-     * @see {@link @serenity-js/assertions~Ensure}
-     * @see {@link @serenity-js/assertions/lib/expectations~equals}
+     * #### Retrieving the selected value
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Select, Selected } from '@serenity-js/web'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Nick')
+     *   .attemptsTo(
+     *     Select.values('UK').from(Countries.dropdown()),
+     *     Ensure.that(Selected.valuesOf(Countries.dropdown()), equals([ 'UK' ])),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     *
+     * - {@apilink Selected.valuesOf}
+     * - {@apilink PageElement}
+     *
+     * @param values
+     *  Values of the [`option` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     *  for the {@apilink Actor} to select
      */
-    static values(...values: Array<Answerable<string[] | string>>): SelectBuilder {
+    static values(...values: Array<Answerable<string[] | string>>): { from: (pageElement: Answerable<PageElement>) => Interaction } {
         return {
             from: (pageElement: Answerable<PageElement>): Interaction =>
-                Interaction.where(`#actor selects values ${ commaSeparated(values.flat(), item => inspected(item, { inline: true })) } from ${ inspected(pageElement, { inline: true }) }`, async actor => {
+                Interaction.where(`#actor selects values ${ commaSeparated(values.flat(), item => stringified(item, { inline: true })) } from ${ stringified(pageElement, { inline: true }) }`, async actor => {
 
-                    const answers = await asyncMap(values, value => actor.answer(value));
+                    const answers       = await asyncMap(values, value => actor.answer(value));
                     const desiredValues = answers.flat();
 
-                    const options: PageElement[] = await PageElements.located(By.css(`option`))
-                        .of(pageElement)
-                        .answeredBy(actor);
+                    const element  = await actor.answer(pageElement);
 
-                    for (const option of options) {
-                        const shouldSelect = await optionsToSelect(hasValueEqualOneOf(desiredValues))(option);
-                        if (shouldSelect) {
-                            await option.click();
-                        }
-                    }
+                    await element.selectOptions(... desiredValues.map(value => SelectOption.withValue(value)));
                 }),
         };
     }
 
     /**
-     * @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 {Answerable<string>} value
+     * Instantiates an {@apilink Interaction|interaction}
+     * that instructs the {@apilink Actor|actor}
+     * to select a single [`<option>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     * with a given description.
+     *
+     * #### Example widget
+     *
+     * ```html
+     * <select data-test='countries'>
+     *   <option value='UK'>United Kingdom</option>
+     *   <option value='PL'>Poland</option>
+     *   <option value='US'>United States</option>
+     * </select>
+     * ```
+     *
+     * #### Lean Page Object describing the widget
+     * ```ts
+     * import { By, PageElement } from '@serenity-js/by'
+     *
+     * class Countries {
+     *   static dropdown = () =>
+     *     PageElement.located(By.css('[data-test="countries"]'))
+     *       .describedAs('countries dropdown')
+     * }
+     * ```
+     *
+     * #### Retrieving the selected value
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Select, Selected } from '@serenity-js/web'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Nick')
+     *   .whoCan(BrowseTheWeb.using(protractor.browser))
+     *   .attemptsTo(
+     *     Select.option('Poland').from(Countries.dropdown()),
+     *     Ensure.that(
+     *       Selected.optionIn(Countries.dropdown()),
+     *       equals('Poland')
+     *     ),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink Selected.optionIn}
+     * - {@apilink PageElement}
+     *
+     * @param 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}
+     *  for the {@apilink Actor} to select
      */
-    static option(value: Answerable<string>): SelectBuilder {
+    static option(value: Answerable<string>): { from: (pageElement: Answerable<PageElement>) => Interaction } {
         return {
             from: (pageElement: Answerable<PageElement>): Interaction =>
-                Interaction.where(formatted `#actor selects ${ value } from ${ pageElement }`, async actor => {
-                    return PageElement.located(By.cssContainingText('option', value))
-                        .of(pageElement)
-                        .click()
-                        .performAs(actor);
+                Interaction.where(d`#actor selects ${ value } from ${ pageElement }`, async actor => {
+                    const element       = await actor.answer(pageElement);
+                    const desiredLabel  = await actor.answer(value);
+
+                    await element.selectOptions(SelectOption.withLabel(desiredLabel));
                 }),
         };
     }
 
     /**
-     * @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
+     * Instantiates an {@apilink Interaction|interaction}
+     * that instructs the {@apilink Actor|actor}
+     * to select multiple [`<option>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     * identified by their descriptions.
+     *
+     * #### Example widget
+     *
+     * ```html
+     * <select multiple data-test='countries'>
+     *   <option value='UK'>United Kingdom</option>
+     *   <option value='PL'>Poland</option>
+     *   <option value='US'>United States</option>
+     * </select>
+     * ```
+     *
+     * #### Lean Page Object describing the widget
+     *
+     * ```ts
+     * import { By, PageElement } from '@serenity-js/web'
+     *
+     * class Countries {
+     *   static dropdown = () =>
+     *     PageElement.located(By.css('[data-test="countries"]'))
+     *       .describedAs('countries dropdown')
+     * }
+     * ```
+     *
+     * ##### Retrieving the selected value
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Select, Selected } from '@serenity-js/web'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * await 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' ])
+     *     ),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink Selected.optionsIn}
+     * - {@apilink PageElement}
+     *
+     * @param 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}
+     *  for the {@apilink Actor} to select
      */
-    static options(...values: Array<Answerable<string[] | string>>): SelectBuilder {
+    static options(...values: Array<Answerable<string[] | string>>): { from: (pageElement: Answerable<PageElement>) => Interaction } {
         return {
             from: (pageElement: Answerable<PageElement>): Interaction =>
-                Interaction.where(`#actor selects ${ commaSeparated(values.flat(), item => inspected(item, { inline: true })) } from ${ inspected(pageElement, { inline: true }) }`, async actor => {
+                Interaction.where(`#actor selects ${ commaSeparated(values.flat(), item => stringified(item, { inline: true })) } from ${ stringified(pageElement, { inline: true }) }`, async actor => {
 
-                    const answers = await asyncMap(values, value => actor.answer(value));
-                    const desiredOptions = answers.flat();
+                    const answers       = await asyncMap(values, value => actor.answer(value));
+                    const desiredLabels = answers.flat();
 
-                    const options: PageElement[]    = await PageElements.located(By.css(`option`)).of(pageElement).answeredBy(actor);
+                    const element  = await actor.answer(pageElement);
 
-                    for (const option of options) {
-                        const shouldSelect = await optionsToSelect(hasTextEqualOneOf(desiredOptions))(option);
-                        if (shouldSelect) {
-                            await option.click()
-                        }
-                    }
+                    await element.selectOptions(... desiredLabels.map(label => SelectOption.withLabel(label)));
                 }),
         };
     }
 }
-
-/** @package */
-function hasValueEqualOneOf(desiredValues: string[]): (option: PageElement) => Promise<boolean> {
-    return async (option: PageElement) => {
-
-        const value = await option.value()
-
-        return desiredValues.includes(value);
-    }
-}
-
-/** @package */
-function hasTextEqualOneOf(desiredValues: string[]): (option: PageElement) => Promise<boolean> {
-    return async (option: PageElement) => {
-
-        const value = await option.text()
-
-        return desiredValues.includes(value);
-    }
-}
-
-/** @package */
-function optionsToSelect(criterion: (option: PageElement) => Promise<boolean>) {
-    return (option: PageElement) =>
-        isAlreadySelected(option)
-            .then(alreadySelected =>
-                criterion(option).then(criterionMet =>
-                    xor(alreadySelected, criterionMet)
-                )
-            );
-}
-
-/** @package */
-function isAlreadySelected(option: PageElement): Promise<boolean> {
-    return option.isSelected();
-}
-
-/** @package */
-function xor(first: boolean, second: boolean): boolean {
-    return first !== second;
-}