Struct chromiumoxide::page::Page

pub struct Page { /* fields omitted */ }

Implementations

impl Page

pub async fn execute<T: Command>(
    &self,
    cmd: T
) -> Result<CommandResponse<T::Response>>

Execute a command and return the Command::Response

pub async fn event_listener<T: IntoEventKind>(&self) -> Result<EventStream<T>>

Adds an event listener to the Target and returns the receiver part as EventStream

An EventStream receives every Event the Target receives. All event listener get notified with the same event, so registering multiple listeners for the same event is possible.

Custom events rely on being deserializable from the received json params in the EventMessage. Custom Events are caught by the CdpEvent::Other variant. If there are mulitple custom event listener is registered for the same event, identified by the MethodType::method_id function, the Target tries to deserialize the json using the type of the event listener. Upon success the Target then notifies all listeners with the deserialized event. This means, while it is possible to register different types for the same custom event, only the type of first registered event listener will be used. The subsequent listeners, that registered for the same event but with another type won’t be able to receive anything and therefor will come up empty until all their preceding event listeners are dropped and they become the first (or longest) registered event listener for an event.

Example Listen for canceled animations

    let mut events = page.event_listener::<EventAnimationCanceled>().await?;
    while let Some(event) = events.next().await {
        //..
    }

Example Liste for a custom event

    #[derive(Debug, Clone, Eq, PartialEq, Deserialize)]
    struct MyCustomEvent {
        name: String,
    }
   impl MethodType for MyCustomEvent {
       fn method_id() -> MethodId {
           "Custom.Event".into()
       }
   }
   impl CustomEvent for MyCustomEvent {}
   let mut events = page.event_listener::<MyCustomEvent>().await?;
   while let Some(event) = events.next().await {
       //..
   }

pub async fn expose_function(
    &self,
    name: impl Into<String>,
    function: impl AsRef<str>
) -> Result<()>

pub async fn wait_for_navigation_response(
    &self
) -> Result<Option<Arc<HttpRequest>>>

This resolves once the navigation finished and the page is loaded.

This is necessary after an interaction with the page that may trigger a navigation (click, press_key) in order to wait until the new browser page is loaded

pub async fn wait_for_navigation(&self) -> Result<&Self>

Same as wait_for_navigation_response but returns Self instead

pub async fn goto(&self, params: impl Into<NavigateParams>) -> Result<&Self>

Navigate directly to the given URL.

This resolves directly after the requested URL is fully loaded.

pub fn target_id(&self) -> &TargetId

The identifier of the Target this page belongs to

pub fn session_id(&self) -> &SessionId

The identifier of the Session target of this page is attached to

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

Returns the current url of the page

pub async fn mainframe(&self) -> Result<Option<FrameId>>

Return the main frame of the page

pub async fn frames(&self) -> Result<Vec<FrameId>>

Return the frames of the page

pub async fn set_user_agent(
    &self,
    params: impl Into<SetUserAgentOverrideParams>
) -> Result<&Self>

Allows overriding user agent with the given string.

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

Returns the user agent of the browser

pub async fn get_document(&self) -> Result<Node>

Returns the root DOM node (and optionally the subtree) of the page.

Note: This does not return the actual HTML document of the page. To

retrieve the HTML content of the page see Page::content.

pub async fn find_element(&self, selector: impl Into<String>) -> Result<Element>

Returns the first element in the document which matches the given CSS selector.

Execute a query selector on the document’s node.

pub async fn find_elements(
    &self,
    selector: impl Into<String>
) -> Result<Vec<Element>>

Return all Elements in the document that match the given selector

pub async fn describe_node(&self, node_id: NodeId) -> Result<Node>

Describes node given its id

pub async fn close(self) -> Result<()>

Tries to close page, running its beforeunload hooks, if any. Calls Page.close with CloseParams

pub async fn click(&self, point: Point) -> Result<&Self>

Performs a single mouse click event at the point’s location.

This scrolls the point into view first, then executes a DispatchMouseEventParams command of type MouseLeft with MousePressed as single click and then releases the mouse with an additional DispatchMouseEventParams of type MouseLeft with MouseReleased

Bear in mind that if click() triggers a navigation the new page is not immediately loaded when click() resolves. To wait until navigation is finished an additional wait_for_navigation() is required:

Example

Trigger a navigation and wait until the triggered navigation is finished

    let html = page.click(point).await?.wait_for_navigation().await?.content();

Example

Perform custom click

     // double click
     let cmd = DispatchMouseEventParams::builder()
            .x(point.x)
            .y(point.y)
            .button(MouseButton::Left)
            .click_count(2);

        page.move_mouse(point).await?.execute(
            cmd.clone()
                .r#type(DispatchMouseEventType::MousePressed)
                .build()
                .unwrap(),
        )
        .await?;

        page.execute(
            cmd.r#type(DispatchMouseEventType::MouseReleased)
                .build()
                .unwrap(),
        )
        .await?;

pub async fn move_mouse(&self, point: Point) -> Result<&Self>

Dispatches a mousemove event and moves the mouse to the position of the point where Point.x is the horizontal position of the mouse and Point.y the vertical position of the mouse.

pub async fn screenshot(
    &self,
    params: impl Into<CaptureScreenshotParams>
) -> Result<Vec<u8>>

Take a screenshot of the current page

pub async fn save_screenshot(
    &self,
    params: impl Into<CaptureScreenshotParams>,
    output: impl AsRef<Path>
) -> Result<Vec<u8>>

Save a screenshot of the page

Example save a png file of a website

        page.goto("http://example.com")
            .await?
            .save_screenshot(
            CaptureScreenshotParams::builder()
                .format(CaptureScreenshotFormat::Png)
                .build(),
            "example.png",
            )
            .await?;

pub async fn pdf(&self, params: PrintToPdfParams) -> Result<Vec<u8>>

Print the current page as pdf.

See PrintToPdfParams

Note Generating a pdf is currently only supported in Chrome headless.

pub async fn save_pdf(
    &self,
    opts: PrintToPdfParams,
    output: impl AsRef<Path>
) -> Result<Vec<u8>>

Save the current page as pdf as file to the output path and return the pdf contents.

Note Generating a pdf is currently only supported in Chrome headless.

pub async fn bring_to_front(&self) -> Result<&Self>

Brings page to front (activates tab)

pub async fn emulate_media_features(
    &self,
    features: Vec<MediaFeature>
) -> Result<&Self>

Emulates the given media type or media feature for CSS media queries

pub async fn emulate_timezone(
    &self,
    timezoune_id: impl Into<SetTimezoneOverrideParams>
) -> Result<&Self>

Overrides default host system timezone

pub async fn reload(&self) -> Result<&Self>

Reloads given page

To reload ignoring cache run:

    page.execute(ReloadParams::builder().ignore_cache(true).build()).await?;
    page.wait_for_navigation().await?;

pub async fn enable_log(&self) -> Result<&Self>

Enables log domain. Enabled by default.

Sends the entries collected so far to the client by means of the entryAdded notification.

See https://chromedevtools.github.io/devtools-protocol/tot/Log#method-enable

pub async fn disable_log(&self) -> Result<&Self>

Disables log domain

Prevents further log entries from being reported to the client

See https://chromedevtools.github.io/devtools-protocol/tot/Log#method-disable

pub async fn enable_runtime(&self) -> Result<&Self>

Enables runtime domain. Activated by default.

pub async fn disable_runtime(&self) -> Result<&Self>

Disables runtime domain

pub async fn enable_debugger(&self) -> Result<&Self>

Enables Debugger. Enabled by default.

pub async fn disable_debugger(&self) -> Result<&Self>

Disables Debugger.

pub async fn activate(&self) -> Result<&Self>

Activates (focuses) the target.

pub async fn get_cookies(&self) -> Result<Vec<Cookie>>

Returns all cookies that match the tab’s current URL.

pub async fn set_cookie(&self, cookie: impl Into<CookieParam>) -> Result<&Self>

Set a single cookie

This fails if the cookie’s url or if not provided, the page’s url is about:blank or a data: url.

Example

    page.set_cookie(CookieParam::new("Cookie-name", "Cookie-value")).await?;

pub async fn set_cookies(&self, cookies: Vec<CookieParam>) -> Result<&Self>

Set all the cookies

pub async fn delete_cookie(
    &self,
    cookie: impl Into<DeleteCookiesParams>
) -> Result<&Self>

Delete a single cookie

pub async fn delete_cookies(
    &self,
    cookies: Vec<DeleteCookiesParams>
) -> Result<&Self>

Delete all the cookies

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

Returns the title of the document.

pub async fn metrics(&self) -> Result<Vec<Metric>>

Retrieve current values of run-time metrics.

pub async fn layout_metrics(&self) -> Result<GetLayoutMetricsReturns>

Returns metrics relating to the layout of the page

pub async fn evaluate_expression(
    &self,
    evaluate: impl Into<EvaluateParams>
) -> Result<EvaluationResult>

This evaluates strictly as expression.

Same as Page::evaluate but no fallback or any attempts to detect whether the expression is actually a function. However you can submit a function evaluation string:

Example Evaluate function call as expression

This will take the arguments (1,2) and will call the function

    let sum: usize = page
        .evaluate_expression("((a,b) => {return a + b;})(1,2)")
        .await?
        .into_value()?;
    assert_eq!(sum, 3);

pub async fn evaluate(
    &self,
    evaluate: impl Into<Evaluation>
) -> Result<EvaluationResult>

Evaluates an expression or function in the page’s context and returns the result.

In contrast to Page::evaluate_expression this is capable of handling function calls and expressions alike. This takes anything that is Into<Evaluation>. When passing a String or str, this will try to detect whether it is a function or an expression. JS function detection is not very sophisticated but works for general cases ((async) functions and arrow functions). If you want a string statement specifically evaluated as expression or function either use the designated functions Page::evaluate_function or Page::evaluate_expression or use the proper parameter type for Page::execute: EvaluateParams for strict expression evaluation or CallFunctionOnParams for strict function evaluation.

If you don’t trust the js function detection and are not sure whether the statement is an expression or of type function (arrow functions: () => {..}), you should pass it as EvaluateParams and set the EvaluateParams::eval_as_function_fallback option. This will first try to evaluate it as expression and if the result comes back evaluated as RemoteObjectType::Function it will submit the statement again but as function:

Example Evaluate function statement as expression with fallback

option

    let eval = EvaluateParams::builder().expression("() => {return 42;}");
    // this will fail because the `EvaluationResult` returned by the browser will be
    // of type `Function`
    let result = page
                .evaluate(eval.clone().build().unwrap())
                .await?;
    assert_eq!(result.object().r#type, RemoteObjectType::Function);
    assert!(result.into_value::<usize>().is_err());

    // This will also fail on the first try but it detects that the browser evaluated the
    // statement as function and then evaluate it again but as function
    let sum: usize = page
        .evaluate(eval.eval_as_function_fallback(true).build().unwrap())
        .await?
        .into_value()?;

Example Evaluate basic expression

    let sum:usize = page.evaluate("1 + 2").await?.into_value()?;
    assert_eq!(sum, 3);

pub async fn evaluate_function(
    &self,
    evaluate: impl Into<CallFunctionOnParams>
) -> Result<EvaluationResult>

Eexecutes a function withinthe page’s context and returns the result.

Example Evaluate a promise

This will wait until the promise resolves and then returns the result.

    let sum:usize = page.evaluate_function("() => Promise.resolve(1 + 2)").await?.into_value()?;
    assert_eq!(sum, 3);

Example Evaluate an async function

    let val:usize = page.evaluate_function("async function() {return 42;}").await?.into_value()?;
    assert_eq!(val, 42);

Example Construct a function call

    let call = CallFunctionOnParams::builder()
           .function_declaration(
               "(a,b) => { return a + b;}"
           )
           .argument(
               CallArgument::builder()
                   .value(serde_json::json!(1))
                   .build(),
           )
           .argument(
               CallArgument::builder()
                   .value(serde_json::json!(2))
                   .build(),
           )
           .build()
           .unwrap();
    let sum:usize = page.evaluate_function(call).await?.into_value()?;
    assert_eq!(sum, 3);

pub async fn execution_context(&self) -> Result<Option<ExecutionContextId>>

Returns the default execution context identifier of this page that represents the context for JavaScript execution.

pub async fn secondary_execution_context(
    &self
) -> Result<Option<ExecutionContextId>>

Returns the secondary execution context identifier of this page that represents the context for JavaScript execution for manipulating the DOM.

See Page::set_contents

pub async fn evaluate_on_new_document(
    &self,
    script: impl Into<AddScriptToEvaluateOnNewDocumentParams>
) -> Result<ScriptIdentifier>

Evaluates given script in every frame upon creation (before loading frame’s scripts)

pub async fn set_content(&self, html: impl AsRef<str>) -> Result<&Self>

Set the content of the frame.

Example

    page.set_content("<body>
 <h1>This was set via chromiumoxide</h1>
 </body>").await?;

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

Returns the HTML content of the page

pub async fn get_script_source(
    &self,
    script_id: impl Into<String>
) -> Result<String>

Returns source for the script with given id.

Debugger must be enabled.

Trait Implementations

impl Debug for Page

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Arc<PageInner>> for Page

fn from(inner: Arc<PageInner>) -> Self

Performs the conversion.