Version: 1.5

ElementHandle

Element Handle represents a remote element in the DOM of the browser. It implements useful methods for querying and interacting with DOM elements.

note

All methods on this class are asynchronous and must be used with await to wait for the result to fulfill from the browser.

Usage

my-test.perf.ts
step("Finding elements", async (b) => {
// Get a collection of handles to all h1,h2, and h3 nodes
let titles = await b.findElements(By.css("h1,h2,h3"));
for (let el of titles) {
// Fetch the text content from each
// Equiv of el.textContent.trim()
console.log(await el.text());
}
});

Methods

blur()

Clears focus from this element so that it will no longer receive keyboard inputs.

Parameters

clear()

Schedules a command to clear the value of this element. This command has no effect if the underlying DOM element is neither a text INPUT, SELECT, or a TEXTAREA element.

Parameters

click([, options])

Sends a click event to the element attached to this handle. If the element is currently outside the viewport it will first scroll to that element.

Parameters

dispose()

Parameters

findElement(locator)

Locates an element using the supplied Locator, returning an ElementHandle.

Parameters

findElements(locator)

Locates all elements using the supplied Locator, returning an array of ElementHandles.

Parameters

focus()

Sends focus to this element so that it receives keyboard inputs.

Parameters

getAttribute(key)

Fetches the value of an attribute on this element

Parameters

getId()

Fetches the remote elements id attribute.

Parameters

getProperty(key)

getProperty

Parameters

highlight()

Parameters

isDisplayed()

Checks whether the remote element is displayed in the DOM and is visible to the user without being hidden by CSS or occluded by another element.

Parameters

isEnabled()

Checks whether the remote element is enabled. Typically this means it does not have a disabled property or attribute applied.

Parameters

isSelectable()

Checks whether the remote element is selectable. An element is selectable if it is an <option> or input[type="checkbox"] or radio button.

Parameters

isSelected()

If the remote element is selectable (such as an <option> or input[type="checkbox"]) this methos will indicate whether it is selected.

Parameters

location()

Fetches the remote elements physical location as x and y.

Parameters

sendKeys(...keys)

Sends a series of key modifiers to the element.

Parameters

size()

Fetches the remote elements physical dimensions as width and height.

Parameters

tagName()

Fetches the remote elements tagName property.

Parameters

takeScreenshot([, options])

Takes a screenshot of this element and saves it to the results folder with a random name.

Parameters

text()

Retrieves the text content of this element excluding leading and trailing whitespace.

Parameters

type(text)

Sends a series of key presses to the element to simulate a user typing on the keyboard. Use this to fill in input fields.

Parameters

uploadFile(filepath)

Sets the value of the file input. The name of a file you uploaded with this script. Relative to the script.

Parameters

  • filepath string relative path to the file to be uploaded, separated by comma in case there're more than 1 file
  • returns: Promise<void>