testivai 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65bd512ddfb0a96d7d0be93240ed9b5f62ffe6a22069062ec140e3a8270bfd14
-  data.tar.gz: 9dbc5d2cfc6104649f47147e60d1dc7669e7a12fbf8ca53a8978f2c044e3f38c
+  metadata.gz: 31e449c5ec19cb4652d9552a3f56c816e31b99646cde457488f2f009c5355092
+  data.tar.gz: bde5b4afcbe120a2a19e3d93f6816eef02ae71c77541724b33c980de017371c5
 SHA512:
-  metadata.gz: d58f7f2eac3856e27e0f446503cf2c43adeb68c623fe421277a7df87df12896216518a4892c9c07f6c3a1f3b075081ec0d49b4e097ace983785f7c5cce23e428
-  data.tar.gz: 3101cc06177e403c240f47380f3e0785e941dc7acabf9a0170bf656435a4a4b361a3236e5c41dc50c2c250d47a5b68ebee99b02ed237ed3500fe377412653b8d
+  metadata.gz: b192e945ee1181628229feab6bf3d27218b08b9d76489047e4793f0dfda96106985bd35585fc98d775df9d3109f5ec8f981a06b08d3a9195ead6869ff93afb58
+  data.tar.gz: 25c9bbe89b6e7886e73870f68dbf030525dd0d0399de79e680197e095288bfe2fc2937935d1777e05794122771d0929be2f2081e2149e70ed4ac5217356e2750

data/lib/testivai/capture.rb

@@ -7,6 +7,8 @@ require "pathname"
 
 require_relative "config"
 require_relative "element_map"
+require_relative "shard"
+require_relative "settle"
 
 module Testivai
   # Capture half of the pipeline: writes `.testivai/temp/<name>/` with the
@@ -95,13 +97,19 @@ module Testivai
       injected = false
       unless css.empty?
         injected = inject_css(browser, css)
-        wait_for_fonts(browser) if stabilize
+        if stabilize
+          wait_for_fonts(browser)
+          # Then wait for the page itself to stop changing — images finished,
+          # DOM quiet. The load question the DOM/style layer cannot answer.
+          Settle.wait_for(browser)
+        end
       end
 
       begin
         screenshot = capture_screenshot(browser)
       ensure
         remove_css(browser) if injected
+        Settle.stop(browser) if stabilize
       end
 
       File.binwrite(temp_dir.join("screenshot.png"), screenshot)
@@ -129,6 +137,12 @@ module Testivai
         end
       end
 
+      # Shard manifest — refreshed per capture because RSpec offers the gem no
+      # end-of-run hook. This is what lets a Ruby suite join the same sharded
+      # CI flow as every other adapter.
+      shard = Shard.from_env
+      Shard.write_manifest(root.join(".testivai", "temp"), shard) if shard
+
       temp_dir
     end
 

data/lib/testivai/settle.js

@@ -0,0 +1,70 @@
+/**
+ * AUTO-GENERATED — DO NOT EDIT.
+ *
+ * Page-settled probe, emitted from
+ *   packages/witness/src/capture/settle.ts
+ * by
+ *   scripts/generate-element-map-asset.js
+ *
+ * Polled by each adapter from its host language until `settled` is true or a
+ * timeout elapses. Deliberately not network idle — Playwright's own docs mark
+ * that DISCOURAGED for testing, and it is the wrong signal for a visual
+ * snapshot anyway.
+ *
+ * Default DOM-quiet threshold: 150ms
+ *
+ * Call form:
+ *   return (<this function>)(document, window, <quietMs>);
+ */
+function settleProbe(doc, win, quietMs) {
+    var KEY = '__testivaiSettleState';
+    var state = win[KEY];
+    if (!state) {
+        state = { last: Date.now() };
+        try {
+            if (typeof win.MutationObserver === 'function') {
+                var observer = new win.MutationObserver(function () {
+                    win[KEY].last = Date.now();
+                });
+                observer.observe(doc.documentElement, {
+                    subtree: true,
+                    childList: true,
+                    attributes: true,
+                    characterData: true,
+                });
+                state.observer = observer;
+            }
+        }
+        catch (e) {
+            // No MutationObserver (or a hostile document): quietness degrades to
+            // "always quiet" rather than blocking the capture.
+        }
+        win[KEY] = state;
+    }
+    var imagesPending = 0;
+    try {
+        for (var i = 0; i < doc.images.length; i++) {
+            if (!doc.images[i].complete)
+                imagesPending++;
+        }
+    }
+    catch (e) {
+        imagesPending = 0;
+    }
+    var fontsPending = false;
+    try {
+        fontsPending = !!(doc.fonts && doc.fonts.status && doc.fonts.status !== 'loaded');
+    }
+    catch (e) {
+        fontsPending = false;
+    }
+    var ready = doc.readyState === 'complete';
+    var quietFor = Date.now() - state.last;
+    return {
+        ready: ready,
+        imagesPending: imagesPending,
+        fontsPending: fontsPending,
+        quietFor: quietFor,
+        settled: ready && imagesPending === 0 && !fontsPending && quietFor >= quietMs,
+    };
+}

data/lib/testivai/settle.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Testivai
+  # Page-settled probe: "has this page stopped changing?"
+  #
+  # `settle.js` is GENERATED from packages/witness/src/capture/settle.ts, so
+  # every language polls the identical predicate.
+  #
+  # Deliberately NOT network idle. Playwright's own docs mark that DISCOURAGED
+  # for testing, and it is the wrong signal for a visual snapshot anyway — a
+  # page with analytics beacons never goes quiet, while a network-idle page can
+  # still be animating. What matters is whether the rendered page settled.
+  module Settle
+    DEFAULT_QUIET_MS = 150
+    DEFAULT_TIMEOUT = 5.0
+    ASSET = Pathname.new(__dir__).join("settle.js")
+
+    STOP_JS = <<~JS
+      try { var s = window.__testivaiSettleState;
+        if (s && s.observer && s.observer.disconnect) s.observer.disconnect(); } catch (e) {}
+      try { delete window.__testivaiSettleState; } catch (e) {}
+    JS
+
+    class << self
+      def source
+        @source ||= begin
+          # Explicit UTF-8: the generated asset is non-ASCII and Pathname#read
+          # would otherwise use the default external encoding.
+          raw = ASSET.read(encoding: "UTF-8")
+          start = raw.index("function settleProbe")
+          raise "settle.js is malformed: settleProbe not found" if start.nil?
+
+          raw[start..].strip
+        end
+      end
+
+      def expression(quiet_ms = DEFAULT_QUIET_MS)
+        "return (#{source})(document, window, #{quiet_ms.to_i});"
+      end
+
+      # Poll until settled or the deadline passes. Always bounded: a page that
+      # never settles yields a capture, not a hang. A browser that cannot
+      # evaluate the probe returns something unusable, so we proceed at once
+      # rather than paying the whole timeout on every capture.
+      def wait_for(browser, quiet_ms: DEFAULT_QUIET_MS, timeout: DEFAULT_TIMEOUT)
+        expr = expression(quiet_ms)
+        deadline = Time.now + timeout
+        loop do
+          state = begin
+            browser.execute_script(expr)
+          rescue StandardError
+            return
+          end
+          return unless state.is_a?(Hash)
+
+          settled = state["settled"]
+          return unless [true, false].include?(settled)
+          return if settled || Time.now >= deadline
+
+          sleep 0.05
+        end
+      end
+
+      # Detach the observer so it does not linger on the page under test.
+      def stop(browser)
+        browser.execute_script(STOP_JS)
+      rescue StandardError # rubocop:disable Lint/SuppressedException
+      end
+    end
+  end
+end

data/lib/testivai/shard.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "pathname"
+
+module Testivai
+  # Shard participation for parallel and sharded runs.
+  #
+  # Playwright can tell its reporter `--shard=i/N`; RSpec cannot. So the
+  # mechanism is the environment, not a framework API, and every TestivAI
+  # adapter honours the same two variables:
+  #
+  #   TESTIVAI_CAPTURE_ONLY=1   capture, do not compare
+  #   TESTIVAI_SHARD=3/8        this process is shard 3 of 8
+  #
+  # That is what keeps a Ruby suite a first-class citizen of the same sharded
+  # CI flow as Playwright rather than a second-class one.
+  module Shard
+    PATTERN = %r{\A\s*(\d+)\s*(?:/|of)\s*(\d+)\s*\z}i
+    MANIFEST = "testivai-shard.json"
+
+    module_function
+
+    # Parse TESTIVAI_SHARD; nil when unset or malformed.
+    def from_env(env = ENV)
+      parse(env["TESTIVAI_SHARD"])
+    end
+
+    def parse(raw)
+      m = PATTERN.match(raw.to_s)
+      return nil unless m
+
+      current = m[1].to_i
+      total = m[2].to_i
+      return nil if total < 1 || current < 1 || current > total
+
+      { current: current, total: total }
+    end
+
+    def capture_only?(env = ENV)
+      raw = env["TESTIVAI_CAPTURE_ONLY"].to_s
+      return !%w[0 false].include?(raw.downcase) unless raw.empty?
+
+      s = from_env(env)
+      !s.nil? && s[:total] > 1
+    end
+
+    # Write (or refresh) the manifest merge-captures reads.
+    #
+    # RSpec gives the gem no end-of-run hook, so this is refreshed on every
+    # capture and `complete` stays false — it records that the shard
+    # participated, not that it finished.
+    def write_manifest(temp_dir, shard, complete: false)
+      dir = Pathname.new(temp_dir)
+      dir.mkpath
+      captures = dir.children.select(&:directory?).map { |p| p.basename.to_s }.sort
+      dir.join(MANIFEST).write(
+        JSON.pretty_generate(
+          "shard" => { "current" => shard[:current], "total" => shard[:total] },
+          "captures" => captures,
+          "complete" => complete,
+          "timestamp" => Time.now.utc.iso8601
+        )
+      )
+    rescue StandardError # rubocop:disable Lint/SuppressedException
+      # Never fail a capture over a manifest.
+    end
+  end
+end

data/lib/testivai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Testivai
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/testivai.rb

@@ -3,6 +3,8 @@
 require_relative "testivai/version"
 require_relative "testivai/config"
 require_relative "testivai/element_map"
+require_relative "testivai/shard"
+require_relative "testivai/settle"
 require_relative "testivai/capture"
 
 # TestivAI — local-first visual regression testing for Ruby test suites.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: testivai
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Budi Sugianto
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 2026-07-31 00:00:00.000000000 Z
 dependencies: []
 description: |
   Capture screenshots, DOM snapshots, and element maps from Capybara or
@@ -28,6 +28,9 @@ files:
 - lib/testivai/config.rb
 - lib/testivai/element_map.js
 - lib/testivai/element_map.rb
+- lib/testivai/settle.js
+- lib/testivai/settle.rb
+- lib/testivai/shard.rb
 - lib/testivai/version.rb
 homepage: https://testiv.ai
 licenses: