add more diagonstics and debug info

Signed-off-by: Andrei Gherghescu <[email protected]>

Author: andrei-ng

.github/workflows/ci.yml

@@ -33,14 +33,19 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Setup Chrome
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: 'latest'
+          install-chromedriver: true
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: clippy
           targets: wasm32-unknown-unknown
       # lint the main library workspace for non-wasm target
-      - run: cargo clippy --all-features -- -D warnings
+      - run: cargo clippy --features all -- -D warnings -A deprecated
       # lint the non-wasm examples
-      - run: cd ${{ github.workspace }}/examples && cargo clippy --workspace --exclude "wasm*" -- -D warnings
+      - run: cd ${{ github.workspace }}/examples && cargo clippy --workspace --exclude "wasm*" --exclude "kaleido" -- -D warnings
       # lint the plotly library for wasm target
       - run: cargo clippy --package plotly --target wasm32-unknown-unknown -- -D warnings
       # lint the wasm examples
@@ -68,9 +73,14 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
+      - name: Setup Chrome
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: 'latest'
+          install-chromedriver: true
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
-      - run: cargo test --features plotly_ndarray,plotly_image,kaleido
+      - run: cargo test --workspace --features plotly_ndarray,plotly_image,static_export_default --exclude plotly_kaleido
       - if: ${{ matrix.os == 'windows-latest' }}
         run: gci -recurse -filter "*example*"
 
@@ -103,12 +113,21 @@ jobs:
           ndarray,
           scientific_charts,
           shapes,
+          static_export,
           subplots,
           themes,
         ]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      
+      - name: Setup Chrome (for static_export)
+        if: matrix.example == 'static_export'
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: 'latest'
+          install-chromedriver: true
+    
       - uses: dtolnay/rust-toolchain@stable
       - run: cd ${{ github.workspace }}/examples/${{ matrix.example }} && cargo build
 
@@ -131,6 +150,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      
+      - name: Setup Chrome (for static_export)
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: 'latest'
+          install-chromedriver: true
+      
       - uses: dtolnay/rust-toolchain@stable
       - run: cargo install mdbook --no-default-features --features search --vers "^0.4" --locked --quiet
       - name: Build examples to generate needed html files
@@ -143,5 +169,6 @@ jobs:
           cd ${{ github.workspace }}/examples/subplots && cargo run
           cd ${{ github.workspace }}/examples/shapes && cargo run
           cd ${{ github.workspace }}/examples/themes && cargo run
+          cd ${{ github.workspace }}/examples/static_export && cargo run
       - name: Build book 
-        run: mdbook build docs/book
+        run: mdbook build docs/book

plotly_static/src/lib.rs

@@ -82,7 +82,7 @@
 //!
 //! ### Custom Configuration
 //!
-//! ```rust
+//! ```no_run
 //! use plotly_static::StaticExporterBuilder;
 //!
 //! let exporter = StaticExporterBuilder::default()
@@ -132,7 +132,7 @@
 //! The library supports logging via the `log` crate. Enable it with
 //! `env_logger`:
 //!
-//! ```rust
+//! ```no_run
 //! use plotly_static::StaticExporterBuilder;
 //!
 //! // Initialize logging (typically done once at the start of your application)
@@ -150,7 +150,7 @@
 //!
 //! The library is designed to work safely in parallel environments:
 //!
-//! ```rust
+//! ```no_run
 //! use plotly_static::{StaticExporterBuilder, ImageFormat};
 //! use std::sync::atomic::{AtomicU32, Ordering};
 //!
@@ -256,25 +256,44 @@ use fantoccini::{wd::Capabilities, ClientBuilder};
 use log::{debug, error, warn};
 use serde::Serialize;
 use serde_json::map::Map as JsonMap;
-use tokio::runtime::Runtime;
 use urlencoding::encode;
 use webdriver::WebDriver;
 
 use crate::template::{IMAGE_EXPORT_JS_SCRIPT, PDF_EXPORT_JS_SCRIPT};
 
-const DEFAULT_CAPS_ARRAY: [&str; 12] = [
+#[cfg(feature = "chromedriver")]
+const CHROME_DEFAULT_CAPS: [&str; 23] = [
     "--headless",
     "--no-sandbox",
-    "--disable-gpu",
+    "--disable-gpu-sandbox",
     "--disable-dev-shm-usage",
     "--disable-extensions",
     "--disable-background-networking",
     "--disable-sync",
     "--disable-translate",
-    "--mute-audio",
-    "--safebrowsing-disable-auto-update",
-    "--ignore-certificate-errors",
-    "--log-level=1",
+    "--disable-background-timer-throttling",
+    "--disable-renderer-backgrounding",
+    "--disable-features=VizDisplayCompositor",
+    "--memory-pressure-off",
+    // macOS-specific flags from choreographer
+    "--enable-unsafe-swiftshader",
+    "--use-mock-keychain",
+    "--password-store=basic",
+    "--disable-web-security",
+    "--disable-breakpad",
+    "--no-first-run",
+    "--no-default-browser-check",
+    // Additional flags for better PDF generation support
+    "--disable-backgrounding-occluded-windows",
+    "--disable-ipc-flooding-protection",
+    "--enable-logging",
+    "--v=1",
+];
+
+#[cfg(feature = "geckodriver")]
+const FIREFOX_DEFAULT_CAPS: [&str; 2] = [
+    "-headless",   // Essential for headless operation (single dash for Firefox)
+    "--no-remote", // Prevents connecting to existing Firefox instances
 ];
 
 mod template;
@@ -383,7 +402,9 @@ struct PlotData<'a> {
 ///
 /// # Examples
 ///
-/// ```rust
+/// ```no_run
+/// // This example requires a running WebDriver (chromedriver/geckodriver) and a browser.
+/// // It cannot be run as a doc test.
 /// use plotly_static::StaticExporterBuilder;
 ///
 /// let exporter = StaticExporterBuilder::default()
@@ -425,7 +446,20 @@ impl Default for StaticExporterBuilder {
             webdriver_url: webdriver::WEBDRIVER_URL.to_string(),
             spawn_webdriver: true,
             offline_mode: false,
-            webdriver_browser_caps: DEFAULT_CAPS_ARRAY.iter().map(|s| s.to_string()).collect(),
+            webdriver_browser_caps: {
+                #[cfg(feature = "chromedriver")]
+                {
+                    CHROME_DEFAULT_CAPS.iter().map(|s| s.to_string()).collect()
+                }
+                #[cfg(feature = "geckodriver")]
+                {
+                    FIREFOX_DEFAULT_CAPS.iter().map(|s| s.to_string()).collect()
+                }
+                #[cfg(not(any(feature = "chromedriver", feature = "geckodriver")))]
+                {
+                    Vec::new()
+                }
+            },
         }
     }
 }
@@ -576,12 +610,20 @@ impl StaticExporterBuilder {
     pub fn build(&self) -> Result<StaticExporter> {
         let wd = self.create_webdriver()?;
 
+        let runtime = std::sync::Arc::new(
+            tokio::runtime::Builder::new_multi_thread()
+                .enable_all()
+                .build()
+                .expect("Failed to create Tokio runtime"),
+        );
+
         Ok(StaticExporter {
             webdriver_port: self.webdriver_port,
-            webdriver_url: self.webdriver_url.to_string(),
+            webdriver_url: self.webdriver_url.clone(),
             webdriver: wd,
             offline_mode: self.offline_mode,
             webdriver_browser_caps: self.webdriver_browser_caps.clone(),
+            runtime,
         })
     }
 
@@ -649,6 +691,7 @@ pub struct StaticExporter {
     webdriver: WebDriver,
     offline_mode: bool,
     webdriver_browser_caps: Vec<String>,
+    runtime: std::sync::Arc<tokio::runtime::Runtime>,
 }
 
 impl Drop for StaticExporter {
@@ -663,8 +706,9 @@ impl Drop for StaticExporter {
     /// - Leaves externally managed WebDriver sessions running
     /// - Logs errors but doesn't panic if cleanup fails
     fn drop(&mut self) {
+        // Stop the WebDriver process
         if let Err(e) = self.webdriver.stop() {
-            error!("Failed to release WebDriver process: {e}");
+            error!("Failed to stop WebDriver: {e}");
         }
     }
 }
@@ -835,7 +879,8 @@ impl StaticExporter {
 
     fn static_export(&mut self, plot: &PlotData<'_>) -> Result<String> {
         let data_uri = template::html_body(self.offline_mode);
-        Runtime::new()?
+        let runtime = self.runtime.clone();
+        runtime
             .block_on(self.extract(&data_uri, plot))
             .with_context(|| "Failed to extract static image from browser session")
     }
@@ -943,11 +988,9 @@ impl StaticExporter {
         // Define browser capabilities
         let mut caps = JsonMap::new();
         let mut browser_opts = JsonMap::new();
+        let browser_args = self.webdriver_browser_caps.clone();
 
-        browser_opts.insert(
-            "args".to_string(),
-            serde_json::json!(self.webdriver_browser_caps.clone()),
-        );
+        browser_opts.insert("args".to_string(), serde_json::json!(browser_args));
 
         caps.insert(
             "browserName".to_string(),
@@ -962,6 +1005,19 @@ impl StaticExporter {
 
         Ok(caps)
     }
+
+    /// Get diagnostic information about the underlying WebDriver process
+    ///
+    /// This method provides detailed information about the WebDriver process
+    /// for debugging purposes, including process status, port information,
+    /// and connection details.
+    ///
+    /// # Returns
+    ///
+    /// Returns a string with diagnostic information
+    pub fn get_webdriver_diagnostics(&self) -> String {
+        self.webdriver.get_diagnostics()
+    }
 }
 
 #[cfg(test)]