feat: deep-merge .percy.yml config with per-snapshot options

Ref: PER-8053

Author: rishigupta1599

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

@@ -368,30 +368,95 @@ private boolean isCaptureResponsiveDOM(Map<String, Object> options) {
         return (responsiveSnapshotCaptureSDK != null && (boolean) responsiveSnapshotCaptureSDK) || responsiveSnapshotCaptureCLI;
     }
 
+    /**
+     * Recursively convert a parsed JSON value (from org.json) into plain Java
+     * collections so it can participate in a generic deep merge.
+     *
+     * JSONObject -> HashMap&lt;String, Object&gt; (recursively),
+     * JSONArray  -> ArrayList&lt;Object&gt; (recursively converting elements),
+     * anything else (scalars, null) is returned as-is.
+     */
+    @SuppressWarnings("unchecked")
+    private Object jsonToJava(Object value) {
+        if (value instanceof JSONObject) {
+            JSONObject obj = (JSONObject) value;
+            Map<String, Object> map = new HashMap<>();
+            for (String key : obj.keySet()) {
+                Object child = obj.get(key);
+                if (child == JSONObject.NULL) {
+                    child = null;
+                }
+                map.put(key, jsonToJava(child));
+            }
+            return map;
+        } else if (value instanceof JSONArray) {
+            JSONArray arr = (JSONArray) value;
+            List<Object> list = new ArrayList<>();
+            for (int i = 0; i < arr.length(); i++) {
+                Object element = arr.get(i);
+                if (element == JSONObject.NULL) {
+                    element = null;
+                }
+                list.add(jsonToJava(element));
+            }
+            return list;
+        }
+        return value;
+    }
+
+    /**
+     * Generic recursive deep merge of two maps. {@code override} wins over
+     * {@code base}. Nested maps are merged recursively; arrays and scalars from
+     * {@code override} replace the corresponding {@code base} value. Null values
+     * in {@code override} are skipped so they never clobber a real config value.
+     */
+    @SuppressWarnings("unchecked")
+    private Map<String, Object> deepMerge(Map<String, Object> base, Map<String, Object> override) {
+        Map<String, Object> result = new HashMap<>();
+        if (base != null) {
+            result.putAll(base);
+        }
+        if (override == null) {
+            return result;
+        }
+        for (Map.Entry<String, Object> entry : override.entrySet()) {
+            String key = entry.getKey();
+            Object overrideValue = entry.getValue();
+            // Skip null per-call values so they don't clobber config values.
+            if (overrideValue == null) {
+                continue;
+            }
+            Object baseValue = result.get(key);
+            if (baseValue instanceof Map && overrideValue instanceof Map) {
+                result.put(key, deepMerge((Map<String, Object>) baseValue, (Map<String, Object>) overrideValue));
+            } else {
+                result.put(key, overrideValue);
+            }
+        }
+        return result;
+    }
+
     public JSONObject snapshot(String name, Map<String, Object> options) {
         if (!isPercyEnabled) { return null; }
         if ("automate".equals(sessionType)) { throw new RuntimeException("Invalid function call - snapshot(). Please use screenshot() function while using Percy with Automate. For more information on usage of PercyScreenshot, refer https://www.browserstack.com/docs/percy/integrate/functional-and-visual"); }
 
         Object domSnapshot = null;
 
-        // Merge .percy.yml config options with snapshot options (snapshot options take priority)
-        Map<String, Object> mergedOptions = new HashMap<>();
+        // Deep-merge .percy.yml config options with snapshot options (snapshot
+        // options take priority). Nested objects merge recursively, per-call
+        // values win at the leaves, arrays/scalars replace wholesale, and per-call
+        // null values do NOT clobber a real value coming from .percy.yml config.
+        Map<String, Object> baseOptions = new HashMap<>();
         if (cliConfig != null && cliConfig.has("snapshot") && !cliConfig.isNull("snapshot")) {
             JSONObject snapshotConfig = cliConfig.getJSONObject("snapshot");
-            for (String key : snapshotConfig.keySet()) {
-                mergedOptions.put(key, snapshotConfig.get(key));
-            }
-        }
-        if (options != null) {
-            // Only overlay non-null per-call options so a null value (set by the
-            // positional snapshot() overloads for unset params) does not clobber a
-            // real value coming from .percy.yml config.
-            for (Map.Entry<String, Object> entry : options.entrySet()) {
-                if (entry.getValue() != null) {
-                    mergedOptions.put(entry.getKey(), entry.getValue());
-                }
+            Object converted = jsonToJava(snapshotConfig);
+            if (converted instanceof Map) {
+                @SuppressWarnings("unchecked")
+                Map<String, Object> convertedMap = (Map<String, Object>) converted;
+                baseOptions = convertedMap;
             }
         }
+        Map<String, Object> mergedOptions = deepMerge(baseOptions, options);
 
         try {
             JavascriptExecutor jse = (JavascriptExecutor) driver;

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

@@ -1247,6 +1247,67 @@ public void snapshotMergesCliConfigWithPerCallOptionsPrecedence() throws Excepti
           "per-call percyCSS should override the .percy.yml config value");
     }
 
+    @Test
+    public void snapshotDeepMergesNestedCliConfigWithPerCallOptions() throws Exception {
+      // .percy.yml config carries a nested discovery object; the per-call option
+      // overrides only one nested leaf and must NOT clobber the sibling leaves.
+      RemoteWebDriver mockedDriver = mock(RemoteWebDriver.class);
+      Percy mockedPercy = spy(new Percy(mockedDriver));
+
+      setField(mockedPercy, "isPercyEnabled", true);
+      setField(mockedPercy, "domJs",
+          "window.PercyDOM = window.PercyDOM || {}; window.PercyDOM.serialize = function(){ return {}; };");
+      setField(mockedPercy, "cliConfig", new JSONObject().put("snapshot",
+          new JSONObject().put("discovery",
+              new JSONObject()
+                  .put("networkIdleTimeout", 50)
+                  .put("disableCache", false))));
+      mockedPercy.sessionType = "web";
+
+      when(mockedDriver.getCurrentUrl()).thenReturn("https://example.com");
+      WebDriver.Options mockedOptions = mock(WebDriver.Options.class);
+      when(mockedDriver.manage()).thenReturn(mockedOptions);
+      when(mockedOptions.getCookies()).thenReturn(Collections.emptySet());
+      when(mockedDriver.findElements(By.tagName("iframe"))).thenReturn(Collections.emptyList());
+
+      ArgumentCaptor<String> scriptCaptor = ArgumentCaptor.forClass(String.class);
+      when(((JavascriptExecutor) mockedDriver).executeScript(any(String.class)))
+          .thenReturn(new HashMap<String, Object>());
+
+      doReturn(new JSONObject()).when(mockedPercy)
+          .request(eq("/percy/snapshot"), any(JSONObject.class), eq("deep merge"));
+
+      Map<String, Object> discoveryOption = new HashMap<String, Object>();
+      discoveryOption.put("disableCache", true);
+      Map<String, Object> options = new HashMap<String, Object>();
+      options.put("discovery", discoveryOption);
+
+      mockedPercy.snapshot("deep merge", options);
+
+      verify((JavascriptExecutor) mockedDriver, atLeastOnce()).executeScript(scriptCaptor.capture());
+
+      String serializeScript = null;
+      for (String script : scriptCaptor.getAllValues()) {
+        if (script != null && script.startsWith("return PercyDOM.serialize(")) {
+          serializeScript = script;
+        }
+      }
+      assertNotNull(serializeScript, "PercyDOM.serialize script should have been executed");
+
+      String jsonArg = serializeScript
+          .substring(serializeScript.indexOf('(') + 1, serializeScript.lastIndexOf(')'))
+          .trim();
+      JSONObject serialized = new JSONObject(jsonArg);
+
+      JSONObject discovery = serialized.getJSONObject("discovery");
+      // Sibling config leaf is preserved (deep merge, not shallow replace).
+      assertEquals(50, discovery.getInt("networkIdleTimeout"),
+          "networkIdleTimeout from .percy.yml config should survive the deep merge");
+      // Per-call leaf wins over the config value.
+      assertTrue(discovery.getBoolean("disableCache"),
+          "per-call discovery.disableCache should override the .percy.yml config value");
+    }
+
     private static Object invokePrivate(Object target, String methodName, Class<?>[] paramTypes, Object... args)
         throws Exception {
       Method method = Percy.class.getDeclaredMethod(methodName, paramTypes);