Leadfoot docs: Module: leadfoot/Command

Inheritance

leadfoot/Command
Object

new (require("leadfoot/Command"))(parent: leadfoot/Command|leadfoot/Session, initialiser: function, errbackopt: function)

The Command class is a chainable, subclassable object type that can be used to execute commands serially against a remote WebDriver environment. The standard Command class includes methods from the leadfoot/Session and leadfoot/Element classes, so you can perform all standard session and element operations that come with Leadfoot without being forced to author long promise chains.

Important: Due to a documentation tool limitation, the documentation on this page currently lists return values of all methods as being of type Promise. All command methods actually return a new object of type Command. This issue will be addressed in future versions of the documentation.

In order to use the Command class, you first need to pass it a leadfoot/Session instance for it to use:

var command = new Command(session);

Once you have created the Command, you can then start chaining methods, and they will execute in order one after another:

command.get('http://example.com')
  .findByTagName('h1')
  .getVisibleText()
  .then(function (text) {
      assert.strictEqual(text, 'Example Domain');
  });

Because these operations are asynchronous, you need to use a then callback in order to retrieve the value from the last method. Command objects are Thenables, which means that they can be used with any Promises/A+ or ES6-confirmant Promises implementation, though there are some specific differences in the arguments and context that are provided to callbacks; see leadfoot/Command#then for more details.

Each call on a Command generates a new Command object, which means that certain operations can be parallelised:

command = command.get('http://example.com');
Promise.all([
  command.getPageTitle(),
  command.findByTagName('h1').getVisibleText()
]).then(function (results) {
  assert.strictEqual(results[0], results[1]);
});

In this example, the commands on line 3 and 4 both depend upon the get call completing successfully but are otherwise independent of each other and so execute here in parallel. This is different from commands in Intern 1 which were always chained onto the last called method within a given test.

Command objects actually encapsulate two different types of interaction: session interactions, which operate against the entire browser session, and element interactions, which operate against specific elements taken from the currently loaded page. Things like navigating the browser, moving the mouse cursor, and executing scripts are session interactions; things like getting text displayed on the page, typing into form fields, and getting element attributes are element interactions.

Session interactions can be performed at any time, from any Command. On the other hand, to perform element interactions, you first need to retrieve one or more elements to interact with. This can be done using any of the find or findAll methods, by the getActiveElement method, or by returning elements from execute or executeAsync calls. The retrieved elements are stored internally as the element context of all chained Commands. When an element method is called on a chained Command with a single element context, the result will be returned as-is:

command = command.get('http://example.com')
  // finds one element -> single element context
  .findByTagName('h1')
  .getVisibleText()
  .then(function (text) {
    // `text` is the text from the element context
    assert.strictEqual(text, 'Example Domain');
  });

When an element method is called on a chained Command with a multiple element context, the result will be returned as an array:

command = command.get('http://example.com')
  // finds multiple elements -> multiple element context
  .findAllByTagName('p')
  .getVisibleText()
  .then(function (texts) {
    // `texts` is an array of text from each of the `p` elements
    assert.deepEqual(texts, [
      'This domain is established to be used for […]',
      'More information...'
    ]);
  });

The find and findAll methods are special and change their behaviour based on the current element filtering state of a given command. If a command has been filtered by element, the find and findAll commands will only find elements within the currently filtered set of elements. Otherwise, they will find elements throughout the page.

Some method names, like click, are identical for both Session and Element APIs; in this case, the element APIs are suffixed with the word Element in order to identify them uniquely.

Commands can be subclassed in order to add additional functionality without making direct modifications to the default Command prototype that might break other parts of the system:

function CustomCommand() {
  Command.apply(this, arguments);
}
CustomCommand.prototype = Object.create(Command.prototype);
CustomCommand.prototype.constructor = CustomCommand;
CustomCommand.prototype.login = function (username, password) {
  return new this.constructor(this, function () {
    return this.parent
      .findById('username')
        .click()
        .type(username)
        .end()
      .findById('password')
        .click()
        .type(password)
        .end()
      .findById('login')
        .click()
        .end();
  });
};

Note that returning this, or a command chain starting from this, from a callback or command initialiser will deadlock the Command, as it waits for itself to settle before settling.

Parameters

Name	Type	Attributes	Description
`parent`	leadfoot/Command\|leadfoot/Session		The parent command that this command is chained to, or a leadfoot/Session object if this is the first command in a command chain.
`initialiser`	function		A function that will be executed when all parent commands have completed execution. This function can create a new context for this command by calling the passed `setContext` function any time prior to resolving the Promise that it returns. If no context is explicitly provided, the context from the parent command will be used.
`errback`	function	optional	A function that will be executed if any parent commands failed to complete successfully. This function can create a new context for the current command by calling the passed `setContext` function any time prior to resolving the Promise that it returns. If no context is explicitly provided, the context from the parent command will be used.

Source

Command.js, line 57

Property	Defined by
context: Array.<leadfoot/Element> (readonly) The filtered elements that will be used if an element-specific method is invoked.	leadfoot/Command
parent: leadfoot/Command (readonly) The parent Command of the Command, if one exists.	leadfoot/Command
promise: Promise.<any> (readonly) The underlying Promise for the Command.	leadfoot/Command
session: leadfoot/Session (readonly) The parent Session of the Command.	leadfoot/Command

Method	Defined by
Command.addElementMethod(target: leadfoot/Command, key: string) (static) Augments `target` with a method that will call `key` on all context elements stored within `target`.	leadfoot/Command
Command.addSessionMethod(target: leadfoot/Command, key: string, originalFn: function) (static) Augments `target` with a conversion of the `originalFn` method that enables its use with a Command object.	leadfoot/Command
acceptAlert(): Promise.<void> Accepts an alert, prompt, or confirmation pop-up.	leadfoot/Command
activateIme(engine: string): Promise.<void> Activates an input method editor in the remote environment.	leadfoot/Command
cancel(): leadfoot/Command.<void> Cancels all outstanding chained operations of the Command.	leadfoot/Command
catch(errback: function): leadfoot/Command.<any> Adds a callback to be invoked when any of the previously chained operations have failed.	leadfoot/Command
clearCookies(): Promise.<void> Clears all cookies for the current page.	leadfoot/Command
clearLocalStorage(): Promise.<void> Clears all data in local storage for the focused window/frame.	leadfoot/Command
clearSessionStorage(): Promise.<void> Clears all data in session storage for the focused window/frame.	leadfoot/Command
clearValue(): Promise.<void> Clears the value of a form element.	leadfoot/Command
click(): Promise.<void> Clicks the element.	leadfoot/Command
clickMouseButton(buttonopt: number): Promise.<void> Clicks a mouse button at the point where the mouse cursor is currently positioned.	leadfoot/Command
closeCurrentWindow(): Promise.<void> Closes the currently focused window.	leadfoot/Command
deactivateIme(): Promise.<void> Deactivates any active input method editor in the remote environment.	leadfoot/Command
deleteCookie(name: string): Promise.<void> Deletes a cookie on the current page.	leadfoot/Command
deleteLocalStorageItem(key: string): Promise.<void> Deletes a value from local storage for the focused window/frame.	leadfoot/Command
deleteSessionStorageItem(key: string): Promise.<void> Deletes a value from session storage for the focused window/frame.	leadfoot/Command
dismissAlert(): Promise.<void> Dismisses an alert, prompt, or confirmation pop-up.	leadfoot/Command
doubleClick(): Promise.<void> Double-clicks the primary mouse button.	leadfoot/Command
doubleTap(element: leadfoot/Element): Promise.<void> Performs a double-tap gesture on an element.	leadfoot/Command
end(numCommandsToPopopt: number): leadfoot/Command.<void> Ends the most recent filtering operation in the current Command chain and returns the set of matched elements to the previous state.	leadfoot/Command
equals(other: leadfoot/Element): Promise.<boolean> Determines if this element is equal to another element.	leadfoot/Command
execute(script: function\|string, args: Array.<any>): Promise.<any> Executes JavaScript code within the focused window/frame.	leadfoot/Command
executeAsync(script: function\|string, args: Array.<any>): Promise.<any> Executes JavaScript code within the focused window/frame.	leadfoot/Command
finally(callback: function): leadfoot/Command.<any> Adds a callback to be invoked once the previously chained operations have resolved.	leadfoot/Command
find(using: string, value: string): Promise.<leadfoot/Element> Gets the first element from the focused window/frame that matches the given query.	leadfoot/Command
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/Command
findAllByClassName(className: string): Promise.<Array.<leadfoot/Element>> Gets all elements in the currently active window/frame matching the given CSS class name.	leadfoot/Command
findAllByCssSelector(selector: string): Promise.<Array.<leadfoot/Element>> Gets all elements in the currently active window/frame matching the given CSS selector.	leadfoot/Command
findAllByLinkText(text: string): Promise.<Array.<leadfoot/Element>> Gets all elements in the currently active window/frame matching the given case-insensitive link text.	leadfoot/Command
findAllByName(name: string): Promise.<Array.<leadfoot/Element>> Gets all elements in the currently active window/frame matching the given name attribute.	leadfoot/Command
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/Command
findAllByTagName(tagName: string): Promise.<Array.<leadfoot/Element>> Gets all elements in the currently active window/frame matching the given HTML tag name.	leadfoot/Command
findAllByXpath(path: string): Promise.<Array.<leadfoot/Element>> Gets all elements in the currently active window/frame matching the given XPath selector.	leadfoot/Command
findByClassName(className: string): Promise.<leadfoot/Element> Gets the first element in the currently active window/frame matching the given CSS class name.	leadfoot/Command
findByCssSelector(selector: string): Promise.<leadfoot/Element> Gets the first element in the currently active window/frame matching the given CSS selector.	leadfoot/Command
findById(id: string): Promise.<leadfoot/Element> Gets the first element in the currently active window/frame matching the given ID.	leadfoot/Command
findByLinkText(text: string): Promise.<leadfoot/Element> Gets the first element in the currently active window/frame matching the given case-insensitive link text.	leadfoot/Command
findByName(name: string): Promise.<leadfoot/Element> Gets the first element in the currently active window/frame matching the given name attribute.	leadfoot/Command
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/Command
findByTagName(tagName: string): Promise.<leadfoot/Element> Gets the first element in the currently active window/frame matching the given HTML tag name.	leadfoot/Command
findByXpath(path: string): Promise.<leadfoot/Element> Gets the first element in the currently active window/frame matching the given XPath selector.	leadfoot/Command
findDisplayed(using: string, value: string): Promise.<leadfoot/Element> Gets the first displayed element in the currently active window/frame matching the given query.	leadfoot/Command
findDisplayedByClassName(className: string): Promise.<leadfoot/Element> Gets the first displayed element in the currently active window/frame matching the given CSS class name.	leadfoot/Command
findDisplayedByCssSelector(selector: string): Promise.<leadfoot/Element> Gets the first displayed element in the currently active window/frame matching the given CSS selector.	leadfoot/Command
findDisplayedById(id: string): Promise.<leadfoot/Element> Gets the first displayed element in the currently active window/frame matching the given ID.	leadfoot/Command
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/Command
findDisplayedByName(name: string): Promise.<leadfoot/Element> Gets the first displayed element in the currently active window/frame matching the given name attribute.	leadfoot/Command
findDisplayedByPartialLinkText(text: string): Promise.<leadfoot/Element> Gets the first displayed element in the currently active window/frame partially matching the given case-insensitive link text.	leadfoot/Command
findDisplayedByTagName(tagName: string): Promise.<leadfoot/Element> Gets the first displayed element in the currently active window/frame matching the given HTML tag name.	leadfoot/Command
findDisplayedByXpath(path: string): Promise.<leadfoot/Element> Gets the first displayed element in the currently active window/frame matching the given XPath selector.	leadfoot/Command
flickFinger(element: leadfoot/Element, xOffset: number, yOffset: number, speed: number): Promise.<void> Flicks a finger.	leadfoot/Command
get(url: string): Promise.<void> Navigates the focused window/frame to a new URL.	leadfoot/Command
getActiveElement(): Promise.<leadfoot/Element> Gets the currently focused element from the focused window/frame.	leadfoot/Command
getActiveImeEngine(): Promise.<string> Gets the currently active input method editor for the remote environment.	leadfoot/Command
getAlertText(): Promise.<string> Gets the text displayed in the currently active alert pop-up.	leadfoot/Command
getAllWindowHandles(): Promise.<Array.<string>> Gets a list of identifiers for all currently open windows.	leadfoot/Command
getApplicationCacheStatus(): Promise.<number> Gets the current state of the HTML5 application cache for the current page.	leadfoot/Command
getAttribute(name: string): Promise.<string> Gets an attribute of the element.	leadfoot/Command
getAvailableImeEngines(): Promise.<Array.<string>> Gets a list of input method editor engines available to the remote environment.	leadfoot/Command
getAvailableLogTypes(): Promise.<Array.<string>> Gets the types of logs that are currently available for retrieval from the remote environment.	leadfoot/Command
getComputedStyle(propertyName: string): Promise.<string> Gets a CSS computed property value for the element.	leadfoot/Command
getCookies(): Promise.<Array.<WebDriverCookie>> Gets all cookies set on the current page.	leadfoot/Command
getCurrentUrl(): Promise.<string> Gets the URL that is loaded in the focused window/frame.	leadfoot/Command
getCurrentWindowHandle(): Promise.<string> Gets the identifier for the window that is currently focused.	leadfoot/Command
getExecuteAsyncTimeout(): Promise.<number> Gets the timeout for leadfoot/Session#executeAsync calls.	leadfoot/Command
getFindTimeout(): Promise.<number> Gets the timeout for leadfoot/Session#find calls.	leadfoot/Command
getGeolocation(): Promise.<Geolocation> Gets the current geographical location of the remote environment.	leadfoot/Command
getLocalStorageItem(key: string): Promise.<string> Gets a value from local storage for the focused window/frame.	leadfoot/Command
getLocalStorageKeys(): Promise.<Array.<string>> Gets the list of keys set in local storage for the focused window/frame.	leadfoot/Command
getLocalStorageLength(): Promise.<number> Gets the number of keys set in local storage for the focused window/frame.	leadfoot/Command
getLogsFor(type: string): Promise.<Array.<LogEntry>> Gets all logs from the remote environment of the given type.	leadfoot/Command
getOrientation(): Promise.<string> Gets the current screen orientation.	leadfoot/Command
getPageLoadTimeout(): Promise.<number> Gets the timeout for leadfoot/Session#get calls.	leadfoot/Command
getPageSource(): Promise.<string> Gets the HTML loaded in the focused window/frame.	leadfoot/Command
getPageTitle(): Promise.<string> Gets the title of the top-level browsing context of the current window or tab.	leadfoot/Command
getPosition(): Promise.<{x: number, y: number}> Gets the position of the element relative to the top-left corner of the document, taking into account scrolling and CSS transformations (if they are supported).	leadfoot/Command
getProperty(name: string): Promise.<any> Gets a property of the element.	leadfoot/Command
getSessionStorageItem(key: string): Promise.<string> Gets a value from session storage for the focused window/frame.	leadfoot/Command
getSessionStorageKeys(): Promise.<Array.<string>> Gets the list of keys set in session storage for the focused window/frame.	leadfoot/Command
getSessionStorageLength(): Promise.<number> Gets the number of keys set in session storage for the focused window/frame.	leadfoot/Command
getSize(): Promise.<{width: number, height: number}> Gets the size of the element, taking into account CSS transformations (if they are supported).	leadfoot/Command
getSpecAttribute(name: string): Promise.<string> Gets a property or attribute of the element according to the WebDriver specification algorithm.	leadfoot/Command
getTagName(): Promise.<string> Gets the tag name of the element.	leadfoot/Command
getTimeout(type: string): Promise.<number> Gets the current value of a timeout for the session.	leadfoot/Command
getVisibleText(): Promise.<string> Gets the visible text within the element.	leadfoot/Command
getWindowPosition(windowHandleopt: string): Promise.<{x: number, y: number}> Gets the position of a window.	leadfoot/Command
getWindowSize(windowHandleopt: string): Promise.<{width: number, height: number}> Gets the dimensions of a window.	leadfoot/Command
goBack(): Promise.<void> Navigates the focused window/frame back one page using the browser’s navigation history.	leadfoot/Command
goForward(): Promise.<void> Navigates the focused window/frame forward one page using the browser’s navigation history.	leadfoot/Command
isDisplayed(): Promise.<boolean> Returns whether or not the element would be visible to an actual user.	leadfoot/Command
isEnabled(): Promise.<boolean> Returns whether or not a form element can be interacted with.	leadfoot/Command
isImeActivated(): Promise.<boolean> Returns whether or not an input method editor is currently active in the remote environment.	leadfoot/Command
isSelected(): Promise.<boolean> Returns whether or not a form element is currently selected (for drop-down options and radio buttons), or whether or not the element is currently checked (for checkboxes).	leadfoot/Command
longTap(element: leadfoot/Element): Promise.<void> Performs a long-tap gesture on an element.	leadfoot/Command
maximizeWindow(windowHandleopt: string): Promise.<void> Maximises a window according to the platform’s window system behaviour.	leadfoot/Command
moveFinger(x: number, y: number): Promise.<void> Moves the last depressed finger to a new point on the touch screen.	leadfoot/Command
moveMouseTo(elementopt: Element, xOffsetopt: number, yOffsetopt: number): Promise.<void> Moves the remote environment’s mouse cursor to the specified element or relative position.	leadfoot/Command
pressFinger(x: number, y: number): Promise.<void> Depresses a new finger at the given point on a touch screen device without releasing it.	leadfoot/Command
pressKeys(keys: string\|Array.<string>): Promise.<void> Types into the focused window/frame/element.	leadfoot/Command
pressMouseButton(buttonopt: number): Promise.<void> Depresses a mouse button without releasing it.	leadfoot/Command
quit(): Promise.<void> Terminates the session.	leadfoot/Command
refresh(): Promise.<void> Reloads the current browser window/frame.	leadfoot/Command
releaseFinger(x: number, y: number): Promise.<void> Releases whatever finger exists at the given point on a touch screen device.	leadfoot/Command
releaseMouseButton(buttonopt: number): Promise.<void> Releases a previously depressed mouse button.	leadfoot/Command
setCookie(cookie: WebDriverCookie): Promise.<void> Sets a cookie on the current page.	leadfoot/Command
setExecuteAsyncTimeout(ms: number): Promise.<void> Sets the timeout for leadfoot/Session#executeAsync calls.	leadfoot/Command
setFindTimeout(ms: number): Promise.<void> Sets the timeout for leadfoot/Session#find calls.	leadfoot/Command
setGeolocation(location: Geolocation): Promise.<void> Sets the geographical location of the remote environment.	leadfoot/Command
setLocalStorageItem(key: string, value: string): Promise.<void> Sets a value in local storage for the focused window/frame.	leadfoot/Command
setOrientation(orientation: string): Promise.<void> Sets the screen orientation.	leadfoot/Command
setPageLoadTimeout(ms: number): Promise.<void> Sets the timeout for leadfoot/Session#get calls.	leadfoot/Command
setSessionStorageItem(key: string, value: string): Promise.<void> Sets a value in session storage for the focused window/frame.	leadfoot/Command
setTimeout(type: string, ms: number): Promise.<void> Sets the value of a timeout for the session.	leadfoot/Command
setWindowPosition(windowHandleopt: string, x: number, y: number): Promise.<void> Sets the position of a window.	leadfoot/Command
setWindowSize(windowHandleopt: string, width: number, height: number): Promise.<void> Sets the dimensions of a window.	leadfoot/Command
sleep(ms: number): leadfoot/Command.<void> Pauses execution of the next command in the chain for `ms` milliseconds.	leadfoot/Command
submit(): Promise.<void> Submits the element, if it is a form, or the form belonging to the element, if it is a form element.	leadfoot/Command
switchToFrame(id: string\|number\|null\|Element): Promise.<void> Switches the currently focused frame to a new frame.	leadfoot/Command
switchToParentFrame(): Promise.<void> Switches the currently focused frame to the parent of the currently focused frame.	leadfoot/Command
switchToWindow(handle: string): Promise.<void> Switches the currently focused window to a new window.	leadfoot/Command
takeScreenshot(): Promise.<Buffer> Gets a screenshot of the focused window and returns it in PNG format.	leadfoot/Command
tap(element: leadfoot/Element): Promise.<void> Taps an element on a touch screen device.	leadfoot/Command
then(callbackopt: function, errbackopt: function): leadfoot/Command.<any> Adds a callback to be invoked once the previously chained operation has completed.	leadfoot/Command
touchScroll(elementopt: Element, xOffsetopt: number, yOffsetopt: number): Promise.<void> Scrolls the currently focused window on a touch screen device.	leadfoot/Command
type(value: string\|Array.<string>): Promise.<void> Types into the element.	leadfoot/Command
typeInPrompt(text: string\|Array.<string>): Promise.<void> Types into the currently active prompt pop-up.	leadfoot/Command
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/Command
waitForDeletedByCssSelector(selector: string): Promise.<void> Waits for all elements in the currently active window/frame matching the given CSS selector to be destroyed.	leadfoot/Command
waitForDeletedById(id: string): Promise.<void> Waits for all elements in the currently active window/frame matching the given ID to be destroyed.	leadfoot/Command
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/Command
waitForDeletedByName(name: string): Promise.<void> Waits for all elements in the currently active window/frame matching the given name attribute to be destroyed.	leadfoot/Command
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/Command
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/Command
waitForDeletedByXpath(path: string): Promise.<void> Waits for all elements in the currently active window/frame matching the given XPath selector to be destroyed.	leadfoot/Command

(readonly) context: Array.<leadfoot/Element>

The filtered elements that will be used if an element-specific method is invoked. Note that this property is not valid until the parent Command has been settled. The context array also has two additional properties:

isSingle (boolean): If true, the context will always contain a single element. This is used to differentiate between methods that should still return scalar values (find) and methods that should return arrays of values even if there is only one element in the context (findAll).
depth (number): The depth of the context within the command chain. This is used to prevent traversal into higher filtering levels by leadfoot/Command#end.

Source

Command.js, line 430

(readonly) parent: leadfoot/Command

The parent Command of the Command, if one exists.

Source

Command.js, line 408

(readonly) promise: Promise.<any>

The underlying Promise for the Command.

Source

Command.js, line 448

(readonly) session: leadfoot/Session

The parent Session of the Command.

Source

Command.js, line 419

(static) Command.addElementMethod(target: leadfoot/Command, key: string)

Augments target with a method that will call key on all context elements stored within target. This can be used to easily add new methods from any custom object that implements the Element API to any target object that implements the Command API.

Functions that are copied may have the following extra properties in order to change the way that Command works with these functions:

createsContext (boolean): If this property is specified, the return value from the function will be used as the new context for the returned Command.

Parameters

Name	Type
`target`	leadfoot/Command
`key`	string

Source

Command.js, line 666

(static) Command.addSessionMethod(target: leadfoot/Command, key: string, originalFn: function)

Augments target with a conversion of the originalFn method that enables its use with a Command object. This can be used to easily add new methods from any custom object that implements the Session API to any target object that implements the Command API.

Functions that are copied may have the following extra properties in order to change the way that Command works with these functions:

createsContext (boolean): If this property is specified, the return value from the function will be used as the new context for the returned Command.
usesElement (boolean): If this property is specified, element(s) from the current context will be used as the first argument to the function, if the explicitly specified first argument is not already an element.

Parameters

Name	Type
`target`	leadfoot/Command
`key`	string
`originalFn`	function

Source

Command.js, line 603

acceptAlert(): Promise.<void>

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

Source

Session.js, line 1461

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.

Source

Session.js, line 801

cancel(): leadfoot/Command.<void>

Cancels all outstanding chained operations of the Command. Calling this method will cause this command and all subsequent chained commands to fail with a CancelError.

Source

Command.js, line 575

catch(errback: function): leadfoot/Command.<any>

Adds a callback to be invoked when any of the previously chained operations have failed.

Parameters

Name	Type
`errback`	function

Source

Command.js, line 555

clearCookies(): Promise.<void>

Clears all cookies for the current page.

Source

Session.js, line 1174

clearLocalStorage(): Promise.<void>

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

Source

Session.js, line 2045

clearSessionStorage(): Promise.<void>

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

Source

Session.js, line 2099

clearValue(): Promise.<void>

Clears the value of a form element.

Source

Element.js, line 312

click(): Promise.<void>

Clicks the element. This method works on both mouse and touch platforms.

Source

Element.js, line 182

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.

Source

Session.js, line 1558

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.

Source

Session.js, line 881

deactivateIme(): Promise.<void>

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

Source

Session.js, line 790

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.

Source

Session.js, line 1207

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.

Source

Session.js, line 2062

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.

Source

Session.js, line 2116

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.

Source

Session.js, line 1471

doubleClick(): Promise.<void>

Double-clicks the primary mouse button.

Source

Session.js, line 1624

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.

Source

Session.js, line 1763

end(numCommandsToPopopt: number): leadfoot/Command.<void>

Ends the most recent filtering operation in the current Command chain and returns the set of matched elements to the previous state. This is equivalent to the jQuery#end method.

Parameters

Name	Type	Attributes	Description
`numCommandsToPop`	number	optional	The number of element contexts to pop. Defaults to 1.

Example

command
  .findById('parent') // sets filter to #parent
    .findByClassName('child') // sets filter to all .child inside #parent
      .getVisibleText()
      .then(function (visibleTexts) {
        // all the visible texts from the children
      })
      .end() // resets filter to #parent
    .end(); // resets filter to nothing (the whole document)

Source

Command.js, line 489

equals(other: leadfoot/Element): Promise.<boolean>

Determines if this element is equal to another element.

Parameters

Name	Type
`other`	leadfoot/Element

Source

Element.js, line 412

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

leadfoot/Session#executeAsync to execute code that returns values asynchronously.

Source

Session.js, line 679

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

leadfoot/Session#execute to execute code that returns values synchronously.
leadfoot/Session#setExecuteAsyncTimeout to set the time until an asynchronous script is considered timed out.

Source

Session.js, line 729

finally(callback: function): leadfoot/Command.<any>

Adds a callback to be invoked once the previously chained operations have resolved.

Parameters

Name	Type
`callback`	function

Source

Command.js, line 565

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.

Source

Session.js, line 1281

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.

Source

Session.js, line 1321

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.

Source

Session.js, line 2208

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.

Source

Session.js, line 2217

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.

Source

Session.js, line 2235

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.

Source

Session.js, line 2226

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.

Source

Session.js, line 2244

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.

Source

Session.js, line 2254

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.

Source

Session.js, line 2263

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.

Source

Session.js, line 2135

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.

Source

Session.js, line 2144

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.

Source

Session.js, line 2153

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.

Source

Session.js, line 2171

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.

Source

Session.js, line 2162

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.

Source

Session.js, line 2180

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.

Source

Session.js, line 2190

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.

Source

Session.js, line 2199

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.

Source

Session.js, line 2273

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.

Source

Session.js, line 2291

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.

Source

Session.js, line 2303

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.

Source

Session.js, line 2315

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.

Source

Session.js, line 2339

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.

Source

Session.js, line 2327

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.

Source

Session.js, line 2351

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.

Source

Session.js, line 2364

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.

Source

Session.js, line 2376

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.

Source

Session.js, line 1802

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

Navigates the focused window/frame to a new URL.

Parameters

Name	Type
`url`	string

Source

Session.js, line 616

getActiveElement(): Promise.<leadfoot/Element>

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

Source

Session.js, line 1355

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.

Source

Session.js, line 770

getAlertText(): Promise.<string>

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

Source

Session.js, line 1436

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

Gets a list of identifiers for all currently open windows.

Source

Session.js, line 590

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).

Source

Session.js, line 1924

getAttribute(name: string): Promise.<string>

Gets an attribute of the element.

Parameters

Name	Type	Description
`name`	string	The name of the attribute.

Returns

The value of the attribute, or null if no such attribute exists.

See

Element#getProperty to retrieve an element property.

Source

Element.js, line 391

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.

Source

Session.js, line 760

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

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

Source

Session.js, line 1909

getComputedStyle(propertyName: string): Promise.<string>

Gets a CSS computed property value for the element.

Parameters

Name	Type	Description
`propertyName`	string	The CSS property to retrieve. This argument must be hyphenated, not camel-case.

Source

Element.js, line 535

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

Gets all cookies set on the current page.

Source

Session.js, line 1093

getCurrentUrl(): Promise.<string>

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

Source

Session.js, line 606

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.

getFindTimeout(): Promise.<number>

Gets the timeout for leadfoot/Session#find calls.

Source

Session.js, line 2499

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.

Source

Session.js, line 1829

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.

Source

Session.js, line 2053

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

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

Source

Session.js, line 2027

getLocalStorageLength(): Promise.<number>

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

Source

Session.js, line 2071

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.

Source

Session.js, line 1875

getOrientation(): Promise.<string>

Gets the current screen orientation.

Returns

Either 'portrait' or 'landscape'.

Source

Session.js, line 1411

getPageLoadTimeout(): Promise.<number>

Gets the timeout for leadfoot/Session#get calls.

Source

Session.js, line 2516

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.

Source

Session.js, line 1244

getPageTitle(): Promise.<string>

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

Source

Session.js, line 1260

getPosition(): Promise.<{x: number, y: number}>

Gets the position of the element relative to the top-left corner of the document, taking into account scrolling and CSS transformations (if they are supported).

Source

Element.js, line 476

getProperty(name: string): Promise.<any>

Gets a property of the element.

Parameters

Name	Type	Description
`name`	string	The name of the property.

Returns

The value of the property.

See

Element#getAttribute to retrieve an element attribute.

Source

Element.js, line 402

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.

Source

Session.js, line 2107

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

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

Source

Session.js, line 2081

getSessionStorageLength(): Promise.<number>

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

Source

Session.js, line 2125

getSize(): Promise.<{width: number, height: number}>

Gets the size of the element, taking into account CSS transformations (if they are supported).

Source

Element.js, line 500

getSpecAttribute(name: string): Promise.<string>

Gets a property or attribute of the element according to the WebDriver specification algorithm. Use of this method is not recommended; instead, use leadfoot/Element#getAttribute to retrieve DOM attributes and leadfoot/Element#getProperty to retrieve DOM properties.

This method uses the following algorithm on the server to determine what value to return:

If name is 'style', returns the style.cssText property of the element.
If the attribute exists and is a boolean attribute, returns 'true' if the attribute is true, or null otherwise.
If the element is an <option> element and name is 'value', returns the value attribute if it exists, otherwise returns the visible text content of the option.
If the element is a checkbox or radio button and name is 'selected', returns 'true' if the element is checked, or null otherwise.
If the returned value is expected to be a URL (e.g. element is <a> and attribute is href), returns the fully resolved URL from the href/src property of the element, not the attribute.
If name is 'class', returns the className property of the element.
If name is 'readonly', returns 'true' if the readOnly property is true, or null otherwise.
If name corresponds to a property of the element, and the property is not an Object, return the property value coerced to a string.
If name corresponds to an attribute of the element, return the attribute value.

Parameters

Name	Type	Description
`name`	string	The property or attribute name.

Returns

The value of the attribute as a string, or null if no such property or attribute exists.

Source

Element.js, line 361

getTagName(): Promise.<string>

Gets the tag name of the element. For HTML documents, the value is always lowercase.

Source

Element.js, line 292

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.

Source

Session.js, line 510

getVisibleText(): Promise.<string>

Gets the visible text within the element. <br> elements are converted to line breaks in the returned text, and whitespace is normalised per the usual XML/HTML whitespace normalisation rules.

Source

Element.js, line 225

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.

Source

Session.js, line 1060

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.

Source

Session.js, line 979

goBack(): Promise.<void>

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

Source

Session.js, line 643

goForward(): Promise.<void>

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

Source

Session.js, line 633

isDisplayed(): Promise.<boolean>

Returns whether or not the element would be visible to an actual user. This means that the following types of elements are considered to be not displayed:

Elements with display: none
Elements with visibility: hidden
Elements positioned outside of the viewport that cannot be scrolled into view
Elements with opacity: 0
Elements with no offsetWidth or offsetHeight

Source

Element.js, line 440

isEnabled(): Promise.<boolean>

Returns whether or not a form element can be interacted with.

Source

Element.js, line 331

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.

Source

Session.js, line 780

isSelected(): Promise.<boolean>

Returns whether or not a form element is currently selected (for drop-down options and radio buttons), or whether or not the element is currently checked (for checkboxes).

Source

Element.js, line 322

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.

Source

Session.js, line 1780

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.

Source

Session.js, line 1080

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.

Source

Session.js, line 1699

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.

Source

Session.js, line 1496

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.

Source

Session.js, line 1669

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.

Source

Session.js, line 1392

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.

Source

Session.js, line 1585

quit(): Promise.<void>

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

Source

Session.js, line 1933

refresh(): Promise.<void>

Reloads the current browser window/frame.

Source

Session.js, line 652

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.

Source

Session.js, line 1685

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.

Source

Session.js, line 1605

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

Sets a cookie on the current page.

Parameters

Name	Type
`cookie`	WebDriverCookie

Source

Session.js, line 1122

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.

Source

Session.js, line 2490

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.

Source

Session.js, line 2507

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.

Source

Session.js, line 1852

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.

Source

Session.js, line 2035

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

Sets the screen orientation.

Parameters

Name	Type	Description
`orientation`	string	Either 'portrait' or 'landscape'.

Source

Session.js, line 1423

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.

Source

Session.js, line 2524

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.

Source

Session.js, line 2089

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.

Source

Session.js, line 526

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.

Source

Session.js, line 1033

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.

Source

Session.js, line 922

sleep(ms: number): leadfoot/Command.<void>

Pauses execution of the next command in the chain for ms milliseconds.

Parameters

Name	Type	Description
`ms`	number	Time to delay, in milliseconds.

Source

Command.js, line 465

submit(): Promise.<void>

Submits the element, if it is a form, or the form belonging to the element, if it is a form element.

Source

Element.js, line 204

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.

Source

Session.js, line 817

switchToParentFrame(): Promise.<void>

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

Source

Session.js, line 846

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.

Source

Session.js, line 834

takeScreenshot(): Promise.<Buffer>

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

Returns

A buffer containing a PNG image.

Source

Session.js, line 747

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.

Source

Session.js, line 1652

then(callbackopt: function, errbackopt: function): leadfoot/Command.<any>

Adds a callback to be invoked once the previously chained operation has completed.

This method is compatible with the Promise#then API, with two important differences:

The context (this) of the callback is set to the Command object, rather than being undefined. This allows promise helpers to be created that can retrieve the appropriate session and element contexts for execution.
A second non-standard setContext argument is passed to the callback. This setContext function can be called at any time before the callback fulfills its return value and expects either a single leadfoot/Element or an array of Elements to be provided as its only argument. The provided element(s) will be used as the context for subsequent element method invocations (click, etc.). If the setContext method is not called, the element context from the parent will be passed through unmodified.

Parameters

Name	Type	Attributes
`callback`	function	optional
`errback`	function	optional

Source

Command.js, line 524

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.

Source

Session.js, line 1724

type(value: string|Array.<string>): Promise.<void>

Types into the element. This method works the same as the leadfoot/Session#pressKeys method except that any modifier keys are automatically released at the end of the command. This method should be used instead of leadfoot/Session#pressKeys to type filenames into file upload fields.

Since 1.5, if the WebDriver server supports remote file uploads, and you type a path to a file on your local computer, that file will be transparently uploaded to the remote server and the remote filename will be typed instead. If you do not want to upload local files, use leadfoot/Session#pressKeys instead.

Parameters

Name	Type	Description
`value`	string\|Array.<string>	The text to type in the remote environment. See leadfoot/Session#pressKeys for more information.

Source

Element.js, line 252

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.

Source

Session.js, line 1446

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.

Source

Session.js, line 2404

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.

Source

Session.js, line 2414

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.

Source

Session.js, line 2423

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.

Source

Session.js, line 2442

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.

Source

Session.js, line 2432

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.

Source

Session.js, line 2452

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.

Source

Session.js, line 2462

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.

Source

Session.js, line 2471

leadfoot/Command

Inheritance

new (require("leadfoot/Command"))(parent: leadfoot/Command|leadfoot/Session, initialiser: function, errbackopt: function)

Parameters

Source

All Properties

All Methods

Properties

(readonly) context: Array.<leadfoot/Element>

Source

(readonly) parent: leadfoot/Command

Source

(readonly) promise: Promise.<any>

Source

(readonly) session: leadfoot/Session

Source

Methods

(static) Command.addElementMethod(target: leadfoot/Command, key: string)

Parameters

Source

(static) Command.addSessionMethod(target: leadfoot/Command, key: string, originalFn: function)

Parameters

Source

acceptAlert(): Promise.<void>

Source

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

Parameters

Source

cancel(): leadfoot/Command.<void>

Source

catch(errback: function): leadfoot/Command.<any>

Parameters

Source

clearCookies(): Promise.<void>

Source

clearLocalStorage(): Promise.<void>

Source

clearSessionStorage(): Promise.<void>

Source

clearValue(): Promise.<void>

Source

click(): Promise.<void>

Source

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

Parameters

Source

closeCurrentWindow(): Promise.<void>

Source

deactivateIme(): Promise.<void>

Source

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

Parameters

Source

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

Parameters

Source

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

Parameters

Source

dismissAlert(): Promise.<void>

Source

doubleClick(): Promise.<void>

Source

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

Parameters

Source

end(numCommandsToPopopt: number): leadfoot/Command.<void>

Parameters

Example

Source

equals(other: leadfoot/Element): Promise.<boolean>

Parameters

Source

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

Parameters

Returns

See

Source

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

Parameters