@serenity-js/web 3.0.0-rc.0

package/src/screenplay/interactions/Select.ts

@@ -0,0 +1,317 @@
+import { Answerable, q } from '@serenity-js/core';
+import { commaSeparated, formatted } from '@serenity-js/core/lib/io';
+import { inspected } from '@serenity-js/core/lib/io/inspected';
+import { Interaction } from '@serenity-js/core/lib/screenplay';
+
+import { PageElement, PageElements } from '../models';
+import { SelectBuilder } from './SelectBuilder';
+
+/**
+ * @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.
+ *
+ * @see {@link Selected}
+ */
+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
+     *  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}
+     */
+    static value(value: Answerable<string>): SelectBuilder {
+        return {
+            from: (pageElement: Answerable<PageElement>): Interaction =>
+                Interaction.where(formatted `#actor selects value ${ value } from ${ pageElement }`, async actor => {
+                    return PageElement.locatedByCss(q`option[value=${ value }]`)
+                        .of(pageElement)
+                        .click()
+                        .performAs(actor);
+                }),
+        };
+    }
+
+    /**
+     * @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
+     *
+     * @returns {SelectBuilder}
+     *
+     * @see {@link Selected.valuesOf}
+     * @see {@link BrowseTheWeb}
+     * @see {@link Target}
+     * @see {@link @serenity-js/assertions~Ensure}
+     * @see {@link @serenity-js/assertions/lib/expectations~equals}
+     */
+    static values(...values: Array<Answerable<string[] | string>>): SelectBuilder {
+        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 => {
+
+                    const desiredValues = (await Promise.all(values.map(value => actor.answer(value)))).flat();    // eslint-disable-line unicorn/no-await-expression-member
+
+                    const options: PageElements  = await PageElements.locatedByCss(`option`).of(pageElement).answeredBy(actor);
+                    const shouldSelect: boolean[]   = await options.map(optionsToSelect(hasValueEqualOneOf(desiredValues)));
+
+                    return options.forEach((option, index) => {
+                        if (shouldSelect[index]) {
+                            return option.click()
+                        }
+                    });
+                }),
+        };
+    }
+
+    /**
+     * @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
+     *  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}
+     */
+    static option(value: Answerable<string>): SelectBuilder {
+        return {
+            from: (pageElement: Answerable<PageElement>): Interaction =>
+                Interaction.where(formatted `#actor selects ${ value } from ${ pageElement }`, async actor => {
+                    return PageElement.locatedByCssContainingText('option', value)
+                        .of(pageElement)
+                        .click()
+                        .performAs(actor);
+                }),
+        };
+    }
+
+    /**
+     * @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
+     *  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}
+     */
+    static options(...values: Array<Answerable<string[] | string>>): SelectBuilder {
+        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 => {
+
+                    const desiredOptions = (await Promise.all(values.map(value => actor.answer(value)))).flat();    // eslint-disable-line unicorn/no-await-expression-member
+
+                    const options: PageElements  = await PageElements.locatedByCss(`option`).of(pageElement).answeredBy(actor);
+                    const shouldSelect: boolean[]   = await options.map(optionsToSelect(hasTextEqualOneOf(desiredOptions)));
+
+                    return options.forEach((option, index) => {
+                        if (shouldSelect[index]) {
+                            return option.click()
+                        }
+                    });
+                }),
+        };
+    }
+}
+
+/** @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;
+}

package/src/screenplay/interactions/SelectBuilder.ts

@@ -0,0 +1,36 @@
+import { Answerable } from '@serenity-js/core';
+import { Interaction } from '@serenity-js/core/lib/screenplay';
+
+import { PageElement } from '../models';
+
+/**
+ * @desc
+ *  Configures the {@link Target} representing
+ *  a [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)
+ *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor}
+ *  to interact with.
+ *
+ * @interface
+ */
+export interface SelectBuilder {
+
+    /**
+     * @desc
+     *  Configures the {@link Target} representing
+     *  a [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)
+     *  for the {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  to interact with
+     *
+     * @param {Answerable<PageElement>} pageElement
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see {@link Select}
+     * @see {@link Select.option}
+     * @see {@link Select.options}
+     * @see {@link Select.value}
+     * @see {@link Select.values}
+     * @see {@link Target}
+     */
+    from: (pageElement: Answerable<PageElement>) => Interaction;
+}

package/src/screenplay/interactions/Switch.ts

@@ -0,0 +1,225 @@
+import { Activity, Answerable, AnswersQuestions, Interaction, PerformsActivities, Task, UsesAbilities } from '@serenity-js/core';
+
+import { BrowseTheWeb } from '../abilities';
+import { PageElement } from '../models';
+
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor}
+ *  to switch to a different [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame),
+ *  [inline frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe),
+ *  or browser window/tab.
+ *
+ * @example <caption>Lean Page Object describing a login form, embedded in an iframe</caption>
+ *
+ *  import { Target } from '@serenity-js/protractor';
+ *  import { by } from 'protractor';
+ *
+ *  class LoginForm {
+ *      static iframe           = Target.the('login form').located(by.tagName('iframe'));
+ *      static usernameField    = Target.the('username field').located(by.css('[data-test="username"]'));
+ *      static passwordField    = Target.the('password field').located(by.css('[data-test="password"]'));
+ *      static submitButton     = Target.the('submit button').located(by.css(`button[type='submit']`));
+ *  }
+ *
+ * @example <caption>Switch to an iframe and back</caption>
+ *
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Switch, Enter, Click } from '@serenity-js/protractor';
+ *  import { protractor } from 'protractor';
+ *
+ *  actorCalled('Francesca')
+ *      .whoCan(BrowseTheWeb.using(protractor.browser))
+ *      .attemptsTo(
+ *          Switch.toFrame(LoginForm.iframe),
+ *
+ *          Enter.theValue('francesca@example.org').into(LoginForm.usernameField),
+ *          Enter.theValue('correct-horse-battery-staple').into(LoginForm.passwordField),
+ *          Click.on(LoginForm.submitButton),
+ *
+ *          Switch.toParentFrame(),
+ *      );
+ *
+ * @example <caption>Perform activities in the context of an iframe</caption>
+ *
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Switch, Enter, Click } from '@serenity-js/protractor';
+ *  import { protractor } from 'protractor';
+ *
+ *  actorCalled('Francesca')
+ *      .whoCan(BrowseTheWeb.using(protractor.browser))
+ *      .attemptsTo(
+ *          Switch.toFrame(LoginForm.iframe).and(
+ *              Enter.theValue('francesca@example.org').into(LoginForm.usernameField),
+ *              Enter.theValue('correct-horse-battery-staple').into(LoginForm.passwordField),
+ *              Click.on(LoginForm.submitButton),
+ *          ),
+ *          // Note that Switch.toParentFrame() is invoked automatically
+ *      );
+ *
+ * @example <caption>Switch to a new window/tab and back</caption>
+ *
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Switch, Close } from '@serenity-js/protractor';
+ *  import { protractor } from 'protractor';
+ *
+ *  actorCalled('Francesca')
+ *      .whoCan(BrowseTheWeb.using(protractor.browser))
+ *      .attemptsTo(
+ *          Switch.toNewWindow(), // or: Switch.toWindow(...)
+ *
+ *          // perform some activities in the context of the new window
+ *
+ *          Close.currentWindow(),
+ *
+ *          Switch.toOriginalWindow(),
+ *      );
+ *
+ * @example <caption>Perform activities in the context of a different window/tab</caption>
+ *
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Switch, Close } from '@serenity-js/protractor';
+ *  import { protractor } from 'protractor';
+ *
+ *  actorCalled('Francesca')
+ *      .whoCan(BrowseTheWeb.using(protractor.browser))
+ *      .attemptsTo(
+ *          Switch.toNewWindow().and(
+ *              // perform some activities in the context of the new window
+ *
+ *              Close.currentWindow()
+ *          ),
+ *
+ *          // Note that Switch.toOriginalWindow() is invoked automatically
+ *      );
+ *
+ * @see {@link Close}
+ * @see {@link BrowseTheWeb}
+ */
+export class Switch {
+
+    /**
+     * @desc
+     *  Switches the current [browsing context](https://w3c.github.io/webdriver/#dfn-current-browsing-context)
+     *  for future commands to a [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame)
+     *  or an [inline frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)
+     *  identified by its name, index or `Question<ElementFinder>`.
+     *
+     * @param {Answerable<ElementFinder | number | string>} targetOrIndex
+     *
+     * @returns {SwitchToFrame}
+     *
+     * @see {@link Switch.toParentFrame}
+     * @see {@link Switch.toDefaultContent}
+     * @see {@link Target}
+     */
+    static toFrame(targetOrIndex: Answerable<PageElement | number | string>): SwitchToFrame {
+        return new SwitchToFrame(targetOrIndex);
+    }
+
+    /**
+     * @desc
+     *  Sets the current [browsing context](https://w3c.github.io/webdriver/#dfn-current-browsing-context)
+     *  for future commands to the parent of the current browsing context,
+     *  i.e. an `iframe` in which the current `iframe` is nested.
+     *
+     *  If the current context is the top-level browsing context, the context remains unchanged.
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see {@link Switch.toFrame}
+     * @see https://w3c.github.io/webdriver/#switch-to-parent-frame
+     * @see https://w3c.github.io/webdriver/#dfn-current-browsing-context
+     */
+    static toParentFrame(): Interaction {
+        return new SwitchToParentFrame();
+    }
+
+    /**
+     * @desc
+     *  Switches the current [browsing context](https://w3c.github.io/webdriver/#dfn-current-browsing-context)
+     *  for future commands to the first frame on the page, or the main document
+     *  when a page contains [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)s.
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see {@link Switch.toFrame}
+     */
+    static toDefaultContent(): Interaction {
+        return new SwitchToDefaultContent();
+    }
+}
+
+/**
+ * @package
+ */
+class SwitchToFrame extends Interaction {
+    constructor(private readonly targetOrIndex: Answerable<PageElement | number | string>) {
+        super();
+    }
+
+    and(...activities: Activity[]): Task {
+        return new SwitchToFrameAndPerformActivities(this.targetOrIndex, activities);
+    }
+
+    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
+        return actor.answer(this.targetOrIndex)
+            .then((targetOrIndex: PageElement | number | string) => {
+                return BrowseTheWeb.as(actor).switchToFrame(targetOrIndex);
+            });
+    }
+
+    toString(): string {
+        return `#actor switches to frame: ${ this.targetOrIndex }`;
+    }
+}
+
+/**
+ * @package
+ */
+class SwitchToFrameAndPerformActivities extends Task {
+    constructor(
+        private readonly targetOrIndex: Answerable<PageElement | number | string>,
+        private readonly activities: Activity[]
+    ) {
+        super();
+    }
+
+    performAs(actor: PerformsActivities): PromiseLike<void> {
+        return actor.attemptsTo(
+            new SwitchToFrame(this.targetOrIndex),
+            ...this.activities,
+            new SwitchToParentFrame()
+        )
+    }
+
+    toString(): string {
+        return `#actor switches to frame: ${ this.targetOrIndex }`;
+    }
+}
+
+/**
+ * @package
+ */
+class SwitchToParentFrame extends Interaction {
+    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
+        return BrowseTheWeb.as(actor).switchToParentFrame();
+    }
+
+    toString(): string {
+        return `#actor switches to parent frame`;
+    }
+}
+
+/**
+ * @package
+ */
+class SwitchToDefaultContent extends Interaction {
+    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
+        return BrowseTheWeb.as(actor).switchToDefaultContent();
+    }
+
+    toString(): string {
+        return `#actor switches to default content`;
+    }
+}

package/src/screenplay/interactions/TakeScreenshot.ts

@@ -0,0 +1,89 @@
+import { Answerable, AnswersQuestions, CollectsArtifacts, Interaction, UsesAbilities } from '@serenity-js/core';
+import { formatted } from '@serenity-js/core/lib/io';
+import { Name, Photo } from '@serenity-js/core/lib/model';
+
+import { BrowseTheWeb } from '../abilities';
+
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  take a screenshot and emit an {@link @serenity-js/core/lib/model~Artifact},
+ *  which can then be persisted by {@link @serenity-js/core/lib/stage/crew/artifact-archiver~ArtifactArchiver}
+ *  and reported by [Serenity BDD reporter](/modules/serenity-bdd).
+ *
+ * @example <caption>Clicking on an element</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Navigate, TakeScreenshot } from '@serenity-js/protractor';
+ *  import { protractor } from 'protractor';
+ *
+ *  actorCalled('Tania')
+ *      .whoCan(BrowseTheWeb.using(protractor.browser))
+ *      .attemptsTo(
+ *          Navigate.to('/app'),
+ *          TakeScreenshot.of('my app'),
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link @serenity-js/core/lib/screenplay/actor~CollectsArtifacts}
+ * @see {@link @serenity-js/core/lib/model~Artifact}
+ * @see {@link @serenity-js/core/lib/stage/crew/artifact-archiver~ArtifactArchiver}
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ */
+export class TakeScreenshot extends Interaction {
+
+    /**
+     * @desc
+     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {Answerable<string>} name
+     *  The name to associate the screenshot with
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static of(name: Answerable<string>): Interaction {
+        return new TakeScreenshot(name);
+    }
+
+    /**
+     * @param {Answerable<string>} name
+     *  The name to associate the screenshot with
+     */
+    constructor(private readonly name: Answerable<string>) {
+        super();
+    }
+
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions} actor
+     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @returns {PromiseLike<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): PromiseLike<void> {
+        return Promise.all([
+            BrowseTheWeb.as(actor).takeScreenshot(),
+            actor.answer(this.name),
+        ]).then(([ screenshot, name ]) => actor.collect(
+            Photo.fromBase64(screenshot),
+            new Name(name),
+        ));
+    }
+
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString(): string {
+        return formatted `#actor takes a screenshot of ${this.name}`;
+    }
+}