feat(client): implement printing pages as PDF (#285)

Author: manuelpelloni

src/client.rs

@@ -6,8 +6,8 @@ use crate::error;
 use crate::session::{Cmd, Session, Task};
 use crate::wait::Wait;
 use crate::wd::{
-    Capabilities, Locator, NewSessionResponse, NewWindowType, TimeoutConfiguration,
-    WebDriverStatus, WindowHandle,
+    Capabilities, Locator, NewSessionResponse, NewWindowType, PrintConfiguration,
+    TimeoutConfiguration, WebDriverStatus, WindowHandle,
 };
 use base64::Engine;
 use http::Method;
@@ -1096,6 +1096,26 @@ impl Client {
             Err(error::CmdError::NotW3C(src))
         }
     }
+
+    /// Get a PDF of the current page.
+    ///
+    /// See [18.1 Print Page](https://www.w3.org/TR/webdriver2/#print-page) of the
+    /// WebDriver2 standard.
+    pub async fn print(
+        &self,
+        print_configuration: PrintConfiguration,
+    ) -> Result<Vec<u8>, error::CmdError> {
+        let src = self
+            .issue(WebDriverCommand::Print(print_configuration.into_params()))
+            .await?;
+        if let Some(src) = src.as_str() {
+            base64::engine::general_purpose::STANDARD
+                .decode(src)
+                .map_err(error::CmdError::PdfDecodeError)
+        } else {
+            Err(error::CmdError::NotW3C(src))
+        }
+    }
 }
 
 /// Operations that wait for a change on the page.

src/error.rs

@@ -72,6 +72,7 @@ impl fmt::Display for NewSessionError {
 
 /// An error occurred while executing some browser action.
 #[derive(Debug)]
+#[non_exhaustive]
 pub enum CmdError {
     /// A standard WebDriver error occurred.
     ///
@@ -118,6 +119,9 @@ pub enum CmdError {
     /// Could not decode a base64 image
     ImageDecodeError(base64::DecodeError),
 
+    /// Could not decode a base64 PDF.
+    PdfDecodeError(base64::DecodeError),
+
     /// Timeout of a wait condition.
     ///
     /// When waiting for a for a condition using [`Client::wait`](crate::Client::wait), any of the
@@ -190,6 +194,7 @@ impl Error for CmdError {
             CmdError::NotW3C(..) => "webdriver returned non-conforming response",
             CmdError::InvalidArgument(..) => "invalid argument provided",
             CmdError::ImageDecodeError(..) => "error decoding image",
+            CmdError::PdfDecodeError(..) => "error decoding PDF",
             CmdError::WaitTimeout => "timeout waiting on condition",
         }
     }
@@ -202,7 +207,7 @@ impl Error for CmdError {
             CmdError::FailedC(ref e) => Some(e),
             CmdError::Lost(ref e) => Some(e),
             CmdError::Json(ref e) => Some(e),
-            CmdError::ImageDecodeError(ref e) => Some(e),
+            CmdError::ImageDecodeError(ref e) | CmdError::PdfDecodeError(ref e) => Some(e),
             CmdError::NotJson(_)
             | CmdError::NotW3C(_)
             | CmdError::InvalidArgument(..)
@@ -224,7 +229,9 @@ impl fmt::Display for CmdError {
             CmdError::NotJson(ref e) => write!(f, "{}", e),
             CmdError::Json(ref e) => write!(f, "{}", e),
             CmdError::NotW3C(ref e) => write!(f, "{:?}", e),
-            CmdError::ImageDecodeError(ref e) => write!(f, "{:?}", e),
+            CmdError::ImageDecodeError(ref e) | CmdError::PdfDecodeError(ref e) => {
+                write!(f, "{:?}", e)
+            }
             CmdError::InvalidArgument(ref arg, ref msg) => {
                 write!(f, "Invalid argument `{}`: {}", arg, msg)
             }
@@ -285,6 +292,35 @@ impl From<InvalidWindowHandle> for CmdError {
     }
 }
 
+/// Error of attempting to build an invalid [`PrintConfiguration`](crate::wd::PrintConfiguration).
+#[derive(Debug, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum PrintConfigurationError {
+    /// One or more dimensions of the page margins/size are negative.
+    NegativeDimensions,
+    /// One or more dimensions of the page margins/size are NaN or infinite.
+    NonFiniteDimensions,
+    /// The margins overflow the page size (e.g. margins.left + margins.right >= page.width).
+    DimensionsOverflow,
+    /// Eighter one of print height or width are smaller than the [`PrintSize::MIN`](crate::wd::PrintSize::MIN).
+    PrintSizeTooSmall,
+}
+
+impl fmt::Display for PrintConfigurationError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(match self {
+            Self::NegativeDimensions => {
+                "one or more dimensions of the page (margins and/or size) are negative"
+            }
+            Self::NonFiniteDimensions => {
+                "one or more dimensions of the page (margins and/or size) are NaN or infinite"
+            }
+            Self::DimensionsOverflow => "the margins overflow the page size",
+            Self::PrintSizeTooSmall => "the print size is too small",
+        })
+    }
+}
+
 /// The error code returned from the WebDriver.
 #[derive(Debug, PartialEq, Eq, Hash)]
 #[non_exhaustive]

src/lib.rs

@@ -275,3 +275,5 @@ pub mod wait;
 pub mod wd;
 #[doc(inline)]
 pub use wd::Locator;
+
+mod print;