percy-capybara 5.0.0 → 5.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45a545941cfa1347d8912e8d94218005a87662f1c07d7633696ed56ba130a319
-  data.tar.gz: e0796a2c700b35b7710c79979ea1d12c136335fce31b3d12c1e68630bd56ba88
+  metadata.gz: 7db2c14fc57a6c57c3b6622525553787384946fb9391a2f725cb2200798973a7
+  data.tar.gz: ac4086661c230766111c2a15ffebf403941f4e42349a2a550b90c2becfd7ecc9
 SHA512:
-  metadata.gz: 6cb49cda9b878968ffb3225c032c5a49e8c8fc712c9598c0c654362dad01a46d8d1f1808a4bef1cc3c2a6593b5da28f0deb7e1484a00416f2aa2ba9d7eaaf0f2
-  data.tar.gz: 45bd57d38c20a550fe956c4b99b13b4d271113b5a8e14ef5b9e832facf36fe2be09b60e8a6ca5539ee54bde4b5885e67fdc6315d33cb75e46abf2e19e92b5757
+  metadata.gz: 6233ec353b93414b17a01300f2c3fdcbe5350a4e9a847c52e1a115da333cf9dbf96c8647540c64ddaeb7cb7cb9913594f16682c77e46e59f76f606b103200ff8
+  data.tar.gz: 44951b8de50525cd017ecc705a02ee57d6faf93f2fa36c174bdadb126ab66f1260191ca53abf046e7dda2ed8aa61961c202441f2aec9c4f3901b63fe70823a0e

data/README.md

@@ -66,7 +66,7 @@ $ percy exec -- [test command]
 `page.snapshot(name[, options])`
 
 - `name` (**required**) - The snapshot name; must be unique to each snapshot
-- `options` - [See per-snapshot configuration options](https://docs.percy.io/docs/cli-configuration#per-snapshot-configuration)
+- `options` - [See per-snapshot configuration options](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview#per-snapshot-configuration)
 
 ## Upgrading
 

data/lib/percy/capybara.rb

@@ -1,3 +1,4 @@
+require 'json'
 require 'net/http'
 require 'uri'
 require 'capybara/dsl'
@@ -14,6 +15,12 @@ module PercyCapybara
   private_constant :CLIENT_INFO
   private_constant :ENV_INFO
 
+  UNSUPPORTED_IFRAME_SRCS = %w[
+    about:blank about:srcdoc javascript: data: blob: vbscript: chrome: chrome-extension:
+  ].freeze
+
+  private_constant :UNSUPPORTED_IFRAME_SRCS
+
   # Take a DOM snapshot and post it to the snapshot endpoint
   def percy_snapshot(name, options = {})
     return unless percy_enabled?
@@ -21,9 +28,29 @@ module PercyCapybara
     page = Capybara.current_session
 
     begin
+      percy_dom_script = fetch_percy_dom
+      page.evaluate_script(percy_dom_script)
+      dom_snapshot = get_serialized_dom(page, options, percy_dom_script)
       page.evaluate_script(fetch_percy_dom)
+
+      # Readiness gate -- runs before serialize when CLI supports it.
+      # Uses evaluate_async_script with a callback signal so the SDK can block
+      # on PercyDOM.waitForReady. In-browser typeof guard makes this a no-op on
+      # older CLIs that lack waitForReady.
+      readiness_diagnostics = wait_for_ready(page, options)
+
+      # Merge .percy.yml config options with snapshot options (snapshot options take priority).
+      # Deep merge with consistent string keys at all levels: nested Hashes merge
+      # recursively, per-call wins at leaves, arrays/scalars replace.
+      config_options = @cli_config&.dig('snapshot') || {}
+      merged_options = deep_merge_options(config_options, deep_stringify(options))
+
       dom_snapshot = page
-        .evaluate_script("(function() { return PercyDOM.serialize(#{options.to_json}) })()")
+        .evaluate_script("(function() { return PercyDOM.serialize(#{merged_options.to_json}) })()")
+
+      if readiness_diagnostics && dom_snapshot.is_a?(Hash)
+        dom_snapshot['readiness_diagnostics'] = readiness_diagnostics
+      end
 
       response = fetch('percy/snapshot',
         name: name,
@@ -33,7 +60,16 @@ module PercyCapybara
         environment_info: ENV_INFO,
         **options,)
 
-      unless response.body.to_json['success']
+      data =
+        begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          log("Could not parse snapshot response for '#{name}': invalid JSON")
+          if PERCY_DEBUG then log(e) end
+          return
+        end
+
+      unless data['success']
         raise StandardError, data['error']
       end
     rescue StandardError => e
@@ -43,6 +79,135 @@ module PercyCapybara
     end
   end
 
+  private def get_serialized_dom(page, options, percy_dom_script)
+    dom_snapshot = page
+      .evaluate_script("(function() { return PercyDOM.serialize(#{options.to_json}) })()")
+
+    driver = page.driver.browser
+    begin
+      page_origin = get_origin(page.current_url)
+      iframes = driver.find_elements(:tag_name, 'iframe')
+      log("Found #{iframes.length} total iframe(s) on page") if PERCY_DEBUG
+
+      processed_frames = []
+      iframes.each do |frame|
+        frame_src = frame.attribute('src')
+
+        if unsupported_iframe_src?(frame_src)
+          log("Skipping unsupported iframe src: #{frame_src}") if PERCY_DEBUG && frame_src
+          next
+        end
+
+        begin
+          frame_origin = get_origin(URI.join(page.current_url, frame_src).to_s)
+        rescue StandardError => e
+          log("Skipping iframe with invalid URL \"#{frame_src}\": #{e}") if PERCY_DEBUG
+          next
+        end
+
+        if frame_origin == page_origin
+          log("Skipping same-origin iframe: #{frame_src}") if PERCY_DEBUG
+          next
+        end
+
+        # Pre-flight check: avoid the switch/serialize round-trip if there's no
+        # data-percy-element-id, since process_frame would discard the snapshot
+        # anyway and we'd silently waste a frame switch.
+        unless frame.attribute('data-percy-element-id')
+          log("Skipping iframe #{frame_src}: no data-percy-element-id found") if PERCY_DEBUG
+          next
+        end
+
+        result = process_frame(driver, frame, options, percy_dom_script)
+        processed_frames << result if result
+      end
+
+      if processed_frames.any?
+        dom_snapshot['corsIframes'] = processed_frames
+        log("Captured #{processed_frames.length} cross-origin iframe(s)")
+      end
+    rescue StandardError => e
+      log("Failed to process cross-origin iframes: #{e}") if PERCY_DEBUG
+      begin
+        driver.switch_to.default_content
+      rescue StandardError
+        nil
+      end
+    end
+
+    dom_snapshot
+  end
+
+  private def unsupported_iframe_src?(src)
+    return true if src.nil? || src.empty?
+
+    UNSUPPORTED_IFRAME_SRCS.any? { |prefix| src == prefix || src.start_with?(prefix) }
+  end
+
+  private def get_origin(url)
+    uri = URI.parse(url)
+    raise URI::InvalidURIError, "no host in #{url}" if uri.host.nil?
+
+    default_ports = {'http' => 80, 'https' => 443}
+    netloc = uri.host.to_s
+    netloc += ":#{uri.port}" if uri.port && uri.port != default_ports[uri.scheme]
+    "#{uri.scheme}://#{netloc}"
+  end
+
+  private def process_frame(driver, frame_element, options, percy_dom_script)
+    frame_url = frame_element.attribute('src') || 'unknown-src'
+    log("Processing cross-origin iframe: #{frame_url}") if PERCY_DEBUG
+
+    begin
+      driver.switch_to.frame(frame_element)
+      begin
+        driver.execute_script(percy_dom_script)
+        iframe_options = options.merge('enableJavaScript' => true)
+        iframe_snapshot =
+          driver.execute_script("return PercyDOM.serialize(#{iframe_options.to_json})")
+        log("Serialized cross-origin iframe: #{frame_url}") if PERCY_DEBUG
+      rescue StandardError => e
+        log("Failed to serialize cross-origin iframe #{frame_url}: #{e}") if PERCY_DEBUG
+        return nil
+      ensure
+        begin
+          driver.switch_to.default_content
+        rescue StandardError
+          begin
+            driver.switch_to.parent_frame
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    rescue StandardError => e
+      log("Failed to switch to frame #{frame_url}: #{e}") if PERCY_DEBUG
+      begin
+        driver.switch_to.default_content
+      rescue StandardError
+        nil
+      end
+      return nil
+    end
+
+    percy_element_id = frame_element.attribute('data-percy-element-id')
+    unless percy_element_id
+      log("Skipping frame #{frame_url}: no data-percy-element-id found") if PERCY_DEBUG
+      return nil
+    end
+
+    if PERCY_DEBUG
+      log("Successfully captured cross-origin iframe: #{frame_url} " \
+          "(percyElementId: #{percy_element_id})")
+    end
+
+    {
+      'iframeData' => {'percyElementId' => percy_element_id},
+      'iframeSnapshot' => iframe_snapshot,
+      'frameUrl' => frame_url,
+    }
+  end
+
   # Determine if the Percy server is running, caching the result so it is only checked once
   private def percy_enabled?
     return @percy_enabled unless @percy_enabled.nil?
@@ -55,7 +220,7 @@ module PercyCapybara
         log('You may be using @percy/agent ' \
             'which is no longer supported by this SDK. ' \
             'Please uninstall @percy/agent and install @percy/cli instead. ' \
-            'https://docs.percy.io/docs/migrating-to-percy-cli')
+            'https://www.browserstack.com/docs/percy/migration/migrate-to-cli')
         @percy_enabled = false
         return false
       end
@@ -66,6 +231,8 @@ module PercyCapybara
         return false
       end
 
+      body = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+      @cli_config = body['config'] || {}
       @percy_enabled = true
       true
     rescue StandardError => e
@@ -85,6 +252,57 @@ module PercyCapybara
     @percy_dom = response.body
   end
 
+  # Readiness gate: runs PercyDOM.waitForReady before serialize.
+  #
+  # Returns diagnostics to attach to the domSnapshot, or nil.
+  # Config precedence: options[:readiness] / options['readiness'] > {} (the
+  # CLI applies its balanced preset default when passed {}). preset='disabled'
+  # skips the script entirely. Opt-in: only runs when the caller explicitly
+  # passes a `readiness` option -- keeps non-opting tests insulated from
+  # Capybara drivers that don't implement evaluate_async_script.
+  # Any StandardError is caught at debug level.
+  private def wait_for_ready(page, options)
+    return nil unless options.key?(:readiness) || options.key?('readiness')
+
+    readiness_config = options[:readiness] || options['readiness'] || {}
+    return nil if readiness_config.is_a?(Hash) && (
+      readiness_config[:preset] == 'disabled' || readiness_config['preset'] == 'disabled'
+    )
+
+    begin
+      page.evaluate_async_script(<<~JS)
+        var cfg = #{readiness_config.to_json};
+        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(); }
+      JS
+    rescue StandardError => e
+      if PERCY_DEBUG then log("waitForReady failed, proceeding to serialize: #{e}") end
+      nil
+    end
+  end
+
+  # Recursively stringify all Hash keys so per-call options match the
+  # string-keyed config parsed from .percy.yml JSON at every nesting level.
+  private def deep_stringify(obj)
+    case obj
+    when Hash then obj.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
+    when Array then obj.map { |e| deep_stringify(e) }
+    else obj
+    end
+  end
+
+  # Deep-merge two string-keyed Hashes: nested Hashes merge recursively,
+  # per-call (override) wins at the leaves, arrays/scalars replace.
+  private def deep_merge_options(base, override)
+    base.merge(override) do |_key, old_val, new_val|
+      old_val.is_a?(Hash) && new_val.is_a?(Hash) ? deep_merge_options(old_val, new_val) : new_val
+    end
+  end
+
   private def log(msg)
     puts "#{PERCY_LABEL} #{msg}"
   end

data/lib/percy/version.rb

@@ -1,3 +1,3 @@
 module PercyCapybara
-  VERSION = '5.0.0'.freeze
+  VERSION = '5.0.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: percy-capybara
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.0.1
 platform: ruby
 authors:
 - Perceptual Inc.
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-07-15 00:00:00.000000000 Z
+date: 2026-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -30,14 +30,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.0.0.beta1
+        version: 4.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.0.0.beta1
+        version: 4.0.0
+- !ruby/object:Gem::Dependency
+  name: geckodriver-bin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.28.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.28.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -84,16 +98,16 @@ dependencies:
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.31'
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.31'
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: percy-style
   requirement: !ruby/object:Gem::Requirement
@@ -125,7 +139,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/percy/percy-capybara/issues
   source_code_uri: https://github.com/percy/percy-capybara
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -140,8 +154,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.0.3.1
+signing_key:
 specification_version: 4
 summary: Percy visual testing for Capybara
 test_files: []