Merge remote-tracking branch 'origin/master' into feat/cors-iframes-and-shadow-dom

# Conflicts:
#	package.json
#	src/main/java/io/percy/selenium/Percy.java

Author: aryanku-dev

package.json

@@ -4,7 +4,7 @@
     "test": "npx percy exec --testing -- mvn test"
   },
   "devDependencies": {
-    "@percy/cli": "1.31.14"
+    "@percy/cli": "^1.31.15-beta.0"
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

pom.xml

@@ -5,7 +5,7 @@
 
   <groupId>io.percy</groupId>
   <artifactId>percy-java-selenium</artifactId>
-  <version>2.2.0</version>
+  <version>2.2.1-beta.0</version>
   <packaging>jar</packaging>
 
   <name>${project.groupId}:${project.artifactId}</name>
@@ -32,7 +32,7 @@
     <connection>scm:git:git://github.com/percy/percy-java-selenium.git</connection>
     <developerConnection>scm:git:https://github.com/percy/percy-java-selenium.git</developerConnection>
     <url>https://github.com/percy/percy-java-selenium/tree/master</url>
-    <tag>v2.1.2</tag>
+    <tag>v2.2.1-beta.0</tag>
   </scm>
 
   <properties>

src/main/java/io/percy/selenium/Environment.java

@@ -10,7 +10,7 @@
  */
 class Environment {
   private WebDriver driver;
-  private final static String SDK_VERSION = "2.1.2";
+  private final static String SDK_VERSION = "2.2.1-beta.0";
   private final static String SDK_NAME = "percy-java-selenium";
 
   private String clientInfoOverride;

src/main/java/io/percy/selenium/Percy.java

@@ -567,6 +567,10 @@ private JSONObject postSnapshot(
 
         // Build a JSON object to POST back to the agent node process
         JSONObject json = new JSONObject(options);
+        // `readiness` is SDK-local — the CLI already has it via healthcheck.
+        // Strip before posting to avoid round-tripping and to stay forward-
+        // compatible with future CLI-side validators rejecting unknown fields.
+        json.remove("readiness");
         json.put("url", url);
         json.put("name", name);
         json.put("domSnapshot", domSnapshot);
@@ -617,11 +621,99 @@ protected JSONObject request(String url, JSONObject json, String name) {
     private String buildSnapshotJS(Map<String, Object> options) {
         StringBuilder jsBuilder = new StringBuilder();
         JSONObject json = new JSONObject(options);
+        // `readiness` is consumed by waitForReady upstream — not a serialize arg.
+        json.remove("readiness");
         jsBuilder.append(String.format("return PercyDOM.serialize(%s)\n", json.toString()));
 
         return jsBuilder.toString();
     }
 
+    /**
+     * Readiness gate: runs PercyDOM.waitForReady BEFORE serialize.
+     *
+     * Uses executeAsyncScript with a callback signal. The embedded JS checks
+     * typeof PercyDOM.waitForReady === 'function' so older CLI versions that
+     * lack the method are a graceful no-op.
+     *
+     * Config precedence: per-snapshot options["readiness"] is shallow-merged
+     * over cliConfig.snapshot.readiness so a partial per-snapshot override
+     * inherits global keys (notably preset: disabled) instead of dropping
+     * them. The merged "disabled" preset skips the executeAsyncScript entirely.
+     *
+     * @return Readiness diagnostics to attach to the domSnapshot, or null.
+     */
+    protected Object waitForReady(JavascriptExecutor jse, Map<String, Object> options) {
+        JSONObject readinessConfig = resolveReadinessConfig(options);
+        if ("disabled".equals(readinessConfig.optString("preset", null))) {
+            return null;
+        }
+        // Match the driver's async-script timeout to readiness.timeoutMs so
+        // a higher user-configured timeout isn't silently capped by WebDriver
+        // firing ScriptTimeoutException before the in-page Promise resolves.
+        long timeoutMs = readinessConfig.optLong("timeoutMs", 0L);
+        Duration previousTimeout = null;
+        if (timeoutMs > 0) {
+            try {
+                previousTimeout = jse instanceof org.openqa.selenium.WebDriver
+                        ? ((org.openqa.selenium.WebDriver) jse).manage().timeouts().getScriptTimeout()
+                        : null;
+                if (jse instanceof org.openqa.selenium.WebDriver) {
+                    ((org.openqa.selenium.WebDriver) jse).manage().timeouts()
+                            .scriptTimeout(Duration.ofMillis(timeoutMs + 2000L));
+                }
+            } catch (Exception e) {
+                previousTimeout = null; // best-effort; older Selenium / unsupported
+            }
+        }
+        try {
+            String script =
+                "var cfg = " + readinessConfig.toString() + ";"
+                + "var done = arguments[arguments.length - 1];"
+                + "try {"
+                + "  if (typeof PercyDOM !== 'undefined' && typeof PercyDOM.waitForReady === 'function') {"
+                + "    PercyDOM.waitForReady(cfg).then(function(r){ done(r); }).catch(function(){ done(); });"
+                + "  } else { done(); }"
+                + "} catch (e) { done(); }";
+            return jse.executeAsyncScript(script);
+        } catch (Exception e) {
+            log("waitForReady failed, proceeding to serialize: " + e.getMessage(), "debug");
+            return null;
+        } finally {
+            if (previousTimeout != null && jse instanceof org.openqa.selenium.WebDriver) {
+                try {
+                    ((org.openqa.selenium.WebDriver) jse).manage().timeouts()
+                            .scriptTimeout(previousTimeout);
+                } catch (Exception ignored) { /* best effort */ }
+            }
+        }
+    }
+
+    /**
+     * Shallow-merge of global (cliConfig.snapshot.readiness) and per-snapshot
+     * (options["readiness"]) readiness config. Per-snapshot keys win, global
+     * keys are inherited. Defensive against null / wrong-type values.
+     */
+    @SuppressWarnings("unchecked")
+    private JSONObject resolveReadinessConfig(Map<String, Object> options) {
+        JSONObject merged = new JSONObject();
+        if (cliConfig != null) {
+            JSONObject snapshotConfig = cliConfig.optJSONObject("snapshot");
+            JSONObject global = snapshotConfig == null ? null : snapshotConfig.optJSONObject("readiness");
+            if (global != null) {
+                for (String key : global.keySet()) merged.put(key, global.get(key));
+            }
+        }
+        Object perSnapshot = options != null ? options.get("readiness") : null;
+        if (perSnapshot instanceof Map) {
+            JSONObject perJson = new JSONObject((Map<String, Object>) perSnapshot);
+            for (String key : perJson.keySet()) merged.put(key, perJson.get(key));
+        } else if (perSnapshot instanceof JSONObject) {
+            JSONObject perJson = (JSONObject) perSnapshot;
+            for (String key : perJson.keySet()) merged.put(key, perJson.get(key));
+        }
+        return merged;
+    }
+
     static class FatalIframeException extends RuntimeException {
         FatalIframeException(String message, Throwable cause) {
             super(message, cause);
@@ -963,7 +1055,10 @@ private List<Map<String, Object>> processFrameTree(
         }
     }
 
-    private Map<String, Object> getSerializedDOM(JavascriptExecutor jse, Set<Cookie> cookies, Map<String, Object> options) {
+    Map<String, Object> getSerializedDOM(JavascriptExecutor jse, Set<Cookie> cookies, Map<String, Object> options) {
+        // Readiness gate before serialize. Graceful on old CLI.
+        Object readinessDiagnostics = waitForReady(jse, options);
+
         Object raw = jse.executeScript(buildSnapshotJS(options));
         if (!(raw instanceof Map)) {
             throw new RuntimeException("PercyDOM.serialize returned null or non-object; "
@@ -974,6 +1069,11 @@ private Map<String, Object> getSerializedDOM(JavascriptExecutor jse, Set<Cookie>
         Map<String, Object> mutableSnapshot = new HashMap<>(domSnapshot);
         mutableSnapshot.put("cookies", cookies);
 
+        // Attach readiness diagnostics so the CLI can log timing and pass/fail
+        if (readinessDiagnostics != null) {
+            mutableSnapshot.put("readiness_diagnostics", readinessDiagnostics);
+        }
+
         // Expose closed shadow roots via CDP (Chromium only) so PercyDOM.serialize
         // can pierce them through the WeakMap it reads. Non-fatal — skip on errors.
         try { exposeClosedShadowRoots(driver); } catch (Exception ignore) {}

src/test/java/io/percy/selenium/SdkTest.java

@@ -1128,6 +1128,82 @@ public void captureResponsiveDomRefreshesDriverForEachWidthWhenReloadFlagSet() t
         }
     }
 
+    // --- Readiness gate -----------------------------------------
+
+    @Test
+    public void readinessRunsBeforeSerializeAndAttachesDiagnostics() throws Exception {
+      RemoteWebDriver mockedDriver = mock(RemoteWebDriver.class);
+      Percy mockedPercy = new Percy(mockedDriver);
+      setField(mockedPercy, "isPercyEnabled", true);
+      setField(mockedPercy, "cliConfig", new JSONObject().put("snapshot", new JSONObject()));
+
+      Map<String, Object> diagnostics = new HashMap<>();
+      diagnostics.put("ok", true);
+      diagnostics.put("timed_out", false);
+      // executeAsyncScript (readiness)
+      when(((JavascriptExecutor) mockedDriver).executeAsyncScript(any(String.class))).thenReturn(diagnostics);
+      // executeScript (serialize + any other sync scripts)
+      Map<String, Object> domSnap = new HashMap<>();
+      domSnap.put("html", "<html></html>");
+      when(((JavascriptExecutor) mockedDriver).executeScript(any(String.class))).thenReturn(domSnap);
+
+      Map<String, Object> result = mockedPercy.getSerializedDOM(
+          (JavascriptExecutor) mockedDriver, new HashSet<>(), new HashMap<>());
+
+      // Readiness script was sent via executeAsyncScript
+      ArgumentCaptor<String> scriptCap = ArgumentCaptor.forClass(String.class);
+      verify((JavascriptExecutor) mockedDriver, atLeastOnce()).executeAsyncScript(scriptCap.capture());
+      assertTrue(scriptCap.getValue().contains("waitForReady"),
+          "readiness script should mention waitForReady");
+      // Diagnostics propagated to the snapshot
+      assertEquals(diagnostics, result.get("readiness_diagnostics"));
+    }
+
+    @Test
+    public void readinessSkippedWhenPresetDisabled() throws Exception {
+      RemoteWebDriver mockedDriver = mock(RemoteWebDriver.class);
+      Percy mockedPercy = new Percy(mockedDriver);
+      setField(mockedPercy, "isPercyEnabled", true);
+
+      Map<String, Object> domSnap = new HashMap<>();
+      domSnap.put("html", "<html></html>");
+      when(((JavascriptExecutor) mockedDriver).executeScript(any(String.class))).thenReturn(domSnap);
+
+      Map<String, Object> disabled = new HashMap<>();
+      disabled.put("preset", "disabled");
+      Map<String, Object> options = new HashMap<>();
+      options.put("readiness", disabled);
+
+      Map<String, Object> result = mockedPercy.getSerializedDOM(
+          (JavascriptExecutor) mockedDriver, new HashSet<>(), options);
+
+      // executeAsyncScript must NOT have been called
+      verify((JavascriptExecutor) mockedDriver, never()).executeAsyncScript(any(String.class));
+      // serialize still ran; no diagnostics attached
+      assertNull(result.get("readiness_diagnostics"));
+    }
+
+    @Test
+    public void snapshotSurvivesReadinessThrow() throws Exception {
+      RemoteWebDriver mockedDriver = mock(RemoteWebDriver.class);
+      Percy mockedPercy = new Percy(mockedDriver);
+      setField(mockedPercy, "isPercyEnabled", true);
+      setField(mockedPercy, "cliConfig", new JSONObject().put("snapshot", new JSONObject()));
+
+      when(((JavascriptExecutor) mockedDriver).executeAsyncScript(any(String.class)))
+          .thenThrow(new RuntimeException("readiness boom"));
+      Map<String, Object> domSnap = new HashMap<>();
+      domSnap.put("html", "<html></html>");
+      when(((JavascriptExecutor) mockedDriver).executeScript(any(String.class))).thenReturn(domSnap);
+
+      Map<String, Object> result = mockedPercy.getSerializedDOM(
+          (JavascriptExecutor) mockedDriver, new HashSet<>(), new HashMap<>());
+
+      // Serialize still ran; no diagnostics attached
+      assertNull(result.get("readiness_diagnostics"));
+      assertEquals("<html></html>", result.get("html"));
+    }
+
     private static Object invokePrivate(Object target, String methodName, Class<?>[] paramTypes, Object... args)
         throws Exception {
       Method method = Percy.class.getDeclaredMethod(methodName, paramTypes);