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

BrowseTheWeb

An Ability that enables the Actor to interact with web front-ends using protractor.

Implements:

Examples:

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

const actor = Actor.named('Wendy').whoCan(
    BrowseTheWeb.using(protractor.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(browser: ProtractorBrowser): BrowseTheWeb

Ability to interact with web front-ends using a given protractor browser instance.

Constructor Summary

Public Constructor
public

constructor(browser: ProtractorBrowser)

Method Summary

Public Methods
public

actions(): external:selenium-webdriver.ActionSequence

Interface for defining sequences of complex user interactions.

public

enableAngularSynchronisation(enable: boolean): Promise<boolean>

If set to false, Protractor will not wait for Angular $http and $timeout tasks to complete before interacting with the browser.

public

executeAsyncScript(script: string | Function, args: any[]): *

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

public

executeScript(description: string, script: string | Function, args: any[]): *

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

public

get(destination: string, timeoutInMillis: number?): Promise<void>

Navigate to the given destination and loads mock modules before Angular.

public

getCapabilities(): Promise<Capabilities>

Returns the capabilities of the browser used in the current session.

public

getCurrentUrl(): Promise<string>

Returns the url of the current page.

public
public

getTitle(): Promise<string>

Returns the title of the current page.

public

locate(locator: Locator): ElementFinder

Locates a single element identified by the locator

public

locateAll(locator: Locator): ElementArrayFinder

Locates all elements identified by the locator

public

manage(): external:selenium-webdriver.Options

Interface for managing browser and driver state.

public

navigate(): Navigation

Interface for navigating back and forth in the browser history.

public

sleep(millis: *): Promise<void>

Pause the actor flow for a specified number of milliseconds.

public

takeScreenshot(): Promise<string>

Schedule a command to take a screenshot.

public

wait(condition: *, timeout: *): Promise<boolean>

Pause the actor flow until the condition is met or the timeout expires.

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(browser: ProtractorBrowser): BrowseTheWeb source

Ability to interact with web front-ends using a given protractor browser instance.

Params:

NameTypeAttributeDescription
browser ProtractorBrowser

Returns:

BrowseTheWeb

Public Constructors

public constructor(browser: ProtractorBrowser) source

Params:

NameTypeAttributeDescription
browser ProtractorBrowser

An instance of a protractor browser

Public Methods

public actions(): external:selenium-webdriver.ActionSequence source

Interface for defining sequences of complex user interactions. Each sequence will not be executed until perform is called.

Returns:

external:selenium-webdriver.ActionSequence

public enableAngularSynchronisation(enable: boolean): Promise<boolean> source

If set to false, Protractor will not wait for Angular $http and $timeout tasks to complete before interacting with the browser.

This can be useful when:

  • you need to switch to a non-Angular app during your tests (i.e. SSO login gateway)
  • your app continuously polls an API with $timeout

If you're not testing an Angular app, it's better to disable Angular synchronisation completely in protractor configuration:

Params:

NameTypeAttributeDescription
enable boolean

Returns:

Promise<boolean>

Examples:

protractor.conf.js
exports.config = {
    onPrepare: function () {
        return browser.waitForAngularEnabled(false);
    },

    // ... other config
};

public executeAsyncScript(script: string | Function, args: 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:

*

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(description: string, script: string | Function, args: 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
description string

useful for debugging

script string | Function
args any[]

Returns:

*

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, timeoutInMillis: number?): Promise<void> source

Navigate to the given destination and loads mock modules before Angular. Assumes that the page being loaded uses Angular.

Params:

NameTypeAttributeDescription
destination string
timeoutInMillis number?

Returns:

Promise<void>

public getCapabilities(): Promise<Capabilities> source

Returns the capabilities of the browser used in the current session.

By default, the session capabilities specified in the protractor.conf.js indicate the desired properties of the remote browser. However, if the remote cannot satisfy all the requirements, it will still create a session.

Returns:

Promise<Capabilities>

The actual capabilities of this browser.

public getCurrentUrl(): Promise<string> source

Returns the url of the current page.

Returns:

Promise<string>

public getLastScriptExecutionResult(): any source

Returns:

any

public getTitle(): Promise<string> source

Returns the title of the current page.

Returns:

Promise<string>

public locate(locator: Locator): ElementFinder source

Locates a single element identified by the locator

Params:

NameTypeAttributeDescription
locator Locator

Returns:

ElementFinder

public locateAll(locator: Locator): ElementArrayFinder source

Locates all elements identified by the locator

Params:

NameTypeAttributeDescription
locator Locator

Returns:

ElementArrayFinder

public manage(): external:selenium-webdriver.Options source

Interface for managing browser and driver state.

Returns:

external:selenium-webdriver.Options

public navigate(): Navigation source

Interface for navigating back and forth in the browser history.

Returns:

Navigation

public sleep(millis: *): Promise<void> source

Pause the actor flow for a specified number of milliseconds.

Params:

NameTypeAttributeDescription
millis *

Returns:

Promise<void>

public takeScreenshot(): Promise<string> source

Schedule a command to take a screenshot. The driver makes a best effort to return a base64-encoded screenshot of the following, in order of preference:

  1. Entire page
  2. Current window
  3. Visible portion of the current frame
  4. The entire display containing the browser

Returns:

Promise<string>

A promise that will be resolved to a base64-encoded screenshot PNG

public wait(condition: *, timeout: *): Promise<boolean> source

Pause the actor flow until the condition is met or the timeout expires.

Params:

NameTypeAttributeDescription
condition *
timeout *

Returns:

Promise<boolean>