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

package/lib/screenplay/interactions/Select.d.ts

@@ -1,212 +1,236 @@
 import { Answerable } from '@serenity-js/core';
-import { SelectBuilder } from './SelectBuilder';
+import { Interaction } from '@serenity-js/core/lib/screenplay';
+import { PageElement } 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 declare 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;
+    };
     /**
-     * @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'
+     *
+     * class Countries {
+     *   static dropdown = () =>
+     *     PageElement.located(By.css('[data-test="countries"]'))
+     *       .describedAs('countries dropdown')
+     * }
+     * ```
      *
-     * @returns {SelectBuilder}
+     * #### Retrieving the selected value
      *
-     * @see {@link Selected.valuesOf}
-     * @see {@link BrowseTheWeb}
-     * @see {@link Target}
-     * @see {@link @serenity-js/assertions~Ensure}
-     * @see {@link @serenity-js/assertions/lib/expectations~equals}
+     * ```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;
+    };
     /**
-     * @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;
+    };
     /**
-     * @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;
+    };
 }
+//# sourceMappingURL=Select.d.ts.map

package/lib/screenplay/interactions/Select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Select.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/Select.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAK,MAAM,mBAAmB,CAAC;AAGlD,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAgB,MAAM,WAAW,CAAC;AAEtD;;;;;;;;;GASG;AACH,qBAAa,MAAM;IAEf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,WAAW,CAAA;KAAE;IAYxG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,WAAW,CAAA;KAAE;IAe/H;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,WAAW,CAAA;KAAE;IAYzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,WAAW,CAAA;KAAE;CAcnI"}