PipeableElement

public class PipeableElement

PipeableElement represents a single element within a web page, accessible through a PipeablePage instance. It encapsulates the functionality to interact with and manipulate web elements within the context of a WKWebView.

Instances of PipeableElement are typically obtained through various query methods provided by PipeablePage, such as querySelector, querySelectorAll, xpathSelector, etc. These methods allow you to locate elements within the web page’s DOM based on CSS selectors or XPath expressions.

Once obtained, a PipeableElement can be used to perform a variety of actions on the corresponding web element, including clicking, typing text, focusing, blurring, and retrieving attributes or text content. It also provides methods to wait for and query further elements within its context, enabling detailed interaction and navigation within web pages.

Show on GitHub


                    
                    
                    click(timeout:)

Asynchronous

Clicks the element. Waits for the element to become visible, hovers it and clicks it. The click event is triggered in the innermost child of this element and propagated up.

Throws

An error if the click action fails.

Declaration

Swift

public func click(timeout: Int? = nil) async throws

Parameters


                                timeout

The maximum time in milliseconds to wait for the click action to complete. Defaults to 30000ms.

Show on GitHub


                    
                    
                    type(_:delay:)

Asynchronous

Types text into the element.

Throws

An error if typing fails.

Declaration

Swift

public func type(_ text: String, delay: Int = 10) async throws

Parameters

`text`	The text to type into the element.
`delay`	The delay between key presses in milliseconds. Defaults to 10ms.

Show on GitHub

focus() Asynchronous
Sets focus on the element.

Throws
An error if the element has been removed from the dom
Declaration
Swift

public func focus() async throws
Show on GitHub
blur() Asynchronous
Removes focus from the element.
Declaration
Swift

public func blur() async throws
Show on GitHub
contentFrame() Asynchronous
Gets the content frame for an iframe/frame element, if it exists.

Throws
An error if fetching the content frame fails.
Declaration
Swift

public func contentFrame() async throws -> PipeablePage?
Return Value

A PipeablePage representing the content frame, or nil if the element does not have a content frame.

Show on GitHub
textContent() Asynchronous
Retrieves the text content of the element.

Throws
An error if fetching the text content fails.
Declaration
Swift

public func textContent() async throws -> String?
Return Value

The text content of the element, or nil if it cannot be retrieved.

Show on GitHub


                    
                    
                    getAttribute(_:)

Asynchronous

Gets the value of a specified attribute of the element.

Throws

An error if fetching the attribute fails.

Declaration

Swift

public func getAttribute(_ attributeName: String) async throws -> String?

Parameters


                                attributeName

The name of the attribute to retrieve.

Return Value

The value of the attribute, or nil if the attribute does not exist.

Show on GitHub


                    
                    
                    querySelector(_:)

Asynchronous

Queries a single descendant element that matches a given CSS selector.

Throws

An error if the query fails.

Declaration

Swift

public func querySelector(_ selector: String) async throws -> PipeableElement?

Parameters


                                selector

The CSS selector to match.

Return Value

A PipeableElement representing the matched descendant, or nil if no match is found.

Show on GitHub


                    
                    
                    querySelectorAll(_:)

Asynchronous

Queries all descendant elements that match a given CSS selector.

Throws

An error if the query fails.

Declaration

Swift

public func querySelectorAll(_ selector: String) async throws -> [PipeableElement]

Parameters


                                selector

The CSS selector to match.

Return Value

An array of PipeableElement objects representing the matched descendants.

Show on GitHub


                    
                    
                    waitForSelector(_:timeout:visible:)

Asynchronous

Waits for a descendant element to appear that matches a given CSS selector.

Throws

An error if the wait fails.

Declaration

Swift

public func waitForSelector(_ selector: String, timeout: Int = 30000, visible: Bool = false) async throws -> PipeableElement?

Parameters

`selector`	The CSS selector to wait for.
`timeout`	The maximum time in milliseconds to wait. Defaults to 30000ms.
`visible`	If `true`, waits for the element to become visible. Defaults to `false`.

Return Value

A PipeableElement representing the matched descendant, or nil if the wait times out.

Show on GitHub


                    
                    
                    xpathSelector(_:)

Asynchronous

Queries the web page for all elements that match a specified XPath expression, relative to the current element.

Throws

An error if the JavaScript evaluation fails, such as from an invalid XPath expression.

Declaration

Swift

public func xpathSelector(_ xpath: String) async throws -> [PipeableElement]

Parameters


                                xpath

A string representing the XPath expression to evaluate against the elements within the current element’s context.

Return Value

An array of PipeableElement objects representing all matching elements found. Returns an empty array if no matching elements are discovered.

Show on GitHub


                    
                    
                    waitForXPath(_:timeout:visible:)

Asynchronous

Waits for an element matching a specified XPath expression to appear within the current element’s context in the web page.

Throws

An error if the JavaScript evaluation fails or the wait operation times out before finding a match.

Declaration

Swift

public func waitForXPath(_ xpath: String, timeout: Int = 30000, visible: Bool = false) async throws -> PipeableElement?

Parameters

`xpath`	A string representing the XPath expression to wait for.
`timeout`	The maximum time, in milliseconds, to wait for the element to appear. Defaults to 30000ms (30 seconds).
`visible`	A Boolean indicating whether the element should be visible upon being found. Defaults to `false`.

Return Value

An optional PipeableElement representing the matching element once it appears within the current element’s context. Returns nil if the element does not appear within the specified timeout period.

Show on GitHub