@serenity-js/web 3.0.0-rc.0

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

@@ -0,0 +1,150 @@
+import { Activity, Answerable, AnswersQuestions, Interaction, Task, UsesAbilities } from '@serenity-js/core';
+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 declare 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;
+    /**
+     * @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;
+    /**
+     * @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;
+}
+/**
+ * @package
+ */
+declare class SwitchToFrame extends Interaction {
+    private readonly targetOrIndex;
+    constructor(targetOrIndex: Answerable<PageElement | number | string>);
+    and(...activities: Activity[]): Task;
+    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void>;
+    toString(): string;
+}
+export {};

package/lib/screenplay/interactions/Switch.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Switch = void 0;
+const core_1 = require("@serenity-js/core");
+const abilities_1 = require("../abilities");
+/**
+ * @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}
+ */
+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) {
+        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() {
+        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() {
+        return new SwitchToDefaultContent();
+    }
+}
+exports.Switch = Switch;
+/**
+ * @package
+ */
+class SwitchToFrame extends core_1.Interaction {
+    constructor(targetOrIndex) {
+        super();
+        this.targetOrIndex = targetOrIndex;
+    }
+    and(...activities) {
+        return new SwitchToFrameAndPerformActivities(this.targetOrIndex, activities);
+    }
+    performAs(actor) {
+        return actor.answer(this.targetOrIndex)
+            .then((targetOrIndex) => {
+            return abilities_1.BrowseTheWeb.as(actor).switchToFrame(targetOrIndex);
+        });
+    }
+    toString() {
+        return `#actor switches to frame: ${this.targetOrIndex}`;
+    }
+}
+/**
+ * @package
+ */
+class SwitchToFrameAndPerformActivities extends core_1.Task {
+    constructor(targetOrIndex, activities) {
+        super();
+        this.targetOrIndex = targetOrIndex;
+        this.activities = activities;
+    }
+    performAs(actor) {
+        return actor.attemptsTo(new SwitchToFrame(this.targetOrIndex), ...this.activities, new SwitchToParentFrame());
+    }
+    toString() {
+        return `#actor switches to frame: ${this.targetOrIndex}`;
+    }
+}
+/**
+ * @package
+ */
+class SwitchToParentFrame extends core_1.Interaction {
+    performAs(actor) {
+        return abilities_1.BrowseTheWeb.as(actor).switchToParentFrame();
+    }
+    toString() {
+        return `#actor switches to parent frame`;
+    }
+}
+/**
+ * @package
+ */
+class SwitchToDefaultContent extends core_1.Interaction {
+    performAs(actor) {
+        return abilities_1.BrowseTheWeb.as(actor).switchToDefaultContent();
+    }
+    toString() {
+        return `#actor switches to default content`;
+    }
+}
+//# sourceMappingURL=Switch.js.map

package/lib/screenplay/interactions/Switch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Switch.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Switch.ts"],"names":[],"mappings":";;;AAAA,4CAAiI;AAEjI,4CAA4C;AAG5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AACH,MAAa,MAAM;IAEf;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,aAAwD;QACnE,OAAO,IAAI,aAAa,CAAC,aAAa,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,aAAa;QAChB,OAAO,IAAI,mBAAmB,EAAE,CAAC;IACrC,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,gBAAgB;QACnB,OAAO,IAAI,sBAAsB,EAAE,CAAC;IACxC,CAAC;CACJ;AApDD,wBAoDC;AAED;;GAEG;AACH,MAAM,aAAc,SAAQ,kBAAW;IACnC,YAA6B,aAAwD;QACjF,KAAK,EAAE,CAAC;QADiB,kBAAa,GAAb,aAAa,CAA2C;IAErF,CAAC;IAED,GAAG,CAAC,GAAG,UAAsB;QACzB,OAAO,IAAI,iCAAiC,CAAC,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;IACjF,CAAC;IAED,SAAS,CAAC,KAAuC;QAC7C,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC;aAClC,IAAI,CAAC,CAAC,aAA4C,EAAE,EAAE;YACnD,OAAO,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;IACX,CAAC;IAED,QAAQ;QACJ,OAAO,6BAA8B,IAAI,CAAC,aAAc,EAAE,CAAC;IAC/D,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,iCAAkC,SAAQ,WAAI;IAChD,YACqB,aAAwD,EACxD,UAAsB;QAEvC,KAAK,EAAE,CAAC;QAHS,kBAAa,GAAb,aAAa,CAA2C;QACxD,eAAU,GAAV,UAAU,CAAY;IAG3C,CAAC;IAED,SAAS,CAAC,KAAyB;QAC/B,OAAO,KAAK,CAAC,UAAU,CACnB,IAAI,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,EACrC,GAAG,IAAI,CAAC,UAAU,EAClB,IAAI,mBAAmB,EAAE,CAC5B,CAAA;IACL,CAAC;IAED,QAAQ;QACJ,OAAO,6BAA8B,IAAI,CAAC,aAAc,EAAE,CAAC;IAC/D,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,mBAAoB,SAAQ,kBAAW;IACzC,SAAS,CAAC,KAAuC;QAC7C,OAAO,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,mBAAmB,EAAE,CAAC;IACxD,CAAC;IAED,QAAQ;QACJ,OAAO,iCAAiC,CAAC;IAC7C,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,sBAAuB,SAAQ,kBAAW;IAC5C,SAAS,CAAC,KAAuC;QAC7C,OAAO,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,sBAAsB,EAAE,CAAC;IAC3D,CAAC;IAED,QAAQ;QACJ,OAAO,oCAAoC,CAAC;IAChD,CAAC;CACJ"}

package/lib/screenplay/interactions/TakeScreenshot.d.ts

@@ -0,0 +1,67 @@
+import { Answerable, AnswersQuestions, CollectsArtifacts, Interaction, UsesAbilities } from '@serenity-js/core';
+/**
+ * @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 declare class TakeScreenshot extends Interaction {
+    private readonly name;
+    /**
+     * @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;
+    /**
+     * @param {Answerable<string>} name
+     *  The name to associate the screenshot with
+     */
+    constructor(name: Answerable<string>);
+    /**
+     * @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>;
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString(): string;
+}

package/lib/screenplay/interactions/TakeScreenshot.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TakeScreenshot = void 0;
+const core_1 = require("@serenity-js/core");
+const io_1 = require("@serenity-js/core/lib/io");
+const model_1 = require("@serenity-js/core/lib/model");
+const abilities_1 = require("../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}
+ */
+class TakeScreenshot extends core_1.Interaction {
+    /**
+     * @param {Answerable<string>} name
+     *  The name to associate the screenshot with
+     */
+    constructor(name) {
+        super();
+        this.name = name;
+    }
+    /**
+     * @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) {
+        return new TakeScreenshot(name);
+    }
+    /**
+     * @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) {
+        return Promise.all([
+            abilities_1.BrowseTheWeb.as(actor).takeScreenshot(),
+            actor.answer(this.name),
+        ]).then(([screenshot, name]) => actor.collect(model_1.Photo.fromBase64(screenshot), new model_1.Name(name)));
+    }
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString() {
+        return (0, io_1.formatted) `#actor takes a screenshot of ${this.name}`;
+    }
+}
+exports.TakeScreenshot = TakeScreenshot;
+//# sourceMappingURL=TakeScreenshot.js.map

package/lib/screenplay/interactions/TakeScreenshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TakeScreenshot.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/TakeScreenshot.ts"],"names":[],"mappings":";;;AAAA,4CAAgH;AAChH,iDAAqD;AACrD,uDAA0D;AAE1D,4CAA4C;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAa,cAAe,SAAQ,kBAAW;IAe3C;;;OAGG;IACH,YAA6B,IAAwB;QACjD,KAAK,EAAE,CAAC;QADiB,SAAI,GAAJ,IAAI,CAAoB;IAErD,CAAC;IAnBD;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,CAAC,IAAwB;QAC9B,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAUD;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,KAA2D;QACjE,OAAO,OAAO,CAAC,GAAG,CAAC;YACf,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,cAAc,EAAE;YACvC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;SAC1B,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,UAAU,EAAE,IAAI,CAAE,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAC3C,aAAK,CAAC,UAAU,CAAC,UAAU,CAAC,EAC5B,IAAI,YAAI,CAAC,IAAI,CAAC,CACjB,CAAC,CAAC;IACP,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,IAAA,cAAS,EAAC,gCAAgC,IAAI,CAAC,IAAI,EAAE,CAAC;IACjE,CAAC;CACJ;AAxDD,wCAwDC"}

package/lib/screenplay/interactions/Wait.d.ts

@@ -0,0 +1,143 @@
+import { Answerable, Duration, Expectation, Interaction } from '@serenity-js/core';
+import { WaitBuilder } from './WaitBuilder';
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  wait before proceeding either for a set {@link @serenity-js/core/lib/model~Duration}
+ *  or until a given {@link @serenity-js/core/lib/screenplay/questions~Expectation} is met.
+ *
+ *  Under the hood, `Wait` uses WebdriverIO ["explicit waiting"](https://webdriver.io/docs/autowait/)
+ *  mechanism.
+ *
+ * @example <caption>Example widget</caption>
+ *  <!--
+ *      After about 1 second, the text will change from 'Loading...' to 'Ready!'
+ *  -->
+ *  <h1 id="status">Loading...</h1>
+ *  <script>
+ *      (function () {
+ *          setTimeout(function () {
+ *              document.getElementById('status').textContent = 'Ready!'
+ *          }, 1000);
+ *      })();
+ *  </script>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class App {
+ *      static status = Target.the('status widget')
+ *          .located(by.id('status'));
+ *  }
+ *
+ * @example <caption>Waiting for a set amount of time</caption>
+ *  import { actorCalled, Duration } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Wait } from '@serenity-js/webdriverio';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Wendy')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Wait.for(Duration.ofSeconds(1.5)),
+ *          Ensure.that(App.status, equals('Ready!')),
+ *      );
+ *
+ *  // Please note that while the above implementation works,
+ *  // this approach is inefficient because at best
+ *  // the actor might wait too long and at worst the test
+ *  // might become "flaky" if any external interference
+ *  // (like network glitches, animations taking a bit too long etc.)
+ *  // makes the actor wait not long enough.
+ *
+ * @example <caption>Waiting until a condition is met</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Wait, Text } from '@serenity-js/webdriverio';
+ *  import { equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Wendy')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Wait.until(Text.of(App.status), equals('Ready!')),
+ *          // app is ready, proceed with the scenario
+ *      );
+ *
+ *  // Wait.until makes the Actor keep asking a Question,
+ *  // in this case Text.of(App.status), until the answer meets
+ *  // the expectation, or a timeout expires (default: 5s).
+ *  //
+ *  // Please note that both Ensure and Wait can be used with
+ *  // the same expectations, like `equals`.
+ *
+ * @example <caption>Changing the default timeout</caption>
+ *  import { actorCalled, Duration } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Wait, Text } from '@serenity-js/webdriverio';
+ *  import { equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Wendy')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Wait.upTo(Duration.ofSeconds(3))
+ *              .until(Text.of(App.status), equals('Ready!')),
+ *          // app is ready, proceed with the scenario
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link Text}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ * @see {@link @serenity-js/core/lib/model~Duration}
+ *
+ * @see {@link @serenity-js/core/lib/screenplay~Interaction}
+ */
+export declare class Wait {
+    /**
+     * @desc
+     *  Default timeout of 5 seconds used with {@link Wait.until}.
+     *
+     * @type {@serenity-js/core~Duration}
+     */
+    static readonly Default_Timeout: Duration;
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to wait for a set duration.
+     *
+     * @param {Answerable<Duration>} duration
+     *  A set duration the {@link @serenity-js/core/lib/screenplay/actor~Actor} should wait for
+     *  before proceeding
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static for(duration: Answerable<Duration>): Interaction;
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to wait until the answer to the question (`actual`) meets the `expectation`,
+     *  or a custom timeout expires.
+     *
+     * @param {Duration} duration
+     *  Custom timeout to override {@link Wait.Default_Timeout}
+     *
+     * @returns {WaitBuilder}
+     */
+    static upTo(duration: Duration): WaitBuilder;
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to wait until the answer to the question (`actual`) meets the `expectation`,
+     *  or a {@link Wait.Default_Timeout} expires.
+     *
+     * @param {Answerable<Actual>} actual
+     *  A {@link @serenity-js/core/lib/screenplay~Question}
+     *  that the {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  will keep asking until the answer meets
+     *  the {@link @serenity-js/core/lib/screenplay/questions~Expectation} provided
+     *
+     * @param {@serenity-js/core/lib/screenplay/questions~<any,Actual>} expectation
+     *  An {@link @serenity-js/core/lib/screenplay/questions~Expectation} to be met before proceeding
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static until<Actual>(actual: Answerable<Actual>, expectation: Expectation<any, Actual>): Interaction;
+}