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

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

@@ -1,73 +1,64 @@
-import { Answerable, AnswersQuestions, UsesAbilities } from '@serenity-js/core';
+import { Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@serenity-js/core';
 import { PageElement } from '../models';
-import { EnterBuilder } from './EnterBuilder';
 import { PageElementInteraction } from './PageElementInteraction';
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  enter a value into a [form `input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) field.
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to enter a value into a [form `input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) field.
  *
- * @example <caption>Example widget</caption>
- *  <form>
- *    <input type="text" name="example" id="example" />
- *  </form>
+ * ## Example widget
+ * ```html
+ * <form>
+ *  <input type="text" name="example" id="example" />
+ * </form>
+ * ```
  *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { by, Target } from '@serenity-js/webdriverio';
+ * ## Lean Page Object describing the widget
  *
- *  class Form {
- *      static exampleInput = Target.the('example input')
- *          .located(by.id('example'));
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
+ *
+ * class Form {
+ *   static exampleInput = () =>
+ *     PageElement.located(By.id('example'))
+ *       .describedAs('example input')
  *  }
+ * ```
+ *
+ * ## Entering the value into a form field
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Enter } from '@serenity-js/web';
  *
- * @example <caption>Entering the value into a form field</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Enter } from '@serenity-js/webdriverio';
+ * await actorCalled('Esme')
+ *   .attemptsTo(
+ *     Enter.theValue('Hello world!').into(Form.exampleInput()),
+ *   )
+ * ```
  *
- *  actorCalled('Esme')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Enter.theValue('Hello world!').into(Form.exampleInput),
- *      );
+ * ## Learn more
  *
- * @see {@link Target}
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink PageElement}
  *
- * @extends {ElementInteraction}
+ * @group Activities
  */
 export declare class Enter extends PageElementInteraction {
     private readonly values;
     private readonly field;
     /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Array<Answerable<string | number | string[] | number[]>>} values
-     *  The value to be entered
-     *
-     * @returns {EnterBuilder}
-     */
-    static theValue(...values: Array<Answerable<string | number | string[] | number[]>>): EnterBuilder;
-    /**
-     * @param {Array<Answerable<string | number | string[] | number[]>>} values
-     *  The value to be entered
+     * Instantiates this {@apilink Interaction}.
      *
-     * @param {Answerable<PageElement>} field
-     *  The field to enter the value into
+     * @param values
+     *  The text value to be entered
      */
-    constructor(values: Array<Answerable<string | number | string[] | number[]>>, field: Answerable<PageElement>);
+    static theValue(...values: Array<Answerable<string | number | string[] | number[]>>): {
+        into: (field: Answerable<PageElement>) => Interaction;
+    };
+    protected constructor(values: Array<Answerable<string | number | string[] | number[]>>, field: Answerable<PageElement>);
     /**
-     * @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 {Promise<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}
+     * @inheritDoc
      */
     performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
 }
+//# sourceMappingURL=Enter.d.ts.map

package/lib/screenplay/interactions/Enter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Enter.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/Enter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAK,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGhG,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,KAAM,SAAQ,sBAAsB;IAgBzC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAf1B;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,WAAW,CAAA;KAAE;IAO/I,SAAS,aACY,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,EAChE,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC;IAKnD;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAO1E"}

package/lib/screenplay/interactions/Enter.js

@@ -1,80 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Enter = void 0;
+const core_1 = require("@serenity-js/core");
 const io_1 = require("@serenity-js/core/lib/io");
 const PageElementInteraction_1 = require("./PageElementInteraction");
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  enter a value into a [form `input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) field.
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to enter a value into a [form `input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) field.
  *
- * @example <caption>Example widget</caption>
- *  <form>
- *    <input type="text" name="example" id="example" />
- *  </form>
+ * ## Example widget
+ * ```html
+ * <form>
+ *  <input type="text" name="example" id="example" />
+ * </form>
+ * ```
  *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { by, Target } from '@serenity-js/webdriverio';
+ * ## Lean Page Object describing the widget
  *
- *  class Form {
- *      static exampleInput = Target.the('example input')
- *          .located(by.id('example'));
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
+ *
+ * class Form {
+ *   static exampleInput = () =>
+ *     PageElement.located(By.id('example'))
+ *       .describedAs('example input')
  *  }
+ * ```
+ *
+ * ## Entering the value into a form field
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Enter } from '@serenity-js/web';
  *
- * @example <caption>Entering the value into a form field</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Enter } from '@serenity-js/webdriverio';
+ * await actorCalled('Esme')
+ *   .attemptsTo(
+ *     Enter.theValue('Hello world!').into(Form.exampleInput()),
+ *   )
+ * ```
  *
- *  actorCalled('Esme')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Enter.theValue('Hello world!').into(Form.exampleInput),
- *      );
+ * ## Learn more
  *
- * @see {@link Target}
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink PageElement}
  *
- * @extends {ElementInteraction}
+ * @group Activities
  */
 class Enter extends PageElementInteraction_1.PageElementInteraction {
     /**
-     * @param {Array<Answerable<string | number | string[] | number[]>>} values
-     *  The value to be entered
-     *
-     * @param {Answerable<PageElement>} field
-     *  The field to enter the value into
-     */
-    constructor(values, field /* todo | Question<AlertPromise> | AlertPromise */) {
-        super((0, io_1.formatted) `#actor enters ${values.join(', ')} into ${field}`);
-        this.values = values;
-        this.field = field;
-    }
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Array<Answerable<string | number | string[] | number[]>>} values
-     *  The value to be entered
+     * Instantiates this {@apilink Interaction}.
      *
-     * @returns {EnterBuilder}
+     * @param values
+     *  The text value to be entered
      */
     static theValue(...values) {
         return {
             into: (field /* todo Question<AlertPromise> | AlertPromise */) => new Enter(values, field),
         };
     }
+    constructor(values, field /* todo | Question<AlertPromise> | AlertPromise */) {
+        super((0, core_1.d) `#actor enters ${values.join(', ')} into ${field}`);
+        this.values = values;
+        this.field = field;
+    }
     /**
-     * @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 {Promise<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}
+     * @inheritDoc
      */
     async performAs(actor) {
         const field = await this.resolve(actor, this.field);

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

@@ -1 +1 @@
-{"version":3,"file":"Enter.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Enter.ts"],"names":[],"mappings":";;;AACA,iDAA+D;AAI/D,qEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAa,KAAM,SAAQ,+CAAsB;IAkB7C;;;;;;OAMG;IACH,YACqB,MAAgE,EAChE,KAA8B,CAAC,kDAAkD;QAElG,KAAK,CAAC,IAAA,cAAS,EAAC,iBAAkB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAE,SAAU,KAAM,EAAE,CAAC,CAAC;QAHvD,WAAM,GAAN,MAAM,CAA0D;QAChE,UAAK,GAAL,KAAK,CAAyB;IAGnD,CAAC;IA5BD;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAgE;QAC/E,OAAO;YACH,IAAI,EAAE,CAAC,KAA8B,CAAE,gDAAgD,EAAE,EAAE,CACvF,IAAI,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC;SAC/B,CAAC;IACN,CAAC;IAgBD;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,KAAK,GAAI,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAErD,MAAM,aAAa,GAAG,MAAM,IAAA,aAAQ,EAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QAE/E,OAAO,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;CACJ;AArDD,sBAqDC"}
+{"version":3,"file":"Enter.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Enter.ts"],"names":[],"mappings":";;;AAAA,4CAAgG;AAChG,iDAAoD;AAGpD,qEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAa,KAAM,SAAQ,+CAAsB;IAE7C;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAgE;QAC/E,OAAO;YACH,IAAI,EAAE,CAAC,KAA8B,CAAE,gDAAgD,EAAE,EAAE,CACvF,IAAI,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC;SAC/B,CAAC;IACN,CAAC;IAED,YACqB,MAAgE,EAChE,KAA8B,CAAC,kDAAkD;QAElG,KAAK,CAAC,IAAA,QAAC,EAAC,iBAAkB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAE,SAAU,KAAM,EAAE,CAAC,CAAC;QAH/C,WAAM,GAAN,MAAM,CAA0D;QAChE,UAAK,GAAL,KAAK,CAAyB;IAGnD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,KAAK,GAAI,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAErD,MAAM,aAAa,GAAG,MAAM,IAAA,aAAQ,EAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QAE/E,OAAO,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;CACJ;AAhCD,sBAgCC"}

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

@@ -1,206 +1,202 @@
 import { Answerable, AnswersQuestions, CollectsArtifacts, Interaction, UsesAbilities } from '@serenity-js/core';
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  execute a script within the context of the current browser window.
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to execute a script within the context of the current browser tab.
  *
- *  Please see the tests below for usage examples.
+ * ## Learn more
  *
- * @see {@link LastScriptExecution.result}
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink LastScriptExecution.result}
+ *
+ * @group Activities
  */
 export declare class ExecuteScript {
     /**
-     * @desc
-     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  configured to load a script from `sourceUrl`.
+     * Instantiates a version of this {@apilink Interaction}
+     * configured to load a script from `sourceUrl`.
      *
-     * @param {string} sourceUrl
+     * @param sourceUrl
      *  The URL to load the script from
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
      */
-    static from(sourceUrl: string): Interaction;
+    static from(sourceUrl: Answerable<string>): Interaction;
     /**
-     * @desc
-     *  Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window.
-     *  The script fragment will be executed as the body of an anonymous function.
-     *  If the script is provided as a function object, that function will be converted to a string for injection
-     *  into the target window.
+     * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+     * to execute an asynchronous script within the context of the current browser tab.
      *
-     *  Any arguments provided in addition to the script will be included as script arguments and may be referenced
-     *  using the `arguments` object. Arguments may be a `boolean`, `number`, `string`
-     *  or {@link Target} (`Answerable<Element>`).
-     *  Arrays and objects may also be used as script arguments as long as each item adheres
-     *  to the types previously mentioned.
+     * The script fragment will be executed as the body of an anonymous function.
+     * If the script is provided as a function object, that function will be converted to a string for injection
+     * into the target window.
      *
-     *  Unlike executing synchronous JavaScript with {@link ExecuteScript#sync},
-     *  scripts executed with this function must explicitly signal they are finished by invoking the provided callback.
+     * Any arguments provided in addition to the script will be included as script arguments and may be referenced
+     * using the `arguments` object. Arguments may be a `boolean`, `number`, `string`
+     * or {@apilink PageElement}.
+     * Arrays and objects may also be used as script arguments as long as each item adheres
+     * to the types previously mentioned.
      *
-     *  This callback will always be injected into the executed function as the last argument,
-     *  and thus may be referenced with `arguments[arguments.length - 1]`.
+     * Unlike executing synchronous JavaScript with {@apilink ExecuteScript.sync},
+     * scripts executed with this function must explicitly signal they are finished by invoking the provided callback.
      *
-     *  If the script invokes the `callback` with a return value, this will be made available
-     *  via the {@link LastScriptExecution.result}.
+     * This callback will always be injected into the executed function as the last argument,
+     * and thus may be referenced with `arguments[arguments.length - 1]`.
      *
-     *  **Please note** that in order to signal an error in the `script` you need to throw an {@link Error}
-     *  instead of passing it to the callback function.
+     * If the script invokes the `callback` with a return value, this will be made available
+     * via the {@apilink LastScriptExecution.result}.
      *
-     * @example <caption>Executing an async script</caption>
-     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     * **Please note** that in order to signal an error in the `script` you need to throw an {@apilink Error}
+     * instead of passing it to the callback function.
      *
-     *  actor.attemptsTo(
-     *      ExecuteScript.async(`
-     *          var callback = arguments[arguments.length - 1];
+     * #### Executing an async script
      *
-     *          // do stuff
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
      *
-     *          callback(result)
-     *      `)
-     *  );
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(`
+     *     var callback = arguments[arguments.length - 1]
      *
-     * @example <caption>Passing arguments to an async script</caption>
-     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     *     // do stuff
      *
-     *  actor.attemptsTo(
-     *      ExecuteScript.async(`
-     *          var name = arguments[0];
-     *          var age = arguments[1];
-     *          var callback = arguments[arguments.length - 1];
+     *     callback(result)
+     *   `)
+     * )
+     * ```
      *
-     *          // do stuff
+     * #### Passing arguments to an async script
      *
-     *          callback(result)
-     *      `).withArguments('Bob', 24)
-     *  );
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
      *
-     * @example <caption>Passing Target arguments to an async script</caption>
-     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(`
+     *     var name = arguments[0];
+     *     var age = arguments[1];
+     *     var callback = arguments[arguments.length - 1]
      *
-     *  actor.attemptsTo(
-     *      ExecuteScript.async(`
-     *          var header = arguments[0];    // Target gets converted to a WebElement
-     *          var callback = arguments[arguments.length - 1];
+     *     // do stuff
      *
-     *          callback(header.innerText)
-     *      `).withArguments(Target.the('header').located(by.css('h1')))
-     *  );
+     *     callback(result)
+     *   `).withArguments('Bob', 24)
+     * )
+     * ```
      *
-     * @example <caption>Executing async script as function</caption>
-     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     * #### Passing Target arguments to an async script
      *
-     *  actor.attemptsTo(
-     *      ExecuteScript.async(function getText(header, callback) {
-     *          callback(header.innerText)
-     *      }).withArguments(Target.the('header').located(by.css('h1')))
-     *  );
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
      *
-     * @param {string | Function} script
-     *  The script to be executed
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(`
+     *     var header = arguments[0]        // PageElement object gets converted to a WebElement
+     *     var callback = arguments[arguments.length - 1]
+     *
+     *     callback(header.innerText)
+     *   `).withArguments(PageElement.located(By.css('h1')).describedAs('header'))
+     * )
+     * ```
      *
-     * @returns {ExecuteScriptWithArguments}
+     * #### Executing async script as function
      *
-     * @see {@link LastScriptExecution.result}
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
+     *
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(function getText(header, callback) {
+     *     callback(header.innerText)
+     *   }).withArguments(PageElement.located(By.css('h1')).describedAs('header'))
+     * )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink LastScriptExecution.result}
+     *
+     * @param script
+     *  The script to be executed
      */
     static async(script: string | Function): ExecuteScriptWithArguments;
     /**
-     * @desc
-     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
-     *  execute a synchronous script in the context of the currently selected frame or window.
-     *
-     *  If the script returns a value, it will be made available via {@link LastScriptExecution.result}.
-     *
-     * @example <caption>Executing a sync script as string and reading the result</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { BrowseTheWeb, ExecuteScript, LastScriptExecution } from '@serenity-js/webdriverio';
-     *  import { Ensure, includes } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Joseph')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          ExecuteScript.sync('return navigator.userAgent'),
-     *          Ensure.that(LastScriptExecution.result<string>(), includes('Chrome')),
-     *      );
-     *
-     * @example <caption>Executing a sync script as function and reading the result</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { by, BrowseTheWeb, Enter, ExecuteScript, LastScriptExecution, Target } from '@serenity-js/webdriverio';
-     *
-     *  const someOfferField      = Target.the('offer code').located(by.id('offer-code'));
-     *  const applyOfferCodeField = Target.the('apply offer field').located(by.id('apply-offer-code'));
-     *
-     *  actorCalled('Joseph')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          // inject JavaScript to read some property of an element
-     *          ExecuteScript.sync(function getValue(element) {
-     *              return element.value;
-     *          }).withArguments(someOfferField),
-     *
-     *          // use LastScriptExecution.result() to read the value
-     *          // returned from the injected script
-     *          // and pass it to another interaction
-     *          Enter.theValue(LastScriptExecution.result<string>()).into(applyOfferCodeField),
-     *      );
-     *
-     * @param {string | Function} script
-     *  The script to be executed
+     * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+     * to execute a synchronous script within the context of the current browser tab.
+     *
+     * If the script returns a value, it will be made available via {@apilink LastScriptExecution.result}.
+     *
+     * #### Executing a sync script as string and reading the result
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript, LastScriptExecution } from '@serenity-js/web'
+     * import { Ensure, includes } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Joseph')
+     *   .attemptsTo(
+     *     ExecuteScript.sync('return navigator.userAgent'),
+     *     Ensure.that(LastScriptExecution.result<string>(), includes('Chrome')),
+     *   )
+     * ```
+     *
+     * #### Executing a sync script as function and reading the result
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { By, Enter, ExecuteScript, LastScriptExecution, PageElement } from '@serenity-js/web'
+     *
+     * const someOfferField = () =>
+     *   PageElement.located(By.id('offer-code'))
+     *     .describedAs('offer code')
      *
-     * @returns {ExecuteScriptWithArguments}
+     * const applyOfferCodeField = () =>
+     *   PageElement.located(By.id('apply-offer-code'))
+     *     .describedAs('apply offer field')
      *
-     * @see {@link LastScriptExecution.result}
+     * await actorCalled('Joseph')
+     *   .attemptsTo(
+     *     // inject JavaScript to read some property of an element
+     *     ExecuteScript.sync(function getValue(element) {
+     *         return element.value;
+     *     }).withArguments(someOfferField),
+     *
+     *     // use LastScriptExecution.result() to read the value
+     *     // returned from the injected script
+     *     // and pass it to another interaction
+     *     Enter.theValue(LastScriptExecution.result<string>()).into(applyOfferCodeField),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink LastScriptExecution.result}
+     *
+     * @param script
+     *  The script to be executed
      */
     static sync(script: string | Function): ExecuteScriptWithArguments;
 }
 /**
- * @desc
- *  Allows for a script to be executed to be parametrised.
+ * Allows for a script to be executed to be parametrised.
  *
- *  **Please note** that the arguments can be both synchronous and asynchronous {@link @serenity-js/core/lib/screenplay~Question}s
- *  as well as regular static values.
+ * ## Learn more
+ * -  {@apilink ExecuteScript}
  *
- * @abstract
- *
- * @see {@link ExecuteScript}
- *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ * @group Activities
  */
 export declare abstract class ExecuteScriptWithArguments extends Interaction {
     protected readonly script: string | Function;
     protected readonly args: Array<Answerable<any>>;
-    /**
-     * @param {string | Function} script
-     *  The script to be executed
-     *
-     * @param {Array<Answerable<any>>} args
-     *  Arguments to parametrise the script with
-     */
-    constructor(script: string | Function, // eslint-disable-line @typescript-eslint/ban-types
+    constructor(description: string, script: string | Function, // eslint-disable-line @typescript-eslint/ban-types
     args?: Array<Answerable<any>>);
     /**
-     * @desc
-     *  Instantiates an {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  to {@link Enter}.
+     * Instantiates this {@apilink Interaction}
      *
-     * @param {...Array<Answerable<any>>} args
+     * @param args
      *  Arguments to parametrise the script with
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
      */
     abstract withArguments(...args: Array<Answerable<any>>): Interaction;
     /**
-     * @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}
+     * @inheritDoc
      */
     performAs(actor: UsesAbilities & CollectsArtifacts & AnswersQuestions): Promise<void>;
     protected abstract executeAs(actor: UsesAbilities & AnswersQuestions, args: any[]): Promise<any>;
 }
+//# sourceMappingURL=ExecuteScript.d.ts.map

package/lib/screenplay/interactions/ExecuteScript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecuteScript.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/ExecuteScript.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAK,WAAW,EAAc,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAM/H;;;;;;;;;;GAUG;AACH,qBAAa,aAAa;IAEtB;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,WAAW;IAIvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgGG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,0BAA0B;IAOnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACH,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,0BAA0B;CAMrE;AAED;;;;;;;GAOG;AACH,8BAAsB,0BAA2B,SAAQ,WAAW;IAI5D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAC5C,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBAF/C,WAAW,EAAE,MAAM,EACA,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAY,mDAAmD;IACxF,IAAI,GAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAM;IAKxD;;;;;OAKG;aACa,aAAa,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW;IAE3E;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3F,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC;CACnG"}