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

BrowseTheWeb

An Ability that enables the Actor to interact with Web apps using WebdriverIO.

Please note: this class is still marked as experimental while new WebdriverIO Interactions and Questions are being developed. This means that its interface can change without affecting the major version of Serenity/JS itself. In particular, please don't rely on the browser field to remain public in future releases.

Implements:

this class is experimental.

Examples:

Using the WebdriverIO browser
 import { Actor } from '@serenity-js/core';
 import { BrowseTheWeb, by, Navigate, Target } from '@serenity-js/webdriverio'
 import { Ensure, equals } from '@serenity-js/assertions';

 const actor = Actor.named('Wendy').whoCan(
     BrowseTheWeb.using(browser),
 );

 const HomePage = {
     Title: Target.the('title').located(by.css('h1')),
 };

 actor.attemptsTo(
     Navigate.to(`https://serenity-js.org`),
     Ensure.that(Text.of(HomePage.Title), equals('Serenity/JS')),
 );

Static Method Summary

Static Public Methods
public static

Used to access the Actor's ability to BrowseTheWeb from within the Interaction classes, such as Navigate.

public static

using(browserInstance: Browser): BrowseTheWeb

Constructor Summary

Public Constructor
public

constructor(browser: Browser)

Method Summary

Public Methods
public

executeAsyncScript(script: string | Function, args: any[]): Promise<any>

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

public

executeScript(script: string | Function, args: any[]): Promise<any>

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

public

get(destination: string): Promise<void>

Navigate to a given destination, specified as an absolute URL or a path relative to WebdriverIO baseUrl.

public

Returns the last result of calling BrowseTheWeb#executeAsyncScript or BrowseTheWeb#executeScript

public

sendKeys(keys: Array<Key|string>): Promise<void>

Send a sequence of Key strokes to the active element.

public

takeScreenshot(): Promise<string>

Take a screenshot of the top-level browsing context's viewport.

Static Public Methods

public static as(actor: UsesAbilities): BrowseTheWeb source

Used to access the Actor's ability to BrowseTheWeb from within the Interaction classes, such as Navigate.

Params:

NameTypeAttributeDescription
actor UsesAbilities

Returns:

BrowseTheWeb

public static using(browserInstance: Browser): BrowseTheWeb source

Params:

NameTypeAttributeDescription
browserInstance Browser

Returns:

BrowseTheWeb

Public Constructors

public constructor(browser: Browser) source

Params:

NameTypeAttributeDescription
browser Browser

Public Methods

public executeAsyncScript(script: string | Function, args: any[]): Promise<any> 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 WebElement 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 BrowseTheWeb#executeScript, 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].

The following steps will be taken for resolving this functions return value against the first argument to the script's callback function:

  • For a HTML element, the value will resolve to a WebElement
  • Null and undefined return values will resolve to null
  • Booleans, numbers, and strings will resolve as is
  • Functions will resolve to their string representation
  • For arrays and objects, each member item will be converted according to the rules above

Params:

NameTypeAttributeDescription
script string | Function
args any[]

Returns:

Promise<any>

Examples:

Perform a sleep in the browser under test
BrowseTheWeb.as(actor).executeAsyncScript(`
  var delay    = arguments[0];
  var callback = arguments[arguments.length - 1];

  window.setTimeout(callback, delay);
`, 500)
Return a value asynchronously
BrowseTheWeb.as(actor).executeAsyncScript(`
  var callback = arguments[arguments.length - 1];

  callback('some return value')
`).then(value => doSomethingWithThe(value))

public executeScript(script: string | Function, args: any[]): Promise<any> source

Schedules a command to execute 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 WebElement. Arrays and objects may also be used as script arguments as long as each item adheres to the types previously mentioned.

The script may refer to any variables accessible from the current window. Furthermore, the script will execute in the window's context, thus document may be used to refer to the current document. Any local variables will not be available once the script has finished executing, though global variables will persist.

If the script has a return value (i.e. if the script contains a return statement), then the following steps will be taken for resolving this functions return value:

For a HTML element, the value will resolve to a WebElement

  • Null and undefined return values will resolve to null
  • Booleans, numbers, and strings will resolve as is
  • Functions will resolve to their string representation
  • For arrays and objects, each member item will be converted according to the rules above

Params:

NameTypeAttributeDescription
script string | Function
args any[]

Returns:

Promise<any>

Examples:

Perform a sleep in the browser under test
BrowseTheWeb.as(actor).executeAsyncScript(`
  return arguments[0].tagName;
`, Target.the('header').located(by.css(h1))

public get(destination: string): Promise<void> source

Navigate to a given destination, specified as an absolute URL or a path relative to WebdriverIO baseUrl.

Params:

NameTypeAttributeDescription
destination string

Returns:

Promise<void>

public getLastScriptExecutionResult(): any source

Returns the last result of calling BrowseTheWeb#executeAsyncScript or BrowseTheWeb#executeScript

Returns:

any

public sendKeys(keys: Array<Key|string>): Promise<void> source

Send a sequence of Key strokes to the active element.

Params:

NameTypeAttributeDescription
keys Array<Key|string>

Keys to enter

Returns:

Promise<void>

public takeScreenshot(): Promise<string> source

Take a screenshot of the top-level browsing context's viewport.

Returns:

Promise<string>

A promise that will resolve to a base64-encoded screenshot PNG