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

package/lib/screenplay/questions/Selected.d.ts

@@ -1,185 +1,216 @@
-import { Answerable, Question } from '@serenity-js/core';
+import { Answerable, QuestionAdapter } from '@serenity-js/core';
 import { PageElement } from '../models';
 /**
- * @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
  */
 export declare 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: Answerable<PageElement>): Question<Promise<string>>;
+    static valueOf(pageElement: Answerable<PageElement>): QuestionAdapter<string>;
     /**
-     * @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: Answerable<PageElement>): Question<Promise<string[]>>;
+    static valuesOf(pageElement: Answerable<PageElement>): QuestionAdapter<Array<string>>;
     /**
-     * @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: Answerable<PageElement>): Question<Promise<string>>;
+    static optionIn(pageElement: Answerable<PageElement>): QuestionAdapter<string>;
     /**
-     * @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: Answerable<PageElement>): Question<Promise<string[]>>;
+    static optionsIn(pageElement: Answerable<PageElement>): QuestionAdapter<Array<string>>;
 }
+//# sourceMappingURL=Selected.d.ts.map

package/lib/screenplay/questions/Selected.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Selected.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/Selected.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAe,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAQ;IAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+CG;IACH,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC;IAW7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+CG;IACH,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAYrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC;IAY9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;CAWzF"}