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.

  • 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.

  • 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.

  • 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
  • blur() Asynchronous

    Removes focus from the element.

    Declaration

    Swift

    public func blur() async throws
  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.