element

Queries the current context (Page or Element) for a single element matching the specified criteria. If multiple elements match, the first one is returned. Returns null if no element is found. Supports various selector strategies including CSS selectors, text content, ARIA roles, and more. Example: element(selector: ".my-class", text: "Submit")

​

Definition

element(
  selector: String
  text: String
  role: String
  label: String
  placeholder: String
  altText: String
  title: String
  testId: String
  filter: ElementFilterOptions
): Element

​

Arguments

​

selector: String

The CSS selector for the element. Example: "#username" for <input id="username" />.

​

text: String

Finds an element by its text content. Example: "Login" for <button>Login</button>.

​

role: String

Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.

​

label: String

Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.

​

placeholder: String

Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.

​

altText: String

Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.

​

title: String

Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.

​

testId: String

Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.

​

filter: ElementFilterOptions

Advanced filtering options for the element.

​

Returns

Element

Represents a single HTML element on a web page. It provides properties and methods to query the state and content of the element. The Element type implements the Node interface, inheriting common element-querying capabilities. Instances of Element are typically obtained by querying a Page or another Element.

​

Usage

This field is available on the Page object. Use it to query page information and content.