leadfoot/Session

Inheritance

  1. leadfoot/Session
  2. Object

new (require("leadfoot/Session"))(sessionId: string, server: leadfoot/Server, capabilities: Capabilities)

A Session represents a connection to a remote environment that can be driven programmatically.

Parameters

Name Type Description
sessionId string

The ID of the session, as provided by the remote.

server leadfoot/Server

The server that the session belongs to.

capabilities Capabilities

A map of bugs and features that the remote environment exposes.

All Properties

Property Defined by
(readonly)

Information about the available features and bugs in the remote environment.

leadfoot/Session
(readonly)

The Server that the session runs on.

leadfoot/Session
sessionId: string
(readonly)

The current session ID.

leadfoot/Session

All Methods

Method Defined by
_manualFindByLinkText(using: string, value: string, multiple: boolean, elementnullable: Element): Element|Array.<Element>

Searches a document or element subtree for links with the given normalized text.

leadfoot/Session
_normalizeWhitespace(text: string): string

Normalize whitespace in the same way that most browsers generate innerText.

leadfoot/Session
acceptAlert(): Promise.<void>

Accepts an alert, prompt, or confirmation pop-up.

leadfoot/Session
activateIme(engine: string): Promise.<void>

Activates an input method editor in the remote environment.

leadfoot/Session
clearCookies(): Promise.<void>

Clears all cookies for the current page.

leadfoot/Session
clearLocalStorage(): Promise.<void>

Clears all data in local storage for the focused window/frame.

leadfoot/Session
clearSessionStorage(): Promise.<void>

Clears all data in session storage for the focused window/frame.

leadfoot/Session
clickMouseButton(buttonopt: number): Promise.<void>

Clicks a mouse button at the point where the mouse cursor is currently positioned.

leadfoot/Session
closeCurrentWindow(): Promise.<void>

Closes the currently focused window.

leadfoot/Session
deactivateIme(): Promise.<void>

Deactivates any active input method editor in the remote environment.

leadfoot/Session
deleteCookie(name: string): Promise.<void>

Deletes a cookie on the current page.

leadfoot/Session
deleteLocalStorageItem(key: string): Promise.<void>

Deletes a value from local storage for the focused window/frame.

leadfoot/Session
deleteSessionStorageItem(key: string): Promise.<void>

Deletes a value from session storage for the focused window/frame.

leadfoot/Session
dismissAlert(): Promise.<void>

Dismisses an alert, prompt, or confirmation pop-up.

leadfoot/Session
doubleClick(): Promise.<void>

Double-clicks the primary mouse button.

leadfoot/Session
doubleTap(element: leadfoot/Element): Promise.<void>

Performs a double-tap gesture on an element.

leadfoot/Session
execute(script: function|string, args: Array.<any>): Promise.<any>

Executes JavaScript code within the focused window/frame.

leadfoot/Session
executeAsync(script: function|string, args: Array.<any>): Promise.<any>

Executes JavaScript code within the focused window/frame.

leadfoot/Session
find(using: string, value: string): Promise.<leadfoot/Element>

Gets the first element from the focused window/frame that matches the given query.

leadfoot/Session
findAll(using: string, value: string): Promise.<Array.<leadfoot/Element>>

Gets an array of elements from the focused window/frame that match the given query.

leadfoot/Session
findAllByClassName(className: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given CSS class name.

leadfoot/Session
findAllByCssSelector(selector: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given CSS selector.

leadfoot/Session
findAllByLinkText(text: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given case-insensitive link text.

leadfoot/Session
findAllByName(name: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given name attribute.

leadfoot/Session
findAllByPartialLinkText(text: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame partially matching the given case-insensitive link text.

leadfoot/Session
findAllByTagName(tagName: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given HTML tag name.

leadfoot/Session
findAllByXpath(path: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given XPath selector.

leadfoot/Session
findByClassName(className: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given CSS class name.

leadfoot/Session
findByCssSelector(selector: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given CSS selector.

leadfoot/Session
findById(id: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given ID.

leadfoot/Session
findByLinkText(text: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given case-insensitive link text.

leadfoot/Session
findByName(name: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given name attribute.

leadfoot/Session
findByPartialLinkText(text: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame partially matching the given case-insensitive link text.

leadfoot/Session
findByTagName(tagName: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given HTML tag name.

leadfoot/Session
findByXpath(path: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given XPath selector.

leadfoot/Session
findDisplayed(using: string, value: string): Promise.<leadfoot/Element>

Gets the first displayed element in the currently active window/frame matching the given query.

leadfoot/Session
findDisplayedByClassName(className: string): Promise.<leadfoot/Element>

Gets the first displayed element in the currently active window/frame matching the given CSS class name.

leadfoot/Session
findDisplayedByCssSelector(selector: string): Promise.<leadfoot/Element>

Gets the first displayed element in the currently active window/frame matching the given CSS selector.

leadfoot/Session
findDisplayedById(id: string): Promise.<leadfoot/Element>

Gets the first displayed element in the currently active window/frame matching the given ID.

leadfoot/Session
findDisplayedByLinkText(text: string): Promise.<leadfoot/Element>

Gets the first displayed element in the currently active window/frame matching the given case-insensitive link text.

leadfoot/Session
findDisplayedByName(name: string): Promise.<leadfoot/Element>

Gets the first displayed element in the currently active window/frame matching the given name attribute.

leadfoot/Session

Gets the first displayed element in the currently active window/frame partially matching the given case-insensitive link text.

leadfoot/Session
findDisplayedByTagName(tagName: string): Promise.<leadfoot/Element>

Gets the first displayed element in the currently active window/frame matching the given HTML tag name.

leadfoot/Session
findDisplayedByXpath(path: string): Promise.<leadfoot/Element>

Gets the first displayed element in the currently active window/frame matching the given XPath selector.

leadfoot/Session
flickFinger(element: leadfoot/Element, xOffset: number, yOffset: number, speed: number): Promise.<void>

Flicks a finger.

leadfoot/Session
get(url: string): Promise.<void>

Navigates the focused window/frame to a new URL.

leadfoot/Session

Gets the currently focused element from the focused window/frame.

leadfoot/Session
getActiveImeEngine(): Promise.<string>

Gets the currently active input method editor for the remote environment.

leadfoot/Session
getAlertText(): Promise.<string>

Gets the text displayed in the currently active alert pop-up.

leadfoot/Session
getAllWindowHandles(): Promise.<Array.<string>>

Gets a list of identifiers for all currently open windows.

leadfoot/Session
getApplicationCacheStatus(): Promise.<number>

Gets the current state of the HTML5 application cache for the current page.

leadfoot/Session
getAvailableImeEngines(): Promise.<Array.<string>>

Gets a list of input method editor engines available to the remote environment.

leadfoot/Session
getAvailableLogTypes(): Promise.<Array.<string>>

Gets the types of logs that are currently available for retrieval from the remote environment.

leadfoot/Session
getCookies(): Promise.<Array.<WebDriverCookie>>

Gets all cookies set on the current page.

leadfoot/Session
getCurrentUrl(): Promise.<string>

Gets the URL that is loaded in the focused window/frame.

leadfoot/Session
getCurrentWindowHandle(): Promise.<string>

Gets the identifier for the window that is currently focused.

leadfoot/Session
getExecuteAsyncTimeout(): Promise.<number>

Gets the timeout for leadfoot/Session#executeAsync calls.

leadfoot/Session
getFindTimeout(): Promise.<number>

Gets the timeout for leadfoot/Session#find calls.

leadfoot/Session

Gets the current geographical location of the remote environment.

leadfoot/Session
getLocalStorageItem(key: string): Promise.<string>

Gets a value from local storage for the focused window/frame.

leadfoot/Session
getLocalStorageKeys(): Promise.<Array.<string>>

Gets the list of keys set in local storage for the focused window/frame.

leadfoot/Session
getLocalStorageLength(): Promise.<number>

Gets the number of keys set in local storage for the focused window/frame.

leadfoot/Session
getLogsFor(type: string): Promise.<Array.<LogEntry>>

Gets all logs from the remote environment of the given type.

leadfoot/Session
getOrientation(): Promise.<string>

Gets the current screen orientation.

leadfoot/Session
getPageLoadTimeout(): Promise.<number>

Gets the timeout for leadfoot/Session#get calls.

leadfoot/Session
getPageSource(): Promise.<string>

Gets the HTML loaded in the focused window/frame.

leadfoot/Session
getPageTitle(): Promise.<string>

Gets the title of the top-level browsing context of the current window or tab.

leadfoot/Session
getSessionStorageItem(key: string): Promise.<string>

Gets a value from session storage for the focused window/frame.

leadfoot/Session
getSessionStorageKeys(): Promise.<Array.<string>>

Gets the list of keys set in session storage for the focused window/frame.

leadfoot/Session
getSessionStorageLength(): Promise.<number>

Gets the number of keys set in session storage for the focused window/frame.

leadfoot/Session
getTimeout(type: string): Promise.<number>

Gets the current value of a timeout for the session.

leadfoot/Session
getWindowPosition(windowHandleopt: string): Promise.<{x: number, y: number}>

Gets the position of a window.

leadfoot/Session
getWindowSize(windowHandleopt: string): Promise.<{width: number, height: number}>

Gets the dimensions of a window.

leadfoot/Session
goBack(): Promise.<void>

Navigates the focused window/frame back one page using the browser’s navigation history.

leadfoot/Session
goForward(): Promise.<void>

Navigates the focused window/frame forward one page using the browser’s navigation history.

leadfoot/Session
isImeActivated(): Promise.<boolean>

Returns whether or not an input method editor is currently active in the remote environment.

leadfoot/Session
longTap(element: leadfoot/Element): Promise.<void>

Performs a long-tap gesture on an element.

leadfoot/Session
maximizeWindow(windowHandleopt: string): Promise.<void>

Maximises a window according to the platform’s window system behaviour.

leadfoot/Session
moveFinger(x: number, y: number): Promise.<void>

Moves the last depressed finger to a new point on the touch screen.

leadfoot/Session
moveMouseTo(elementopt: Element, xOffsetopt: number, yOffsetopt: number): Promise.<void>

Moves the remote environment’s mouse cursor to the specified element or relative position.

leadfoot/Session
pressFinger(x: number, y: number): Promise.<void>

Depresses a new finger at the given point on a touch screen device without releasing it.

leadfoot/Session
pressKeys(keys: string|Array.<string>): Promise.<void>

Types into the focused window/frame/element.

leadfoot/Session
pressMouseButton(buttonopt: number): Promise.<void>

Depresses a mouse button without releasing it.

leadfoot/Session
quit(): Promise.<void>

Terminates the session.

leadfoot/Session
refresh(): Promise.<void>

Reloads the current browser window/frame.

leadfoot/Session
releaseFinger(x: number, y: number): Promise.<void>

Releases whatever finger exists at the given point on a touch screen device.

leadfoot/Session
releaseMouseButton(buttonopt: number): Promise.<void>

Releases a previously depressed mouse button.

leadfoot/Session
setCookie(cookie: WebDriverCookie): Promise.<void>

Sets a cookie on the current page.

leadfoot/Session
setExecuteAsyncTimeout(ms: number): Promise.<void>

Sets the timeout for leadfoot/Session#executeAsync calls.

leadfoot/Session
setFindTimeout(ms: number): Promise.<void>

Sets the timeout for leadfoot/Session#find calls.

leadfoot/Session
setGeolocation(location: Geolocation): Promise.<void>

Sets the geographical location of the remote environment.

leadfoot/Session
setLocalStorageItem(key: string, value: string): Promise.<void>

Sets a value in local storage for the focused window/frame.

leadfoot/Session
setOrientation(orientation: string): Promise.<void>

Sets the screen orientation.

leadfoot/Session
setPageLoadTimeout(ms: number): Promise.<void>

Sets the timeout for leadfoot/Session#get calls.

leadfoot/Session
setSessionStorageItem(key: string, value: string): Promise.<void>

Sets a value in session storage for the focused window/frame.

leadfoot/Session
setTimeout(type: string, ms: number): Promise.<void>

Sets the value of a timeout for the session.

leadfoot/Session
setWindowPosition(windowHandleopt: string, x: number, y: number): Promise.<void>

Sets the position of a window.

leadfoot/Session
setWindowSize(windowHandleopt: string, width: number, height: number): Promise.<void>

Sets the dimensions of a window.

leadfoot/Session
switchToFrame(id: string|number|null|Element): Promise.<void>

Switches the currently focused frame to a new frame.

leadfoot/Session
switchToParentFrame(): Promise.<void>

Switches the currently focused frame to the parent of the currently focused frame.

leadfoot/Session
switchToWindow(handle: string): Promise.<void>

Switches the currently focused window to a new window.

leadfoot/Session
takeScreenshot(): Promise.<Buffer>

Gets a screenshot of the focused window and returns it in PNG format.

leadfoot/Session
tap(element: leadfoot/Element): Promise.<void>

Taps an element on a touch screen device.

leadfoot/Session
touchScroll(elementopt: Element, xOffsetopt: number, yOffsetopt: number): Promise.<void>

Scrolls the currently focused window on a touch screen device.

leadfoot/Session
typeInPrompt(text: string|Array.<string>): Promise.<void>

Types into the currently active prompt pop-up.

leadfoot/Session
waitForDeleted(using: string, value: string): Promise.<void>

Waits for all elements in the currently active window/frame to be destroyed.

leadfoot/Session
waitForDeletedByClassName(className: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given CSS class name to be destroyed.

leadfoot/Session
waitForDeletedByCssSelector(selector: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given CSS selector to be destroyed.

leadfoot/Session
waitForDeletedById(id: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given ID to be destroyed.

leadfoot/Session
waitForDeletedByLinkText(text: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given case-insensitive link text to be destroyed.

leadfoot/Session
waitForDeletedByName(name: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given name attribute to be destroyed.

leadfoot/Session
waitForDeletedByPartialLinkText(text: string): Promise.<void>

Waits for all elements in the currently active window/frame partially matching the given case-insensitive link text to be destroyed.

leadfoot/Session
waitForDeletedByTagName(tagName: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given HTML tag name to be destroyed.

leadfoot/Session
waitForDeletedByXpath(path: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given XPath selector to be destroyed.

leadfoot/Session

Properties

(readonly) capabilities: Capabilities

Information about the available features and bugs in the remote environment.

(readonly) server: leadfoot/Server

The Server that the session runs on.

(readonly) sessionId: string

The current session ID.

Methods

_manualFindByLinkText(using: string, value: string, multiple: boolean, elementnullable: Element): Element|Array.<Element>

Searches a document or element subtree for links with the given normalized text. This method works for 'link text' and 'partial link text' search strategies.

Note that this method should be passed to an execute call, not called directly.

Parameters

Name Type Attributes Description
using string

The strategy in use ('link text' or 'partial link text')

value string

The link text to search for

multiple boolean

If true, return all matching links

element Element nullable

A context element

Returns

  • The found element or elements

_normalizeWhitespace(text: string): string

Normalize whitespace in the same way that most browsers generate innerText.

Parameters

Name Type
text string

Returns

  • Text with leading and trailing whitespace removed, with inner runs of spaces changed to a single space, and with "\r\n" pairs converted to "\n".

acceptAlert(): Promise.<void>

Accepts an alert, prompt, or confirmation pop-up. Equivalent to clicking the 'OK' button.

activateIme(engine: string): Promise.<void>

Activates an input method editor in the remote environment. As of April 2014, no known remote environments support IME functions.

Parameters

Name Type Description
engine string

The type of IME to activate.

clearCookies(): Promise.<void>

Clears all cookies for the current page.

clearLocalStorage(): Promise.<void>

Clears all data in local storage for the focused window/frame.

clearSessionStorage(): Promise.<void>

Clears all data in session storage for the focused window/frame.

clickMouseButton(buttonopt: number): Promise.<void>

Clicks a mouse button at the point where the mouse cursor is currently positioned. This method may fail to execute with an error if the mouse has not been moved anywhere since the page was loaded.

Parameters

Name Type Attributes Description
button number optional

The button to click. 0 corresponds to the primary mouse button, 1 to the middle mouse button, 2 to the secondary mouse button. Numbers above 2 correspond to any additional buttons a mouse might provide.

closeCurrentWindow(): Promise.<void>

Closes the currently focused window. In most environments, after the window has been closed, it is necessary to explicitly switch to whatever window is now focused.

deactivateIme(): Promise.<void>

Deactivates any active input method editor in the remote environment. As of April 2014, no known remote environments support IME functions.

deleteCookie(name: string): Promise.<void>

Deletes a cookie on the current page.

Parameters

Name Type Description
name string

The name of the cookie to delete.

deleteLocalStorageItem(key: string): Promise.<void>

Deletes a value from local storage for the focused window/frame.

Parameters

Name Type Description
key string

The key of the data to delete.

deleteSessionStorageItem(key: string): Promise.<void>

Deletes a value from session storage for the focused window/frame.

Parameters

Name Type Description
key string

The key of the data to delete.

dismissAlert(): Promise.<void>

Dismisses an alert, prompt, or confirmation pop-up. Equivalent to clicking the 'OK' button of an alert pop-up or the 'Cancel' button of a prompt or confirmation pop-up.

doubleClick(): Promise.<void>

Double-clicks the primary mouse button.

doubleTap(element: leadfoot/Element): Promise.<void>

Performs a double-tap gesture on an element.

Parameters

Name Type Description
element leadfoot/Element

The element to double-tap.

execute(script: function|string, args: Array.<any>): Promise.<any>

Executes JavaScript code within the focused window/frame. The code should return a value synchronously.

Parameters

Name Type Description
script function|string

The code to execute. This function will always be converted to a string, sent to the remote environment, and reassembled as a new anonymous function on the remote end. This means that you cannot access any variables through closure. If your code needs to get data from variables on the local end, they should be passed using args.

args Array.<any>

An array of arguments that will be passed to the executed code. Only values that can be serialised to JSON, plus leadfoot/Element objects, can be specified as arguments.

Returns

  • The value returned by the remote code. Only values that can be serialised to JSON, plus DOM elements, can be returned.

See

executeAsync(script: function|string, args: Array.<any>): Promise.<any>

Executes JavaScript code within the focused window/frame. The code must invoke the provided callback in order to signal that it has completed execution.

Parameters

Name Type Description
script function|string

The code to execute. This function will always be converted to a string, sent to the remote environment, and reassembled as a new anonymous function on the remote end. This means that you cannot access any variables through closure. If your code needs to get data from variables on the local end, they should be passed using args.

args Array.<any>

An array of arguments that will be passed to the executed code. Only values that can be serialised to JSON, plus leadfoot/Element objects, can be specified as arguments. In addition to these arguments, a callback function will always be passed as the final argument to the function specified in script. This callback function must be invoked in order to signal that execution has completed. The return value of the execution, if any, should be passed to this callback function.

Returns

  • The value returned by the remote code. Only values that can be serialised to JSON, plus DOM elements, can be returned.

See

find(using: string, value: string): Promise.<leadfoot/Element>

Gets the first element from the focused window/frame that matches the given query.

Parameters

Name Type Description
using string

The element retrieval strategy to use. One of 'class name', 'css selector', 'id', 'name', 'link text', 'partial link text', 'tag name', 'xpath'.

value string

The strategy-specific value to search for. For example, if using is 'id', value should be the ID of the element to retrieve.

See

  • leadfoot/Session#setFindTimeout to set the amount of time it the remote environment should spend waiting for an element that does not exist at the time of the `find` call before timing out.

findAll(using: string, value: string): Promise.<Array.<leadfoot/Element>>

Gets an array of elements from the focused window/frame that match the given query.

Parameters

Name Type Description
using string

The element retrieval strategy to use. See leadfoot/Session#find for options.

value string

The strategy-specific value to search for. See leadfoot/Session#find for details.

findAllByClassName(className: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given CSS class name.

Parameters

Name Type Description
className string

The CSS class name to search for.

findAllByCssSelector(selector: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given CSS selector.

Parameters

Name Type Description
selector string

The CSS selector to search for.

findAllByLinkText(text: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given case-insensitive link text.

Parameters

Name Type Description
text string

The link text of the element.

findAllByName(name: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given name attribute.

Parameters

Name Type Description
name string

The name of the element.

findAllByPartialLinkText(text: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame partially matching the given case-insensitive link text.

Parameters

Name Type Description
text string

The partial link text of the element.

findAllByTagName(tagName: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given HTML tag name.

Parameters

Name Type Description
tagName string

The tag name of the element.

findAllByXpath(path: string): Promise.<Array.<leadfoot/Element>>

Gets all elements in the currently active window/frame matching the given XPath selector.

Parameters

Name Type Description
path string

The XPath selector to search for.

findByClassName(className: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given CSS class name.

Parameters

Name Type Description
className string

The CSS class name to search for.

findByCssSelector(selector: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given CSS selector.

Parameters

Name Type Description
selector string

The CSS selector to search for.

findById(id: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given ID.

Parameters

Name Type Description
id string

The ID of the element.

findByLinkText(text: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given case-insensitive link text.

Parameters

Name Type Description
text string

The link text of the element.

findByName(name: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given name attribute.

Parameters

Name Type Description
name string

The name of the element.

findByPartialLinkText(text: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame partially matching the given case-insensitive link text.

Parameters

Name Type Description
text string

The partial link text of the element.

findByTagName(tagName: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given HTML tag name.

Parameters

Name Type Description
tagName string

The tag name of the element.

findByXpath(path: string): Promise.<leadfoot/Element>

Gets the first element in the currently active window/frame matching the given XPath selector.

Parameters

Name Type Description
path string

The XPath selector to search for.

findDisplayed(using: string, value: string): Promise.<leadfoot/Element>

Since

1.6

Gets the first displayed element in the currently active window/frame matching the given query. This is inherently slower than leadfoot/Session#find, so should only be used in cases where the visibility of an element cannot be ensured in advance.

Parameters

Name Type Description
using string

The element retrieval strategy to use. See leadfoot/Session#find for options.

value string

The strategy-specific value to search for. See leadfoot/Session#find for details.

findDisplayedByClassName(className: string): Promise.<leadfoot/Element>

Since

1.6

Gets the first displayed element in the currently active window/frame matching the given CSS class name. This is inherently slower than leadfoot/Session#find, so should only be used in cases where the visibility of an element cannot be ensured in advance.

Parameters

Name Type Description
className string

The CSS class name to search for.

findDisplayedByCssSelector(selector: string): Promise.<leadfoot/Element>

Since

1.6

Gets the first displayed element in the currently active window/frame matching the given CSS selector. This is inherently slower than leadfoot/Session#find, so should only be used in cases where the visibility of an element cannot be ensured in advance.

Parameters

Name Type Description
selector string

The CSS selector to search for.

findDisplayedById(id: string): Promise.<leadfoot/Element>

Since

1.6

Gets the first displayed element in the currently active window/frame matching the given ID. This is inherently slower than leadfoot/Session#find, so should only be used in cases where the visibility of an element cannot be ensured in advance.

Parameters

Name Type Description
id string

The ID of the element.

findDisplayedByLinkText(text: string): Promise.<leadfoot/Element>

Since

1.6

Gets the first displayed element in the currently active window/frame matching the given case-insensitive link text. This is inherently slower than leadfoot/Session#find, so should only be used in cases where the visibility of an element cannot be ensured in advance.

Parameters

Name Type Description
text string

The link text of the element.

findDisplayedByName(name: string): Promise.<leadfoot/Element>

Since

1.6

Gets the first displayed element in the currently active window/frame matching the given name attribute. This is inherently slower than leadfoot/Session#find, so should only be used in cases where the visibility of an element cannot be ensured in advance.

Parameters

Name Type Description
name string

The name of the element.

findDisplayedByPartialLinkText(text: string): Promise.<leadfoot/Element>

Since

1.6

Gets the first displayed element in the currently active window/frame partially matching the given case-insensitive link text. This is inherently slower than leadfoot/Session#find, so should only be used in cases where the visibility of an element cannot be ensured in advance.

Parameters

Name Type Description
text string

The partial link text of the element.

findDisplayedByTagName(tagName: string): Promise.<leadfoot/Element>

Since

1.6

Gets the first displayed element in the currently active window/frame matching the given HTML tag name. This is inherently slower than leadfoot/Session#find, so should only be used in cases where the visibility of an element cannot be ensured in advance.

Parameters

Name Type Description
tagName string

The tag name of the element.

findDisplayedByXpath(path: string): Promise.<leadfoot/Element>

Since

1.6

Gets the first displayed element in the currently active window/frame matching the given XPath selector. This is inherently slower than leadfoot/Session#find, so should only be used in cases where the visibility of an element cannot be ensured in advance.

Parameters

Name Type Description
path string

The XPath selector to search for.

flickFinger(element: leadfoot/Element, xOffset: number, yOffset: number, speed: number): Promise.<void>

Flicks a finger. Note that this method is currently badly specified and highly dysfunctional and is only provided for the sake of completeness.

Parameters

Name Type Description
element leadfoot/Element

The element where the flick should start.

xOffset number

The x-offset in pixels to flick by.

yOffset number

The x-offset in pixels to flick by.

speed number

The speed of the flick, in pixels per second. Most human flicks are 100–200ms, so this value will be higher than expected.

get(url: string): Promise.<void>

Navigates the focused window/frame to a new URL.

Parameters

Name Type
url string

getActiveElement(): Promise.<leadfoot/Element>

Gets the currently focused element from the focused window/frame.

getActiveImeEngine(): Promise.<string>

Gets the currently active input method editor for the remote environment. As of April 2014, no known remote environments support IME functions.

getAlertText(): Promise.<string>

Gets the text displayed in the currently active alert pop-up.

getAllWindowHandles(): Promise.<Array.<string>>

Gets a list of identifiers for all currently open windows.

getApplicationCacheStatus(): Promise.<number>

Gets the current state of the HTML5 application cache for the current page.

Returns

  • The cache status. One of 0 (uncached), 1 (cached/idle), 2 (checking), 3 (downloading), 4 (update ready), 5 (obsolete).

getAvailableImeEngines(): Promise.<Array.<string>>

Gets a list of input method editor engines available to the remote environment. As of April 2014, no known remote environments support IME functions.

getAvailableLogTypes(): Promise.<Array.<string>>

Gets the types of logs that are currently available for retrieval from the remote environment.

getCookies(): Promise.<Array.<WebDriverCookie>>

Gets all cookies set on the current page.

getCurrentUrl(): Promise.<string>

Gets the URL that is loaded in the focused window/frame.

getCurrentWindowHandle(): Promise.<string>

Gets the identifier for the window that is currently focused.

Returns

  • A window handle identifier that can be used with other window handling functions.

getExecuteAsyncTimeout(): Promise.<number>

Gets the timeout for leadfoot/Session#executeAsync calls.

getFindTimeout(): Promise.<number>

Gets the timeout for leadfoot/Session#find calls.

getGeolocation(): Promise.<Geolocation>

Gets the current geographical location of the remote environment.

Returns

  • Latitude and longitude are specified using standard WGS84 decimal latitude/longitude. Altitude is specified as meters above the WGS84 ellipsoid. Not all environments support altitude.

getLocalStorageItem(key: string): Promise.<string>

Gets a value from local storage for the focused window/frame.

Parameters

Name Type Description
key string

The key of the data to get.

getLocalStorageKeys(): Promise.<Array.<string>>

Gets the list of keys set in local storage for the focused window/frame.

getLocalStorageLength(): Promise.<number>

Gets the number of keys set in local storage for the focused window/frame.

getLogsFor(type: string): Promise.<Array.<LogEntry>>

Gets all logs from the remote environment of the given type. The logs in the remote environment are cleared once they have been retrieved.

Parameters

Name Type Description
type string

The type of log entries to retrieve. Available log types differ between remote environments. Use leadfoot/Session#getAvailableLogTypes to learn what log types are currently available. Not all environments support all possible log types.

Returns

  • An array of log entry objects. Timestamps in log entries are Unix timestamps, in seconds.

getOrientation(): Promise.<string>

Gets the current screen orientation.

Returns

  • Either 'portrait' or 'landscape'.

getPageLoadTimeout(): Promise.<number>

Gets the timeout for leadfoot/Session#get calls.

getPageSource(): Promise.<string>

Gets the HTML loaded in the focused window/frame. This markup is serialised by the remote environment so may not exactly match the HTML provided by the Web server.

getPageTitle(): Promise.<string>

Gets the title of the top-level browsing context of the current window or tab.

getSessionStorageItem(key: string): Promise.<string>

Gets a value from session storage for the focused window/frame.

Parameters

Name Type Description
key string

The key of the data to get.

getSessionStorageKeys(): Promise.<Array.<string>>

Gets the list of keys set in session storage for the focused window/frame.

getSessionStorageLength(): Promise.<number>

Gets the number of keys set in session storage for the focused window/frame.

getTimeout(type: string): Promise.<number>

Gets the current value of a timeout for the session.

Parameters

Name Type Description
type string

The type of timeout to retrieve. One of 'script', 'implicit', or 'page load'.

Returns

  • The timeout, in milliseconds.

getWindowPosition(windowHandleopt: string): Promise.<{x: number, y: number}>

Gets the position of a window.

Note that this method is not part of the W3C WebDriver standard.

Parameters

Name Type Attributes Description
windowHandle string optional

The name of the window to query. See leadfoot/Session#switchToWindow to learn about valid window names. Omit this argument to query the currently focused window.

Returns

  • An object describing the position of the window, in CSS pixels, relative to the top-left corner of the primary monitor. If a secondary monitor exists above or to the left of the primary monitor, these values will be negative.

getWindowSize(windowHandleopt: string): Promise.<{width: number, height: number}>

Gets the dimensions of a window.

Parameters

Name Type Attributes Description
windowHandle string optional

The name of the window to query. See leadfoot/Session#switchToWindow to learn about valid window names. Omit this argument to query the currently focused window.

Returns

  • An object describing the width and height of the window, in CSS pixels.

goBack(): Promise.<void>

Navigates the focused window/frame back one page using the browser’s navigation history.

goForward(): Promise.<void>

Navigates the focused window/frame forward one page using the browser’s navigation history.

isImeActivated(): Promise.<boolean>

Returns whether or not an input method editor is currently active in the remote environment. As of April 2014, no known remote environments support IME functions.

longTap(element: leadfoot/Element): Promise.<void>

Performs a long-tap gesture on an element.

Parameters

Name Type Description
element leadfoot/Element

The element to long-tap.

maximizeWindow(windowHandleopt: string): Promise.<void>

Maximises a window according to the platform’s window system behaviour.

Parameters

Name Type Attributes Description
windowHandle string optional

The name of the window to resize. See leadfoot/Session#switchToWindow to learn about valid window names. Omit this argument to resize the currently focused window.

moveFinger(x: number, y: number): Promise.<void>

Moves the last depressed finger to a new point on the touch screen.

Parameters

Name Type Description
x number

The screen x-coordinate to move to, maybe in device pixels.

y number

The screen y-coordinate to move to, maybe in device pixels.

moveMouseTo(elementopt: Element, xOffsetopt: number, yOffsetopt: number): Promise.<void>

Moves the remote environment’s mouse cursor to the specified element or relative position. If the element is outside of the viewport, the remote driver will attempt to scroll it into view automatically.

Parameters

Name Type Attributes Description
element Element optional

The element to move the mouse to. If x-offset and y-offset are not specified, the mouse will be moved to the centre of the element.

xOffset number optional

The x-offset of the cursor, maybe in CSS pixels, relative to the left edge of the specified element’s bounding client rectangle. If no element is specified, the offset is relative to the previous position of the mouse, or to the left edge of the page’s root element if the mouse was never moved before.

yOffset number optional

The y-offset of the cursor, maybe in CSS pixels, relative to the top edge of the specified element’s bounding client rectangle. If no element is specified, the offset is relative to the previous position of the mouse, or to the top edge of the page’s root element if the mouse was never moved before.

pressFinger(x: number, y: number): Promise.<void>

Depresses a new finger at the given point on a touch screen device without releasing it.

Parameters

Name Type Description
x number

The screen x-coordinate to press, maybe in device pixels.

y number

The screen y-coordinate to press, maybe in device pixels.

pressKeys(keys: string|Array.<string>): Promise.<void>

Types into the focused window/frame/element.

Parameters

Name Type Description
keys string|Array.<string>

The text to type in the remote environment. It is possible to type keys that do not have normal character representations (modifier keys, function keys, etc.) as well as keys that have two different representations on a typical US-ASCII keyboard (numpad keys); use the values from leadfoot/keys to type these special characters. Any modifier keys that are activated by this call will persist until they are deactivated. To deactivate a modifier key, type the same modifier key a second time, or send \uE000 ('NULL') to deactivate all currently active modifier keys.

pressMouseButton(buttonopt: number): Promise.<void>

Depresses a mouse button without releasing it.

Parameters

Name Type Attributes Description
button number optional

The button to press. See leadfoot/Session#click for available options.

quit(): Promise.<void>

Terminates the session. No more commands will be accepted by the remote after this point.

refresh(): Promise.<void>

Reloads the current browser window/frame.

releaseFinger(x: number, y: number): Promise.<void>

Releases whatever finger exists at the given point on a touch screen device.

Parameters

Name Type Description
x number

The screen x-coordinate where a finger is pressed, maybe in device pixels.

y number

The screen y-coordinate where a finger is pressed, maybe in device pixels.

releaseMouseButton(buttonopt: number): Promise.<void>

Releases a previously depressed mouse button.

Parameters

Name Type Attributes Description
button number optional

The button to press. See leadfoot/Session#click for available options.

setCookie(cookie: WebDriverCookie): Promise.<void>

Sets a cookie on the current page.

Parameters

Name Type
cookie WebDriverCookie

setExecuteAsyncTimeout(ms: number): Promise.<void>

Sets the timeout for leadfoot/Session#executeAsync calls.

Parameters

Name Type Description
ms number

The length of the timeout, in milliseconds.

setFindTimeout(ms: number): Promise.<void>

Sets the timeout for leadfoot/Session#find calls.

Parameters

Name Type Description
ms number

The length of the timeout, in milliseconds.

setGeolocation(location: Geolocation): Promise.<void>

Sets the geographical location of the remote environment.

Parameters

Name Type Description
location Geolocation

Latitude and longitude are specified using standard WGS84 decimal latitude/longitude. Altitude is specified as meters above the WGS84 ellipsoid. Not all environments support altitude.

setLocalStorageItem(key: string, value: string): Promise.<void>

Sets a value in local storage for the focused window/frame.

Parameters

Name Type Description
key string

The key to set.

value string

The value to set.

setOrientation(orientation: string): Promise.<void>

Sets the screen orientation.

Parameters

Name Type Description
orientation string

Either 'portrait' or 'landscape'.

setPageLoadTimeout(ms: number): Promise.<void>

Sets the timeout for leadfoot/Session#get calls.

Parameters

Name Type Description
ms number

The length of the timeout, in milliseconds.

setSessionStorageItem(key: string, value: string): Promise.<void>

Sets a value in session storage for the focused window/frame.

Parameters

Name Type Description
key string

The key to set.

value string

The value to set.

setTimeout(type: string, ms: number): Promise.<void>

Sets the value of a timeout for the session.

Parameters

Name Type Description
type string

The type of timeout to set. One of 'script', 'implicit', or 'page load'.

ms number

The length of time to use for the timeout, in milliseconds. A value of 0 will cause operations to time out immediately.

setWindowPosition(windowHandleopt: string, x: number, y: number): Promise.<void>

Sets the position of a window.

Note that this method is not part of the W3C WebDriver standard.

Parameters

Name Type Attributes Description
windowHandle string optional

The name of the window to move. See leadfoot/Session#switchToWindow to learn about valid window names. Omit this argument to move the currently focused window.

x number

The screen x-coordinate to move to, in CSS pixels, relative to the left edge of the primary monitor.

y number

The screen y-coordinate to move to, in CSS pixels, relative to the top edge of the primary monitor.

setWindowSize(windowHandleopt: string, width: number, height: number): Promise.<void>

Sets the dimensions of a window.

Parameters

Name Type Attributes Description
windowHandle string optional

The name of the window to resize. See leadfoot/Session#switchToWindow to learn about valid window names. Omit this argument to resize the currently focused window.

width number

The new width of the window, in CSS pixels.

height number

The new height of the window, in CSS pixels.

switchToFrame(id: string|number|null|Element): Promise.<void>

Switches the currently focused frame to a new frame.

Parameters

Name Type Description
id string|number|null|Element

The frame to switch to. In most environments, a number or string value corresponds to a key in the window.frames object of the currently active frame. If null, the topmost (default) frame will be used. If an Element is provided, it must correspond to a <frame> or <iframe> element.

switchToParentFrame(): Promise.<void>

Switches the currently focused frame to the parent of the currently focused frame.

switchToWindow(handle: string): Promise.<void>

Switches the currently focused window to a new window.

Parameters

Name Type Description
handle string

The handle of the window to switch to. In mobile environments and environments based on the W3C WebDriver standard, this should be a handle as returned by leadfoot/Session#getAllWindowHandles.

In environments using the JsonWireProtocol, this value corresponds to the window.name property of a window.

takeScreenshot(): Promise.<Buffer>

Gets a screenshot of the focused window and returns it in PNG format.

Returns

  • A buffer containing a PNG image.

tap(element: leadfoot/Element): Promise.<void>

Taps an element on a touch screen device. If the element is outside of the viewport, the remote driver will attempt to scroll it into view automatically.

Parameters

Name Type Description
element leadfoot/Element

The element to tap.

touchScroll(elementopt: Element, xOffsetopt: number, yOffsetopt: number): Promise.<void>

Scrolls the currently focused window on a touch screen device.

Parameters

Name Type Attributes Description
element Element optional

An element to scroll to. The window will be scrolled so the element is as close to the top-left corner of the window as possible.

xOffset number optional

An optional x-offset, relative to the left edge of the element, in CSS pixels. If no element is specified, the offset is relative to the previous scroll position of the window.

yOffset number optional

An optional y-offset, relative to the top edge of the element, in CSS pixels. If no element is specified, the offset is relative to the previous scroll position of the window.

typeInPrompt(text: string|Array.<string>): Promise.<void>

Types into the currently active prompt pop-up.

Parameters

Name Type Description
text string|Array.<string>

The text to type into the pop-up’s input box.

waitForDeleted(using: string, value: string): Promise.<void>

Waits for all elements in the currently active window/frame to be destroyed.

Parameters

Name Type Description
using string

The element retrieval strategy to use. See leadfoot/Session#find for options.

value string

The strategy-specific value to search for. See leadfoot/Session#find for details.

waitForDeletedByClassName(className: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given CSS class name to be destroyed.

Parameters

Name Type Description
className string

The CSS class name to search for.

waitForDeletedByCssSelector(selector: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given CSS selector to be destroyed.

Parameters

Name Type Description
selector string

The CSS selector to search for.

waitForDeletedById(id: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given ID to be destroyed.

Parameters

Name Type Description
id string

The ID of the element.

waitForDeletedByLinkText(text: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given case-insensitive link text to be destroyed.

Parameters

Name Type Description
text string

The link text of the element.

waitForDeletedByName(name: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given name attribute to be destroyed.

Parameters

Name Type Description
name string

The name of the element.

waitForDeletedByPartialLinkText(text: string): Promise.<void>

Waits for all elements in the currently active window/frame partially matching the given case-insensitive link text to be destroyed.

Parameters

Name Type Description
text string

The partial link text of the element.

waitForDeletedByTagName(tagName: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given HTML tag name to be destroyed.

Parameters

Name Type Description
tagName string

The tag name of the element.

waitForDeletedByXpath(path: string): Promise.<void>

Waits for all elements in the currently active window/frame matching the given XPath selector to be destroyed.

Parameters

Name Type Description
path string

The XPath selector to search for.