Struct fantoccini::Client

pub struct Client { /* fields omitted */ }

A WebDriver client tied to a single browser session.

Implementations

impl Client

pub async fn new<'_>(webdriver: &'_ str) -> Result<Self, NewSessionError>

Create a new Client associated with a new WebDriver session on the server at the given URL.

Calls with_capabilities with an empty capabilities list.

pub async fn with_capabilities<'_>(
    webdriver: &'_ str,
    cap: Capabilities
) -> Result<Self, NewSessionError>

Create a new Client associated with a new WebDriver session on the server at the given URL.

The given capabilities will be requested in alwaysMatch or desiredCapabilities depending on the protocol version supported by the server.

Returns a future that resolves to a handle for issuing additional WebDriver tasks.

Note that most callers should explicitly call Client::close, and wait for the returned future before exiting. Not doing so may result in the WebDriver session not being cleanly closed, which is particularly important for some drivers, such as geckodriver, where multiple simulatenous sessions are not supported. If close is not explicitly called, a session close request will be spawned on the given handle when the last instance of this Client is dropped.

pub async fn session_id<'_>(&'_ mut self) -> Result<Option<String>, CmdError>

Get the session ID assigned by the WebDriver server to this client.

pub async fn set_ua<S: Into<String>, '_>(
    &'_ mut self,
    ua: S
) -> Result<(), CmdError>

Set the User Agent string to use for all subsequent requests.

pub async fn get_ua<'_>(&'_ mut self) -> Result<Option<String>, CmdError>

Get the current User Agent string.

pub async fn close<'_>(&'_ mut self) -> Result<(), CmdError>

Terminate the WebDriver session.

Normally, a shutdown of the WebDriver connection will be initiated when the last clone of a Client is dropped. Specifically, the shutdown request will be issued using the tokio Handle given when creating this Client. This in turn means that any errors will be dropped.

This function is safe to call multiple times, but once it has been called on one instance of a Client, all requests to other instances of that Client will fail.

This function may be useful in conjunction with raw_client_for, as it allows you to close the automated browser window while doing e.g., a large download.

pub async fn persist<'_>(&'_ mut self) -> Result<(), CmdError>

Mark this client's session as persistent.

After all instances of a Client have been dropped, we normally shut down the WebDriver session, which also closes the associated browser window or tab. By calling this method, the shutdown command will not be sent to this client's session, meaning its window or tab will remain open.

Note that an explicit call to Client::close will still terminate the session.

This function is safe to call multiple times.

pub async fn set_window_rect<'_>(
    &'_ mut self,
    x: u32,
    y: u32,
    width: u32,
    height: u32
) -> Result<(), CmdError>

Sets the x, y, width, and height properties of the current window.

pub async fn get_window_rect<'_>(
    &'_ mut self
) -> Result<(u64, u64, u64, u64), CmdError>

Gets the x, y, width, and height properties of the current window.

pub async fn set_window_size<'_>(
    &'_ mut self,
    width: u32,
    height: u32
) -> Result<(), CmdError>

Sets the x, y, width, and height properties of the current window.

pub async fn get_window_size<'_>(&'_ mut self) -> Result<(u64, u64), CmdError>

Gets the width and height of the current window.

pub async fn set_window_position<'_>(
    &'_ mut self,
    x: u32,
    y: u32
) -> Result<(), CmdError>

Sets the x, y, width, and height properties of the current window.

pub async fn get_window_position<'_>(
    &'_ mut self
) -> Result<(u64, u64), CmdError>

Gets the x and y top-left coordinate of the current window.

pub async fn goto<'_, '_>(&'_ mut self, url: &'_ str) -> Result<(), CmdError>

Navigate directly to the given URL.

pub async fn active_element<'_>(&'_ mut self) -> Result<Element, CmdError>

Get the active element for this session.

The "active" element is the Element within the DOM that currently has focus. This will often be an <input> or <textarea> element that currently has the text selection, or another input element such as a checkbox or radio button. Which elements are focusable depends on the platform and browser configuration.

If no element has focus, the result may be the page body or a NoSuchElement error.

pub async fn current_url<'_>(&'_ mut self) -> Result<Url, CmdError>

Retrieve the currently active URL for this session.

pub async fn screenshot<'_>(&'_ mut self) -> Result<Vec<u8>, CmdError>

Get a PNG-encoded screenshot of the current page.

pub async fn source<'_>(&'_ mut self) -> Result<String, CmdError>

Get the HTML source for the current page.

pub async fn back<'_>(&'_ mut self) -> Result<(), CmdError>

Go back to the previous page.

pub async fn refresh<'_>(&'_ mut self) -> Result<(), CmdError>

Refresh the current previous page.

pub async fn execute<'_, '_>(
    &'_ mut self,
    script: &'_ str,
    __arg2: Vec<Json>
) -> Result<Json, CmdError>

Execute the given JavaScript script in the current browser session.

args is available to the script inside the arguments array. Since Element implements Serialize, you can also provide serialized Elements as arguments, and they will correctly deserialize to DOM elements on the other side.

To retrieve the value of a variable, return has to be used in the JavaScript code.

pub async fn execute_async<'_, '_>(
    &'_ mut self,
    script: &'_ str,
    __arg2: Vec<Json>
) -> Result<Json, CmdError>

Execute the given async JavaScript script in the current browser session.

The provided JavaScript has access to args through the JavaScript variable arguments. The arguments array also holds an additional element at the end that provides a completion callback for the asynchronous code.

Since Element implements Serialize, you can also provide serialized Elements as arguments, and they will correctly deserialize to DOM elements on the other side.

Examples

Call a web API from the browser and retrieve the value asynchronously

const JS: &'static str = r#"
    const [date, callback] = arguments;

    fetch(`http://weather.api/${date}/hourly`)
    // whenever the HTTP Request completes,
    // send the value back to the Rust context
    .then(data => {
        callback(data.json())
    })
"#;

let weather = client.execute_async(JS, vec![date]).await?;

pub async fn raw_client_for<'_, '_>(
    &'_ mut self,
    method: Method,
    url: &'_ str
) -> Result<Response<Body>, CmdError>

Issue an HTTP request to the given url with all the same cookies as the current session.

Calling this method is equivalent to calling with_raw_client_for with an empty closure.

pub async fn with_raw_client_for<F, '_, '_>(
    &'_ mut self,
    method: Method,
    url: &'_ str,
    before: F
) -> Result<Response<Body>, CmdError> where
    F: FnOnce(Builder) -> Request<Body>, 

Build and issue an HTTP request to the given url with all the same cookies as the current session.

Before the HTTP request is issued, the given before closure will be called with a handle to the Request about to be sent.

pub async fn enter_frame(
    __arg0: Self,
    index: Option<u16>
) -> Result<Client, CmdError>

Switches to the frame specified at the index.

pub async fn enter_parent_frame(__arg0: Self) -> Result<Client, CmdError>

Switches to the parent of the frame the client is currently contained within.

pub async fn find<'_, '_>(
    &'_ mut self,
    search: Locator<'_>
) -> Result<Element, CmdError>

Find an element on the page.

pub async fn find_all<'_, '_>(
    &'_ mut self,
    search: Locator<'_>
) -> Result<Vec<Element>, CmdError>

Find elements on the page.

pub async fn wait_for<F, FF, '_>(
    &'_ mut self,
    __arg1: F
) -> Result<(), CmdError> where
    F: FnMut(&mut Client) -> FF,
    FF: Future<Output = Result<bool, CmdError>>, 

Wait for the given function to return true before proceeding.

This can be useful to wait for something to appear on the page before interacting with it. While this currently just spins and yields, it may be more efficient than this in the future. In particular, in time, it may only run is_ready again when an event occurs on the page.

pub async fn wait_for_find<'_, '_>(
    &'_ mut self,
    search: Locator<'_>
) -> Result<Element, CmdError>

Wait for the given element to be present on the page.

This can be useful to wait for something to appear on the page before interacting with it. While this currently just spins and yields, it may be more efficient than this in the future. In particular, in time, it may only run is_ready again when an event occurs on the page.

pub async fn wait_for_navigation<'_>(
    &'_ mut self,
    current: Option<Url>
) -> Result<(), CmdError>

Wait for the page to navigate to a new URL before proceeding.

If the current URL is not provided, self.current_url() will be used. Note however that this introduces a race condition: the browser could finish navigating before we call current_url(), which would lead to an eternal wait.

pub async fn form<'_, '_>(
    &'_ mut self,
    search: Locator<'_>
) -> Result<Form, CmdError>

Locate a form on the page.

Through the returned Form, HTML forms can be filled out and submitted.

pub async fn window<'_>(&'_ mut self) -> Result<WebWindow, CmdError>

Gets the current window handle.

pub async fn windows<'_>(&'_ mut self) -> Result<Vec<WebWindow>, CmdError>

Gets a list of all active windows (and tabs)

pub async fn switch_to_window<'_>(
    &'_ mut self,
    window: WebWindow
) -> Result<(), CmdError>

Switches to the chosen window.

pub async fn close_window<'_>(&'_ mut self) -> Result<(), CmdError>

Closes the current window.

Will close the session if no other windows exist.

Closing a window will not switch the client to one of the remaining windows. The switching must be done by calling switch_to_window using a still live window after the current window has been closed.

pub async fn new_window<'_>(
    &'_ mut self,
    as_tab: bool
) -> Result<NewWindowResponse, CmdError>

Creates a new window. If is_tab is true, then a tab will be created instead.

Requires geckodriver > 0.24 and firefox > 66

Windows are treated the same as tabs by the webdriver protocol. The functions new_window, switch_to_window, close_window, window and windows all operate on both tabs and windows.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

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

Formats the value using the given formatter.