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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa2f41ca77fb6671ac305eb3ff0a99f61cef87b290b885ed8c16a462a865bbb9
-  data.tar.gz: f45b3651099a2f84d098d4eb48db83b3685646ad3902b85a10b5f865a3b9fd48
+  metadata.gz: 685b6a737cf5d8ebe9ce59dc70736248b7d5f30a6131bcc34d98ccdb7d1b6a03
+  data.tar.gz: b25796e9354d99d64ce0022263e4987cae49a57bb5e0e31443afc490240d7ec2
 SHA512:
-  metadata.gz: 821f02d3e049227bb1e294402cfb37ce097c21c775d3c8870871cc650db787784696ef55e0df593d817123a86664e8e868a9171526168a9d3d72835208d08c56
-  data.tar.gz: 7e54763dd644d9a65489d2d9c043d0e82bee79637467b812e2ff9f80267d943c0fcf722095ca4c94b35a24258158e8af96c713edb6c27bf14aaee64dd3a86fc0
+  metadata.gz: 5e410bb024a3e3bac312041bd907e3a39a5f9f61f14450c0962dbb82af505ebec08319672e63d6e525da1679f14052c0c243bcfd818c65295bfb0c60baf53f4f
+  data.tar.gz: 46991f060f602406612f78986767bd5c5f64cfc0e21e4ef6834ee0609f113725dafd455d16d5ef3c0b3eb4b430475e0d9c4ce87a988e1328ad963914383397b5

data/.gitignore

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

data/README.md

@@ -62,3 +62,136 @@ $ percy exec -- [ruby test command]
 - `driver` (**required**) - A selenium-webdriver driver instance
 - `name` (**required**) - The snapshot name; must be unique to each snapshot
 - `options` - [See per-snapshot configuration options](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview#per-snapshot-configuration)
+
+## Running Percy on Automate
+`Percy.percy_screenshot(driver, name, options)` [ needs @percy/cli 1.27.0-beta.0+ ]
+
+This is an example test using the `percy_screenshot` method.
+
+``` ruby
+require 'percy'
+
+capabilities = {
+  'browserName' => 'chrome',
+  'bstack:options' => {
+    'userName' => '<your-username>',
+    'accessKey' => '<your-access-key>'
+  }
+}
+
+driver = Selenium::WebDriver.for(
+  :remote,
+  url: 'https://hub-cloud.browserstack.com/wd/hub',
+  capabilities: capabilities
+)
+
+driver.navigate.to "https://example.com"
+
+# Take a Percy screenshot
+Percy.percy_screenshot(driver, 'Screenshot 1')
+
+driver.navigate.to "https://google.com"
+Percy.percy_screenshot(driver, 'Screenshot 2')
+
+driver.quit
+```
+
+- `driver` (**required**) - A Selenium driver instance
+- `name` (**required**) - The screenshot name; must be unique to each screenshot
+- `options` (**optional**) - There are various options supported by `percy_screenshot` to serve further functionality.
+    - `sync` - Boolean value by default it falls back to `false`, Gives the processed result around screenshot [From CLI v1.28.0-beta.0+]
+    - `fullPage` - Boolean value by default it falls back to `false`, Takes full page screenshot [From CLI v1.27.6+]
+    - `freezeAnimatedImage` - Boolean value by default it falls back to `false`, you can pass `true` and Percy will freeze image based animations.
+    - `freezeImageBySelectors` - List of selectors. Images will be frozen which are passed using selectors. For this to work `freezeAnimatedImage` must be set to true.
+    - `freezeImageByXpaths` - List of xpaths. Images will be frozen which are passed using xpaths. For this to work `freezeAnimatedImage` must be set to true.
+    - `percyCSS` - Custom CSS to be added to DOM before the screenshot being taken. Note: This gets removed once the screenshot is taken.
+    - `ignoreRegionXpaths` - List of xpaths. Elements in the DOM can be ignored using xpath.
+    - `ignoreRegionSelectors` - List of selectors. Elements in the DOM can be ignored using selectors.
+    - `ignoreRegionSeleniumElements` - List of Selenium WebElement. Elements can be ignored using selenium elements.
+    - `customIgnoreRegions` - List of custom objects. Elements can be ignored using custom boundaries. Just passing a simple hash for it like below.
+      - example: `{top: 10, right: 10, bottom: 120, left: 10}`
+      - In the above example it will draw a rectangle of ignore region as per given coordinates.
+        - `top` (int): Top coordinate of the ignore region.
+        - `bottom` (int): Bottom coordinate of the ignore region.
+        - `left` (int): Left coordinate of the ignore region.
+        - `right` (int): Right coordinate of the ignore region.
+    - `considerRegionXpaths` - List of xpaths. Elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using xpaths.
+    - `considerRegionSelectors` - List of selectors. Elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using selectors.
+    - `considerRegionSeleniumElements` - List of Selenium WebElement. Elements can be considered for diffing and will be ignored by Intelli Ignore using selenium elements.
+    - `customConsiderRegions` - List of custom objects. Elements can be considered for diffing and will be ignored by Intelli Ignore using custom boundaries.
+      - example: `{top: 10, right: 10, bottom: 120, left: 10}`
+      - In the above example a rectangle of consider region will be drawn.
+      - Parameters:
+        - `top` (int): Top coordinate of the consider region.
+        - `bottom` (int): Bottom coordinate of the consider region.
+        - `left` (int): Left coordinate of the consider region.
+        - `right` (int): Right coordinate of the consider region.
+    - `regions` - Parameter that allows users to apply snapshot options to specific areas of the page. This parameter is an array where each object defines a custom region with configurations.
+      - Parameters:
+        - `elementSelector` (optional, only one of the following must be provided, if this is not provided then full page will be considered as region)
+            - `boundingBox` (hash): Defines the coordinates and size of the region.
+              - `x` (number): X-coordinate of the region.
+              - `y` (number): Y-coordinate of the region.
+              - `width` (number): Width of the region.
+              - `height` (number): Height of the region.
+            - `elementXpath` (string): The XPath selector for the element.
+            - `elementCSS` (string): The CSS selector for the element.
+        - `algorithm` (mandatory)
+            - Specifies the snapshot comparison algorithm.
+            - Allowed values: `standard`, `layout`, `ignore`, `intelliignore`.
+        - `configuration` (required for `standard` and `intelliignore` algorithms, ignored otherwise)
+            - `diffSensitivity` (number): Sensitivity level for detecting differences.
+            - `imageIgnoreThreshold` (number): Threshold for ignoring minor image differences.
+            - `carouselsEnabled` (boolean): Whether to enable carousel detection.
+            - `bannersEnabled` (boolean): Whether to enable banner detection.
+            - `adsEnabled` (boolean): Whether to enable ad detection.
+        - `assertion` (optional)
+            - Defines assertions to apply to the region.
+            - `diffIgnoreThreshold` (number): The threshold for ignoring minor differences.
+
+### Example Usage for regions
+
+``` ruby
+region1 = {
+  elementSelector: {
+    elementCSS: '.ad-banner'
+  },
+  algorithm: 'intelliignore',
+  configuration: {
+    diffSensitivity: 2,
+    imageIgnoreThreshold: 0.2,
+    carouselsEnabled: true,
+    bannersEnabled: true,
+    adsEnabled: true
+  },
+  assertion: {
+    diffIgnoreThreshold: 0.4
+  }
+}
+
+# Using Percy.create_region helper
+region2 = Percy.create_region(
+  algorithm: 'intelliignore',
+  diff_sensitivity: 3,
+  ads_enabled: true,
+  diff_ignore_threshold: 0.4
+)
+
+Percy.percy_screenshot(driver, 'Screenshot 1', regions: [region1, region2])
+```
+
+### Creating Percy on Automate build
+Note: Automate Percy Token starts with `auto` keyword. The command can be triggered using `exec` keyword.
+
+```sh-session
+$ export PERCY_TOKEN=[your-project-token]
+$ percy exec -- [ruby test command]
+[percy] Percy has started!
+[percy] [Ruby example] : Starting automate screenshot ...
+[percy] Screenshot taken "Ruby example"
+[percy] Stopping percy...
+[percy] Finalized build #1: https://percy.io/[your-project]
+[percy] Done!
+```
+
+Refer to docs here: [Percy on Automate](https://www.browserstack.com/docs/percy/integrate/functional-and-visual)

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-beta.0'.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.pre.beta.0
+  version: 1.1.3.pre.beta.0
 platform: ruby
 authors:
 - Perceptual Inc.