@serenity-js/web 3.0.0-rc.0

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

@@ -0,0 +1,206 @@
+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.
+ *
+ *  Please see the tests below for usage examples.
+ *
+ * @see {@link LastScriptExecution.result}
+ */
+export declare class ExecuteScript {
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to load a script from `sourceUrl`.
+     *
+     * @param {string} sourceUrl
+     *  The URL to load the script from
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static from(sourceUrl: 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.
+     *
+     *  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.
+     *
+     *  Unlike executing synchronous JavaScript with {@link ExecuteScript#sync},
+     *  scripts executed with this function must explicitly signal they are finished by invoking the provided callback.
+     *
+     *  This callback will always be injected into the executed function as the last argument,
+     *  and thus may be referenced with `arguments[arguments.length - 1]`.
+     *
+     *  If the script invokes the `callback` with a return value, this will be made available
+     *  via the {@link LastScriptExecution.result}.
+     *
+     *  **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.
+     *
+     * @example <caption>Executing an async script</caption>
+     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     *
+     *  actor.attemptsTo(
+     *      ExecuteScript.async(`
+     *          var callback = arguments[arguments.length - 1];
+     *
+     *          // do stuff
+     *
+     *          callback(result)
+     *      `)
+     *  );
+     *
+     * @example <caption>Passing arguments to an async script</caption>
+     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     *
+     *  actor.attemptsTo(
+     *      ExecuteScript.async(`
+     *          var name = arguments[0];
+     *          var age = arguments[1];
+     *          var callback = arguments[arguments.length - 1];
+     *
+     *          // do stuff
+     *
+     *          callback(result)
+     *      `).withArguments('Bob', 24)
+     *  );
+     *
+     * @example <caption>Passing Target arguments to an async script</caption>
+     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     *
+     *  actor.attemptsTo(
+     *      ExecuteScript.async(`
+     *          var header = arguments[0];    // Target gets converted to a WebElement
+     *          var callback = arguments[arguments.length - 1];
+     *
+     *          callback(header.innerText)
+     *      `).withArguments(Target.the('header').located(by.css('h1')))
+     *  );
+     *
+     * @example <caption>Executing async script as function</caption>
+     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     *
+     *  actor.attemptsTo(
+     *      ExecuteScript.async(function getText(header, callback) {
+     *          callback(header.innerText)
+     *      }).withArguments(Target.the('header').located(by.css('h1')))
+     *  );
+     *
+     * @param {string | Function} script
+     *  The script to be executed
+     *
+     * @returns {ExecuteScriptWithArguments}
+     *
+     * @see {@link LastScriptExecution.result}
+     */
+    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
+     *
+     * @returns {ExecuteScriptWithArguments}
+     *
+     * @see {@link LastScriptExecution.result}
+     */
+    static sync(script: string | Function): ExecuteScriptWithArguments;
+}
+/**
+ * @desc
+ *  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.
+ *
+ * @abstract
+ *
+ * @see {@link ExecuteScript}
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ */
+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
+    args?: Array<Answerable<any>>);
+    /**
+     * @desc
+     *  Instantiates an {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  to {@link Enter}.
+     *
+     * @param {...Array<Answerable<any>>} 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}
+     */
+    performAs(actor: UsesAbilities & CollectsArtifacts & AnswersQuestions): PromiseLike<void>;
+    protected abstract executeAs(actor: UsesAbilities & AnswersQuestions, args: any[]): Promise<any>;
+}

package/lib/screenplay/interactions/ExecuteScript.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecuteScriptWithArguments = exports.ExecuteScript = 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
+ *  execute a script within the context of the current browser window.
+ *
+ *  Please see the tests below for usage examples.
+ *
+ * @see {@link LastScriptExecution.result}
+ */
+class ExecuteScript {
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to load a script from `sourceUrl`.
+     *
+     * @param {string} sourceUrl
+     *  The URL to load the script from
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static from(sourceUrl) {
+        return new ExecuteScriptFromUrl(sourceUrl);
+    }
+    /**
+     * @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.
+     *
+     *  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.
+     *
+     *  Unlike executing synchronous JavaScript with {@link ExecuteScript#sync},
+     *  scripts executed with this function must explicitly signal they are finished by invoking the provided callback.
+     *
+     *  This callback will always be injected into the executed function as the last argument,
+     *  and thus may be referenced with `arguments[arguments.length - 1]`.
+     *
+     *  If the script invokes the `callback` with a return value, this will be made available
+     *  via the {@link LastScriptExecution.result}.
+     *
+     *  **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.
+     *
+     * @example <caption>Executing an async script</caption>
+     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     *
+     *  actor.attemptsTo(
+     *      ExecuteScript.async(`
+     *          var callback = arguments[arguments.length - 1];
+     *
+     *          // do stuff
+     *
+     *          callback(result)
+     *      `)
+     *  );
+     *
+     * @example <caption>Passing arguments to an async script</caption>
+     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     *
+     *  actor.attemptsTo(
+     *      ExecuteScript.async(`
+     *          var name = arguments[0];
+     *          var age = arguments[1];
+     *          var callback = arguments[arguments.length - 1];
+     *
+     *          // do stuff
+     *
+     *          callback(result)
+     *      `).withArguments('Bob', 24)
+     *  );
+     *
+     * @example <caption>Passing Target arguments to an async script</caption>
+     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     *
+     *  actor.attemptsTo(
+     *      ExecuteScript.async(`
+     *          var header = arguments[0];    // Target gets converted to a WebElement
+     *          var callback = arguments[arguments.length - 1];
+     *
+     *          callback(header.innerText)
+     *      `).withArguments(Target.the('header').located(by.css('h1')))
+     *  );
+     *
+     * @example <caption>Executing async script as function</caption>
+     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     *
+     *  actor.attemptsTo(
+     *      ExecuteScript.async(function getText(header, callback) {
+     *          callback(header.innerText)
+     *      }).withArguments(Target.the('header').located(by.css('h1')))
+     *  );
+     *
+     * @param {string | Function} script
+     *  The script to be executed
+     *
+     * @returns {ExecuteScriptWithArguments}
+     *
+     * @see {@link LastScriptExecution.result}
+     */
+    static async(script) {
+        return new ExecuteAsynchronousScript(script);
+    }
+    /**
+     * @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
+     *
+     * @returns {ExecuteScriptWithArguments}
+     *
+     * @see {@link LastScriptExecution.result}
+     */
+    static sync(script) {
+        return new ExecuteSynchronousScript(script);
+    }
+}
+exports.ExecuteScript = ExecuteScript;
+/**
+ * @desc
+ *  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.
+ *
+ * @abstract
+ *
+ * @see {@link ExecuteScript}
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ */
+class ExecuteScriptWithArguments extends core_1.Interaction {
+    /**
+     * @param {string | Function} script
+     *  The script to be executed
+     *
+     * @param {Array<Answerable<any>>} args
+     *  Arguments to parametrise the script with
+     */
+    constructor(script, // eslint-disable-line @typescript-eslint/ban-types
+    args = []) {
+        super();
+        this.script = script;
+        this.args = args;
+    }
+    /**
+     * @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) {
+        // todo: interaction should store the result on the ability; the ability should not have a side-effect (?)
+        return Promise.all(this.args.map(arg => actor.answer(arg)))
+            .then(args => this.executeAs(actor, args))
+            .then(() => actor.collect(model_1.TextData.fromJSON({
+            contentType: 'text/javascript;charset=UTF-8',
+            data: this.script.toString(),
+        }), new model_1.Name('Script source')));
+    }
+}
+exports.ExecuteScriptWithArguments = ExecuteScriptWithArguments;
+/**
+ * @package
+ */
+class ExecuteAsynchronousScript extends ExecuteScriptWithArguments {
+    withArguments(...args) {
+        return new ExecuteAsynchronousScript(this.script, args);
+    }
+    executeAs(actor, args) {
+        return abilities_1.BrowseTheWeb.as(actor).executeAsyncScript(this.script, ...args); // todo: fix types
+    }
+    toString() {
+        return this.args.length > 0
+            ? (0, io_1.formatted) `#actor executes an asynchronous script with arguments: ${this.args}`
+            : `#actor executes an asynchronous script`;
+    }
+}
+/**
+ * @package
+ *
+ * https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/JavascriptExecutor.html
+ * https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement
+ */
+class ExecuteScriptFromUrl extends core_1.Interaction {
+    constructor(sourceUrl) {
+        super();
+        this.sourceUrl = sourceUrl;
+    }
+    /**
+     * @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
+     * @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}
+     */
+    performAs(actor) {
+        return abilities_1.BrowseTheWeb.as(actor)
+            .executeAsyncScript(
+        /* istanbul ignore next */
+        function executeScriptFromUrl(sourceUrl, callback) {
+            const alreadyLoadedScripts = Array.prototype.slice
+                .call(document.querySelectorAll('script'))
+                .map(script => script.src);
+            if (~alreadyLoadedScripts.indexOf(sourceUrl)) {
+                return callback('Script from ' + sourceUrl + ' has already been loaded');
+            }
+            const script = document.createElement('script');
+            script.addEventListener('load', function () {
+                callback();
+            });
+            script.addEventListener('error', function () {
+                return callback('Couldn\'t load script from ' + sourceUrl);
+            });
+            script.src = sourceUrl;
+            script.async = true;
+            document.head.append(script);
+        }, this.sourceUrl)
+            .then(errorMessage => {
+            if (errorMessage) {
+                throw new core_1.LogicError(errorMessage);
+            }
+        });
+    }
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString() {
+        return `#actor executes a script from ${this.sourceUrl}`;
+    }
+}
+/**
+ * @package
+ */
+class ExecuteSynchronousScript extends ExecuteScriptWithArguments {
+    withArguments(...args) {
+        return new ExecuteSynchronousScript(this.script, args);
+    }
+    executeAs(actor, args) {
+        return abilities_1.BrowseTheWeb.as(actor).executeScript(this.script, ...args); // todo fix type
+    }
+    toString() {
+        return this.args.length > 0
+            ? (0, io_1.formatted) `#actor executes a synchronous script with arguments: ${this.args}`
+            : `#actor executes a synchronous script`;
+    }
+}
+//# sourceMappingURL=ExecuteScript.js.map

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

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

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

@@ -0,0 +1,78 @@
+import { Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@serenity-js/core';
+import { PageElement } from '../models';
+import { PageElementInteraction } from './PageElementInteraction';
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  hover the mouse pointer over a given Web element.
+ *
+ * @example <caption>Example widget</caption>
+ *  <a data-test="example-link"
+ *      class="off"
+ *      onmouseover="this.className='on';"
+ *      onmouseout="this.className='off';"
+ *      href="/">hover over me</a>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class Example {
+ *      static link = Target.the('example link')
+ *          .located(by.css('[data-test="example-link"]'));
+ *  }
+ *
+ * @example <caption>Hovering over an element</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Hover, CssClasses } from '@serenity-js/webdriverio';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Hank')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(CssClasses.of(Example.link), equals([ 'off' ])),
+ *
+ *          Hover.over(Example.link),
+ *          Ensure.that(CssClasses.of(Example.link), equals([ 'on' ])),
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link CssClasses}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ *
+ * @extends {ElementInteraction}
+ */
+export declare class Hover extends PageElementInteraction {
+    private readonly target;
+    /**
+     * @desc
+     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {Answerable<PageElement>} target
+     *  The element to be hovered over
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static over(target: Answerable<PageElement>): Interaction;
+    /**
+     * @param {Answerable<PageElement>} target
+     *  The element to be hovered over
+     */
+    constructor(target: 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 {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): Promise<void>;
+}