PipeablePage

public class PipeablePage

PipeablePage provides methods to interact with a web page loaded in the webview. It can be constructed by wrapping an existing WKWebView using a constructor or by using a PipeableWebView and acquiring it from there. Note that in the case of using a constructor, you need to make sure that the lifecycle of the PipeablePage is managed correctly.

Example:

let webView = PipeableWebView()
let page = webView.page

try? await page.goto("https://example.com", waitUntil: .load)
let exampleEl = try? await page.querySelector("input[name='example']")
Show on GitHub

  • Constructs a PipeablePage from an existing WKWebView.

    Declaration

    Swift

    public convenience init(_ webView: WKWebView, debugPrintConsoleLogs: Bool? = nil)
    Show on GitHub

  • Adds a script to be included in any page and frame loaded in the webview.

    Declaration

    Swift

    public func addUserScript(_ contents: String, injectionTime: WKUserScriptInjectionTime = .atDocumentEnd, forMainFrameOnly: Bool = false)

    Parameters

    contents

    The script content to be added.
    injectionTime

    Specifies when the script should be injected into the web page. Defaults to .atDocumentEnd.
    forMainFrameOnly

    Boolean indicating whether the script should be injected into all frames or just the main frame. Defaults to false.
    Show on GitHub
  • submitActiveForm() Asynchronous

    Submits the currently active form on the page. Useful when there is no submit button and a form is only submitted from the mobile keyboard.

    Throws

    An error if JavaScript evaluation fails.

    Declaration

    Swift

    public func submitActiveForm() async throws -> Bool

    Return Value

    A boolean indicating whether the form submission was successful.

    Show on GitHub

  • Undocumented

    Declaration

    Swift

    public func loadCookies(fromJSONString jsonString: String)
    Show on GitHub

  • Retrieves the current URL of the web view.

    Declaration

    Swift

    @MainActor
public func url() -> URL?

    Return Value

    The current URL, or nil if no URL is loaded.

    Show on GitHub
  • evaluate(_:) Asynchronous

    Evaluates a JavaScript expression synchronously.

    Throws

    An error if the JavaScript evaluation fails.

    Declaration

    Swift

    func evaluate(_ javascript: String) async throws -> Any?

    Parameters

    javascript

    The JavaScript expression to evaluate.

    Return Value

    The result of the evaluation.

    Show on GitHub

  • Evaluates a JavaScript function asynchronously.

    • arguments: A dictionary of arguments to pass to the function. The valid types are:

      • PipeableElement: The element to pass to the function.
      • Basic types: Int, String, etc.
      • Collections (arrays and dictionaries) of the above types.

    Throws

    An error if the JavaScript evaluation fails or if the provided arguments are not valid.

    Declaration

    Swift

    func evaluateAsyncFunction(_ javascript: String, arguments: [String : Any] = [:]) async throws -> Any?

    Parameters

    javascript

    The body of the javascript function to evaluate. It should not start with the function definition, but start straight with the function body. The arguments provided in the arguments parameter will be available as variables in the function body.

    Return Value

    The result of the function. Can return a promise or a value.

    Show on GitHub

  • Enum representing the various states to wait for before considering a navigation or page action complete.

    • load: Wait until the load event is fired, indicating that the entire page and all dependent resources have loaded.
    • domcontentloaded: Wait until the DOMContentLoaded event is fired, indicating that the HTML is fully parsed, but stylesheets, images, and subframes may still be loading.
    • networkidle: Wait until the network is idle, meaning there are no ongoing network requests for a specified time period (0.5s). This state implies that most, if not all, resources have been fetched and processed.
    See more

    Declaration

    Swift

    enum WaitUntilOption : String
    Show on GitHub

  • Navigates the web view to a specified URL.

    Throws

    PipeableError.navigationError if navigation fails.

    Declaration

    Swift

    func goto(_ url: String, waitUntil: WaitUntilOption = .load, timeout: Int = 30000) async throws -> PipeableHTTPResponse?

    Parameters

    url

    The URL to navigate to.
    waitUntil

    Specifies the event to wait for before considering the navigation complete. Defaults to .load. Other options are .domcontentloaded and .networkidle.
    timeout

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

    Return Value

    A PipeableHTTPResponse object representing the HTTP response, or nil if the response is not available.

    Show on GitHub

  • Reloads the current page.

    Throws

    PipeableError.navigationError if reload fails.

    Declaration

    Swift

    func reload(waitUntil: WaitUntilOption = .load, timeout: Int = 30000) async throws

    Parameters

    waitUntil

    Specifies the event to wait for before considering the reload complete. Defaults to .load.
    timeout

    The maximum time in milliseconds to wait for the reload to complete. Defaults to 30000ms.
    Show on GitHub

  • Waits for a specified load state.

    Throws

    An error if the wait condition is not met within the timeout.

    Declaration

    Swift

    func waitForLoadState(waitUntil: WaitUntilOption = .load, timeout: Int = 30000) async throws

    Parameters

    waitUntil

    The load state to wait for.
    timeout

    The maximum time in milliseconds to wait. Defaults to 30000ms.
    Show on GitHub

  • Waits for the WebView to navigate to a URL that matches the given predicate.

    • predicate: A closure that takes a URL and returns a boolean.
    • waitUntil: When to consider navigation as finished, defaults to .load.
    • timeout: Maximum time to wait for the navigation to finish, defaults to 30000ms.
    • ignoreNavigationErrors: If true, ignores navigation errors and waits for the URL to match the predicate.

    Throws

    PipeableError.navigationError if the navigation fails and ignoreNavigationErrors is false.

    Declaration

    Swift

    func waitForURL(
    _ predicate: @escaping (String) -> Bool,
    waitUntil: WaitUntilOption = .load,
    timeout: Int = 30000,
    ignoreNavigationErrors: Bool = false
) async throws
    Show on GitHub

  • Waits for an asynchornous request made via XMLHttpRequest (XHR) or fetch to complete that matches the specified URL.

    Throws

    PipeableError.invalidResponse if the function fails to decode the XHR response or if the JavaScript execution returns an unexpected result. This error indicates an issue with the response format or a failure in the underlying JavaScript execution mechanism.

    Declaration

    Swift

    func waitForResponse(_ url: String, timeout: Int = 30000) async throws -> XHRResult?

    Parameters

    url

    Partial URL of the request to wait for.
    timeout

    The maximum time, in milliseconds, to wait for the XHR request to complete. Defaults to 30000ms (30 seconds).

    Return Value

    An optional XHRResult object containing details about the completed XHR request, including status code, response body, response headers, the request URL, and the response type. Returns nil if the request does not complete within the specified timeout or if the response cannot be properly decoded.

    Show on GitHub
  • querySelector(_:) Asynchronous

    Queries a single element matching a CSS selector.

    Throws

    An error if JavaScript evaluation fails, e.g. a bad selector

    Declaration

    Swift

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

    Parameters

    selector

    The CSS selector to match.

    Return Value

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

    Show on GitHub
  • querySelectorAll(_:) Asynchronous

    Queries all elements matching a CSS selector.

    Throws

    An error if JavaScript evaluation fails, e.g. a bad selector.

    Declaration

    Swift

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

    Parameters

    selector

    The CSS selector to match.

    Return Value

    An array of PipeableElement objects representing the matched elements.

    Show on GitHub
  • xpathSelector(_:) Asynchronous

    Queries the web page for all elements that match a specified XPath expression.

    Throws

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

    Declaration

    Swift

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

    Parameters

    xpath

    A string representing the XPath expression to evaluate against the elements in the page.

    Return Value

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

    Show on GitHub

  • Waits for an element matching a specified XPath expression to appear in the web page.

    Throws

    An error if the JavaScript evaluation fails or the wait operation times out.

    Declaration

    Swift

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

    A Boolean indicating whether the element should be visible. Defaults to false.

    Return Value

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

    Show on GitHub

  • Waits for an element matching a specified CSS selector to appear in the web page.

    Throws

    An error if the JavaScript evaluation fails or the wait operation times out.

    Declaration

    Swift

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

    Parameters

    selector

    A string representing the CSS selector to wait for.
    timeout

    The maximum time, in milliseconds, to wait for the element to appear. Defaults to 30000ms.
    visible

    A Boolean indicating whether the element should be visible. Defaults to false.

    Return Value

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

    Show on GitHub