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:

Ability

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	as(actor: UsesAbilities): BrowseTheWeb 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(): ActionSequence Interface for defining sequences of complex user interactions.
public	alert(): AlertPromise Changes focus to the active modal dialog, such as those opened by `Window.alert()`, `Window.prompt()`, or `Window.confirm()`.
public	closeCurrentWindow(): Promise<void> Closes the currently active browser window/tab.
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[]): Promise<any> Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window.
public	executeFunction(fn: Function, args: Parameters<fn>): Promise<ReturnType<fn>> A simplified version of BrowseTheWeb#executeScript that doesn't affect {@link LastScriptExecution.result()}.
public	executeScript(description: string, 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, timeoutInMillis: number?): Promise<void> Navigate to the given destination and loads mock modules before Angular.
public	getAllWindowHandles(): Promise<string[]> Returns the handles of all the available windows.
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	getCurrentWindowHandle(): Promise<string> Returns the current window handle.
public	getLastScriptExecutionResult(): any Returns the last result of calling BrowseTheWeb#executeAsyncScript or BrowseTheWeb#executeScript
public	getOriginalWindowHandle(): Promise<string> Returns the handle of the browser window last used to navigate to a URL.
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(): Options Interface for managing browser and driver state.
public	navigate(): Navigation Interface for navigating back and forth in the browser history.
public	param(path: string): T Returns Protractor configuration parameter at `path`.
public	sleep(millis: number): Promise<void> Pause the actor flow for a specified number of milliseconds.
public	switchToDefaultContent(): Promise<void> Switches the focus from any `frame` or `iframe` back to default content, a.k.a.
public	switchToFrame(elementOrIndexOrName: number \| string \| WebElement): Promise<void> Switches the focus to a `frame` or `iframe` identified by `elementOrIndexOrName`, which can be specified either as WebElement, the name of the frame, or its index.
public	switchToOriginalWindow(): Promise<void> Switches the window back to the original one that was used to call get.
public	switchToParentFrame(): Promise<void> Switches the focus from any `frame` or `iframe` back to its parent iframe.
public	switchToWindow(nameOrHandleOrIndex: string \| number): Promise<void> Switches browser window/tab to the one identified by `nameOrHandleOrIndex`, which can be specified as the name of the window to switch to, its handle, or numeric index.
public	takeScreenshot(): Promise<string> Schedule a command to take a screenshot.
public	wait(condition: function(): Promise<boolean>, timeoutInMillis: number): 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:

Name	Type	Attribute	Description
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:

Name	Type	Attribute	Description
browser	ProtractorBrowser

Returns:

BrowseTheWeb

Public Constructors

public constructor(browser: ProtractorBrowser) source

Params:

Name	Type	Attribute	Description
browser	ProtractorBrowser		An instance of a protractor browser

Public Methods

public actions(): ActionSequence source

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

Returns:

ActionSequence

See:

https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/actions.html

public alert(): AlertPromise source

Changes focus to the active modal dialog, such as those opened by Window.alert(), Window.prompt(), or Window.confirm().

The returned promise will be rejected with an error.NoSuchAlertError if there are no open alerts.

Returns:

AlertPromise

See:

https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/webdriver_exports_TargetLocator.html#alert

public closeCurrentWindow(): Promise<void> source

Closes the currently active browser window/tab.

Returns:

Promise<void>

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:

Name	Type	Attribute	Description
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[]): 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:

Name	Type	Attribute	Description
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))

See:

public executeFunction(fn: Function, args: Parameters<fn>): Promise<ReturnType<fn>> source

A simplified version of BrowseTheWeb#executeScript that doesn't affect {@link LastScriptExecution.result()}.

Params:

Name	Type	Attribute	Description
fn	Function
args	Parameters<fn>

Returns:

Promise<ReturnType<fn>>

public executeScript(description: string, 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:

Name	Type	Attribute	Description
description	string		useful for debugging
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))

See:

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:

Name	Type	Attribute	Description
destination	string
timeoutInMillis	number?

Returns:

Promise<void>

public getAllWindowHandles(): Promise<string[]> source

Returns the handles of all the available windows.

Please note that while some browsers organise entries of this list in the same order new windows have been spawned, other browsers order it alphabetically. For this reason, you should not make any assumptions about how this list is ordered.

Returns:

Promise<string[]>

A list of window handles

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

Promise<string>

A window handle

See:

public getTitle(): Promise<string> source

Returns the title of the current page.

Returns:

Promise<string>

See:

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title

public locate(locator: Locator): ElementFinder source

Locates a single element identified by the locator

Params:

Name	Type	Attribute	Description
locator	Locator

Returns:

ElementFinder

public locateAll(locator: Locator): ElementArrayFinder source

Locates all elements identified by the locator

Params:

Name	Type	Attribute	Description
locator	Locator

Returns:

ElementArrayFinder

public manage(): Options source

Interface for managing browser and driver state.

Returns:

Options

See:

https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/webdriver_exports_WebDriver.html#manage

public navigate(): Navigation source

Interface for navigating back and forth in the browser history.

Returns:

Navigation

public param(path: string): T source

Returns Protractor configuration parameter at path.

Params:

Name	Type	Attribute	Description
path	string		Either a name or a dot-delimited path to the param.

Returns:

Throws:

ConfigurationError

Throws a ConfigurationError if the parameter is undefined

Examples:

protractor.conf.js

 exports.config = {
   params: {
       login: {
           username: 'jane@example.org'
           password: process.env.PASSWORD
       }
   }
   // ...
}

Retrieving config param by name

 BrowseTheWeb.as(actor).param('login') // returns object with username and password

Retrieving config param by path

 BrowseTheWeb.as(actor).param('login.username') // returns string 'jane@example.org'

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

Pause the actor flow for a specified number of milliseconds.

Params:

Name	Type	Attribute	Description
millis	number

Entire page
Current window
Visible portion of the current frame
The entire display containing the browser

Returns:

Promise<string>

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

public wait(condition: function(): Promise<boolean>, timeoutInMillis: number): Promise<boolean> source

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

Params:

Name	Type	Attribute	Description
condition	function(): Promise<boolean>
timeoutInMillis	number

Returns:

Promise<boolean>

BrowseTheWeb

Implements:

Examples:

See also:

Static Method Summary

Constructor Summary

Method Summary

Static Public Methods

public static as(actor: UsesAbilities): BrowseTheWeb source

Params:

Returns:

public static using(browser: ProtractorBrowser): BrowseTheWeb source

Params:

Returns:

Public Constructors

public constructor(browser: ProtractorBrowser) source

Params:

Public Methods

public actions(): ActionSequence source

Returns:

See:

public alert(): AlertPromise source

Returns:

See:

public closeCurrentWindow(): Promise<void> source

Returns:

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

Params:

Returns:

Examples:

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

Params:

Returns:

Examples:

See:

public executeFunction(fn: Function, args: Parameters<fn>): Promise<ReturnType<fn>> source

Params:

Returns:

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

Params:

Returns:

Examples:

See:

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

Params:

Returns:

public getAllWindowHandles(): Promise<string[]> source

Returns:

public getCapabilities(): Promise<Capabilities> source

Returns:

public getCurrentUrl(): Promise<string> source

Returns:

public getCurrentWindowHandle(): Promise<string> source

Returns:

See:

public getLastScriptExecutionResult(): any source

Returns:

public getOriginalWindowHandle(): Promise<string> source

Returns:

See:

public getTitle(): Promise<string> source

Returns:

See:

public locate(locator: Locator): ElementFinder source

Params:

Returns:

public locateAll(locator: Locator): ElementArrayFinder source

Params:

Returns:

public manage(): Options source

Returns:

See:

public navigate(): Navigation source

Returns:

public param(path: string): T source

Params:

Returns:

Throws:

Examples:

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