testivai 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65bd512ddfb0a96d7d0be93240ed9b5f62ffe6a22069062ec140e3a8270bfd14
+  data.tar.gz: 9dbc5d2cfc6104649f47147e60d1dc7669e7a12fbf8ca53a8978f2c044e3f38c
+SHA512:
+  metadata.gz: d58f7f2eac3856e27e0f446503cf2c43adeb68c623fe421277a7df87df12896216518a4892c9c07f6c3a1f3b075081ec0d49b4e097ace983785f7c5cce23e428
+  data.tar.gz: 3101cc06177e403c240f47380f3e0785e941dc7acabf9a0170bf656435a4a4b361a3236e5c41dc50c2c250d47a5b68ebee99b02ed237ed3500fe377412653b8d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TestivAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# testivai (Ruby)
+
+Local-first visual regression testing for Capybara and Selenium suites.
+Part of [testivai-oss](https://github.com/mcbuddy/testivai-oss) — MIT, no
+account, nothing uploaded.
+
+```ruby
+# Gemfile
+gem "testivai", group: :test
+```
+
+```ruby
+require "testivai"
+
+RSpec.describe "Homepage", type: :feature do
+  it "looks right" do
+    visit "/"
+    Testivai.witness(page, "homepage")
+  end
+end
+```
+
+Run your suite exactly as you already do, then compare:
+
+```bash
+bundle exec rspec
+npx testivai report
+```
+
+The first run writes baselines under `.testivai/baselines/` — commit them.
+Later runs diff against them and write `visual-report/index.html`.
+
+## Options
+
+```ruby
+Testivai.witness(page, "checkout",
+  ignore_selectors: [".live-chat"],  # hidden from pixels and the DOM signal
+  stabilize: true,                   # freeze animations, hide caret, await fonts
+  skip_dom: false,                   # DOM snapshot powers the noise hint
+  skip_element_map: false,           # element map powers selector attribution
+  max_elements: 3000)
+```
+
+## What it captures
+
+| File | Purpose |
+|---|---|
+| `screenshot.png` | Full page on Chromium (CDP) and Firefox; viewport elsewhere |
+| `dom.html` | Powers the noise hint and text-change detection |
+| `elements.json` | Powers region→selector attribution, shift detection, style checks |
+
+The element-map collector is generated from one TypeScript source shared by
+every TestivAI adapter, so Ruby, Python, Java, and JavaScript lanes produce
+identical maps against the same baselines.
+
+## Why `npx testivai report`?
+
+Capture is native Ruby; the diff engine and HTML report are shared across all
+languages and live in the `@testivai/witness` npm package. Same split as the
+Python and Java adapters — one comparison implementation, not five.
+
+Docs: <https://testiv.ai/docs/frameworks/ruby/>

data/lib/testivai/capture.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "fileutils"
+require "pathname"
+
+require_relative "config"
+require_relative "element_map"
+
+module Testivai
+  # Capture half of the pipeline: writes `.testivai/temp/<name>/` with the
+  # screenshot, the DOM snapshot, and the element map. The compare half is
+  # `npx testivai report`, shared with every other adapter.
+  #
+  # Works against any Capybara session or a bare Selenium driver — all this
+  # needs is `execute_script` plus some way to take a screenshot, which is
+  # exactly what every Capybara driver already exposes.
+  module Capture
+    STYLE_ID = "__testivai_capture_style__"
+
+    # Collapses animations and transitions to ~0s, hides the caret, and
+    # disables smooth scrolling — the top causes of flaky visual diffs.
+    # Near-zero rather than `none` so animations land on their final frame
+    # instead of never rendering.
+    STABILIZE_CSS = <<~CSS
+      *, *::before, *::after {
+        animation-duration: 0.001s !important;
+        animation-delay: 0s !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.001s !important;
+        transition-delay: 0s !important;
+        caret-color: transparent !important;
+        scroll-behavior: auto !important;
+      }
+    CSS
+
+    INJECT_STYLE_JS = <<~JS
+      var s = document.createElement('style');
+      s.id = arguments[0];
+      s.textContent = arguments[1];
+      document.head.appendChild(s);
+    JS
+
+    REMOVE_STYLE_JS = <<~JS
+      var s = document.getElementById(arguments[0]);
+      if (s && s.parentNode) { s.parentNode.removeChild(s); }
+    JS
+
+    FONTS_READY_JS = <<~JS
+      return !document.fonts || document.fonts.status === 'loaded';
+    JS
+
+    DOM_SNAPSHOT_JS = <<~JS
+      var clone = document.documentElement.cloneNode(true);
+      var sels = arguments[0] || [];
+      for (var i = 0; i < sels.length; i++) {
+        try {
+          var found = clone.querySelectorAll(sels[i]);
+          for (var j = 0; j < found.length; j++) { found[j].remove(); }
+        } catch (e) {}
+      }
+      return clone.outerHTML;
+    JS
+
+    module_function
+
+    # Capture a snapshot.
+    #
+    # @param session  a Capybara session (`page`) or a Selenium driver
+    # @param name     snapshot name; becomes the directory under temp/
+    # @return [Pathname] the temp directory written
+    def witness(session, name,
+                ignore_selectors: nil,
+                stabilize: nil,
+                skip_dom: false,
+                skip_element_map: false,
+                max_elements: nil,
+                project_root: nil)
+      browser = resolve_browser(session)
+      root = Pathname.new(project_root || Config.project_root)
+      config = Config.load(root)
+
+      selectors = ((config["ignoreSelectors"] || []) + (ignore_selectors || [])).uniq
+      stabilize = config["stabilize"] if stabilize.nil?
+      stabilize = true if stabilize.nil?
+
+      temp_dir = root.join(".testivai", "temp", name.to_s)
+      FileUtils.mkdir_p(temp_dir)
+
+      css = +""
+      css << STABILIZE_CSS if stabilize
+      css << hide_css(selectors) unless selectors.empty?
+
+      injected = false
+      unless css.empty?
+        injected = inject_css(browser, css)
+        wait_for_fonts(browser) if stabilize
+      end
+
+      begin
+        screenshot = capture_screenshot(browser)
+      ensure
+        remove_css(browser) if injected
+      end
+
+      File.binwrite(temp_dir.join("screenshot.png"), screenshot)
+
+      # DOM snapshot — best-effort. Losing it only costs the noise hint;
+      # it must never break the screenshot path.
+      unless skip_dom
+        begin
+          dom = browser.execute_script(DOM_SNAPSHOT_JS, selectors)
+          temp_dir.join("dom.html").write(dom) if dom.is_a?(String) && !dom.empty?
+        rescue StandardError # rubocop:disable Lint/SuppressedException
+        end
+      end
+
+      # Element map — same best-effort contract. Powers region→selector
+      # attribution, shift classification, and the style fingerprint.
+      unless skip_element_map
+        begin
+          expr = ElementMap.expression(max_elements || ElementMap::DEFAULT_MAX_ELEMENTS, selectors)
+          map = browser.execute_script(expr)
+          if map.is_a?(Array) && !map.empty?
+            temp_dir.join("elements.json").write(JSON.generate(map))
+          end
+        rescue StandardError # rubocop:disable Lint/SuppressedException
+        end
+      end
+
+      temp_dir
+    end
+
+    # Capybara sessions wrap the real driver; a bare Selenium driver is
+    # already what we want. Accept both so this works in RSpec/Capybara,
+    # Cucumber, or plain selenium-webdriver.
+    def resolve_browser(session)
+      return session.driver.browser if session.respond_to?(:driver) && session.driver.respond_to?(:browser)
+      return session.browser if session.respond_to?(:browser)
+
+      session
+    end
+
+    def hide_css(selectors)
+      selectors.map { |s| "#{s} { visibility: hidden !important; }" }.join("\n")
+    end
+
+    def inject_css(browser, css)
+      browser.execute_script(INJECT_STYLE_JS, STYLE_ID, css)
+      true
+    rescue StandardError
+      false
+    end
+
+    def remove_css(browser)
+      browser.execute_script(REMOVE_STYLE_JS, STYLE_ID)
+    rescue StandardError # rubocop:disable Lint/SuppressedException
+    end
+
+    def wait_for_fonts(browser, timeout: 10.0)
+      deadline = Time.now + timeout
+      loop do
+        return if browser.execute_script(FONTS_READY_JS)
+        return if Time.now > deadline
+
+        sleep 0.05
+      end
+    rescue StandardError # rubocop:disable Lint/SuppressedException
+    end
+
+    # Full page where the browser offers it, viewport otherwise.
+    #
+    #   - Chromium: CDP Page.captureScreenshot with captureBeyondViewport,
+    #     the same mechanism Playwright uses — a true full-page capture with
+    #     no window resizing (resizing breaks 100vh layouts).
+    #   - Firefox: selenium-webdriver exposes save_full_page_screenshot.
+    #   - anything else: the plain viewport screenshot.
+    def capture_screenshot(browser)
+      if browser.respond_to?(:execute_cdp)
+        begin
+          result = browser.execute_cdp("Page.captureScreenshot",
+                                       "captureBeyondViewport" => true, "format" => "png")
+          data = result && (result["data"] || result[:data])
+          return Base64.decode64(data) if data
+        rescue StandardError # rubocop:disable Lint/SuppressedException
+        end
+      end
+
+      if browser.respond_to?(:full_screenshot_as)
+        begin
+          return browser.full_screenshot_as(:png)
+        rescue StandardError # rubocop:disable Lint/SuppressedException
+        end
+      end
+
+      browser.screenshot_as(:png)
+    end
+  end
+end

data/lib/testivai/config.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module Testivai
+  # Reads `.testivai/config.json`, the same file every other TestivAI adapter
+  # reads. Absent or malformed config falls back to defaults rather than
+  # raising: a broken config should not fail somebody's test suite.
+  module Config
+    DEFAULTS = {
+      "stabilize" => true,
+      "ignoreSelectors" => [],
+      "baselinesDir" => nil
+    }.freeze
+
+    # Walk up from `start` looking for a `.testivai/` directory, the way
+    # Bundler finds a Gemfile. Falls back to `start` so a first run in a
+    # fresh project still writes somewhere sensible.
+    def self.project_root(start = Dir.pwd)
+      current = Pathname.new(start).expand_path
+      current.ascend do |dir|
+        return dir if dir.join(".testivai").directory?
+      end
+      Pathname.new(start).expand_path
+    end
+
+    def self.load(root)
+      path = Pathname.new(root).join(".testivai", "config.json")
+      return DEFAULTS.dup unless path.file?
+
+      DEFAULTS.merge(JSON.parse(path.read))
+    rescue JSON::ParserError, SystemCallError
+      DEFAULTS.dup
+    end
+  end
+end

data/lib/testivai/element_map.js

@@ -0,0 +1,135 @@
+/**
+ * AUTO-GENERATED — DO NOT EDIT.
+ *
+ * Canonical element-map collector, emitted from
+ *   packages/witness/src/capture/element-map.ts
+ * by
+ *   scripts/generate-element-map-asset.js
+ *
+ * Every TestivAI adapter injects this exact function so that element maps
+ * are identical across languages sharing one baseline directory. Edit the
+ * TypeScript source and re-run the generator; CI fails if this file is
+ * stale.
+ *
+ * Default element cap: 3000
+ *
+ * Call form (each adapter wraps it the same way):
+ *   return (<this function>)(document, window, <maxElements>, <ignoreSelectors>);
+ */
+function collectElementMap(doc, win, maxElements, ignoreSelectors = []) {
+    var STYLE_PROPS = [
+        'color', 'background-color', 'background-image',
+        'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',
+        'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
+        'border-top-style', 'border-bottom-style', 'border-radius',
+        'font-family', 'font-size', 'font-weight', 'font-style', 'line-height',
+        'text-align', 'text-transform', 'letter-spacing',
+        'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+        'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+        'display', 'opacity', 'visibility', 'box-shadow',
+    ];
+    function fnv1a(str) {
+        var h = 0x811c9dc5;
+        for (var i = 0; i < str.length; i++) {
+            h ^= str.charCodeAt(i);
+            h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+        }
+        return ('0000000' + h.toString(16)).slice(-8);
+    }
+    function segment(el) {
+        var tag = el.tagName.toLowerCase();
+        var cls = '';
+        if (el.classList && el.classList.length > 0) {
+            cls = '.' + el.classList[0];
+        }
+        var parent = el.parentElement;
+        if (!parent)
+            return tag + cls;
+        var sameTag = 0;
+        var index = 0;
+        for (var i = 0; i < parent.children.length; i++) {
+            var sib = parent.children[i];
+            if (sib.tagName === el.tagName) {
+                sameTag++;
+                if (sib === el)
+                    index = sameTag;
+            }
+        }
+        return sameTag > 1 ? tag + cls + ':nth-of-type(' + index + ')' : tag + cls;
+    }
+    function pathOf(el, stopAt) {
+        var parts = [];
+        var node = el;
+        while (node && node !== stopAt.parentElement) {
+            parts.unshift(segment(node));
+            node = node.parentElement;
+        }
+        return parts.join(' > ');
+    }
+    var dpr = win.devicePixelRatio || 1;
+    var scrollX = win.scrollX || 0;
+    var scrollY = win.scrollY || 0;
+    var out = [];
+    var body = doc.body;
+    if (!body)
+        return out;
+    var stack = [body];
+    while (stack.length > 0 && out.length < maxElements) {
+        var el = stack.pop();
+        // The consistency rule: elements covered by ignoreSelectors are
+        // excluded from pixels and the DOM snapshot — they must be excluded
+        // from the element map too (subtree included), or their dynamic
+        // styles would trip the style fingerprint they were meant to escape.
+        var ignored = false;
+        if (ignoreSelectors.length > 0 && typeof el.matches === 'function') {
+            for (var g = 0; g < ignoreSelectors.length; g++) {
+                try {
+                    if (el.matches(ignoreSelectors[g])) {
+                        ignored = true;
+                        break;
+                    }
+                }
+                catch (e) {
+                    // invalid selector — never breaks the walk
+                }
+            }
+        }
+        if (ignored)
+            continue; // skip element AND subtree
+        var rect = el.getBoundingClientRect();
+        if (rect.width >= 4 && rect.height >= 4) {
+            var styleParts = [];
+            var hidden = false;
+            try {
+                var cs = win.getComputedStyle(el);
+                for (var p = 0; p < STYLE_PROPS.length; p++) {
+                    var value = cs.getPropertyValue(STYLE_PROPS[p]);
+                    if (STYLE_PROPS[p] === 'visibility' && value === 'hidden')
+                        hidden = true;
+                    styleParts.push(STYLE_PROPS[p] + ':' + value);
+                }
+            }
+            catch (e) {
+                // styleHash stays a digest of the empty string — still deterministic
+            }
+            // visibility:hidden elements paint no pixels, so their style changes
+            // can never explain a pixel diff — keep them out of the map. Their
+            // CHILDREN may override visibility, so the subtree still walks.
+            if (!hidden) {
+                out.push({
+                    path: pathOf(el, body),
+                    x: Math.round((rect.x + scrollX) * dpr),
+                    y: Math.round((rect.y + scrollY) * dpr),
+                    width: Math.round(rect.width * dpr),
+                    height: Math.round(rect.height * dpr),
+                    styleHash: fnv1a(styleParts.join(';')),
+                });
+            }
+        }
+        // Push children in reverse so the walk stays document-ordered
+        for (var c = el.children.length - 1; c >= 0; c--) {
+            stack.push(el.children[c]);
+        }
+    }
+    return out;
+}

data/lib/testivai/element_map.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module Testivai
+  # Loads the canonical element-map collector and builds the expression the
+  # adapter injects.
+  #
+  # `element_map.js` is GENERATED from
+  # packages/witness/src/capture/element-map.ts by
+  # scripts/generate-element-map-asset.js, and CI fails when it is stale.
+  # Every adapter — TypeScript, Python, Java, Ruby — injects that identical
+  # function. That matters because they all write into one shared
+  # `.testivai/baselines/` directory: two languages producing subtly
+  # different maps for the same page would show up as a phantom regression.
+  module ElementMap
+    # Matches DEFAULT_MAX_ELEMENTS in the TypeScript source.
+    DEFAULT_MAX_ELEMENTS = 3000
+
+    ASSET = Pathname.new(__dir__).join("element_map.js")
+
+    class << self
+      # Collector source with the generated banner stripped — that comment
+      # helps a reader but is pure weight on the wire, and this string ships
+      # to the browser on every capture.
+      def source
+        @source ||= begin
+          # Explicit UTF-8: the generated asset contains non-ASCII characters,
+          # and Pathname#read would otherwise use the default external
+          # encoding (US-ASCII on some systems), making `strip` raise.
+          raw = ASSET.read(encoding: "UTF-8")
+          start = raw.index("function collectElementMap")
+          if start.nil?
+            raise "element_map.js is malformed: collectElementMap not found. " \
+                  "Regenerate with scripts/generate-element-map-asset.js"
+          end
+          raw[start..].strip
+        end
+      end
+
+      # Wrapped exactly as `buildElementMapExpression` does on the TypeScript
+      # side. WebDriver needs the explicit `return`.
+      def expression(max_elements, ignore_selectors)
+        "return (#{source})(document, window, #{max_elements.to_i}, " \
+          "#{JSON.generate(Array(ignore_selectors))});"
+      end
+    end
+  end
+end

data/lib/testivai/version.rb

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

data/lib/testivai.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "testivai/version"
+require_relative "testivai/config"
+require_relative "testivai/element_map"
+require_relative "testivai/capture"
+
+# TestivAI — local-first visual regression testing for Ruby test suites.
+#
+#   require "testivai"
+#
+#   it "renders the homepage" do
+#     visit "/"
+#     Testivai.witness(page, "homepage")
+#   end
+#
+# Then compare and build the report:
+#
+#   npx testivai report
+module Testivai
+  # Capture a snapshot. See Testivai::Capture.witness for options.
+  def self.witness(session, name, **options)
+    Capture.witness(session, name, **options)
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: testivai
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Budi Sugianto
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-28 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Capture screenshots, DOM snapshots, and element maps from Capybara or
+  Selenium, diff them against baselines committed to your repository, and
+  get a self-contained HTML report that explains what changed and why.
+  No account, no API key, nothing uploaded.
+email:
+- testivai.app@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/testivai.rb
+- lib/testivai/capture.rb
+- lib/testivai/config.rb
+- lib/testivai/element_map.js
+- lib/testivai/element_map.rb
+- lib/testivai/version.rb
+homepage: https://testiv.ai
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://testiv.ai
+  source_code_uri: https://github.com/mcbuddy/testivai-oss
+  documentation_uri: https://testiv.ai/docs/frameworks/ruby/
+  changelog_uri: https://github.com/mcbuddy/testivai-oss/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Local-first visual regression testing for Ruby test suites
+test_files: []