import {ExecuteScript} from '@serenity-js/webdriverio/lib/screenplay/interactions'
public class | source

ExecuteScript

Instructs the Actor to execute a script within the context of the current browser window.

Please see the tests below for usage examples.

Static Method Summary

Static Public Methods
public static

async(script: string | Function): ExecuteScriptWithArguments

Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window.

public static

from(sourceUrl: string): Interaction

Instantiates a version of this Interaction configured to load a script from sourceUrl.

public static

sync(script: string | Function): ExecuteScriptWithArguments

Instructs the Actor to execute a synchronous script in the context of the currently selected frame or window.

Static Public Methods

public static async(script: string | Function): ExecuteScriptWithArguments source

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 Target (Answerable<Element<'async'>>). 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 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 LastScriptExecution.result.

Please note that in order to signal an error in the script you need to throw an Error instead of passing it to the callback function.

Params:

NameTypeAttributeDescription
script string | Function

The script to be executed

Examples:

Executing an async script
 import { ExecuteScript } from '@serenity-js/webdriverio';

 actor.attemptsTo(
     ExecuteScript.async(`
         var callback = arguments[arguments.length - 1];

         // do stuff

         callback(result)
     `)
 );
Passing arguments to an async script
 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)
 );
Passing Target arguments to an async script
 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')))
 );
Executing async script as function
 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')))
 );

public static from(sourceUrl: string): Interaction source

Instantiates a version of this Interaction configured to load a script from sourceUrl.

Params:

NameTypeAttributeDescription
sourceUrl string

The URL to load the script from

Returns:

Interaction

public static sync(script: string | Function): ExecuteScriptWithArguments source

Instructs the 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 LastScriptExecution.result.

Params:

NameTypeAttributeDescription
script string | Function

The script to be executed

Examples:

Executing a sync script as string and reading the result
 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')),
     );
Executing a sync script as function and reading the result
 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),
     );