Skip to main content

ExecuteScript

Instructs an actor who has the ability to BrowseTheWeb to execute a script within the context of the current browser tab.

Learn more

Index

Constructors

Methods

Constructors

constructor

Methods

staticfrom

  • from(sourceUrl: Answerable<string>): Interaction

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

    Parameters

    • sourceUrl: Answerable<string>

      The URL to load the script from

    Returns Interaction

staticasync

  • Instructs an actor who has the ability to BrowseTheWeb to execute an asynchronous script within the context of the current browser tab.

    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 PageElement. 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.

    Executing an async script

    import { actorCalled } from '@serenity-js/core'
    import { ExecuteScript } from '@serenity-js/web'

    await actorCalled('Esti').attemptsTo(
      ExecuteScript.async(`
        var callback = arguments[arguments.length - 1]

        // do stuff

        callback(result)
      `)
    )

    Passing arguments to an async script

    import { actorCalled } from '@serenity-js/core'
    import { ExecuteScript } from '@serenity-js/web'

    await actorCalled('Esti').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 { actorCalled } from '@serenity-js/core'
    import { ExecuteScript } from '@serenity-js/web'

    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'))
    )

    Executing async script as function

    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

    Parameters

    • script: string | Function

      The script to be executed

    Returns ExecuteScriptWithArguments

staticsync

  • Instructs an actor who has the ability to 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 LastScriptExecution.result.

    Executing a sync script as string and reading the result

    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

    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')

    const applyOfferCodeField = () =>
      PageElement.located(By.id('apply-offer-code'))
        .describedAs('apply offer field')

    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

    Parameters

    • script: string | Function

      The script to be executed

    Returns ExecuteScriptWithArguments