percy-selenium 1.1.2 → 1.1.3.pre.beta.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6479ecd72851c243d9e31660d690bb4f0a85447715418612c0af5b7c33e3a7e
-  data.tar.gz: 172072160f5612dbf40d82c6f1703627bbf04aa7ef245b29b9aca7668875b667
+  metadata.gz: 685b6a737cf5d8ebe9ce59dc70736248b7d5f30a6131bcc34d98ccdb7d1b6a03
+  data.tar.gz: b25796e9354d99d64ce0022263e4987cae49a57bb5e0e31443afc490240d7ec2
 SHA512:
-  metadata.gz: b5111c9ba7c89adf7e11cb58278333c3a650ffa3d3276291654d0c4fee6c6a66f9b883a84bbb9597f739bdd77155496825a0f04fd0f2bf3ff771c6bf2c200394
-  data.tar.gz: 37d6c0a4a53942f8574dd73dbb0cc5d7043819e21983306fe6800cca355e0f0db8c2976f53935cdbef019cf2fa72b7c2794837149d1c78af342d77df9327400f
+  metadata.gz: 5e410bb024a3e3bac312041bd907e3a39a5f9f61f14450c0962dbb82af505ebec08319672e63d6e525da1679f14052c0c243bcfd818c65295bfb0c60baf53f4f
+  data.tar.gz: 46991f060f602406612f78986767bd5c5f64cfc0e21e4ef6834ee0609f113725dafd455d16d5ef3c0b3eb4b430475e0d9c4ce87a988e1328ad963914383397b5

data/.gitignore

@@ -15,3 +15,4 @@ mkmf.log
 .DS_Store
 Gemfile.lock
 node_modules/
+.venv/

data/lib/percy.rb

@@ -85,13 +85,16 @@ module Percy
         get_serialized_dom(driver, options, percy_dom_script: percy_dom_script)
       end
 
+      # Strip `readiness` before POSTing -- SDK-local config that the CLI
+      # already has via healthcheck.
+      post_options = options.reject { |k, _| k.to_s == 'readiness' }
       response = fetch('percy/snapshot',
         name: name,
         url: driver.current_url,
         dom_snapshot: dom_snapshot,
         client_info: CLIENT_INFO,
         environment_info: ENV_INFO,
-        **options,)
+        **post_options,)
 
       body = JSON.parse(response.body)
       unless body['success']
@@ -113,8 +116,79 @@ module Percy
     driver.manage
   end
 
+  # Shallow-merge of global (@cli_config.snapshot.readiness) and per-snapshot
+  # (options[:readiness] / options['readiness']) readiness config. Per-snapshot
+  # keys win, unspecified global keys (notably preset: disabled) are inherited.
+  def self.resolve_readiness_config(options)
+    global = @cli_config&.dig('snapshot', 'readiness')
+    global = {} unless global.is_a?(Hash)
+    per_snapshot = options[:readiness] || options['readiness']
+    per_snapshot = {} unless per_snapshot.is_a?(Hash)
+    # Normalise symbol keys to strings so the merge collapses :preset and 'preset'.
+    [global, per_snapshot].each_with_object({}) do |hash, merged|
+      hash.each { |k, v| merged[k.to_s] = v }
+    end
+  end
+
+  # Readiness gate: runs PercyDOM.waitForReady via
+  # execute_async_script BEFORE serialize. Graceful on old CLIs that lack the
+  # method. Returns readiness diagnostics (or nil) for attachment to domSnapshot.
+  def self.wait_for_ready(driver, options)
+    readiness_config = resolve_readiness_config(options)
+    return nil if readiness_config['preset'] == 'disabled'
+
+    # Match the driver's async-script timeout to readiness.timeoutMs so a
+    # higher user-configured timeout isn't silently capped by Selenium's
+    # default (~30s) firing ScriptTimeoutException before the in-page
+    # Promise resolves.
+    timeout_ms = readiness_config['timeoutMs']
+    previous_timeout = nil
+    if timeout_ms.is_a?(Numeric) && timeout_ms > 0
+      begin
+        previous_timeout = driver.manage.timeouts.script_timeout
+        driver.manage.timeouts.script_timeout = (timeout_ms / 1000.0) + 2
+      rescue StandardError
+        previous_timeout = nil # best-effort; older Selenium / unsupported
+      end
+    end
+
+    begin
+      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
+      driver.execute_async_script(script)
+    rescue StandardError => e
+      log("waitForReady failed, proceeding to serialize: #{e}", 'debug')
+      nil
+    ensure
+      if previous_timeout
+        begin
+          driver.manage.timeouts.script_timeout = previous_timeout
+        rescue StandardError
+          # best-effort
+        end
+      end
+    end
+  end
+
   def self.get_serialized_dom(driver, options, percy_dom_script: nil)
-    dom_snapshot = driver.execute_script("return PercyDOM.serialize(#{options.to_json})")
+    # Readiness gate before serialize. Graceful on old CLI.
+    readiness_diagnostics = wait_for_ready(driver, options)
+    # Strip `readiness` from forwarded serialize args -- it's consumed by
+    # wait_for_ready upstream, not a PercyDOM.serialize argument.
+    serialize_options = options.reject { |k, _| k.to_s == 'readiness' }
+    dom_snapshot = driver.execute_script("return PercyDOM.serialize(#{serialize_options.to_json})")
+    # `!nil?` preserves legitimate falsy returns like {} ("gate ran, no
+    # notable diagnostics").
+    if !readiness_diagnostics.nil? && dom_snapshot.is_a?(Hash)
+      dom_snapshot['readiness_diagnostics'] = readiness_diagnostics
+    end
     begin
       page_origin = get_origin(driver.current_url)
       iframes = percy_dom_script ? driver.find_elements(:tag_name, 'iframe') : []

data/lib/version.rb

@@ -1,3 +1,3 @@
 module Percy
-  VERSION = '1.1.2'.freeze
+  VERSION = '1.1.3-beta.0'.freeze
 end

data/package.json

@@ -4,6 +4,6 @@
     "test": "percy exec --testing -- bundle exec rspec"
   },
   "devDependencies": {
-    "@percy/cli": "1.31.10"
+    "@percy/cli": "^1.31.15-beta.0"
   }
 }

data/spec/lib/percy/percy_spec.rb

@@ -748,6 +748,59 @@ RSpec.describe Percy do
       expect(dom['corsIframes'].length).to eq(1)
       expect(dom['corsIframes'][0]['frameUrl']).to eq('https://other.example.com/page')
     end
+
+    # --- Readiness gate --------------------------------------
+
+    it 'runs waitForReady before serialize and attaches diagnostics' do
+      allow(driver).to receive(:execute_async_script).and_return(
+        'ok' => true, 'timed_out' => false,
+      )
+      allow(driver).to receive(:execute_script).and_return({'html' => '<html/>'})
+      allow(driver).to receive(:current_url).and_return('http://main.example.com/')
+      allow(driver).to receive(:find_elements).and_return([])
+
+      dom = Percy.get_serialized_dom(driver, {})
+      expect(driver).to have_received(:execute_async_script) do |script| # rubocop:disable RSpec/MessageSpies
+        expect(script).to include('waitForReady')
+        expect(script).to include("typeof PercyDOM.waitForReady === 'function'")
+      end
+      expect(dom['readiness_diagnostics']).to eq('ok' => true, 'timed_out' => false)
+    end
+
+    it 'embeds per-snapshot readiness config in the script' do
+      allow(driver).to receive(:execute_async_script).and_return(nil)
+      allow(driver).to receive(:execute_script).and_return({'html' => '<html/>'})
+      allow(driver).to receive(:current_url).and_return('http://main.example.com/')
+      allow(driver).to receive(:find_elements).and_return([])
+
+      Percy.get_serialized_dom(driver, readiness: {preset: 'strict', stabilityWindowMs: 500})
+      expect(driver).to have_received(:execute_async_script) do |script| # rubocop:disable RSpec/MessageSpies
+        expect(script).to include('"preset":"strict"')
+        expect(script).to include('"stabilityWindowMs":500')
+      end
+    end
+
+    it 'skips execute_async_script when preset is disabled' do
+      allow(driver).to receive(:execute_script).and_return({'html' => '<html/>'})
+      allow(driver).to receive(:current_url).and_return('http://main.example.com/')
+      allow(driver).to receive(:find_elements).and_return([])
+      expect(driver).to_not receive(:execute_async_script)
+
+      dom = Percy.get_serialized_dom(driver, readiness: {preset: 'disabled'})
+      expect(dom).to_not have_key('readiness_diagnostics')
+      expect(dom['html']).to eq('<html/>')
+    end
+
+    it 'still serializes when execute_async_script raises' do
+      allow(driver).to receive(:execute_async_script).and_raise(StandardError, 'readiness boom')
+      allow(driver).to receive(:execute_script).and_return({'html' => '<html/>'})
+      allow(driver).to receive(:current_url).and_return('http://main.example.com/')
+      allow(driver).to receive(:find_elements).and_return([])
+
+      dom = Percy.get_serialized_dom(driver, {})
+      expect(dom).to_not have_key('readiness_diagnostics')
+      expect(dom['html']).to eq('<html/>')
+    end
   end
 
   describe '.change_window_dimension_and_wait' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: percy-selenium
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.3.pre.beta.0
 platform: ruby
 authors:
 - Perceptual Inc.