Pan gesture example with Locator.dispatchEvent
This example demonstrates emulating a pan gesture by dispatching touchstart, touchmove, and touchend events to a locator. The pan function accepts a locator, optional deltaX, deltaY, and steps parameters (steps defaults to 5). Touch objects contain identifier, clientX, and clientY properties. The touchstart and touchmove events include touches, changedTouches, and targetTouches arrays. JavaScript: async function pan(locator, deltaX=0, deltaY=0, steps=5) dispatches events with calculated touch coordinates moving from center position. For touchstart: one touch at centerX, centerY. For touchmove: steps iterations with touches moving by deltaX*i/steps, deltaY*i/steps. For touchend: no arguments or empty touches arrays.
Locator.dispatchEvent does not set Event.isTrusted
The Locator.dispatchEvent method does not set the Event.isTrusted property. If a web page relies on the isTrusted property to validate that an event is trusted, users must disable the isTrusted check during tests.
Pinch gesture example with Locator.dispatchEvent
This example demonstrates emulating a pinch (zoom) gesture by dispatching touchstart, touchmove, and touchend events with two touch points. The pinch function accepts a locator and an options object with deltaX (default 50), steps (default 5), and direction ('in' or 'out') properties. For pinch 'in', touches start with maximum offset (deltaX) and converge toward center. For pinch 'out', touches start close and diverge away. Each touch has identifier (0 or 1), clientX, and clientY. touchstart has two touches positioned symmetrically on left and right of center. touchmove has steps iterations where offset changes based on direction. touchend has empty touches arrays.
Legacy touch events are handled via Locator.dispatchEvent
Web applications that handle legacy touch events (swipe, pinch, tap gestures) can be tested by manually dispatching TouchEvent objects to the page using Locator.dispatchEvent. The method accepts a string event type ('touchstart', 'touchmove', 'touchend') and an event object containing touches, changedTouches, and targetTouches arrays of Touch objects.
Locator.allTextContents() returns array of text contents
The allTextContents() method on a locator returns an array of text contents for all matching elements.
Locator.waitFor() with state and timeout parameters
The waitFor() method on a locator accepts an options object. The state property specifies the desired state (e.g., 'hidden'). The timeout property specifies the maximum time in milliseconds to wait (e.g., 10000).
Locator.contentFrame() for iframe element access
The contentFrame() method on a locator returns the Frame object for an iframe element, allowing access to elements within the iframe.
Frame.getByRole() semantic locator method
Frame.getByRole() is a non-async method that returns Locator. Parameters: role (ARIA role string). Options: exact (boolean), description (string, filter by accessible description). Targets elements by their semantic ARIA role attribute.
Frame.getByTestId() locator method
Frame.getByTestId() is a non-async method that returns Locator. Parameters: testId (test ID value to match). Targets elements by their test ID attribute.
Frame.getByTitle() locator method
Frame.getByTitle() is a non-async method that returns Locator. Parameters: text (title text to match). Options: exact (boolean). Targets elements by their title attribute.
Frame.getByText() locator method
Frame.getByText() is a non-async method that returns Locator. Parameters: text (text content to match). Options: exact (boolean, exact text match). Targets elements by their text content.
Frame.locator() method parameters and return type
Frame.locator() is a non-async method that returns Locator. Parameters: selector (CSS/XPath selector). Options: has (Locator for filtering), hasNot (Locator for negative filtering), hasNotText (string or regex for negative text filtering).
Locator methods targeting semantic/accessibility attributes
The following Frame locator methods target elements by semantic/accessibility attributes: getByAltText (alt text attribute), getByLabel (associated label), getByPlaceholder (placeholder attribute), getByRole (ARIA role attribute), getByTitle (title attribute).
Frame.get() method in JavaScript
Frame.get() is a non-async method available in JavaScript that returns Locator. Parameters: by (a By object built with Playwright.by). This is a page-free locator method.
Frame.getByAltText() semantic locator method
Frame.getByAltText() is a non-async method that returns Locator. Parameters: text (alt text to match). Options: exact (boolean, exact text match). Targets elements by their alt text attribute, a semantic/accessibility attribute.
Frame.getByLabel() semantic locator method
Frame.getByLabel() is a non-async method that returns Locator. Parameters: text (label text to match). Options: exact (boolean). Targets elements by their associated label, a semantic/accessibility attribute.
Frame.getByPlaceholder() semantic locator method
Frame.getByPlaceholder() is a non-async method that returns Locator. Parameters: text (placeholder text to match). Options: exact (boolean). Targets elements by their placeholder attribute, a semantic/accessibility attribute.
Locator.get() method
Locator.get() is a synchronous method available in JavaScript that returns a new Locator. Takes parameter 'by' of type By (a page-free locator built with Playwright.by).
Locator.blur() method
Locator.blur() is an async method that calls blur on the matching element. Supports timeout and signal options.
Locator.all() method
Locator.all() is an async method that returns an array of Locators pointing to each matching element. It does not wait for elements to match the locator and immediately returns whatever is present in the page. Does not produce reliable results when the list of elements changes dynamically.
Locator.allInnerTexts() method
Locator.allInnerTexts() is an async method that returns an array of strings containing the node.innerText values for all matching elements.
Locator.allTextContents() method
Locator.allTextContents() is an async method that returns an array of strings containing the node.textContent values for all matching elements.
Locator.and() method
Locator.and() is a synchronous method that returns a new Locator matching both this locator and the argument locator. Takes parameter 'locator' of type Locator. In Python, the method is named and_().
Locator.ariaSnapshot() method
Locator.ariaSnapshot() is an async method that returns a string containing the ARIA snapshot of the given element. The snapshot is represented using YAML markup language with role names and optional accessible names as keys, and text content or child element arrays as values. Supports options: mode ('ai' or 'default', defaults to 'default'), timeout, signal, depth (integer limiting snapshot depth), and boxes (boolean, defaults to false; when true appends bounding box as [box=x,y,width,height]).
Locator.ariaSnapshotJSON() method
Locator.ariaSnapshotJSON() is an async method available in JavaScript that returns a Serializable JSON object of the ARIA snapshot instead of YAML. The result is a list of nodes with properties: role, name, text, children, boolean state flags (checked, disabled, expanded, active, invalid, pressed, selected), value properties (level), additional element properties (url for links, placeholder for textboxes), ref (element reference for AI-optimized snapshots), cursor ('pointer' for clickable elements in AI-optimized snapshots), and box (bounding box when boxes option is set). Supports options: mode ('ai' or 'default', defaults to 'default'), timeout, signal, depth (integer), and boxes (boolean, defaults to false).
Locator.boundingBox() method
Locator.boundingBox() is an async method that returns the bounding box of the element matching the locator, or null if the element is not visible. Returns an object with properties: x (float, x coordinate in pixels), y (float, y coordinate in pixels), width (float, width in pixels), height (float, height in pixels). The bounding box is calculated relative to the main frame viewport. Supports timeout and signal options.
Locator.count() method
Locator.count() is an async method that returns an integer representing the number of elements matching the locator.
Locator.describe() method
Locator.describe() is a synchronous method that sets a description for the locator used in trace viewer and reports. Takes parameter 'description' of type string. Returns the same Locator pointing to the same element.
Locator.description() method
Locator.description() is a synchronous method that returns the locator description previously set with Locator.describe(), or null if no custom description has been set. Available in Python, Java, C#, and JavaScript.
Locator.elementHandle() method
Locator.elementHandle() is an async method that resolves the locator to the first matching DOM element as an ElementHandle. Waits for an element if none match initially. Throws if multiple elements match. Discouraged in favor of using Locators and web assertions. Supports timeout and signal options.
Locator.elementHandles() method
Locator.elementHandles() is an async method that resolves the locator to all matching DOM elements as an array of ElementHandles. Returns an empty array if no elements match. Discouraged in favor of using Locators and web assertions.
Locator.contentFrame() method
Locator.contentFrame() is a synchronous method that returns a FrameLocator object pointing to the same iframe as the locator. Useful for obtaining a FrameLocator from a Locator object obtained elsewhere to interact with content inside the frame. Reverse of FrameLocator.owner().
Locator.evaluateAll() method
Locator.evaluateAll() is an async method that executes JavaScript code in the page with an array of all matching elements as the first argument and optional arg parameter as the second. Returns the serializable return value of the expression. If expression returns a Promise, waits for it.
Locator.evaluateHandle() method
Locator.evaluateHandle() is an async method that executes JavaScript code in the page with the matching element as the first argument and optional arg parameter as the second, returning a JSHandle with the result. Similar to Locator.evaluate() but returns JSHandle instead of serializable value. Supports options: exposeFunctions and timeout.
Locator.filter() method
Locator.filter() is a synchronous method that narrows an existing locator according to options, for example by text content. Can be chained multiple times. Returns a new Locator. Supports options: has, hasText, hasNot (since v1.33), hasNotText (since v1.33), and visible (since v1.51).
Locator.first() method
Locator.first() is a synchronous method that returns a new Locator pointing to the first matching element.
Locator.focus() method
Locator.focus() is an async method that calls focus on the matching element. Supports timeout and signal options.
Locator.frameLocator() method
Locator.frameLocator() is a synchronous method that returns a FrameLocator allowing element location within an iframe. Takes parameter 'selector' of type string (selector to find iframe). Used when working with iframes to enter the iframe and locate elements within it.
Locator.getByAltText() method
Locator.getByAltText() is a synchronous method that returns a new Locator targeting elements by their alt text. Takes parameter 'text' (text or regex pattern to match). Supports option 'exact' (boolean, exact string matching).
Locator.getByLabel() method
Locator.getByLabel() is a synchronous method that returns a new Locator targeting form elements by their associated label text. Takes parameter 'text' (text or regex pattern to match). Supports option 'exact' (boolean, exact string matching).
Locator.getByPlaceholder() method
Locator.getByPlaceholder() is a synchronous method that returns a new Locator targeting input elements by their placeholder text. Takes parameter 'text' (text or regex pattern to match). Supports option 'exact' (boolean, exact string matching).
Locator.getByRole() method
Locator.getByRole() is a synchronous method that returns a new Locator targeting elements by their ARIA role. Takes parameter 'role' (AriaRole enum value). Supports options: name, checked, selected, expanded, disabled, level, pressed, included, heading level, and description. Also supports option 'exact' for exact name matching.
Locator.getByTestId() method
Locator.getByTestId() is a synchronous method that returns a new Locator targeting elements by their data-testid attribute. Takes parameter 'testId' of type string.
Locator.getByText() method
Locator.getByText() is a synchronous method that returns a new Locator targeting elements by their text content. Takes parameter 'text' (text or regex pattern to match). Supports option 'exact' (boolean, exact string matching).
Locator.getByTitle() method
Locator.getByTitle() is a synchronous method that returns a new Locator targeting elements by their title attribute. Takes parameter 'text' (text or regex pattern to match). Supports option 'exact' (boolean, exact string matching).
Locator.hideHighlight() method
Locator.hideHighlight() is an async method that hides the element highlight previously added by Locator.highlight().
Locator.highlight() method
Locator.highlight() is an async method that highlights the corresponding element(s) on the screen by adding a visual outline. Returns a Disposable. Useful for debugging. Supports option 'style' (inline CSS or object of CSS properties to apply to the highlight overlay, e.g., 'outline: 2px dashed red').
Locator.last() method
Locator.last() is a synchronous method that returns a new Locator pointing to the last matching element.
Locator.locator() method
Locator.locator() is a synchronous method that returns a new Locator representing elements found by the selector or locator within this locator. Takes parameter 'selectorOrLocator' of type string or Locator. Supports locator options including has, hasNot (v1.33+), and hasNotText (v1.33+).
Locator.normalize() method
Locator.normalize() is an async method that returns a new locator using best practices for referencing the matched element, prioritizing test IDs, ARIA roles, and other user-facing attributes over CSS selectors. Useful for converting implementation-detail selectors into more resilient, human-readable locators.
Locator.nth() method
Locator.nth() is a synchronous method that returns a new Locator pointing to the n-th matching element, zero-based. Takes parameter 'index' of type int. nth(0) selects the first element.
Locator.or() method
Locator.or() is a synchronous method that creates a new Locator matching elements that match one or both of two locators. In Python, the method is named or_(). Returns a new Locator. Note: if both locators match something, the resulting locator may have multiple matches, potentially causing a strictness violation.
Locator.or() method combines multiple locators with OR logic
The or() method takes an alternative Locator parameter and returns a locator that matches when either the original locator or the alternative locator matches. It was introduced in v1.33.
Locator.page property returns the owning Page
The page property of a Locator returns the Page object that the locator belongs to. It has been available since v1.19.
Locator.or() example combining locators with OR logic
Example showing Locator.or() usage:
```python
new_email = page.get_by_role("button", name="New")
dialog = page.get_by_text("Confirm security settings")
expect(new_email.or_(dialog).first).to_be_visible()
if (dialog.is_visible()):
page.get_by_role("button", name="Dismiss").click()
new_email.click()
```
This example creates two locators, combines them with or_(), selects the first matching element, and checks if it is visible.
input-timeout for JavaScript
The timeout parameter is type float. Maximum time in milliseconds. Defaults to 0 (no timeout). Default can be changed via actionTimeout option in config, or using BrowserContext.setDefaultTimeout or Page.setDefaultTimeout methods.
Locator.getByRole() option: selected
The selected option for getByRole() is a boolean attribute that is usually set by aria-selected. Available since v1.27.
Locator.getByAltText() usage
getByAltText() allows locating elements by their alt text. For example, it can find images by alt text like 'Playwright logo' matching <img alt='Playwright logo'>.
Locator.getByLabel() usage
getByLabel() allows locating input elements by the text of the associated <label> or aria-labelledby element, or by the aria-label attribute. For example, it can find inputs by label text like 'Username' or 'Password'.
Locator.getByPlaceholder() usage
getByPlaceholder() allows locating input elements by the placeholder text. For example, it can find an input with placeholder 'name@example.com' and fill it with a different email.