Struct Frame

Source

pub struct Frame { /* private fields */ }

Expand description

Frame represents a frame within a page.

Every page has a main frame, and pages can have additional child frames (iframes). Frame is where navigation, selector queries, and DOM operations actually happen.

In Playwright’s architecture, Page delegates navigation and interaction methods to Frame.

See: https://playwright.dev/docs/api/class-frame

Implementations§

Source §

impl Frame

Source

pub fn new( parent: Arc<dyn ChannelOwner>, type_name: String, guid: Arc<str>, initializer: Value, ) -> Result<Self>

Creates a new Frame from protocol initialization.

This is called by the object factory when the server sends a __create__ message for a Frame object.

Source

pub fn page(&self) -> Option<Page>

Returns the owning Page for this frame, if it has been set.

Returns None if set_page() has not been called yet (i.e., before the frame has been adopted by a Page). In normal usage the main frame always has a Page.

See: https://playwright.dev/docs/api/class-frame#frame-page

Source

pub fn name(&self) -> &str

Returns the name attribute value of the frame element used to create this frame.

For the main (top-level) frame this is always an empty string.

See: https://playwright.dev/docs/api/class-frame#frame-name

Source

pub fn parent_frame(&self) -> Option<Frame>

Returns the parent Frame, or None if this is the top-level (main) frame.

See: https://playwright.dev/docs/api/class-frame#frame-parent-frame

Source

pub fn is_detached(&self) -> bool

Returns true if the frame has been detached from its page.

A frame becomes detached when the corresponding <iframe> element is removed from the DOM or when the owning page is closed.

See: https://playwright.dev/docs/api/class-frame#frame-is-detached

Source

pub fn child_frames(&self) -> Vec<Frame>

Returns all child frames embedded in this frame.

Child frames are created by <iframe> elements within this frame. For the main frame this may include multiple iframes.

§Implementation Note

This iterates all objects in the connection registry to find Frame objects whose parentFrame initializer field matches this frame’s GUID. This matches the relationship Playwright establishes when creating child frames.

See: https://playwright.dev/docs/api/class-frame#frame-child-frames

Source

pub async fn evaluate_handle( &self, expression: &str, ) -> Result<Arc<ElementHandle>>

Evaluates a JavaScript expression and returns a handle to the result.

Unlike evaluate which serializes the return value to JSON, evaluate_handle returns a handle to the in-browser object. This is useful when the return value is a non-serializable DOM element or complex JS object.

§Arguments

expression - JavaScript expression to evaluate in the frame context

§Returns

An Arc<ElementHandle> pointing to the in-browser object.

§Example

let playwright = Playwright::launch().await?;
let browser = playwright.chromium().launch().await?;
let page = browser.new_page().await?;
page.goto("https://example.com", None).await?;
let frame = page.main_frame().await?;

let handle = frame.evaluate_handle("document.body").await?;
let screenshot = handle.screenshot(None).await?;

§Errors

Returns error if:

The JavaScript expression throws an error
The result handle GUID cannot be found in the registry
Communication with the browser fails

See: https://playwright.dev/docs/api/class-frame#frame-evaluate-handle

Source

pub async fn evaluate_handle_js( &self, expression: &str, ) -> Result<Arc<JSHandle>>

Evaluates a JavaScript expression and returns a JSHandle to the result.

Unlike evaluate_handle which returns an Arc<ElementHandle>, this method returns an Arc<JSHandle> and is suitable for non-DOM values such as plain objects, numbers, and strings.

§Arguments

expression - JavaScript expression to evaluate in the frame context

§Returns

An Arc<JSHandle> pointing to the in-browser value.

§Errors

Returns error if:

The JavaScript expression throws an error
The result handle GUID cannot be found in the registry
Communication with the browser fails

See: https://playwright.dev/docs/api/class-frame#frame-evaluate-handle

Source

pub fn locator(&self, selector: &str) -> Locator

Creates a Locator scoped to this frame.

The locator is lazy — it does not query the DOM until an action is performed on it.

§Arguments

selector - A CSS selector or other Playwright selector strategy

§Panics

Panics if the owning Page has not been set (i.e., set_page() was never called). In normal usage the main frame always has its page wired up by Page::main_frame().

See: https://playwright.dev/docs/api/class-frame#frame-locator

Source

pub fn get_by_text(&self, text: &str, exact: bool) -> Locator

Returns a locator that matches elements containing the given text.

See: https://playwright.dev/docs/api/class-frame#frame-get-by-text

Source

pub fn get_by_label(&self, text: &str, exact: bool) -> Locator

Returns a locator that matches elements by their associated label text.

See: https://playwright.dev/docs/api/class-frame#frame-get-by-label

Source

pub fn get_by_placeholder(&self, text: &str, exact: bool) -> Locator

Returns a locator that matches elements by their placeholder text.

See: https://playwright.dev/docs/api/class-frame#frame-get-by-placeholder

Source

pub fn get_by_alt_text(&self, text: &str, exact: bool) -> Locator

Returns a locator that matches elements by their alt text.

See: https://playwright.dev/docs/api/class-frame#frame-get-by-alt-text

Source

pub fn get_by_title(&self, text: &str, exact: bool) -> Locator

Returns a locator that matches elements by their title attribute.

See: https://playwright.dev/docs/api/class-frame#frame-get-by-title

Source

pub fn get_by_test_id(&self, test_id: &str) -> Locator

Returns a locator that matches elements by their test ID attribute.

By default, uses the data-testid attribute. Call playwright.selectors().set_test_id_attribute() to change the attribute name.

See: https://playwright.dev/docs/api/class-frame#frame-get-by-test-id

Source

pub fn get_by_role( &self, role: AriaRole, options: Option<GetByRoleOptions>, ) -> Locator

Returns a locator that matches elements by their ARIA role.

See: https://playwright.dev/docs/api/class-frame#frame-get-by-role

Source

pub fn url(&self) -> String

Returns the current URL of the frame.

This returns the last committed URL. Initially, frames are at “about:blank”.

See: https://playwright.dev/docs/api/class-frame#frame-url

Source

pub async fn goto( &self, url: &str, options: Option<GotoOptions>, ) -> Result<Option<Response>>

Navigates the frame to the specified URL.

This is the actual protocol method for navigation. Page.goto() delegates to this.

Returns None when navigating to URLs that don’t produce responses (e.g., data URLs, about:blank). This matches Playwright’s behavior across all language bindings.

§Arguments

url - The URL to navigate to
options - Optional navigation options (timeout, wait_until)

See: https://playwright.dev/docs/api/class-frame#frame-goto

Source

pub async fn title(&self) -> Result<String>

Returns the frame’s title.

See: https://playwright.dev/docs/api/class-frame#frame-title

Source

pub async fn content(&self) -> Result<String>

Returns the full HTML content of the frame, including the DOCTYPE.

See: https://playwright.dev/docs/api/class-frame#frame-content

Source

pub async fn set_content( &self, html: &str, options: Option<GotoOptions>, ) -> Result<()>

Sets the content of the frame.

See: https://playwright.dev/docs/api/class-frame#frame-set-content

Source

pub async fn wait_for_load_state(&self, state: Option<WaitUntil>) -> Result<()>

Waits for the required load state to be reached.

Playwright’s protocol doesn’t expose waitForLoadState as a server-side command — it’s implemented client-side using lifecycle events. We implement it by polling document.readyState via JavaScript evaluation.

See: https://playwright.dev/docs/api/class-frame#frame-wait-for-load-state

Source

pub async fn wait_for_url( &self, url: &str, options: Option<GotoOptions>, ) -> Result<()>

Waits for the frame to navigate to a URL matching the given string or glob pattern.

Playwright’s protocol doesn’t expose waitForURL as a server-side command — it’s implemented client-side. We implement it by polling window.location.href.

See: https://playwright.dev/docs/api/class-frame#frame-wait-for-url

Source

pub async fn query_selector( &self, selector: &str, ) -> Result<Option<Arc<ElementHandle>>>

Returns the first element matching the selector, or None if not found.

See: https://playwright.dev/docs/api/class-frame#frame-query-selector

Source

pub async fn query_selector_all( &self, selector: &str, ) -> Result<Vec<Arc<ElementHandle>>>

Returns all elements matching the selector.

See: https://playwright.dev/docs/api/class-frame#frame-query-selector-all

Source

pub async fn evaluate<T: Serialize>( &self, expression: &str, arg: Option<&T>, ) -> Result<Value>

Evaluates a JavaScript expression in the frame context with optional arguments.

Executes the provided JavaScript expression within the frame’s context and returns the result. The return value must be JSON-serializable.

§Arguments

expression - JavaScript code to evaluate
arg - Optional argument to pass to the expression (must implement Serialize)

§Returns

The result as a serde_json::Value

§Example

use serde_json::json;
use playwright_rs::protocol::Playwright;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let playwright = Playwright::launch().await?;
    let browser = playwright.chromium().launch().await?;
    let page = browser.new_page().await?;
    let frame = page.main_frame().await?;

    // Evaluate without arguments
    let result = frame.evaluate::<()>("1 + 1", None).await?;

    // Evaluate with argument
    let arg = json!({"x": 5, "y": 3});
    let result = frame.evaluate::<serde_json::Value>("(arg) => arg.x + arg.y", Some(&arg)).await?;
    assert_eq!(result, json!(8));
    Ok(())
}

See: https://playwright.dev/docs/api/class-frame#frame-evaluate

Source

pub async fn add_style_tag( &self, options: AddStyleTagOptions, ) -> Result<Arc<ElementHandle>>

Adds a <style> tag into the page with the desired content.

§Arguments

options - Style tag options (content, url, or path)

At least one of content, url, or path must be specified.

§Example

use playwright_rs::protocol::AddStyleTagOptions;

// With inline CSS
frame.add_style_tag(
    AddStyleTagOptions::builder()
        .content("body { background-color: red; }")
        .build()
).await?;

// With URL
frame.add_style_tag(
    AddStyleTagOptions::builder()
        .url("https://example.com/style.css")
        .build()
).await?;

See: https://playwright.dev/docs/api/class-frame#frame-add-style-tag

Source