BrowseTheWeb
Implements:
Examples:
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')),
);
See also:
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 |
Changes focus to the active modal dialog,
such as those opened by
|
|
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 |
Interface for managing browser and driver state. |
|
public |
Interface for navigating back and forth in the browser history. |
|
public |
param(path: string): T Returns Protractor configuration parameter at |
|
public |
sleep(millis: number): Promise<void> Pause the actor flow for a specified number of milliseconds. |
|
public |
switchToDefaultContent(): Promise<void> |
|
public |
switchToFrame(elementOrIndexOrName: number | string | WebElement): Promise<void> Switches the focus to a |
|
public |
switchToOriginalWindow(): Promise<void> Switches the window back to the original one that was used to call get. |
|
public |
switchToParentFrame(): Promise<void> |
|
public |
switchToWindow(nameOrHandleOrIndex: string | number): Promise<void> Switches browser window/tab to the one identified by |
|
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 |
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 |
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 |
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.
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:
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:
BrowseTheWeb.as(actor).executeAsyncScript(`
var delay = arguments[0];
var callback = arguments[arguments.length - 1];
window.setTimeout(callback, delay);
`, 500)
BrowseTheWeb.as(actor).executeAsyncScript(`
var callback = arguments[arguments.length - 1];
callback('some return value')
`).then(value => doSomethingWithThe(value))
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:
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:
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.
public getCurrentUrl(): Promise<string> source
Returns the url of the current page.
Returns:
Promise<string> |
public getCurrentWindowHandle(): Promise<string> source
Returns the current window handle. Please note that the current handle changes with each browser window you Switch to.
Returns:
Promise<string> | A window handle |
See:
public getLastScriptExecutionResult(): any source
Returns the last result of calling BrowseTheWeb#executeAsyncScript or BrowseTheWeb#executeScript
Returns:
any |
public getOriginalWindowHandle(): Promise<string> source
Returns the handle of the browser window last used to navigate to a URL.
Returns:
Promise<string> | A window handle |
See:
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:
Name | Type | Attribute | Description |
locator | Locator |
public locateAll(locator: Locator): ElementArrayFinder source
Locates all elements identified by the locator
Params:
Name | Type | Attribute | Description |
locator | Locator |
public navigate(): Navigation source
Interface for navigating back and forth in the browser history.
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:
T |
Throws:
Throws a |
Examples:
exports.config = {
params: {
login: {
username: 'jane@example.org'
password: process.env.PASSWORD
}
}
// ...
}
BrowseTheWeb.as(actor).param('login') // returns object with username and password
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 |
Returns:
Promise<void> |
public switchToFrame(elementOrIndexOrName: number | string | WebElement): Promise<void> source
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.
Params:
Name | Type | Attribute | Description |
elementOrIndexOrName | number | string | WebElement |
Returns:
Promise<void> |
public switchToOriginalWindow(): Promise<void> source
Switches the window back to the original one that was used to call get.
Returns:
Promise<void> |
public switchToWindow(nameOrHandleOrIndex: string | number): Promise<void> source
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.
Params:
Name | Type | Attribute | Description |
nameOrHandleOrIndex | string | number |
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:
- 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> |