@serenity-js/web 3.41.1 → 3.42.0

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

@@ -0,0 +1,235 @@
+import { type Answerable, Interaction } from '@serenity-js/core';
+import type { PageElement } from '../models/index.js';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/) who has the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/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.
+ *
+ * ## Learn more
+ * - [`Selected`](https://serenity-js.org/api/web/class/Selected/)
+ *
+ * @group Activities
+ */
+export declare class Select {
+    /**
+     * Instantiates an [interaction](https://serenity-js.org/api/core/class/Interaction/)
+     * that instructs the [actor](https://serenity-js.org/api/core/class/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>
+     * ```C
+     *
+     * #### 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
+     * - [`Selected.valueOf`](https://serenity-js.org/api/web/class/Selected/#valueOf)
+     * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+     *
+     * @param value
+     *  A value of the [`option` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     *  for the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to select
+     */
+    static value(value: Answerable<string>): {
+        from: (pageElement: Answerable<PageElement>) => Interaction;
+    };
+    /**
+     * Instantiates an [interaction](https://serenity-js.org/api/core/class/Interaction/)
+     * that instructs the [actor](https://serenity-js.org/api/core/class/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')
+     * }
+     * ```
+     *
+     * #### 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
+     *
+     * - [`Selected.valuesOf`](https://serenity-js.org/api/web/class/Selected/#valuesOf)
+     * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+     *
+     * @param values
+     *  Values of the [`option` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     *  for the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to select
+     */
+    static values(...values: Array<Answerable<string[] | string>>): {
+        from: (pageElement: Answerable<PageElement>) => Interaction;
+    };
+    /**
+     * Instantiates an [interaction](https://serenity-js.org/api/core/class/Interaction/)
+     * that instructs the [actor](https://serenity-js.org/api/core/class/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
+     * - [`Selected.optionIn`](https://serenity-js.org/api/web/class/Selected/#optionIn)
+     * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+     *
+     * @param value
+     *  Text of the [`option` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     *  for the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to select
+     */
+    static option(value: Answerable<string>): {
+        from: (pageElement: Answerable<PageElement>) => Interaction;
+    };
+    /**
+     * Instantiates an [interaction](https://serenity-js.org/api/core/class/Interaction/)
+     * that instructs the [actor](https://serenity-js.org/api/core/class/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
+     * - [`Selected.optionsIn`](https://serenity-js.org/api/web/class/Selected/#optionsIn)
+     * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+     *
+     * @param values
+     *  Text of the [`option` elements  ](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     *  for the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to select
+     */
+    static options(...values: Array<Answerable<string[] | string>>): {
+        from: (pageElement: Answerable<PageElement>) => Interaction;
+    };
+}
+//# sourceMappingURL=Select.d.ts.map

package/esm/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,KAAK,UAAU,EAAE,WAAW,EAAM,MAAM,mBAAmB,CAAC;AAGrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD;;;;;;;;;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"}

package/esm/screenplay/interactions/Select.js

@@ -0,0 +1,262 @@
+import { Interaction, the } from '@serenity-js/core';
+import { asyncMap, commaSeparated, stringified } from '@serenity-js/core/io';
+import { SelectOption } from '../models/index.js';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/) who has the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/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.
+ *
+ * ## Learn more
+ * - [`Selected`](https://serenity-js.org/api/web/class/Selected/)
+ *
+ * @group Activities
+ */
+export class Select {
+    /**
+     * Instantiates an [interaction](https://serenity-js.org/api/core/class/Interaction/)
+     * that instructs the [actor](https://serenity-js.org/api/core/class/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>
+     * ```C
+     *
+     * #### 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
+     * - [`Selected.valueOf`](https://serenity-js.org/api/web/class/Selected/#valueOf)
+     * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+     *
+     * @param value
+     *  A value of the [`option` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     *  for the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to select
+     */
+    static value(value) {
+        return {
+            from: (pageElement) => Interaction.where(the `#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));
+            }),
+        };
+    }
+    /**
+     * Instantiates an [interaction](https://serenity-js.org/api/core/class/Interaction/)
+     * that instructs the [actor](https://serenity-js.org/api/core/class/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')
+     * }
+     * ```
+     *
+     * #### 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
+     *
+     * - [`Selected.valuesOf`](https://serenity-js.org/api/web/class/Selected/#valuesOf)
+     * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+     *
+     * @param values
+     *  Values of the [`option` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     *  for the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to select
+     */
+    static values(...values) {
+        return {
+            from: (pageElement) => 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 desiredValues = answers.flat();
+                const element = await actor.answer(pageElement);
+                await element.selectOptions(...desiredValues.map(value => SelectOption.withValue(value)));
+            }),
+        };
+    }
+    /**
+     * Instantiates an [interaction](https://serenity-js.org/api/core/class/Interaction/)
+     * that instructs the [actor](https://serenity-js.org/api/core/class/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
+     * - [`Selected.optionIn`](https://serenity-js.org/api/web/class/Selected/#optionIn)
+     * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+     *
+     * @param value
+     *  Text of the [`option` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     *  for the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to select
+     */
+    static option(value) {
+        return {
+            from: (pageElement) => Interaction.where(the `#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));
+            }),
+        };
+    }
+    /**
+     * Instantiates an [interaction](https://serenity-js.org/api/core/class/Interaction/)
+     * that instructs the [actor](https://serenity-js.org/api/core/class/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
+     * - [`Selected.optionsIn`](https://serenity-js.org/api/web/class/Selected/#optionsIn)
+     * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+     *
+     * @param values
+     *  Text of the [`option` elements  ](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     *  for the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to select
+     */
+    static options(...values) {
+        return {
+            from: (pageElement) => 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 desiredLabels = answers.flat();
+                const element = await actor.answer(pageElement);
+                await element.selectOptions(...desiredLabels.map(label => SelectOption.withLabel(label)));
+            }),
+        };
+    }
+}
+//# sourceMappingURL=Select.js.map

package/esm/screenplay/interactions/Select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Select.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Select.ts"],"names":[],"mappings":"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"}

package/esm/screenplay/interactions/Switch.d.ts

@@ -0,0 +1,130 @@
+import type { Activity, Answerable, AnswersQuestions, UsesAbilities } from '@serenity-js/core';
+import { Interaction, Task } from '@serenity-js/core';
+import type { Switchable } from '../models/index.js';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/) who has the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * to switch the context for future activities to a [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/), such as a [`Page`](https://serenity-js.org/api/web/class/Page/) or a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+ *
+ * Please note that when the [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) implementing [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/) represents an [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe),
+ * using [`Switch`](https://serenity-js.org/api/web/class/Switch/) will result in switching the top-level browsing context to that [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe).
+ *
+ * When the [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) represents any other [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement),
+ * using [`Switch`](https://serenity-js.org/api/web/class/Switch/) sets [`HTMLElement#focus`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus)
+ * on the specified element. Assuming it can be focused.
+ *
+ * **Note:** The focused element is the element which will receive keyboard [press](https://serenity-js.org/api/web/class/Press/) events by default.
+ *
+ * ## Perform activities in the context of an iframe
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { By, Click, Enter, PageElement, Switch } from '@serenity-js/web'
+ *
+ * // Lean Page Object describing a login form, embedded in an iframe
+ * class LoginForm {
+ *   static iframe = () =>
+ *     PageElement.located(By.css('iframe'))
+ *       .describedAs('login form')
+ *
+ *   static usernameField = () =>
+ *     PageElement.located(By.css('[data-testid="username"]'))
+ *       .describedAs('username field')
+ *
+ *   static passwordField = () =>
+ *     PageElement.located(By.css('[data-testid="password"]'))
+ *       .describedAs('password field')
+ *
+ *   static submitButton = () =>
+ *     PageElement.located(By.css('button[type="submit"]'))
+ *       .describedAs('submit button')
+ *  }
+ *
+ *  await actorCalled('Francesca')
+ *    .attemptsTo(
+ *      Switch.to(LoginForm.iframe).and(
+ *        Enter.theValue('francesca@example.org').into(LoginForm.usernameField()),
+ *        Enter.theValue('correct-horse-battery-staple').into(LoginForm.passwordField()),
+ *        Click.on(LoginForm.submitButton()),
+ *      )
+ *    )
+ * ```
+ *
+ * ## Perform activities in the context of another page
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Click, Enter, Switch } from '@serenity-js/web'
+ * import { browser } from '@wdio/globals'
+ *
+ * await actorCalled('Francesca')
+ *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *   .attemptsTo(
+ *     Switch.to(Page.whichName(startsWith('popup'))).and(
+ *       // perform some activities in the context of the new window
+ *
+ *       // optionally, close the browser tab
+ *       Page.current().close(),
+ *     ),
+ *
+ *     // Note that switching back to the original page happens automatically
+ *     // after the last activity from the list finishes
+ *   )
+ * ```
+ *
+ * ## Perform activities in the context of a focused page element
+ *
+ * ```ts
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Key, PageElement, Press, Switch, Value } from '@serenity-js/web'
+ * import { browser } from '@wdio/globals'
+ *
+ * const inputField = () =>
+ *   PageElement.located(By.css('input'));
+ *
+ * await actorCalled('Francesca')
+ *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *   .attemptsTo(
+ *     Switch.to(inputField()).and(
+ *       Press.the('h', 'e', 'l', 'l', 'o'),
+ *       Press.the(Key.Tab),
+ *     ),
+ *     Ensure.that(Value.of(inputField()), equals('hello'))
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/)
+ * - [`SwitchableOrigin`](https://serenity-js.org/api/web/interface/SwitchableOrigin/)
+ *
+ * @group Activities
+ */
+export declare class Switch extends Interaction {
+    private readonly switchable;
+    /**
+     * Instructs the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     * to switch the context for future activities to a [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/),
+     * such as a [`Page`](https://serenity-js.org/api/web/class/Page/) or a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+     *
+     * @param switchable
+     */
+    static to(switchable: Answerable<Switchable>): Switch;
+    protected constructor(switchable: Answerable<Switchable>);
+    /**
+     * Instructs the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     * to switch the context for future activities to a [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/),
+     * such as a [`Page`](https://serenity-js.org/api/web/class/Page/) or a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/),
+     * perform a sequence of `activities`, and then switch the context back.
+     *
+     * @param activities
+     *  A sequence of activities to perform
+     */
+    and(...activities: Activity[]): Task;
+    /**
+     * @inheritDoc
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
+}
+//# sourceMappingURL=Switch.d.ts.map

package/esm/screenplay/interactions/Switch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Switch.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/Switch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAS,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACtG,OAAO,EAAE,WAAW,EAAE,IAAI,EAAO,MAAM,mBAAmB,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,qBAAa,MAAO,SAAQ,WAAW;IAab,OAAO,CAAC,QAAQ,CAAC,UAAU;IAXjD;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,GAAG,MAAM;IAIrD,SAAS,aAA8B,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC;IAIzE;;;;;;;;OAQG;IACH,GAAG,CAAC,GAAG,UAAU,EAAE,QAAQ,EAAE,GAAG,IAAI;IAIpC;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAK1E"}