Interface ThenableWebDriver

A thenable wrapper around a webdriver.IWebDriver IWebDriver instance that allows commands to be issued directly instead of having to repeatedly call then:

let driver = new Builder().build();
driver.then(d => d.get(url));  // You can do this...
driver.get(url);               // ...or this

If the driver instance fails to resolve (e.g. the session cannot be created), every issued command will fail.

Hierarchy

WebDriver
Promise<WebDriver>
- ThenableWebDriver

Properties

`Readonly` [toStringTag]

[toStringTag]: string

Methods

actions

actions(options?): Actions
Creates a new action sequence using this driver. The sequence will not be scheduled for execution until actions.ActionSequence#perform is called. Example:
```
driver.actions().
    mouseDown(element1).
    mouseMove(element2).
    mouseUp().
    perform();
```
Parameters
- Optional options: {
      async: boolean;
      bridge: boolean;
  } | {
      async: boolean;
  } | {
      bridge: boolean;
  }
Returns Actions
A new action sequence for this instance.

Inherited from WebDriver.actions

catch

catch<TResult>(onrejected?): Promise<WebDriver | TResult>
Attaches a callback for only the rejection of the Promise.
Type Parameters
- TResult = never
Parameters
- Optional onrejected: null | ((reason) => TResult | PromiseLike<TResult>)
  The callback to execute when the Promise is rejected.
Returns Promise<WebDriver | TResult>
A Promise for the completion of the callback.

Inherited from Promise.catch

close

close(): Promise<void>
Schedules a command to close the current window.

Returns Promise<void>
A promise that will be resolved when this command has completed.

Inherited from WebDriver.close

createCDPConnection

createCDPConnection(target): Promise<any>
Creates a new WebSocket connection.
Parameters
- target: string
Returns Promise<any>
A new CDP instance.

Inherited from WebDriver.createCDPConnection

execute

execute<T>(command, description?): Promise<T>
Schedules a command.Command to be executed by this driver's command.Executor.
Type Parameters
- T
Parameters
- command: Command
  The command to schedule.
- Optional description: string
  A description of the command for debugging.
Returns Promise<T>
A promise that will be resolved with the command result.

Inherited from WebDriver.execute

executeAsyncScript

executeAsyncScript<T>(script, ...var_args): Promise<T>
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 {@code arguments} object. Arguments may be a boolean, number, string, or {@code 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 #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 {@code 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
Example #1: Performing a sleep that is synchronized with the currently selected window:
```
var start = new Date().getTime();
driver.executeAsyncScript(
    'window.setTimeout(arguments[arguments.length - 1], 500);').
    then(function() {
      console.log(
          'Elapsed time: ' + (new Date().getTime() - start) + ' ms');
    });
```
Example #2: Synchronizing a test with an AJAX application:
```
var button = driver.findElement(By.id('compose-button'));
button.click();
driver.executeAsyncScript(
    'var callback = arguments[arguments.length - 1];' +
    'mailClient.getComposeWindowWidget().onload(callback);');
driver.switchTo().frame('composeWidget');
driver.findElement(By.id('to')).sendKeys('dog@example.com');
```
Example #3: Injecting a XMLHttpRequest and waiting for the result. In this example, the inject script is specified with a function literal. When using this format, the function is converted to a string for injection, so it should not reference any symbols not defined in the scope of the page under test.
```
driver.executeAsyncScript(function() {
  var callback = arguments[arguments.length - 1];
  var xhr = new XMLHttpRequest();
  xhr.open('GET', '/resource/data.json', true);
  xhr.onreadystatechange = function() {
    if (xhr.readyState == 4) {
      callback(xhr.responseText);
    }
  }
  xhr.send('');
}).then(function(str) {
  console.log(JSON.parse(str)['food']);
});
```
Type Parameters
- T
Parameters
- script: string | Function
  The script to execute.
- Rest ...var_args: any[]
  The arguments to pass to the script.
Returns Promise<T>
A promise that will resolve to the scripts return value.

Inherited from WebDriver.executeAsyncScript

executeScript

executeScript<T>(script, ...var_args): Promise<T>
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 {@code arguments} object. Arguments may be a boolean, number, string, or {@code 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 {@code 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
Type Parameters
- T
Parameters
- script: string | Function
  The script to execute.
- Rest ...var_args: any[]
  The arguments to pass to the script.
Returns Promise<T>
A promise that will resolve to the scripts return value.

Inherited from WebDriver.executeScript

finally

finally(onfinally?): Promise<WebDriver>
Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.
Parameters
- Optional onfinally: null | (() => void)
  The callback to execute when the Promise is settled (fulfilled or rejected).
Returns Promise<WebDriver>
A Promise for the completion of the callback.

Inherited from Promise.finally

findElement

findElement(locator): WebElementPromise
Schedule a command to find an element on the page. If the element cannot be found, a bot.ErrorCode.NO_SUCH_ELEMENT result will be returned by the driver. Unlike other commands, this error cannot be suppressed. In other words, scheduling a command to find an element doubles as an assert that the element is present on the page. To test whether an element is present on the page, use #findElements.

The search criteria for an element may be defined using one of the factories in the By namespace, or as a short-hand By.Hash object. For example, the following two statements are equivalent:
```
var e1 = driver.findElement(By.id('foo'));
var e2 = driver.findElement({id:'foo'});
```
You may also provide a custom locator function, which takes as input this instance and returns a WebElement, or a promise that will resolve to a WebElement. If the returned promise resolves to an array of WebElements, WebDriver will use the first element. For example, to find the first visible link on a page, you could write:
```
var link = driver.findElement(firstVisibleLink);

function firstVisibleLink(driver) {
  var links = driver.findElements(By.tagName('a'));
  return promise.filter(links, function(link) {
    return link.isDisplayed();
  });
}
```
Parameters
- locator: Locator
  The locator to use.
Returns WebElementPromise
A WebElement that can be used to issue commands against the located element. If the element is not found, the element will be invalidated and all scheduled commands aborted.

Inherited from WebDriver.findElement

findElementInternal_

findElementInternal_(locatorFn, context): Promise<WebElement>
Parameters
- locatorFn: Function
  The locator function to use.
- context: WebDriver | WebElement
  The search context.
Returns Promise<WebElement>
A promise that will resolve to a list of WebElements.

Inherited from WebDriver.findElementInternal_

findElements

findElements(locator): Promise<WebElement[]>
Schedule a command to search for multiple elements on the page.
Parameters
- locator: Locator
  The locator to use.
Returns Promise<WebElement[]>
A promise that will resolve to an array of WebElements.

Inherited from WebDriver.findElements

findElementsInternal_

findElementsInternal_(locatorFn, context): Promise<WebElement[]>
Parameters
- locatorFn: Function
  The locator function to use.
- context: WebDriver | WebElement
  The search context.
Returns Promise<WebElement[]>
A promise that will resolve to an array of WebElements.

Inherited from WebDriver.findElementsInternal_

get

get(url): Promise<void>
Schedules a command to navigate to the given URL.
Parameters
- url: string
  The fully qualified URL to open.
Returns Promise<void>
A promise that will be resolved when the document has finished loading.

Inherited from WebDriver.get

getAllWindowHandles

getAllWindowHandles(): Promise<string[]>
Schedules a command to retrieve the current list of available window handles.

Returns Promise<string[]>
A promise that will be resolved with an array of window handles.

Inherited from WebDriver.getAllWindowHandles

getCapabilities

getCapabilities(): Promise<Capabilities>
Returns Promise<Capabilities>
A promise that will resolve with the this instance's capabilities.

Inherited from WebDriver.getCapabilities

getCurrentUrl

getCurrentUrl(): Promise<string>
Schedules a command to retrieve the URL of the current page.

Returns Promise<string>
A promise that will be resolved with the current URL.

Inherited from WebDriver.getCurrentUrl

getExecutor

getExecutor(): Executor
Returns Executor
Inherited from WebDriver.getExecutor

getPageSource

getPageSource(): Promise<string>
Schedules a command to retrieve the current page's source. The page source returned is a representation of the underlying DOM: do not expect it to be formatted or escaped in the same way as the response sent from the web server.

Returns Promise<string>
A promise that will be resolved with the current page source.

Inherited from WebDriver.getPageSource

getSession

getSession(): Promise<Session>
Returns Promise<Session>
A promise for this client's session.

Inherited from WebDriver.getSession

getTitle

getTitle(): Promise<string>
Schedules a command to retrieve the current page's title.

Returns Promise<string>
A promise that will be resolved with the current page's title.

Inherited from WebDriver.getTitle

getWindowHandle

getWindowHandle(): Promise<string>
Schedules a command to retrieve they current window handle.

Returns Promise<string>
A promise that will be resolved with the current window handle.

Inherited from WebDriver.getWindowHandle

getWsUrl

getWsUrl(debuggerAddress, target, caps): Promise<string>
Retrieves 'webSocketDebuggerUrl' by sending a http request using debugger address
Parameters
- debuggerAddress: string
- target: string
- caps: Capabilities
Returns Promise<string>
Returns parsed webSocketDebuggerUrl obtained from the http request

Inherited from WebDriver.getWsUrl

logMutationEvents

logMutationEvents(connection, callback): Promise<void>
Parameters
- connection: WebSocket
- callback: ((event) => void)
  - - (event): void
    - Parameters
      event: any
      Returns void
Returns Promise<void>
Inherited from WebDriver.logMutationEvents

manage

manage(): Options
Returns Options
The options interface for this instance.

Inherited from WebDriver.manage

navigate

navigate(): Navigation
Returns Navigation
The navigation interface for this instance.

Inherited from WebDriver.navigate

normalize_

normalize_(webElementPromise): Promise<WebElement>
Parameters
- webElementPromise: Function
  The webElement in unresolved state
Returns Promise<WebElement>
First single WebElement from array of resolved promises

Inherited from WebDriver.normalize_

onIntercept

onIntercept(connection, httpResponse, callback): Promise<void>
Handle Network interception requests
Parameters
- connection: WebSocket
  WebSocket connection to the browser
- httpResponse: HttpResponse
  Object representing what we are intercepting as well as what should be returned.
- callback: (() => void)
  callback called when we intercept requests.
  - - (): void
    - Returns void
Returns Promise<void>
Inherited from WebDriver.onIntercept

onLogEvent

onLogEvent(connection, callback): Promise<void>
Parameters
- connection: WebSocket
- callback: ((event) => void)
  - - (event): void
    - Parameters
      event: any
      Returns void
Returns Promise<void>
Inherited from WebDriver.onLogEvent

onLogException

onLogException(connection, callback): Promise<void>
Parameters
- connection: WebSocket
- callback: ((event) => void)
  - - (event): void
    - Parameters
      event: any
      Returns void
Returns Promise<void>
Inherited from WebDriver.onLogException

quit

quit(): Promise<void>
Schedules a command to quit the current session. After calling quit, this instance will be invalidated and may no longer be used to issue commands against the browser.

Returns Promise<void>
A promise that will be resolved when the command has completed.

Inherited from WebDriver.quit

register

register(username, password, connection): Promise<void>
Sets a listener for Fetch.authRequired event from CDP If event is triggered, it enter username and password and allows the test to move forward
Parameters
- username: string
- password: string
- connection: any
  CDP Connection
Returns Promise<void>
Inherited from WebDriver.register

setFileDetector

setFileDetector(detector): void
Sets the input.FileDetector file detector that should be used with this instance.
Parameters
- detector: FileDetector
  The detector to use or {@code null}.
Returns void
Inherited from WebDriver.setFileDetector

sleep

sleep(ms): Promise<void>
Schedules a command to make the driver sleep for the given amount of time.
Parameters
- ms: number
  The amount of time, in milliseconds, to sleep.
Returns Promise<void>
A promise that will be resolved when the sleep has finished.

Inherited from WebDriver.sleep

switchTo

switchTo(): TargetLocator
Returns TargetLocator
The target locator interface for this instance.

Inherited from WebDriver.switchTo

takeScreenshot

takeScreenshot(): Promise<string>
Schedule a command to take a screenshot. The driver makes a best effort to return a 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 the screenshot as a base-64 encoded PNG.

Inherited from WebDriver.takeScreenshot

then

then<TResult1, TResult2>(onfulfilled?, onrejected?): Promise<TResult1 | TResult2>
Attaches callbacks for the resolution and/or rejection of the Promise.
Type Parameters
- TResult1 = WebDriver
- TResult2 = never
Parameters
- Optional onfulfilled: null | ((value) => TResult1 | PromiseLike<TResult1>)
  The callback to execute when the Promise is resolved.
- Optional onrejected: null | ((reason) => TResult2 | PromiseLike<TResult2>)
  The callback to execute when the Promise is rejected.
Returns Promise<TResult1 | TResult2>
A Promise for the completion of which ever callback is executed.

Inherited from Promise.then

wait

wait(condition, opt_timeout?, opt_message?, opt_pollTimeout?): WebElementPromise
Schedules a command to wait for a condition to hold. The condition may be specified by a Condition, as a custom function, or as a Promise.

For a Condition or function, the wait will repeatedly evaluate the condition until it returns a truthy value. If any errors occur while evaluating the condition, they will be allowed to propagate. In the event a condition returns a Promise promise, the polling loop will wait for it to be resolved and use the resolved value for whether the condition has been satisified. Note the resolution time for a promise is factored into whether a wait has timed out.

Note, if the provided condition is a WebElementCondition, then the wait will return a WebElementPromise that will resolve to the element that satisified the condition.

Example: waiting up to 10 seconds for an element to be present and visible on the page.
```
var button = driver.wait(until.elementLocated(By.id('foo'), 10000);
button.click();
```
This function may also be used to block the command flow on the resolution of a Promise promise. When given a promise, the command will simply wait for its resolution before completing. A timeout may be provided to fail the command if the promise does not resolve before the timeout expires.

Example: Suppose you have a function, startTestServer, that returns a promise for when a server is ready for requests. You can block a WebDriver client on this promise with:
```
var started = startTestServer();
driver.wait(started, 5 * 1000, 'Server should start within 5 seconds');
driver.get(getServerUrl());
```
Parameters
- condition: WebElementCondition
  The condition to wait on, defined as a promise, condition object, or a function to evaluate as a condition.
- Optional opt_timeout: number
  How long to wait for the condition to be true.
- Optional opt_message: string
  An optional message to use if the wait times out.
- Optional opt_pollTimeout: number
  Duration in milliseconds to wait between polling the condition.
Returns WebElementPromise
A promise that will be fulfilled with the first truthy value returned by the condition function, or rejected if the condition times out.

Inherited from WebDriver.wait
wait<T>(condition, opt_timeout?, opt_message?, opt_pollTimeout?): Promise<T>
Schedules a command to wait for a condition to hold. The condition may be specified by a webdriver.Condition, as a custom function, or as a Promise.

For a webdriver.Condition or function, the wait will repeatedly evaluate the condition until it returns a truthy value. If any errors occur while evaluating the condition, they will be allowed to propagate. In the event a condition returns a Promise promise, the polling loop will wait for it to be resolved and use the resolved value for whether the condition has been satisified. Note the resolution time for a promise is factored into whether a wait has timed out.

Note, if the provided condition is a WebElementCondition, then the wait will return a WebElementPromise that will resolve to the element that satisified the condition.

Example: waiting up to 10 seconds for an element to be present and visible on the page.
```
var button = driver.wait(until.elementLocated(By.id('foo'), 10000);
button.click();
```
This function may also be used to block the command flow on the resolution of a Promise promise. When given a promise, the command will simply wait for its resolution before completing. A timeout may be provided to fail the command if the promise does not resolve before the timeout expires.

Example: Suppose you have a function, startTestServer, that returns a promise for when a server is ready for requests. You can block a WebDriver client on this promise with:
```
var started = startTestServer();
driver.wait(started, 5 * 1000, 'Server should start within 5 seconds');
driver.get(getServerUrl());
```
Type Parameters
- T
Parameters
- condition: Function | PromiseLike<T> | Condition<T> | ((driver) => T | PromiseLike<T>)
  The condition to wait on, defined as a promise, condition object, or a function to evaluate as a condition.
- Optional opt_timeout: number
  How long to wait for the condition to be true.
- Optional opt_message: string
  An optional message to use if the wait times out.
- Optional opt_pollTimeout: number
  Duration in milliseconds to wait between polling the condition.
Returns Promise<T>
A promise that will be fulfilled with the first truthy value returned by the condition function, or rejected if the condition times out.

Inherited from WebDriver.wait

Interface ThenableWebDriver

Hierarchy

Index

Properties

Methods

Properties

Readonly [toStringTag]

Methods

actions

Parameters

Optional options: { async: boolean; bridge: boolean; } | { async: boolean; } | { bridge: boolean; }

Returns Actions

catch

Type Parameters

TResult = never

Parameters

Optional onrejected: null | ((reason) => TResult | PromiseLike<TResult>)

Returns Promise<WebDriver | TResult>

close

Returns Promise<void>

createCDPConnection

Parameters

target: string

Returns Promise<any>

execute

Type Parameters

T

Parameters

command: Command

Optional description: string

Returns Promise<T>

executeAsyncScript

Type Parameters

T

Parameters

script: string | Function

Rest ...var_args: any[]

Returns Promise<T>

executeScript

Type Parameters

T

Parameters

script: string | Function

Rest ...var_args: any[]

Returns Promise<T>

finally

Parameters

Optional onfinally: null | (() => void)

Returns Promise<WebDriver>

findElement

Parameters

locator: Locator

Returns WebElementPromise

findElementInternal_

Parameters

locatorFn: Function

context: WebDriver | WebElement

Returns Promise<WebElement>

findElements

Parameters

locator: Locator

Returns Promise<WebElement[]>

findElementsInternal_

Parameters

locatorFn: Function

context: WebDriver | WebElement

Returns Promise<WebElement[]>

get

Parameters

url: string

Returns Promise<void>

getAllWindowHandles

Returns Promise<string[]>

getCapabilities

Returns Promise<Capabilities>

getCurrentUrl

Returns Promise<string>

getExecutor

Returns Executor

getPageSource

`Readonly` [toStringTag]

`Optional` options: {
async: boolean;
bridge: boolean;
} | {
async: boolean;
} | {
bridge: boolean;
}

`Optional` onrejected: null | ((reason) => TResult | PromiseLike<TResult>)

`Optional` description: string

`Rest` ...var_args: any[]

`Rest` ...var_args: any[]

`Optional` onfinally: null | (() => void)