class: locator

[10:14] (extern: com.lehman.aussom.ALocator) extends: object

The locator class is the primary element interaction surface in Playwright. It represents a lazy, auto-retrying reference to DOM elements. Instances are obtained by calling page.locator(), page.getByRole(), page.getByText(), and similar factory methods on page or locator objects. Locator methods auto-retry until the element is actionable or a timeout is exceeded.

Methods

• all ()

  Returns a list of locator objects for every element currently matching this locator's selector.

  • @r A list of locator objects.

• count ()

  Returns the number of elements currently matching this locator.

  • @r An int count of matching elements.

• first ()

  Returns a new locator narrowed to the first matching element.

  • @r A locator for the first match.

• last ()

  Returns a new locator narrowed to the last matching element.

  • @r A locator for the last match.

• nth (int Index)

  Returns a new locator narrowed to the nth matching element (0-indexed).

  • @p Index is an int zero-based index of the element to select.
  • @r A locator for the nth match.

• filter (string HasText)

  Returns a new locator filtered to elements whose visible text contains the given string.

  • @p HasText is a string of text that must be present in the element.
  • @r A filtered locator.

• and (object Other)

  Returns a new locator that matches elements satisfying both this locator and the given other locator.

  • @p Other is a locator to intersect with.
  • @r A combined locator.

• or (object Other)

  Returns a new locator that matches elements satisfying either this locator or the given other locator.

  • @p Other is a locator to union with.
  • @r A combined locator.

• newLocator (string Selector)

  Returns a new locator scoped to descendants matching the given selector within this locator's matched elements.

  • @p Selector is a string CSS or XPath selector.
  • @r A scoped locator.

• getByRole (string Role)

  Returns a locator for descendants matching the given ARIA role.

  • @p Role is a string ARIA role name.
  • @r A locator.

• getByText (string Text)

  Returns a locator for descendants by visible text.

  • @p Text is a string of visible text to match.
  • @r A locator.

• getByLabel (string Label)

  Returns a locator for form inputs by associated label text within scope.

  • @p Label is a string label text to match.
  • @r A locator.

• getByPlaceholder (string Placeholder)

  Returns a locator for form inputs by placeholder text within scope.

  • @p Placeholder is a string placeholder to match.
  • @r A locator.

• getByTestId (string TestId)

  Returns a locator for elements by test ID within scope.

  • @p TestId is a string test ID value.
  • @r A locator.

• click ()

  Clicks the element. Auto-waits for the element to be actionable.

  • @r This object.

• dblclick ()

  Double-clicks the element.

  • @r This object.

• hover ()

  Moves the mouse pointer over the element.

  • @r This object.

• tap ()

  Taps the element (touch gesture).

  • @r This object.

• fill (string Value)

  Clears any existing value and fills the element with the provided text. Works for input, textarea, and contenteditable elements.

  • @p Value is a string value to fill.
  • @r This object.

• clear ()

  Clears the value of an editable element (input, textarea, contenteditable).

  • @r This object.

• pressSequentially (string Text)

  Types text character-by-character, triggering keydown, keypress, and keyup events for each character.

  • @p Text is a string of text to type sequentially.
  • @r This object.

• press (string Key)

  Presses a single key or key combination on the element.

  • @p Key is a string key name (e.g. 'Enter', 'Tab', 'Control+a').
  • @r This object.

• check ()

  Checks the element if it is a checkbox or radio button.

  • @r This object.

• uncheck ()

  Unchecks the element if it is a checkbox.

  • @r This object.

• setChecked (bool Checked)

  Sets the checked state of a checkbox or radio button explicitly.

  • @p Checked is a bool - true to check, false to uncheck.
  • @r This object.

• selectOption (string Value)

  Selects one or more options in a select element by their value strings.

  • @p Value is a string option value to select.
  • @r A list of strings with the selected option values.

• focus ()

  Focuses the element.

  • @r This object.

• blur ()

  Removes focus from the element.

  • @r This object.

• dragTo (object Target)

  Drags this element to the target locator's element.

  • @p Target is a locator object representing the drop target.
  • @r This object.

• dispatchEvent (string Type)

  Dispatches a DOM event of the given type on the element.

  • @p Type is a string DOM event type (e.g. 'click', 'input', 'change').
  • @r This object.

• isVisible ()

  Returns whether the element is visible.

  • @r A bool - true if visible.

• isHidden ()

  Returns whether the element is hidden.

  • @r A bool - true if hidden.

• isEnabled ()

  Returns whether the element is enabled.

  • @r A bool - true if enabled.

• isDisabled ()

  Returns whether the element is disabled.

  • @r A bool - true if disabled.

• isChecked ()

  Returns whether the checkbox or radio button element is checked.

  • @r A bool - true if checked.

• isEditable ()

  Returns whether the element is editable (not readonly and not disabled).

  • @r A bool - true if editable.

• boundingBox ()

  Returns the bounding box of the element as a map with keys 'x', 'y', 'width', and 'height' in pixels.

  • @r A map with double values for x, y, width, height, or null if not visible.

• getAttribute (string Name)

  Returns the value of the named attribute on the element.

  • @p Name is a string attribute name.
  • @r A string attribute value, or null if the attribute does not exist.

• innerHTML ()

  Returns the element.innerHTML of the matched element.

  • @r A string with the inner HTML.

• innerText ()

  Returns the element.innerText of the matched element (visible text only).

  • @r A string with the inner text.

• textContent ()

  Returns the node.textContent of the matched element (includes hidden text).

  • @r A string with the text content.

• inputValue ()

  Returns the current value of an input, textarea, or select element.

  • @r A string with the current input value.

• allInnerTexts ()

  Returns the innerText of every element matching this locator.

  • @r A list of strings.

• allTextContents ()

  Returns the textContent of every element matching this locator.

  • @r A list of strings.

• evaluate (string Expression)

  Evaluates a JavaScript expression with the matched element as the first argument and returns the serialized result.

  • @p Expression is a string JavaScript expression (e.g. 'el => el.value').
  • @r The result of the expression.

• evaluateAll (string Expression)

  Evaluates a JavaScript expression against all matching elements and returns the serialized result.

  • @p Expression is a string JavaScript expression (e.g. 'els => els.length').
  • @r The result of the expression.

• waitFor (string State = "visible")

  Waits for the element to become visible (default state) or to satisfy another state such as 'hidden', 'attached', or 'detached'.

  • @p State is a string state to wait for: 'visible', 'hidden', 'attached', 'detached'.
  • @r This object.

• screenshot (string Path)

  Captures a screenshot of the matched element and saves it to disk.

  • @p Path is a string file path where the screenshot will be saved.
  • @r This object.

• highlight ()

  Highlights the matched element on screen for visual debugging.

  • @r This object.

• page ()

  Returns the page that this locator belongs to.

  • @r A page object.