fix: merge .percy.yml config options with snapshot options for serializeDOM

Percy.Test/Percy.Test.cs

@@ -3,6 +3,7 @@
 using System.IO;
 using System.Linq;
 using System.Net.Http;
+using System.Reflection;
 using System.Threading.Tasks;
 using System.Collections.Generic;
 using System.Text;
@@ -384,6 +385,106 @@ public void PostsSnapshotWithReadinessDisabled()
             Assert.Contains("Received snapshot: readiness-disabled", logs);
         }
     }
+
+    // Verifies the .percy.yml config (cliConfig.snapshot) <-> per-snapshot
+    // option merge that Percy.Snapshot performs (MergeSnapshotOptions) before
+    // handing the result to PercyDOM.serialize. Two precedence rules:
+    //
+    //   - config seeds the merge: a config-only key (enableJavaScript) is
+    //     inherited into the merged options, AND
+    //   - per-call overlays config: a key present in BOTH config and the
+    //     per-snapshot call (percyCSS) is won by the per-snapshot value.
+    //
+    // MergeSnapshotOptions is the single source of truth for what reaches
+    // PercyDOM.serialize, and Selenium 4's WebDriver is not mockable (no public
+    // parameterless ctor, the ctor starts a real session, and ExecuteScript /
+    // Manage / Url are non-virtual). So we exercise the merge directly through
+    // its private static surface via reflection — fully deterministic, no
+    // browser and no CLI server required.
+    public class MergePrecedenceTests
+    {
+        private static Dictionary<string, object> InvokeMerge(
+            JsonElement cliConfig, Dictionary<string, object>? perSnapshotOptions)
+        {
+            // Seed the SDK's cliConfig (internal setter, visible to Percy.Test).
+            Percy.ResetInternalCaches();
+            Percy.setCliConfig(cliConfig);
+
+            MethodInfo merge = typeof(Percy).GetMethod(
+                "MergeSnapshotOptions", BindingFlags.NonPublic | BindingFlags.Static)!;
+            object? result = merge.Invoke(null, new object?[] { perSnapshotOptions });
+            return (Dictionary<string, object>)result!;
+        }
+
+        [Fact]
+        public void PerSnapshotOptionWinsOverConfigDuringMerge()
+        {
+            try
+            {
+                // .percy.yml config: enableJavaScript is config-only; percyCSS is
+                // set here AND overridden per-snapshot to exercise the conflict.
+                JsonElement cliConfig = JsonSerializer.Deserialize<JsonElement>(
+                    "{\"snapshot\":{\"enableJavaScript\":true,\"percyCSS\":\"FROM_CONFIG\"}}");
+
+                var perSnapshotOptions = new Dictionary<string, object>
+                {
+                    { "percyCSS", "FROM_CALL" }
+                };
+
+                Dictionary<string, object> merged = InvokeMerge(cliConfig, perSnapshotOptions);
+
+                // Config seeds the merge: the config-only key is inherited.
+                Assert.True(merged.ContainsKey("enableJavaScript"));
+                Assert.Equal(true, merged["enableJavaScript"]);
+
+                // Per-call overlays config: the per-snapshot value wins on conflict.
+                Assert.Equal("FROM_CALL", merged["percyCSS"]);
+            }
+            finally
+            {
+                Percy.ResetInternalCaches();
+            }
+        }
+
+        [Fact]
+        public void NestedConfigObjectIsDeepMergedWithPerSnapshotOptions()
+        {
+            try
+            {
+                // .percy.yml config: nested discovery object with two leaves.
+                JsonElement cliConfig = JsonSerializer.Deserialize<JsonElement>(
+                    "{\"snapshot\":{\"discovery\":{\"networkIdleTimeout\":50,\"disableCache\":false}}}");
+
+                // Per-snapshot call overrides only one leaf of the nested object.
+                var perSnapshotOptions = new Dictionary<string, object>
+                {
+                    {
+                        "discovery", new Dictionary<string, object>
+                        {
+                            { "disableCache", true }
+                        }
+                    }
+                };
+
+                Dictionary<string, object> merged = InvokeMerge(cliConfig, perSnapshotOptions);
+
+                // Nested object is deep-merged, not replaced wholesale.
+                Assert.True(merged.ContainsKey("discovery"));
+                var discovery = Assert.IsType<Dictionary<string, object>>(merged["discovery"]);
+
+                // Config-only leaf is preserved.
+                Assert.Equal(50, discovery["networkIdleTimeout"]);
+
+                // Per-call leaf wins at the leaf level.
+                Assert.Equal(true, discovery["disableCache"]);
+            }
+            finally
+            {
+                Percy.ResetInternalCaches();
+            }
+        }
+    }
+
     public class RegionTests
     {
         [Fact]

Percy/Percy.cs

@@ -832,6 +832,124 @@ public static List<Dictionary<string, object>> CaptureResponsiveDom(WebDriver dr
             return domSnapshots;
         }
 
+        private static Dictionary<string, object> MergeSnapshotOptions(Dictionary<string, object>? options)
+        {
+            var merged = new Dictionary<string, object>();
+            if (cliConfig != null)
+            {
+                try
+                {
+                    JsonElement config = (JsonElement)cliConfig;
+                    if (config.TryGetProperty("snapshot", out JsonElement snapshotElement) &&
+                        snapshotElement.ValueKind == JsonValueKind.Object)
+                    {
+                        foreach (JsonProperty prop in snapshotElement.EnumerateObject())
+                        {
+                            // Recursively convert config values so nested JSON
+                            // objects become Dictionary<string, object> and can be
+                            // deep-merged with per-call options below.
+                            var converted = JsonElementToObjectDeep(prop.Value);
+                            if (converted != null)
+                                merged[prop.Name] = converted;
+                        }
+                    }
+                }
+                catch (Exception) { }
+            }
+            if (options != null)
+            {
+                // Deep-merge: nested objects merge recursively (per-call wins at
+                // leaves), arrays/scalars replace. Matches the JS sdk-utils fix.
+                merged = DeepMerge(merged, options);
+            }
+            return merged;
+        }
+
+        // Recursively converts a JSON element into plain CLR objects:
+        // Object -> Dictionary<string, object> (recursive),
+        // Array  -> List<object> (recursive),
+        // primitives -> bool / int / double / string.
+        private static object? JsonElementToObjectDeep(JsonElement el)
+        {
+            switch (el.ValueKind)
+            {
+                case JsonValueKind.Object:
+                    var dict = new Dictionary<string, object>();
+                    foreach (JsonProperty prop in el.EnumerateObject())
+                    {
+                        var converted = JsonElementToObjectDeep(prop.Value);
+                        if (converted != null)
+                            dict[prop.Name] = converted;
+                    }
+                    return dict;
+                case JsonValueKind.Array:
+                    var items = el.EnumerateArray().ToList();
+                    // All-integer arrays (e.g. config `widths`) must stay List<int> so
+                    // downstream consumers like CaptureResponsiveDom can use them directly.
+                    if (items.Count > 0 && items.All(i => i.ValueKind == JsonValueKind.Number && i.TryGetInt32(out _)))
+                        return items.Select(i => i.GetInt32()).ToList();
+                    var list = new List<object>();
+                    foreach (JsonElement item in items)
+                    {
+                        var converted = JsonElementToObjectDeep(item);
+                        if (converted != null)
+                            list.Add(converted);
+                    }
+                    return list;
+                case JsonValueKind.True:
+                    return true;
+                case JsonValueKind.False:
+                    return false;
+                case JsonValueKind.Number:
+                    return el.TryGetInt32(out int intVal) ? (object)intVal : el.GetDouble();
+                case JsonValueKind.String:
+                    return el.GetString();
+                default:
+                    return null;
+            }
+        }
+
+        // Deep-merges override into a copy of baseDict: when a key exists in both
+        // and both values are Dictionary<string, object>, recurse; otherwise the
+        // override value wins (arrays and scalars replace).
+        private static Dictionary<string, object> DeepMerge(
+            Dictionary<string, object> baseDict, Dictionary<string, object> overrideDict)
+        {
+            var result = new Dictionary<string, object>(baseDict);
+            foreach (var kvp in overrideDict)
+            {
+                if (result.TryGetValue(kvp.Key, out var existing) &&
+                    existing is Dictionary<string, object> existingDict &&
+                    kvp.Value is Dictionary<string, object> overrideNested)
+                {
+                    result[kvp.Key] = DeepMerge(existingDict, overrideNested);
+                }
+                else
+                {
+                    result[kvp.Key] = kvp.Value;
+                }
+            }
+            return result;
+        }
+
+        private static object ConvertJsonArray(JsonElement array)
+        {
+            var items = array.EnumerateArray().ToList();
+            if (items.Count > 0 && items.All(item => item.ValueKind == JsonValueKind.Number && item.TryGetInt32(out _)))
+            {
+                return items.Select(item => item.GetInt32()).ToList();
+            }
+
+            return items.Select(item => item.ValueKind switch
+            {
+                JsonValueKind.True => true,
+                JsonValueKind.False => false,
+                JsonValueKind.Number => item.TryGetInt32(out int intVal) ? intVal : (object)item.GetDouble(),
+                JsonValueKind.String => item.GetString(),
+                _ => (object)item
+            }).ToList();
+        }
+
         private static bool isResponsiveSnapshotCapture(Dictionary<string, object>? options)
         {
             if (cliConfig == null) return false;
@@ -882,14 +1000,16 @@ public class Options : Dictionary<string, object> {}
                 if (_dom == null)
                     _dom = GetPercyDOM();
 
+                // Merge .percy.yml config options with snapshot options (snapshot options take priority)
+                var mergedOptions = MergeSnapshotOptions(options);
+
                 var cookies = driver.Manage().Cookies.AllCookies;
-                string opts = JsonSerializer.Serialize(options);
                 dynamic domSnapshot = null;
 
-                if (isResponsiveSnapshotCapture(options)) {
-                    domSnapshot = CaptureResponsiveDom(driver, cookies, options);
+                if (isResponsiveSnapshotCapture(mergedOptions)) {
+                    domSnapshot = CaptureResponsiveDom(driver, cookies, mergedOptions);
                 } else {
-                    domSnapshot = getSerializedDom(driver, cookies, options, _dom);
+                    domSnapshot = getSerializedDom(driver, cookies, mergedOptions, _dom);
                 }
 
                 Options snapshotOptions = new Options {