feat: snapshot diff

Author: junhsss

src/browser/daemon/protocol.rs

@@ -282,6 +282,21 @@ pub enum DaemonCommand {
         offline: bool,
     },
 
+    // ── Diff ──
+    DiffSnapshot {
+        baseline: Option<String>,
+        selector: Option<String>,
+        compact: bool,
+        max_depth: Option<usize>,
+    },
+    DiffScreenshot {
+        baseline: String,
+        threshold: Option<f64>,
+        selector: Option<String>,
+        full_page: bool,
+        output: Option<String>,
+    },
+
     Close,
     Ping,
     Shutdown,

src/browser/daemon/server.rs

@@ -662,6 +662,35 @@ async fn dispatch_inner(
             Ok(json!({"offline": offline}))
         }
 
+        // ── Diff ──
+        DaemonCommand::DiffSnapshot {
+            baseline,
+            selector,
+            compact,
+            max_depth,
+        } => {
+            let options = build_snapshot_options(false, selector, compact, max_depth, false);
+            engine.diff_snapshot(baseline.as_deref(), options).await
+        }
+        DaemonCommand::DiffScreenshot {
+            baseline,
+            threshold,
+            selector,
+            full_page,
+            output,
+        } => {
+            let options =
+                build_screenshot_options(full_page, selector, None, None, false, None, None);
+            engine
+                .diff_screenshot(
+                    &baseline,
+                    threshold.unwrap_or(0.1),
+                    options,
+                    output.as_deref(),
+                )
+                .await
+        }
+
         DaemonCommand::Close | DaemonCommand::Shutdown => Ok(json!({"closed": true})),
         DaemonCommand::Ping => Ok(json!("pong")),
         DaemonCommand::GetSessionInfo => {

src/browser/engine.rs

@@ -9,6 +9,7 @@ use anyhow::Result;
 
 use browser_engine::native::browser::{BrowserManager, WaitUntil};
 use browser_engine::native::cdp::client::CdpClient;
+use browser_engine::native::diff;
 use browser_engine::native::element::{self, RefMap};
 use browser_engine::native::interaction;
 use browser_engine::native::network;
@@ -900,6 +901,66 @@ impl BrowserEngine {
             .map_err(|e| anyhow::anyhow!(e))
     }
 
+    // ── Diff ─────────────────────────────────────────────────────────
+
+    /// Diff current snapshot against a baseline string or file path.
+    pub async fn diff_snapshot(
+        &mut self,
+        baseline: Option<&str>,
+        options: SnapshotOptions,
+    ) -> Result<serde_json::Value> {
+        let current = self.snapshot(options).await?;
+        let baseline_text = match baseline {
+            Some(b) if std::path::Path::new(b).exists() => std::fs::read_to_string(b)
+                .map_err(|e| anyhow::anyhow!("Failed to read baseline: {e}"))?,
+            Some(b) => b.to_string(),
+            None => String::new(),
+        };
+        let result = diff::diff_snapshots(&baseline_text, &current);
+        Ok(serde_json::json!({
+            "diff": result.diff,
+            "additions": result.additions,
+            "removals": result.removals,
+            "unchanged": result.unchanged,
+            "changed": result.changed,
+        }))
+    }
+
+    /// Diff current screenshot against a baseline image file.
+    pub async fn diff_screenshot(
+        &mut self,
+        baseline_path: &str,
+        threshold: f64,
+        options: ScreenshotOptions,
+        output_path: Option<&str>,
+    ) -> Result<serde_json::Value> {
+        let result = self.take_screenshot(options).await?;
+
+        let current_bytes =
+            base64::Engine::decode(&base64::engine::general_purpose::STANDARD, &result.base64)
+                .map_err(|e| anyhow::anyhow!("Failed to decode screenshot: {e}"))?;
+
+        let baseline_bytes = std::fs::read(baseline_path)
+            .map_err(|e| anyhow::anyhow!("Failed to read baseline: {e}"))?;
+
+        let diff_result = diff::diff_screenshot(&baseline_bytes, &current_bytes, threshold)
+            .map_err(|e| anyhow::anyhow!(e))?;
+
+        if let (Some(out), Some(diff_data)) = (output_path, &diff_result.diff_image) {
+            std::fs::write(out, diff_data)
+                .map_err(|e| anyhow::anyhow!("Failed to write diff image: {e}"))?;
+        }
+
+        Ok(serde_json::json!({
+            "match": diff_result.matched,
+            "mismatchPercentage": diff_result.mismatch_percentage,
+            "totalPixels": diff_result.total_pixels,
+            "differentPixels": diff_result.different_pixels,
+            "diffPath": output_path,
+            "dimensionMismatch": diff_result.dimension_mismatch,
+        }))
+    }
+
     /// Set offline mode.
     pub async fn set_offline(&self, offline: bool) -> Result<()> {
         let (client, session_id) = self.active_client_and_session()?;

src/commands/browser/action.rs

@@ -146,6 +146,13 @@ pub enum ActionCommand {
     #[command(name = "bringtofront")]
     BringToFront,
 
+    // --- Diff ---
+    /// Compare snapshots or screenshots
+    Diff {
+        #[command(subcommand)]
+        command: DiffCommand,
+    },
+
     // --- Session ---
     /// Close the browser session
     #[command(aliases = ["quit", "exit"])]
@@ -259,6 +266,51 @@ pub enum SetCommand {
     UserAgent(SetUserAgentArgs),
 }
 
+// ── Diff subcommands ────────────────────────────────────────────────
+
+#[derive(Subcommand)]
+pub enum DiffCommand {
+    /// Compare current snapshot against a baseline
+    Snapshot(DiffSnapshotArgs),
+    /// Compare current screenshot against a baseline image
+    Screenshot(DiffScreenshotArgs),
+}
+
+#[derive(Parser)]
+pub struct DiffSnapshotArgs {
+    /// Baseline snapshot text or file path
+    #[arg(short, long)]
+    pub baseline: Option<String>,
+    /// Restrict snapshot to a subtree
+    #[arg(short, long)]
+    pub selector: Option<String>,
+    /// Use compact output format
+    #[arg(short, long)]
+    pub compact: bool,
+    /// Maximum nesting depth
+    #[arg(short = 'd', long, alias = "depth")]
+    pub max_depth: Option<usize>,
+}
+
+#[derive(Parser)]
+pub struct DiffScreenshotArgs {
+    /// Baseline image file path (required)
+    #[arg(short, long)]
+    pub baseline: String,
+    /// Color difference threshold (0.0–1.0)
+    #[arg(short, long)]
+    pub threshold: Option<f64>,
+    /// Save diff image to this path
+    #[arg(short, long)]
+    pub output: Option<String>,
+    /// Restrict screenshot to an element
+    #[arg(short, long)]
+    pub selector: Option<String>,
+    /// Capture the full scrollable page
+    #[arg(long, alias = "full")]
+    pub full_page: bool,
+}
+
 // ── Arg structs ─────────────────────────────────────────────────────
 
 #[derive(Parser)]
@@ -1123,6 +1175,63 @@ async fn dispatch_action(client: &mut DaemonClient, action: ActionCommand) -> Re
             output::success(data, "");
         }
 
+        // --- Diff ---
+        ActionCommand::Diff { command } => match command {
+            DiffCommand::Snapshot(args) => {
+                let data = client
+                    .send(DaemonCommand::DiffSnapshot {
+                        baseline: args.baseline,
+                        selector: args.selector,
+                        compact: args.compact,
+                        max_depth: args.max_depth,
+                    })
+                    .await?;
+                if output::is_json() {
+                    output::success_data(data);
+                } else {
+                    let diff_text = data["diff"].as_str().unwrap_or("");
+                    if diff_text.is_empty() {
+                        println!("No changes.");
+                    } else {
+                        print!("{diff_text}");
+                    }
+                }
+            }
+            DiffCommand::Screenshot(args) => {
+                let output_path = args
+                    .output
+                    .as_ref()
+                    .map(|p| resolve_output_path(p))
+                    .transpose()?;
+                let data = client
+                    .send(DaemonCommand::DiffScreenshot {
+                        baseline: resolve_output_path(&args.baseline)?,
+                        threshold: args.threshold,
+                        selector: args.selector,
+                        full_page: args.full_page,
+                        output: output_path,
+                    })
+                    .await?;
+                if output::is_json() {
+                    output::success_data(data);
+                } else {
+                    let matched = data["match"].as_bool().unwrap_or(false);
+                    let pct = data["mismatchPercentage"]
+                        .as_f64()
+                        .map(|p| format!("{p:.2}%"))
+                        .unwrap_or_default();
+                    if matched {
+                        println!("Screenshots match.");
+                    } else {
+                        println!("Mismatch: {pct}");
+                        if let Some(p) = data["diffPath"].as_str() {
+                            println!("Diff image: {p}");
+                        }
+                    }
+                }
+            }
+        },
+
         // --- Session ---
         ActionCommand::Close => {
             let data = client.send(DaemonCommand::Close).await?;