@serenity-js/web 3.0.0-rc.0

package/src/screenplay/questions/Selected.ts

@@ -0,0 +1,212 @@
+import { Answerable, Question } from '@serenity-js/core';
+import { formatted } from '@serenity-js/core/lib/io';
+
+import { PageElement, PageElements } from '../models';
+
+/**
+ * @desc
+ *  Represents options and values selected in a
+ *  [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).
+ *
+ * @see {@link Select}
+ */
+export 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}
+     */
+    static valueOf(pageElement: Answerable<PageElement>): Question<Promise<string>> {
+        return PageElement.locatedByCss('option:checked')
+            .of(pageElement)
+            .value()
+            .describedAs(formatted `value selected in ${ pageElement }`);
+    }
+
+    /**
+     * @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}
+     */
+    static valuesOf(pageElement: Answerable<PageElement>): Question<Promise<string[]>> {
+        return PageElements.locatedByCss('option:checked')
+            .of(pageElement)
+            .map(item => item.value())
+            .describedAs(formatted `values selected in ${ pageElement }`) as Question<Promise<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}
+     */
+    static optionIn(pageElement: Answerable<PageElement>): Question<Promise<string>> {
+        return PageElement.locatedByCss('option:checked')
+            .of(pageElement)
+            .text()
+            .describedAs(formatted `option selected in ${ pageElement }`);
+    }
+
+    /**
+     * @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}
+     */
+    static optionsIn(pageElement: Answerable<PageElement>): Question<Promise<string[]>> {
+        return PageElements.locatedByCss('option:checked')
+            .of(pageElement)
+            .map(item => item.text())
+            .describedAs(formatted `options selected in ${ pageElement }`) as Question<Promise<string[]>>;
+    }
+}

package/src/screenplay/questions/Text.ts

@@ -0,0 +1,153 @@
+import { Adapter, Answerable, AnswersQuestions, createAdapter, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
+
+import { PageElement, PageElements } from '../models';
+import { ElementQuestion } from './ElementQuestion';
+
+/**
+ * @desc
+ *  Resolves to the visible (i.e. not hidden by CSS) `innerText` of:
+ *  - a given {@link WebElement}, represented by Answerable<{@link @wdio/types~Element}>
+ *  - a group of {@link WebElement}s, represented by Answerable<{@link @wdio/types~ElementList}>
+ *
+ *  The result includes the visible text of any sub-elements, without any leading or trailing whitespace.
+ *
+ * @example <caption>Example widget</caption>
+ *  <h1>Shopping list</h1>
+ *  <ul id="shopping-list">
+ *    <li>Coffee<li>
+ *    <li class="bought">Honey<li>
+ *    <li>Chocolate<li>
+ *  </ul>
+ *
+ * @example <caption>Retrieve text of a single element</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *  import { BrowseTheWeb, by, Target, Text } from '@serenity-js/webdriverio';
+ *
+ *  const header = () =>
+ *      Target.the('header').located(by.tagName('h1'))
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(Text.of(header()), equals('Shopping list')),
+ *      )
+ *
+ * @example <caption>Retrieve text of a multiple elements</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *  import { BrowseTheWeb, by, Target, Text } from '@serenity-js/webdriverio';
+ *
+ *  const shoppingListItems = () =>
+ *      Target.the('shopping list items').located(by.css('#shopping-list li'))
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(
+ *              Text.ofAll(shoppingListItems()),
+ *              equals([ 'Coffee', 'Honey', 'Chocolate' ])
+ *          ),
+ *      )
+ *
+ * @example <caption>Find element with matching text</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { contain, Ensure } from '@serenity-js/assertions';
+ *  import { BrowseTheWeb, by, CssClasses, Target, Text } from '@serenity-js/webdriverio';
+ *
+ *  const shoppingListItemCalled = (name: string) =>
+ *      Target.the('shopping list items').located(by.css('#shopping-list li'))
+ *          .where(Text, equals(name))
+ *          .first()
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(
+ *              CssClasses.of(shoppingListItemCalled('Honey)),
+ *              contain('bought')
+ *          ),
+ *      )
+ *
+ * @public
+ * @see {@link Target}
+ */
+export class Text {
+
+    /**
+     * @desc
+     *  Retrieves text of a single {@link WebElement},
+     *  represented by Answerable<{@link @wdio/types~Element}>.
+     *
+     * @param {Answerable<PageElement>} element
+     * @returns {Question<Promise<string>> & MetaQuestion<Answerable<PageElement>, Promise<string>>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     */
+    static of(element: Answerable<PageElement>):
+        Question<Promise<string>> &                                 // eslint-disable-line @typescript-eslint/indent
+        MetaQuestion<Answerable<PageElement>, Promise<string>> &    // eslint-disable-line @typescript-eslint/indent
+        Adapter<string>                                                // eslint-disable-line @typescript-eslint/indent
+    {
+        return createAdapter<Promise<string>, ElementQuestion<Promise<string>> & MetaQuestion<Answerable<PageElement>, Promise<string>>>(
+            new TextOfSingleElement(element)
+        );
+    }
+
+    /**
+     * @desc
+     *  Retrieves text of a group of {@link WebElement}s,
+     *  represented by Answerable<{@link @wdio/types~ElementList}>
+     *
+     * @param {Answerable<PageElements>} elements
+     * @returns {Question<Promise<string[]>> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     */
+    static ofAll(elements: Answerable<PageElements>):
+        Question<Promise<string[]>> &                               // eslint-disable-line @typescript-eslint/indent
+        MetaQuestion<Answerable<PageElement>, Promise<string[]>> &  // eslint-disable-line @typescript-eslint/indent
+        Adapter<string[]>                                              // eslint-disable-line @typescript-eslint/indent
+    {
+        return createAdapter<Promise<string[]>, ElementQuestion<Promise<string[]>> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>>(
+            new TextOfMultipleElements(elements)
+        );
+    }
+}
+
+class TextOfSingleElement
+    extends ElementQuestion<Promise<string>>
+    implements MetaQuestion<Answerable<PageElement>, Promise<string>>
+{
+    constructor(private readonly element: Answerable<PageElement>) {
+        super(`the text of ${ element }`);
+    }
+
+    of(parent: Answerable<PageElement>): Question<Promise<string>> {
+        return new TextOfSingleElement(PageElement.of(this.element, parent));
+    }
+
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string> {
+        const element = await this.resolve(actor, this.element);
+
+        return element.text();
+    }
+}
+
+class TextOfMultipleElements
+    extends ElementQuestion<Promise<string[]>>
+    implements MetaQuestion<Answerable<PageElement>, Promise<string[]>>
+{
+    constructor(private readonly elements: Answerable<PageElements>) {
+        super(`the text of ${ elements }`);
+    }
+
+    of(parent: Answerable<PageElement>): Question<Promise<string[]>> {
+        return new TextOfMultipleElements(PageElements.of(this.elements, parent));
+    }
+
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string[]> {
+        const elements = await this.resolve(actor, this.elements);
+        return elements.map(element => element.text());
+    }
+}

package/src/screenplay/questions/Value.ts

@@ -0,0 +1,82 @@
+import { Answerable, AnswersQuestions, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
+import { formatted } from '@serenity-js/core/lib/io';
+
+import { PageElement } from '../models';
+import { ElementQuestion } from './ElementQuestion';
+
+/**
+ * @desc
+ *  Returns the `value` attribute of a given {@link WebElement},
+ *  represented by Answerable<{@link @wdio/types~Element}>
+ *
+ * @example <caption>Example widget</caption>
+ *  <input type="text" id="username" value="Alice" />
+ *
+ * @example <caption>Retrieve CSS classes of a given WebElement</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *  import { BrowseTheWeb, by, Value, Target } from '@serenity-js/webdriverio';
+ *
+ *  const usernameField = () =>
+ *      Target.the('username field').located(by.id('username'))
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(Value.of(usernameField), equals('Alice')),
+ *      )
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Question}
+ * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
+ */
+export class Value
+    extends ElementQuestion<Promise<string>>
+    implements MetaQuestion<Answerable<PageElement>, Promise<string>>
+{
+    /**
+     * @param {Answerable<PageElement>} element
+     * @returns {Value}
+     */
+    static of(element: Answerable<PageElement>): Question<Promise<string>> & MetaQuestion<Answerable<PageElement>, Promise<string>> {
+        return new Value(element);
+    }
+
+    /**
+     * @param {Answerable<PageElement>} element
+     */
+    constructor(private readonly element: Answerable<PageElement>) {
+        super(formatted`the value of ${ element }`);
+    }
+
+    /**
+     * @desc
+     *  Resolves to the value of a given [`input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)
+     *  {@link WebElement}, located in the context of a `parent` element.
+     *
+     * @param {Answerable<PageElement>} parent
+     * @returns {Question<Promise<string>>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     */
+    of(parent: Answerable<PageElement>): Question<Promise<string>> {
+        return new Value(PageElement.of(this.element, parent));
+    }
+
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  answer this {@link @serenity-js/core/lib/screenplay~Question}.
+     *
+     * @param {AnswersQuestions & UsesAbilities} actor
+     * @returns {Promise<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     */
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string> {
+        const element = await this.resolve(actor, this.element);
+
+        return element.value();
+    }
+}

package/src/screenplay/questions/index.ts

@@ -0,0 +1,6 @@
+export * from './Attribute';
+export * from './CssClasses';
+export * from './LastScriptExecution';
+export * from './Selected';
+export * from './Text';
+export * from './Value';

package/src/stage/crew/index.ts

@@ -0,0 +1 @@
+export * from './photographer';

package/src/stage/crew/photographer/Photographer.ts

@@ -0,0 +1,108 @@
+import { LogicError } from '@serenity-js/core';
+import { ActivityFinished, ActivityStarts, DomainEvent } from '@serenity-js/core/lib/events';
+import { Stage, StageCrewMember } from '@serenity-js/core/lib/stage';
+
+import { PhotoTakingStrategy } from './strategies';
+
+/**
+ * @desc
+ *  The Photographer is a {@link @serenity-js/core/lib/stage~StageCrewMember} who takes screenshots
+ *  of the web browser that the {@link @serenity-js/core/lib/screenplay/actor~Actor} in the spotlight is using.
+ *
+ * @example <caption>Assigning the Photographer to the Stage</caption>
+ * // wdio.conf.ts
+ * import { ArtifactArchiver } from '@serenity-js/core';
+ * import { Photographer, TakePhotosOfFailures } from '@serenity-js/webdriverio';
+ *
+ * export const config = {
+ *
+ *     serenity: {
+ *         crew: [
+ *             ArtifactArchiver.storingArtifactsAt(process.cwd(), 'target/site/serenity'),
+ *             Photographer.whoWill(TakePhotosOfFailures),
+ *         ]
+ *     },
+ *
+ *     // ... rest of the config omitted for brevity
+ * };
+ *
+ * @example <caption>Taking photos upon failures only</caption>
+ *
+ * import { Photographer, TakePhotosOfFailures } from '@serenity-js/webdriverio';
+ *
+ * Photographer.whoWill(TakePhotosOfFailures)
+ *
+ * @example <caption>Taking photos of all the interactions</caption>
+ *
+ * import { Photographer, TakePhotosOfInteractions } from '@serenity-js/webdriverio';
+ *
+ * Photographer.whoWill(TakePhotosOfInteractions)
+ *
+ * @example <caption>Taking photos before and after all the interactions</caption>
+ *
+ * import { Photographer, TakePhotosBeforeAndAfterInteractions } from '@serenity-js/webdriverio';
+ *
+ * Photographer.whoWill(TakePhotosBeforeAndAfterInteractions)
+ *
+ * @see {@link @serenity-js/core/lib/stage~Stage}
+ * @see {@link TakePhotosBeforeAndAfterInteractions}
+ * @see {@link TakePhotosOfFailures}
+ * @see {@link TakePhotosOfInteractions}
+ */
+export class Photographer implements StageCrewMember {
+
+    /**
+     * @desc
+     *  Instantiates a new {@link Photographer} configured to take photos (screenshots)
+     *  as per the specified {@link PhotoTakingStrategy}.
+     *
+     * @param {Function} strategy - A no-arg constructor function that instantiates a {@link PhotoTakingStrategy}.
+     * @returns {StageCrewMember}
+     */
+    static whoWill(strategy: new () => PhotoTakingStrategy): StageCrewMember {
+        return new Photographer(new strategy());
+    }
+
+    /**
+     * @param {PhotoTakingStrategy} photoTakingStrategy
+     * @param {Stage} stage
+     */
+    constructor(
+        private readonly photoTakingStrategy: PhotoTakingStrategy,
+        private stage?: Stage,
+    ) {
+    }
+
+    /**
+     * @desc
+     *  Creates a new instance of this {@link StageCrewMember} and assigns it to a given {@link Stage}.
+     *
+     * @param {Stage} stage - An instance of a {@link Stage} this {@link StageCrewMember} will be assigned to
+     * @returns {StageCrewMember} - A new instance of this {@link StageCrewMember}
+     */
+    assignedTo(stage: Stage): StageCrewMember {
+        return new Photographer(this.photoTakingStrategy, stage);
+    }
+
+    /**
+     * @desc
+     *  Handles {@link DomainEvent} objects emitted by the {@link Stage}
+     *  this {@link StageCrewMember} is assigned to.
+     *
+     * @param {DomainEvent} event
+     * @returns {void}
+     */
+    notifyOf(event: DomainEvent): void {
+        if (! this.stage) {
+            throw new LogicError(`Photographer needs to be assigned to the Stage before it can be notified of any DomainEvents`);
+        }
+
+        if (! this.stage.theShowHasStarted()) {
+            return void 0;
+        }
+
+        if (event instanceof ActivityStarts || event instanceof ActivityFinished) {
+            this.photoTakingStrategy.considerTakingPhoto(event, this.stage);
+        }
+    }
+}

package/src/stage/crew/photographer/index.ts

@@ -0,0 +1,2 @@
+export * from './Photographer';
+export * from './strategies';

package/src/stage/crew/photographer/strategies/PhotoTakingStrategy.ts

@@ -0,0 +1,116 @@
+import { Stage } from '@serenity-js/core';
+import { ActivityFinished, ActivityRelatedArtifactGenerated, ActivityStarts, AsyncOperationAttempted, AsyncOperationCompleted, AsyncOperationFailed, DomainEvent } from '@serenity-js/core/lib/events';
+import { CorrelationId, Description, Name, Photo } from '@serenity-js/core/lib/model';
+
+import { BrowseTheWeb } from '../../../../screenplay';
+
+/**
+ * @desc
+ *  Configures the {@link Photographer} to take photos (a.k.a. screenshots)
+ *  of the {@link @serenity-js/core/lib/screenplay~Activity} performed
+ *  by the {@link @serenity-js/core/lib/screenplay/actor~Actor} in the spotlight
+ *  under specific conditions.
+ *
+ * @abstract
+ */
+export abstract class PhotoTakingStrategy {
+
+    /**
+     * @desc
+     *  Takes a photo of the web browser held by the {@link @serenity-js/core/lib/screenplay/actor~Actor} in the spotlight.
+     *
+     * @param {@serenity-js/core/lib/events~ActivityStarts | @serenity-js/core/lib/events~ActivityFinished} event
+     * @param {@serenity-js/core/lib/stage~Stage} stage - the Stage that holds reference to the Actor in the spotlight
+     * @returns {void}
+     *
+     * @see {@link @serenity-js/core/lib/stage~Stage#theActorInTheSpotlight}
+     */
+    async considerTakingPhoto(event: ActivityStarts | ActivityFinished, stage: Stage): Promise<void> {
+        if (! this.shouldTakeAPhotoOf(event)) {
+            return void 0;
+        }
+
+        let browseTheWeb: BrowseTheWeb;
+
+        try {
+            browseTheWeb = BrowseTheWeb.as(stage.theActorInTheSpotlight());
+        } catch {
+            // actor doesn't have a browser, abort
+            return void 0;
+        }
+
+        const
+            id              = CorrelationId.create(),
+            nameSuffix      = this.photoNameFor(event);
+
+        stage.announce(new AsyncOperationAttempted(
+            new Description(`[Photographer:${ this.constructor.name }] Taking screenshot of '${ nameSuffix }'...`),
+            id,
+        ));
+
+        let dialogIsPresent: boolean;
+
+        try {
+            dialogIsPresent = await browseTheWeb.modalDialog().then(dialog => dialog.isPresent());
+
+            if (dialogIsPresent) {
+                return stage.announce(new AsyncOperationCompleted(
+                    new Description(`[${ this.constructor.name }] Aborted taking screenshot of '${ nameSuffix }' because of a modal dialog obstructing the view`),
+                    id,
+                ));
+            }
+        } catch (error) {
+            return stage.announce(new AsyncOperationFailed(error, id));
+        }
+
+        try {
+            const [ screenshot, capabilities ] = await Promise.all([
+                browseTheWeb.takeScreenshot(),
+                browseTheWeb.browserCapabilities(),
+            ]);
+
+            const
+                context   = [ capabilities.platformName, capabilities.browserName, capabilities.browserVersion ],
+                photoName = this.combinedNameFrom(...context, nameSuffix);
+
+            stage.announce(new ActivityRelatedArtifactGenerated(
+                event.sceneId,
+                event.activityId,
+                photoName,
+                Photo.fromBase64(screenshot),
+            ));
+
+            return stage.announce(new AsyncOperationCompleted(
+                new Description(`[${ this.constructor.name }] Took screenshot of '${ nameSuffix }' on ${ context }`),
+                id,
+            ));
+        }
+        catch (error) {
+            if (this.shouldIgnore(error)) {
+                stage.announce(new AsyncOperationCompleted(
+                    new Description(`[${ this.constructor.name }] Aborted taking screenshot of '${ nameSuffix }' because of ${ error.constructor && error.constructor.name }`),
+                    id,
+                ));
+            }
+            else {
+                stage.announce(new AsyncOperationFailed(error, id));
+            }
+        }
+    }
+
+    protected abstract shouldTakeAPhotoOf(event: DomainEvent): boolean;
+
+    protected abstract photoNameFor(event: DomainEvent): string;
+
+    private combinedNameFrom(...parts: string[]): Name {
+        return new Name(parts.filter(v => !! v).join('-'));
+    }
+
+    private shouldIgnore(error: Error) {
+        return error.name
+            && (error.name === 'NoSuchSessionError');
+        // todo: add SauceLabs
+        //  [0-0] 2021-12-02T01:32:36.402Z ERROR webdriver: Request failed with status 404 due to no such window: no such window: target window already closed
+        //  [0-0] from unknown error: web view not found
+    }
+}