@serenity-js/web 3.0.0-rc.9 → 3.0.1

package/lib/screenplay/questions/Selected.js

@@ -1,211 +1,250 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Selected = void 0;
-const io_1 = require("@serenity-js/core/lib/io");
-const models_1 = require("../models");
-const Text_1 = require("./Text");
-const Value_1 = require("./Value");
+const core_1 = require("@serenity-js/core");
 /**
- * @desc
- *  Represents options and values selected in a
- *  [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).
+ * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+ * options and values selected in a
+ * [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).
  *
- * @see {@link Select}
+ * ## Learn more
+ * - {@apilink Select}
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink QuestionAdapter}
+ * - {@apilink Question}
+ *
+ * @group Questions
  */
 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 {Answerable<PageElement>} pageElement
-     *  A {@link PageElement} identifying the `<select>` element of interest
-     *
-     * @returns {Question<Promise<string>>}
-     *
-     * @see {@link Select.value}
+     * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+     * a single [option](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     * selected in an [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).
+     *
+     * #### 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.value('UK').from(Countries.dropdown),
+     *     Ensure.that(Selected.valueOf(Countries.dropdown), equals('UK')),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink Select.value}
+     *
+     * @param pageElement
+     *  A {@apilink PageElement} identifying the `<select>` element of interest
      */
     static valueOf(pageElement) {
-        return models_1.PageElement.located(models_1.By.css('option:checked'))
-            .of(pageElement)
-            .value()
-            .describedAs((0, io_1.formatted) `value selected in ${pageElement}`);
+        return core_1.Question.about((0, core_1.d) `value selected in ${pageElement}`, async (actor) => {
+            const element = await actor.answer(pageElement);
+            const options = await element.selectedOptions();
+            return options
+                .filter(option => option.selected)
+                .map(option => option.value)[0];
+        });
     }
     /**
-     * @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 {Answerable<PageElement>} pageElement
-     *  A {@link Target} identifying the `<select>` element of interest
-     *
-     * @returns {Question<Promise<string[]>>}
-     *
-     * @see {@link Select.values}
+     * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+     * values of [options](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     * selected in an [HTML `<select multiple>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
+     *
+     * #### 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.values('UK').from(Countries.dropdown),
+     *     Ensure.that(Selected.valuesOf(Countries.dropdown), equals([ 'UK' ])),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink Select.values}
+     *
+     * @param pageElement
+     *  A {@apilink PageElement} identifying the `<select>` element of interest
      */
     static valuesOf(pageElement) {
-        return models_1.PageElements.located(models_1.By.css('option:checked'))
-            .of(pageElement)
-            .eachMappedTo(Value_1.Value)
-            .describedAs((0, io_1.formatted) `values selected in ${pageElement}`);
+        return core_1.Question.about((0, core_1.d) `values selected in ${pageElement}`, async (actor) => {
+            const element = await actor.answer(pageElement);
+            const options = await element.selectedOptions();
+            return options
+                .filter(option => option.selected)
+                .map(option => option.value);
+        });
     }
     /**
-     * @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 {Answerable<PageElement>} pageElement
-     *  A {@link Target} identifying the `<select>` element of interest
-     *
-     * @returns {Question<Promise<string>>}
-     *
-     * @see {@link Select.option}
+     * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+     * a single option selected in an [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
+     *
+     * #### 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')
+     *   .attemptsTo(
+     *     Select.option('Poland').from(Countries.dropdown),
+     *     Ensure.that(
+     *       Selected.optionIn(Countries.dropdown),
+     *       equals('Poland')
+     *     ),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink Select.option}
+     *
+     * @param pageElement
+     *  A {@apilink PageElement} identifying the `<select>` element of interest
      */
     static optionIn(pageElement) {
-        return models_1.PageElement.located(models_1.By.css('option:checked'))
-            .of(pageElement)
-            .text()
-            .describedAs((0, io_1.formatted) `option selected in ${pageElement}`);
+        return core_1.Question.about((0, core_1.d) `option selected in ${pageElement}`, async (actor) => {
+            const element = await actor.answer(pageElement);
+            const options = await element.selectedOptions();
+            return options
+                .filter(option => option.selected)
+                .map(option => option.label)[0];
+        });
     }
     /**
-     * @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 {Answerable<PageElement>} pageElement
-     *  A {@link Target} identifying the `<select>` element of interest
-     *
-     * @returns {Question<Promise<string[]>>}
-     *
-     * @see {@link Select.options}
+     * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+     * options selected in an [HTML `<select multiple>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
+     *
+     * #### 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')
+     *   .attemptsTo(
+     *     Select.options('Poland', 'United States').from(Countries.dropdown),
+     *     Ensure.that(
+     *       Selected.optionsIn(Countries.dropdown),
+     *       equals([ 'Poland', 'United States' ])
+     *     ),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink Select.options}
+     *
+     * @param pageElement
+     *  A {@apilink PageElement} identifying the `<select>` element of interest
      */
     static optionsIn(pageElement) {
-        return models_1.PageElements.located(models_1.By.css('option:checked'))
-            .of(pageElement)
-            .eachMappedTo(Text_1.Text)
-            .describedAs((0, io_1.formatted) `options selected in ${pageElement}`);
+        return core_1.Question.about((0, core_1.d) `options selected in ${pageElement}`, async (actor) => {
+            const element = await actor.answer(pageElement);
+            const options = await element.selectedOptions();
+            return options
+                .filter(option => option.selected)
+                .map(option => option.label);
+        });
     }
 }
 exports.Selected = Selected;

package/lib/screenplay/questions/Selected.js.map

@@ -1 +1 @@
-{"version":3,"file":"Selected.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Selected.ts"],"names":[],"mappings":";;;AACA,iDAAqD;AAErD,sCAA0D;AAC1D,iCAA8B;AAC9B,mCAAgC;AAEhC;;;;;;GAMG;AACH,MAAa,QAAQ;IAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,MAAM,CAAC,OAAO,CAAC,WAAoC;QAC/C,OAAO,oBAAW,CAAC,OAAO,CAAC,WAAE,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;aAC/C,EAAE,CAAC,WAAW,CAAC;aACf,KAAK,EAAE;aACP,WAAW,CAAC,IAAA,cAAS,EAAC,qBAAsB,WAAY,EAAE,CAAC,CAAC;IACrE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,MAAM,CAAC,QAAQ,CAAC,WAAoC;QAChD,OAAO,qBAAY,CAAC,OAAO,CAAC,WAAE,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;aAChD,EAAE,CAAC,WAAW,CAAC;aACf,YAAY,CAAC,aAAK,CAAC;aACnB,WAAW,CAAC,IAAA,cAAS,EAAC,sBAAuB,WAAY,EAAE,CAAgC,CAAC;IACrG,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,MAAM,CAAC,QAAQ,CAAC,WAAoC;QAChD,OAAO,oBAAW,CAAC,OAAO,CAAC,WAAE,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;aAC/C,EAAE,CAAC,WAAW,CAAC;aACf,IAAI,EAAE;aACN,WAAW,CAAC,IAAA,cAAS,EAAC,sBAAuB,WAAY,EAAE,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,MAAM,CAAC,SAAS,CAAC,WAAoC;QACjD,OAAO,qBAAY,CAAC,OAAO,CAAC,WAAE,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;aAChD,EAAE,CAAC,WAAW,CAAC;aACf,YAAY,CAAC,WAAI,CAAC;aAClB,WAAW,CAAC,IAAA,cAAS,EAAC,uBAAwB,WAAY,EAAE,CAAgC,CAAC;IACtG,CAAC;CACJ;AAvMD,4BAuMC"}
+{"version":3,"file":"Selected.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Selected.ts"],"names":[],"mappings":";;;AAAA,4CAA6E;AAI7E;;;;;;;;;;;;GAYG;AACH,MAAa,QAAQ;IAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+CG;IACH,MAAM,CAAC,OAAO,CAAC,WAAoC;QAC/C,OAAO,eAAQ,CAAC,KAAK,CAAC,IAAA,QAAC,EAAA,qBAAsB,WAAY,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACvE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAChD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC;YAEhD,OAAO,OAAO;iBACT,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;iBACjC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+CG;IACH,MAAM,CAAC,QAAQ,CAAC,WAAoC;QAChD,OAAO,eAAQ,CAAC,KAAK,CAAC,IAAA,QAAC,EAAA,sBAAuB,WAAY,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACxE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAEhD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC;YAEhD,OAAO,OAAO;iBACT,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;iBACjC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,MAAM,CAAC,QAAQ,CAAC,WAAoC;QAChD,OAAO,eAAQ,CAAC,KAAK,CAAC,IAAA,QAAC,EAAA,sBAAuB,WAAY,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACxE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAEhD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC;YAEhD,OAAO,OAAO;iBACT,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;iBACjC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,MAAM,CAAC,SAAS,CAAC,WAAoC;QACjD,OAAO,eAAQ,CAAC,KAAK,CAAC,IAAA,QAAC,EAAA,uBAAwB,WAAY,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACzE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAEhD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC;YAEhD,OAAO,OAAO;iBACT,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;iBACjC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AAlPD,4BAkPC"}