//! WebDriver client implementation.
use crate::actions::Actions;
use crate::elements::{Element, Form};
use crate::error;
use crate::session::{Cmd, Session, Task};
use crate::wait::Wait;
use crate::wd::{
Capabilities, Locator, NewWindowType, TimeoutConfiguration, WebDriverStatus, WindowHandle,
};
use hyper::{client::connect, Method};
use serde_json::Value as Json;
use std::convert::{TryFrom, TryInto as _};
use std::future::Future;
use tokio::sync::{mpsc, oneshot};
use webdriver::command::{SendKeysParameters, WebDriverCommand};
use webdriver::common::{FrameId, ELEMENT_KEY};
// Used only under `native-tls`
#[cfg_attr(not(feature = "native-tls"), allow(unused_imports))]
use crate::ClientBuilder;
/// A WebDriver client tied to a single browser
/// [session](https://www.w3.org/TR/webdriver1/#sessions).
///
/// Use [`ClientBuilder`](crate::ClientBuilder) to create a new session.
///
/// 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.
#[derive(Clone, Debug)]
pub struct Client {
pub(crate) tx: mpsc::UnboundedSender<Task>,
pub(crate) is_legacy: bool,
}
impl Client {
/// Connect to the WebDriver host running the given address.
///
/// This connects using a platform-native TLS library, and is only available with the
/// `native-tls` feature. To customize, use [`ClientBuilder`] instead.
#[cfg(feature = "native-tls")]
#[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))]
#[deprecated(since = "0.17.1", note = "Prefer ClientBuilder::native")]
pub async fn new(webdriver: &str) -> Result<Self, error::NewSessionError> {
ClientBuilder::native().connect(webdriver).await
}
/// Connect to the WebDriver host running the given address.
///
/// The provided `connector` is used to establish the connection to the WebDriver host, and
/// should generally be one that supports HTTPS, as that is commonly required by WebDriver
/// implementations.
///
/// Calls `with_capabilities_and_connector` with an empty capabilities list.
pub(crate) async fn new_with_connector<C>(
webdriver: &str,
connector: C,
) -> Result<Self, error::NewSessionError>
where
C: connect::Connect + Unpin + 'static + Clone + Send + Sync,
{
Self::with_capabilities_and_connector(
webdriver,
&webdriver::capabilities::Capabilities::new(),
connector,
)
.await
}
/// Connect to the WebDriver host running the given address.
///
/// Prefer using [`ClientBuilder`](crate::ClientBuilder) over calling this method directly.
///
/// 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.
pub async fn with_capabilities_and_connector<C>(
webdriver: &str,
cap: &Capabilities,
connector: C,
) -> Result<Self, error::NewSessionError>
where
C: connect::Connect + Unpin + 'static + Clone + Send + Sync,
{
Session::with_capabilities_and_connector(webdriver, cap, connector).await
}
/// Get the unique session ID assigned by the WebDriver server to this client.
pub async fn session_id(&self) -> Result<Option<String>, error::CmdError> {
match self.issue(Cmd::GetSessionId).await? {
Json::String(s) => Ok(Some(s)),
Json::Null => Ok(None),
v => unreachable!("response to GetSessionId was not a string: {:?}", v),
}
}
/// Set the User Agent string to use for all subsequent requests.
pub async fn set_ua<S: Into<String>>(&self, ua: S) -> Result<(), error::CmdError> {
self.issue(Cmd::SetUa(ua.into())).await?;
Ok(())
}
/// Get the current User Agent string.
pub async fn get_ua(&self) -> Result<Option<String>, error::CmdError> {
match self.issue(Cmd::GetUa).await? {
Json::String(s) => Ok(Some(s)),
Json::Null => Ok(None),
v => unreachable!("response to GetSessionId was not a string: {:?}", v),
}
}
/// 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.
///
/// 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 close(self) -> Result<(), error::CmdError> {
self.issue(Cmd::Shutdown).await?;
Ok(())
}
/// 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 persist(&self) -> Result<(), error::CmdError> {
self.issue(Cmd::Persist).await?;
Ok(())
}
}
// NOTE: new impl block to keep related methods together.
/// [Sessions](https://www.w3.org/TR/webdriver1/#sessions)
impl Client {
/// Get the WebDriver status.
///
/// See [8.3 Status](https://www.w3.org/TR/webdriver1/#status) of the WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Status"))]
pub async fn status(&self) -> Result<WebDriverStatus, error::CmdError> {
let res = self.issue(WebDriverCommand::Status).await?;
let status: WebDriverStatus = serde_json::from_value(res)?;
Ok(status)
}
/// Get the timeouts for the current session.
///
/// See [8.4 Get Timeouts](https://www.w3.org/TR/webdriver1/#get-timeouts) of the WebDriver
/// standard.
#[cfg_attr(docsrs, doc(alias = "Get Timeouts"))]
pub async fn get_timeouts(&self) -> Result<TimeoutConfiguration, error::CmdError> {
let res = self.issue(WebDriverCommand::GetTimeouts).await?;
let timeouts: TimeoutConfiguration = serde_json::from_value(res)?;
Ok(timeouts)
}
/// Set the timeouts for the current session.
///
/// See [8.5 Set Timeouts](https://www.w3.org/TR/webdriver1/#set-timeouts) of the WebDriver
/// standard.
#[cfg_attr(docsrs, doc(alias = "Set Timeouts"))]
#[cfg_attr(docsrs, doc(alias = "Update Timeouts"))]
pub async fn update_timeouts(
&self,
timeouts: TimeoutConfiguration,
) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::SetTimeouts(timeouts.into_params()))
.await?;
Ok(())
}
}
/// [Navigation](https://www.w3.org/TR/webdriver1/#navigation)
impl Client {
/// Navigate directly to the given URL.
///
/// See [9.1 Navigate To](https://www.w3.org/TR/webdriver1/#dfn-navigate-to) of the WebDriver
/// standard.
#[cfg_attr(docsrs, doc(alias = "Navigate To"))]
pub async fn goto(&self, url: &str) -> Result<(), error::CmdError> {
let url = url.to_owned();
let base = self.current_url_().await?;
let url = base.join(&url)?;
self.issue(WebDriverCommand::Get(webdriver::command::GetParameters {
url: url.into(),
}))
.await?;
Ok(())
}
/// Retrieve the currently active URL for this session.
///
/// See [9.2 Get Current URL](https://www.w3.org/TR/webdriver1/#dfn-get-current-url) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Get Current URL"))]
pub async fn current_url(&self) -> Result<url::Url, error::CmdError> {
self.current_url_().await
}
pub(crate) async fn current_url_(&self) -> Result<url::Url, error::CmdError> {
let url = self.issue(WebDriverCommand::GetCurrentUrl).await?;
if let Some(url) = url.as_str() {
let url = if url.is_empty() { "about:blank" } else { url };
Ok(url.parse()?)
} else {
Err(error::CmdError::NotW3C(url))
}
}
/// Go back to the previous page.
///
/// See [9.3 Back](https://www.w3.org/TR/webdriver1/#dfn-back) of the WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Back"))]
pub async fn back(&self) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::GoBack).await?;
Ok(())
}
/// Go forward to the next page.
///
/// See [9.4 Forward](https://www.w3.org/TR/webdriver1/#dfn-forward) of the WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Forward"))]
pub async fn forward(&self) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::GoForward).await?;
Ok(())
}
/// Refresh the current previous page.
///
/// See [9.5 Refresh](https://www.w3.org/TR/webdriver1/#dfn-refresh) of the WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Refresh"))]
pub async fn refresh(&self) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::Refresh).await?;
Ok(())
}
/// Get the current page title.
///
/// See [9.6 Get Title](https://www.w3.org/TR/webdriver1/#dfn-get-title) of the WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Get Title"))]
pub async fn title(&self) -> Result<String, error::CmdError> {
let title = self.issue(WebDriverCommand::GetTitle).await?;
if let Json::String(s) = title {
Ok(s)
} else {
Err(error::CmdError::NotW3C(title))
}
}
}
/// [Command Contexts](https://www.w3.org/TR/webdriver1/#command-contexts)
impl Client {
/// Gets the current window handle.
///
/// See [10.1 Get Window Handle](https://www.w3.org/TR/webdriver1/#get-window-handle) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Get Window Handle"))]
pub async fn window(&self) -> Result<WindowHandle, error::CmdError> {
let res = self.issue(WebDriverCommand::GetWindowHandle).await?;
match res {
Json::String(x) => Ok(x.try_into()?),
v => Err(error::CmdError::NotW3C(v)),
}
}
/// 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.
///
/// See [10.2 Close Window](https://www.w3.org/TR/webdriver1/#close-window) of the WebDriver
/// standard.
#[cfg_attr(docsrs, doc(alias = "Close Window"))]
pub async fn close_window(&self) -> Result<(), error::CmdError> {
let _res = self.issue(WebDriverCommand::CloseWindow).await?;
Ok(())
}
/// Switches to the chosen window.
///
/// See [10.3 Switch To Window](https://www.w3.org/TR/webdriver1/#switch-to-window) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Switch To Window"))]
pub async fn switch_to_window(&self, window: WindowHandle) -> Result<(), error::CmdError> {
let params = webdriver::command::SwitchToWindowParameters {
handle: window.into(),
};
let _res = self.issue(WebDriverCommand::SwitchToWindow(params)).await?;
Ok(())
}
/// Gets a list of all active windows (and tabs)
///
/// See [10.4 Get Window Handles](https://www.w3.org/TR/webdriver1/#get-window-handles) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Get Window Handles"))]
pub async fn windows(&self) -> Result<Vec<WindowHandle>, error::CmdError> {
let res = self.issue(WebDriverCommand::GetWindowHandles).await?;
match res {
Json::Array(handles) => handles
.into_iter()
.map(|handle| match handle {
Json::String(x) => Ok(x.try_into()?),
v => Err(error::CmdError::NotW3C(v)),
})
.collect::<Result<Vec<_>, _>>(),
v => Err(error::CmdError::NotW3C(v)),
}
}
/// Creates a new window. If `as_tab` is `true`, then a tab will be created instead.
///
/// 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.
///
/// This operation is only in the editor's draft of the next iteration of the WebDriver
/// protocol, and may thus not be supported by all WebDriver implementations. For example, if
/// you're using `geckodriver`, you will need `geckodriver > 0.24` and `firefox > 66` to use
/// this feature.
///
/// See [11.5 New Window](https://w3c.github.io/webdriver/#dfn-new-window) of the editor's
/// draft standard.
#[cfg_attr(docsrs, doc(alias = "New Window"))]
pub async fn new_window(&self, as_tab: bool) -> Result<NewWindowResponse, error::CmdError> {
let type_hint = if as_tab { "tab" } else { "window" }.to_string();
let type_hint = Some(type_hint);
let params = webdriver::command::NewWindowParameters { type_hint };
match self.issue(WebDriverCommand::NewWindow(params)).await? {
Json::Object(mut obj) => {
let handle = match obj
.remove("handle")
.and_then(|x| x.as_str().map(WindowHandle::try_from))
{
Some(Ok(handle)) => handle,
_ => return Err(error::CmdError::NotW3C(Json::Object(obj))),
};
let typ = match obj.get("type").and_then(|x| x.as_str()) {
Some(typ) => match typ {
"tab" => NewWindowType::Tab,
"window" => NewWindowType::Window,
_ => return Err(error::CmdError::NotW3C(Json::Object(obj))),
},
None => return Err(error::CmdError::NotW3C(Json::Object(obj))),
};
Ok(NewWindowResponse { handle, typ })
}
v => Err(error::CmdError::NotW3C(v)),
}
}
/// Switches to the frame specified at the index.
///
/// See [10.5 Switch To Frame](https://www.w3.org/TR/webdriver1/#switch-to-frame) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Switch To Frame"))]
pub async fn enter_frame(&self, index: Option<u16>) -> Result<(), error::CmdError> {
let params = webdriver::command::SwitchToFrameParameters {
id: index.map(FrameId::Short),
};
self.issue(WebDriverCommand::SwitchToFrame(params)).await?;
Ok(())
}
/// Switches to the parent of the frame the client is currently contained within.
///
/// See [10.6 Switch To Parent Frame](https://www.w3.org/TR/webdriver1/#switch-to-parent-frame)
/// of the WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Switch To Parent Frame"))]
pub async fn enter_parent_frame(&self) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::SwitchToParentFrame).await?;
Ok(())
}
/// Sets the x, y, width, and height properties of the current window.
///
/// See [10.7.2 Set Window Rect](https://www.w3.org/TR/webdriver1/#dfn-set-window-rect) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Set Window Rect"))]
pub async fn set_window_rect(
&self,
x: u32,
y: u32,
width: u32,
height: u32,
) -> Result<(), error::CmdError> {
let cmd = WebDriverCommand::SetWindowRect(webdriver::command::WindowRectParameters {
x: Some(x as i32),
y: Some(y as i32),
width: Some(width as i32),
height: Some(height as i32),
});
self.issue(cmd).await?;
Ok(())
}
/// Gets the x, y, width, and height properties of the current window.
///
/// See [10.7.1 Get Window Rect](https://www.w3.org/TR/webdriver1/#dfn-get-window-rect) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Get Window Rect"))]
pub async fn get_window_rect(&self) -> Result<(u64, u64, u64, u64), error::CmdError> {
match self.issue(WebDriverCommand::GetWindowRect).await? {
Json::Object(mut obj) => {
let x = match obj.remove("x").and_then(|x| x.as_u64()) {
Some(x) => x,
None => return Err(error::CmdError::NotW3C(Json::Object(obj))),
};
let y = match obj.remove("y").and_then(|y| y.as_u64()) {
Some(y) => y,
None => return Err(error::CmdError::NotW3C(Json::Object(obj))),
};
let width = match obj.remove("width").and_then(|width| width.as_u64()) {
Some(width) => width,
None => return Err(error::CmdError::NotW3C(Json::Object(obj))),
};
let height = match obj.remove("height").and_then(|height| height.as_u64()) {
Some(height) => height,
None => return Err(error::CmdError::NotW3C(Json::Object(obj))),
};
Ok((x, y, width, height))
}
v => Err(error::CmdError::NotW3C(v)),
}
}
/// Sets the x, y, width, and height properties of the current window.
///
/// See [10.7.2 Set Window Rect](https://www.w3.org/TR/webdriver1/#dfn-set-window-rect) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Set Window Rect"))]
pub async fn set_window_size(&self, width: u32, height: u32) -> Result<(), error::CmdError> {
let cmd = WebDriverCommand::SetWindowRect(webdriver::command::WindowRectParameters {
x: None,
y: None,
width: Some(width as i32),
height: Some(height as i32),
});
self.issue(cmd).await?;
Ok(())
}
/// Gets the width and height of the current window.
///
/// See [10.7.1 Get Window Rect](https://www.w3.org/TR/webdriver1/#dfn-get-window-rect) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Get Window Rect"))]
pub async fn get_window_size(&self) -> Result<(u64, u64), error::CmdError> {
let (_, _, width, height) = self.get_window_rect().await?;
Ok((width, height))
}
/// Sets the x, y, width, and height properties of the current window.
///
/// See [10.7.2 Set Window Rect](https://www.w3.org/TR/webdriver1/#dfn-set-window-rect) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Set Window Rect"))]
pub async fn set_window_position(&self, x: u32, y: u32) -> Result<(), error::CmdError> {
let cmd = WebDriverCommand::SetWindowRect(webdriver::command::WindowRectParameters {
x: Some(x as i32),
y: Some(y as i32),
width: None,
height: None,
});
self.issue(cmd).await?;
Ok(())
}
/// Gets the x and y top-left coordinate of the current window.
///
/// See [10.7.1 Get Window Rect](https://www.w3.org/TR/webdriver1/#dfn-get-window-rect) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Get Window Rect"))]
pub async fn get_window_position(&self) -> Result<(u64, u64), error::CmdError> {
let (x, y, _, _) = self.get_window_rect().await?;
Ok((x, y))
}
/// Maximize the current window.
///
/// See [10.7.3 Maximize Window](https://www.w3.org/TR/webdriver1/#dfn-maximize-window) of the
/// WebDriver standard.
pub async fn maximize_window(&self) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::MaximizeWindow).await?;
Ok(())
}
/// Minimize the current window.
///
/// See [10.7.4 Minimize Window](https://www.w3.org/TR/webdriver1/#dfn-minimize-window) of the
/// WebDriver standard.
pub async fn minimize_window(&self) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::MinimizeWindow).await?;
Ok(())
}
/// Make the current window fullscreen.
///
/// See [10.7.5 Fullscreen Window](https://www.w3.org/TR/webdriver1/#dfn-fullscreen-window) of the
/// WebDriver standard.
pub async fn fullscreen_window(&self) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::FullscreenWindow).await?;
Ok(())
}
}
/// [Element Retrieval](https://www.w3.org/TR/webdriver1/#element-retrieval)
impl Client {
/// Find an element on the page that matches the given [`Locator`].
///
/// See [12.2 Find Element](https://www.w3.org/TR/webdriver1/#find-element) of the WebDriver
/// standard.
#[cfg_attr(docsrs, doc(alias = "Find Element"))]
pub async fn find(&self, search: Locator<'_>) -> Result<Element, error::CmdError> {
self.by(search.into_parameters()).await
}
/// Find all elements on the page that match the given [`Locator`].
///
/// See [12.3 Find Elements](https://www.w3.org/TR/webdriver1/#find-elements) of the WebDriver
/// standard.
#[cfg_attr(docsrs, doc(alias = "Find Elements"))]
pub async fn find_all(&self, search: Locator<'_>) -> Result<Vec<Element>, error::CmdError> {
let res = self
.issue(WebDriverCommand::FindElements(search.into_parameters()))
.await?;
let array = self.parse_lookup_all(res)?;
Ok(array
.into_iter()
.map(move |e| Element {
client: self.clone(),
element: e,
})
.collect())
}
/// 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.
///
/// See [12.6 Get Active Element](https://www.w3.org/TR/webdriver1/#dfn-get-active-element) of
/// the WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Get Active Element"))]
pub async fn active_element(&self) -> Result<Element, error::CmdError> {
let res = self.issue(WebDriverCommand::GetActiveElement).await?;
let e = self.parse_lookup(res)?;
Ok(Element {
client: self.clone(),
element: e,
})
}
/// Locate a form on the page.
///
/// Through the returned `Form`, HTML forms can be filled out and submitted.
pub async fn form(&self, search: Locator<'_>) -> Result<Form, error::CmdError> {
let l = search.into_parameters();
let res = self.issue(WebDriverCommand::FindElement(l)).await?;
let f = self.parse_lookup(res)?;
Ok(Form {
client: self.clone(),
form: f,
})
}
}
/// [Document Handling](https://www.w3.org/TR/webdriver1/#document-handling)
impl Client {
/// Get the HTML source for the current page.
///
/// See [15.1 Get Page Source](https://www.w3.org/TR/webdriver1/#dfn-get-page-source) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Get Page Source"))]
pub async fn source(&self) -> Result<String, error::CmdError> {
let src = self.issue(WebDriverCommand::GetPageSource).await?;
if let Some(src) = src.as_str() {
Ok(src.to_string())
} else {
Err(error::CmdError::NotW3C(src))
}
}
/// 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 `Element`s 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.
///
/// See [15.2.1 Execute Script](https://www.w3.org/TR/webdriver1/#dfn-execute-script) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Execute Script"))]
pub async fn execute(
&self,
script: &str,
mut args: Vec<Json>,
) -> Result<Json, error::CmdError> {
self.fixup_elements(&mut args);
let cmd = webdriver::command::JavascriptCommandParameters {
script: script.to_string(),
args: Some(args),
};
self.issue(WebDriverCommand::ExecuteScript(cmd)).await
}
/// 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 `Element`s 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
///
/// ```ignore
/// 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?;
/// ```
///
/// See [15.2.2 Execute Async
/// Script](https://www.w3.org/TR/webdriver1/#dfn-execute-async-script) of the WebDriver
/// standard.
#[cfg_attr(docsrs, doc(alias = "Execute Async Script"))]
pub async fn execute_async(
&self,
script: &str,
mut args: Vec<Json>,
) -> Result<Json, error::CmdError> {
self.fixup_elements(&mut args);
let cmd = webdriver::command::JavascriptCommandParameters {
script: script.to_string(),
args: Some(args),
};
self.issue(WebDriverCommand::ExecuteAsyncScript(cmd)).await
}
}
/// [Actions](https://www.w3.org/TR/webdriver1/#actions)
impl Client {
/// Create a new Actions chain.
///
/// ```ignore
/// let mouse_actions = MouseActions::new("mouse")
/// .then(PointerAction::Down {
/// button: MOUSE_BUTTON_LEFT,
/// })
/// .then(PointerAction::MoveBy {
/// duration: Some(Duration::from_secs(2)),
/// x: 100,
/// y: 0,
/// })
/// .then(PointerAction::Up {
/// button: MOUSE_BUTTON_LEFT,
/// });
/// client.perform_actions(mouse_actions).await?;
/// ```
///
/// See the documentation for [`Actions`] for more information.
/// Perform the specified input actions.
///
/// See [17.5 Perform Actions](https://www.w3.org/TR/webdriver1/#perform-actions) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Perform Actions"))]
pub async fn perform_actions(
&self,
actions: impl Into<Actions>,
) -> Result<(), error::CmdError> {
let params = webdriver::command::ActionsParameters {
actions: actions.into().sequences.into_iter().map(|x| x.0).collect(),
};
self.issue(WebDriverCommand::PerformActions(params)).await?;
Ok(())
}
/// Release all input actions.
///
/// See [17.6 Release Actions](https://www.w3.org/TR/webdriver1/#release-actions) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Release Actions"))]
pub async fn release_actions(&self) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::ReleaseActions).await?;
Ok(())
}
}
/// [User Prompts](https://www.w3.org/TR/webdriver1/#user-prompts)
impl Client {
/// Dismiss the active alert, if there is one.
///
/// See [18.1 Dismiss Alert](https://www.w3.org/TR/webdriver1/#dismiss-alert) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Dismiss Alert"))]
pub async fn dismiss_alert(&self) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::DismissAlert).await?;
Ok(())
}
/// Accept the active alert, if there is one.
///
/// See [18.2 Accept Alert](https://www.w3.org/TR/webdriver1/#accept-alert) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Accept Alert"))]
pub async fn accept_alert(&self) -> Result<(), error::CmdError> {
self.issue(WebDriverCommand::AcceptAlert).await?;
Ok(())
}
/// Get the text of the active alert, if there is one.
///
/// See [18.3 Get Alert Text](https://www.w3.org/TR/webdriver1/#get-alert-text) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Get Alert Text"))]
pub async fn get_alert_text(&self) -> Result<String, error::CmdError> {
let res = self.issue(WebDriverCommand::GetAlertText).await?;
if let Json::String(s) = res {
Ok(s)
} else {
Err(error::CmdError::NotW3C(res))
}
}
/// Send the specified text to the active alert, if there is one.
///
/// See [18.4 Send Alert Text](https://www.w3.org/TR/webdriver1/#send-alert-text) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Send Alert Text"))]
pub async fn send_alert_text(&self, text: &str) -> Result<(), error::CmdError> {
let params = SendKeysParameters {
text: text.to_string(),
};
self.issue(WebDriverCommand::SendAlertText(params)).await?;
Ok(())
}
}
/// [Screen Capture](https://www.w3.org/TR/webdriver1/#screen-capture)
impl Client {
/// Get a PNG-encoded screenshot of the current page.
///
/// See [19.1 Take Screenshot](https://www.w3.org/TR/webdriver1/#dfn-take-screenshot) of the
/// WebDriver standard.
#[cfg_attr(docsrs, doc(alias = "Take Screenshot"))]
pub async fn screenshot(&self) -> Result<Vec<u8>, error::CmdError> {
let src = self.issue(WebDriverCommand::TakeScreenshot).await?;
if let Some(src) = src.as_str() {
base64::decode(src).map_err(error::CmdError::ImageDecodeError)
} else {
Err(error::CmdError::NotW3C(src))
}
}
}
/// Operations that wait for a change on the page.
impl Client {
/// 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.
#[deprecated(
since = "0.17.5",
note = "This method might block forever. Please use client.wait().on(...) instead. You can still wait forever using: client.wait().forever().on(...)"
)]
pub async fn wait_for<F, FF>(&self, mut is_ready: F) -> Result<(), error::CmdError>
where
F: FnMut(&Client) -> FF,
FF: Future<Output = Result<bool, error::CmdError>>,
{
while !is_ready(self).await? {}
Ok(())
}
/// 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.
#[deprecated(
since = "0.17.5",
note = "This method might block forever. Please use client.wait().on(locator) instead. You can still wait forever using: client.wait().forever().on(locator)"
)]
pub async fn wait_for_find(&self, search: Locator<'_>) -> Result<Element, error::CmdError> {
self.wait().forever().for_element(search).await
}
/// 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.
#[deprecated(
since = "0.17.5",
note = "This method might block forever and has a chance of randomly blocking. Please use client.wait().on(url) instead, to check if you navigated successfully to the new URL."
)]
pub async fn wait_for_navigation(
&self,
current: Option<url::Url>,
) -> Result<(), error::CmdError> {
let current = match current {
Some(current) => current,
None => self.current_url_().await?,
};
#[allow(deprecated)]
self.wait_for(move |c| {
// TODO: get rid of this clone
let current = current.clone();
// TODO: and this one too
let c = c.clone();
async move { Ok(c.current_url().await? != current) }
})
.await
}
}
/// Raw access to the WebDriver instance.
impl Client {
/// 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 raw_client_for(
&self,
method: Method,
url: &str,
) -> Result<hyper::Response<hyper::Body>, error::CmdError> {
self.with_raw_client_for(method, url, |req| req.body(hyper::Body::empty()).unwrap())
.await
}
/// 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 with_raw_client_for<F>(
&self,
method: Method,
url: &str,
before: F,
) -> Result<hyper::Response<hyper::Body>, error::CmdError>
where
F: FnOnce(http::request::Builder) -> hyper::Request<hyper::Body>,
{
let url = url.to_owned();
// We need to do some trickiness here. GetCookies will only give us the cookies for the
// *current* domain, whereas we want the cookies for `url`'s domain. So, we navigate to the
// URL in question, fetch its cookies, and then navigate back. *Except* that we can't do
// that either (what if `url` is some huge file?). So we *actually* navigate to some weird
// url that's unlikely to exist on the target doamin, and which won't resolve into the
// actual content, but will still give the same cookies.
//
// The fact that cookies can have /path and security constraints makes this even more of a
// pain. /path in particular is tricky, because you could have a URL like:
//
// example.com/download/some_identifier/ignored_filename_just_for_show
//
// Imagine if a cookie is set with path=/download/some_identifier. How do we get that
// cookie without triggering a request for the (large) file? I don't know. Hence: TODO.
let old_url = self.current_url_().await?;
let url = old_url.clone().join(&url)?;
let cookie_url = url.clone().join("/please_give_me_your_cookies")?;
self.goto(cookie_url.as_str()).await?;
// TODO: go back before we return if this call errors:
let cookies = self.issue(WebDriverCommand::GetCookies).await?;
if !cookies.is_array() {
return Err(error::CmdError::NotW3C(cookies));
}
self.back().await?;
let ua = self.get_ua().await?;
// now add all the cookies
let mut all_ok = true;
let mut jar = Vec::new();
for cookie in cookies.as_array().unwrap() {
if !cookie.is_object() {
all_ok = false;
break;
}
// https://w3c.github.io/webdriver/webdriver-spec.html#cookies
let cookie = cookie.as_object().unwrap();
if !cookie.contains_key("name") || !cookie.contains_key("value") {
all_ok = false;
break;
}
if !cookie["name"].is_string() || !cookie["value"].is_string() {
all_ok = false;
break;
}
// Note that since we're sending these cookies, all that matters is the mapping
// from name to value. The other fields only matter when deciding whether to
// include a cookie or not, and the driver has already decided that for us
// (GetCookies is for a particular URL).
jar.push(
cookie::Cookie::new(
cookie["name"].as_str().unwrap().to_owned(),
cookie["value"].as_str().unwrap().to_owned(),
)
.encoded()
.to_string(),
);
}
if !all_ok {
return Err(error::CmdError::NotW3C(cookies));
}
let mut req = hyper::Request::builder();
req = req
.method(method)
.uri(http::Uri::try_from(url.as_str()).unwrap());
req = req.header(hyper::header::COOKIE, jar.join("; "));
if let Some(s) = ua {
req = req.header(hyper::header::USER_AGENT, s);
}
let req = before(req);
let (tx, rx) = oneshot::channel();
self.issue(Cmd::Raw { req, rsp: tx }).await?;
match rx.await {
Ok(Ok(r)) => Ok(r),
Ok(Err(e)) => Err(e.into()),
Err(e) => unreachable!("Session ended prematurely: {:?}", e),
}
}
}
/// Allow to wait for conditions.
impl Client {
/// Starting building a new wait operation. This can be used to wait for a certain condition, by
/// periodically checking the state and optionally returning a value:
///
/// ```no_run
/// # use fantoccini::{ClientBuilder, Locator};
/// # #[tokio::main]
/// # async fn main() -> Result<(), fantoccini::error::CmdError> {
/// # #[cfg(all(feature = "native-tls", not(feature = "rustls-tls")))]
/// # let client = ClientBuilder::native().connect("http://localhost:4444").await.expect("failed to connect to WebDriver");
/// # #[cfg(feature = "rustls-tls")]
/// # let client = ClientBuilder::rustls().connect("http://localhost:4444").await.expect("failed to connect to WebDriver");
/// # #[cfg(all(not(feature = "native-tls"), not(feature = "rustls-tls")))]
/// # let client: fantoccini::Client = unreachable!("no tls provider available");
/// // -- snip wrapper code --
/// let button = client.wait().for_element(Locator::Css(
/// r#"a.button-download[href="/learn/get-started"]"#,
/// )).await?;
/// // -- snip wrapper code --
/// # client.close().await
/// # }
/// ```
///
/// Also see: [`crate::wait`].
pub fn wait(&self) -> Wait<'_> {
Wait::new(self)
}
}
/// Helper methods
impl Client {
pub(crate) async fn by(
&self,
locator: webdriver::command::LocatorParameters,
) -> Result<Element, error::CmdError> {
let res = self.issue(WebDriverCommand::FindElement(locator)).await?;
let e = self.parse_lookup(res)?;
Ok(Element {
client: self.clone(),
element: e,
})
}
/// Extract the `WebElement` from a `FindElement` or `FindElementElement` command.
pub(crate) fn parse_lookup(
&self,
res: Json,
) -> Result<webdriver::common::WebElement, error::CmdError> {
let mut res = match res {
Json::Object(o) => o,
res => return Err(error::CmdError::NotW3C(res)),
};
// legacy protocol uses "ELEMENT" as identifier
let key = if self.is_legacy() {
"ELEMENT"
} else {
ELEMENT_KEY
};
if !res.contains_key(key) {
return Err(error::CmdError::NotW3C(Json::Object(res)));
}
match res.remove(key) {
Some(Json::String(wei)) => {
return Ok(webdriver::common::WebElement(wei));
}
Some(v) => {
res.insert(key.to_string(), v);
}
None => {}
}
Err(error::CmdError::NotW3C(Json::Object(res)))
}
/// Extract `WebElement`s from a `FindElements` or `FindElementElements` command.
pub(crate) fn parse_lookup_all(
&self,
res: Json,
) -> Result<Vec<webdriver::common::WebElement>, error::CmdError> {
let res = match res {
Json::Array(a) => a,
res => return Err(error::CmdError::NotW3C(res)),
};
let mut array = Vec::new();
for json in res {
let e = self.parse_lookup(json)?;
array.push(e);
}
Ok(array)
}
pub(crate) fn fixup_elements(&self, args: &mut [Json]) {
if self.is_legacy() {
for arg in args {
// the serialization of WebElement uses the W3C index,
// but legacy implementations need us to use the "ELEMENT" index
if let Json::Object(ref mut o) = *arg {
if let Some(wei) = o.remove(ELEMENT_KEY) {
o.insert("ELEMENT".to_string(), wei);
}
}
}
}
}
}
/// Response returned by [`Client::new_window()`] method.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct NewWindowResponse {
/// Handle to the created browser window.
pub handle: WindowHandle,
/// Type of the created browser window.
pub typ: NewWindowType,
}