lookbook_visual_tester 0.5.7 → 0.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5198b58b3f8bffad2cb68f1bce804b1bce9d2ccc3e32513699f68a83e04fb054
-  data.tar.gz: bca7f0aa36413c702b5c65e3ed330ac18c4c05edeeeb36e5cb94b0ec1aaa4831
+  metadata.gz: 8a9ad38fc0f69bfa66579bfb8b1228a6a9df8dc9899442174162811586336814
+  data.tar.gz: c258c211b4181e49b4ec8ea13ce5fc8b00a7095c8f5bad664ad8082d6c7e4c34
 SHA512:
-  metadata.gz: 7908ba3fb95002233392bc7b570bdf21f7bfd38f25c0206b0521f5fc89a8773173ea2689fbc1ddaca41b1e838d904118d47d4d3a2760dd829265e7e46d8148c9
-  data.tar.gz: ee266274b9ee9bfd9dd24c146bf6537618da8c10490cee78c8a667d072a8c1bb06e5a43d0ac402ca98131de425fe7e5df9ace5c9b015ca8830db35788940f8b6
+  metadata.gz: 7790e3658daf75df2fe6c18892c4f20ef4738568b1e3731391be847b6857ffd2602a6ade0e7e0850adfaec1c5af8d09b08eb3fa671beda67b9a4af485b2d520c
+  data.tar.gz: 5fd17716ff8b4a1bd0d424201a96a75c0dd8c4f2ccdf69207a96c231c73d0ad7115bf047644afde6684590f40e3361d2fa684916ed526984725aaed4be114cbf

data/CHANGELOG.md

@@ -1,4 +1,11 @@
 # Changelog
+## [0.5.8] - 2026-01-08
+
+### ✨ New Features & Improvements
+- **AI-Native Inspection Tools**: Added `lookbook:inspect` and `lookbook:context` Rake tasks to assist AI agents in understanding preview structure and code context.
+- **Debug Artifacts**: Automatically save HTML DOM snapshots alongside failed visual regression tests for easier debugging.
+- **Visual Tolerance**: Added `tolerance` configuration option and fuzzy matching (Euclidean distance) to `ImageComparator` to reduce flakiness.
+
 ## [0.5.7] - 2026-01-06
 
 ### Fixed

data/README.md

@@ -51,9 +51,26 @@ LookbookVisualTester.configure do |config|
   config.copy_to_clipboard = true                # Enable xclip support
   config.threads = 4                             # Number of parallel threads (default: 4)
   config.wait_time = 0.5                         # Optional: Wait time (seconds) before screenshot (fixes blank screens)
+  config.tolerance = 0.05                        # Optional: Mismatch tolerance (0.0 to 1.0) to ignore minor rendering differences
 end
 ```
 
+## AI Integration
+
+The gem includes tools designed to help AI agents understand and debug your components.
+
+### Inspection
+Get JSON metadata about a preview:
+```bash
+bundle exec rake lookbook:inspect[example/default]
+```
+
+### Context Dump
+Get full source code of the component, preview, and template:
+```bash
+bundle exec rake lookbook:context[example/default]
+```
+
 ## Usage
 
 ### Running Visual Tests
@@ -170,7 +187,6 @@ bundle exec rake lookbook:missing
 ## Next Steps
 
 - **Enhanced Approval Workflow**: Implement a `rake lookbook:approve` task (and potentially an interactive mode) to verify and promote changes to baselines without manual file operations.
-- **Tolerance Configuration**: Add support for configuring pixel mismatch tolerance levels to reduce flakiness in rendering (anti-aliasing, shadow rendering differences).
 - **Ignore Regions**: Allow defining specific areas of a component to exclude from visual comparison (useful for unavoidable dynamic content).
 - **Markdown Reports**: Generate markdown summaries of test runs suitable for posting automatically as Pull Request comments.
 - **Cloud Storage**: Integration with cloud storage (S3, GCS) for managing baseline images to keep the git repository light.

data/lib/lookbook_visual_tester/configuration.rb

@@ -4,7 +4,7 @@ module LookbookVisualTester
     attr_accessor :lookbook_host, :ui_comparison, :diff_dir, :baseline_dir, :current_dir,
                   :history_dir, :history_keep_last_n, :threads, :copy_to_clipboard,
                   :components_folder, :automatic_run, :mask_selectors, :driver_adapter,
-                  :preview_checker_setup, :logger, :wait_time
+                  :preview_checker_setup, :logger, :wait_time, :tolerance
 
     DEFAULT_THREADS = 4
 
@@ -27,7 +27,9 @@ module LookbookVisualTester
       @mask_selectors = []
       @driver_adapter = :ferrum
       @preview_checker_setup = nil
+      @preview_checker_setup = nil
       @wait_time = 0.5
+      @tolerance = 0.0
       @logger = if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
                   Rails.logger
                 else

data/lib/lookbook_visual_tester/drivers/ferrum_driver.rb

@@ -77,6 +77,10 @@ module LookbookVisualTester
         # Usually for visual testing full page is better unless specifically testing viewport.
       end
 
+      def page_source
+        @browser.body
+      end
+
       def cleanup
         @browser.quit
       end

data/lib/lookbook_visual_tester/runner.rb

@@ -182,6 +182,12 @@ module LookbookVisualTester
         elsif result[:mismatch] > 0
           mismatch = result[:mismatch]
           puts "  [FAIL] Mismatch: #{mismatch.round(2)}%. Diff saved to #{diff_path}"
+
+          # Save DOM snapshot for debugging
+          dom_path = diff_path.sub('.png', '.html')
+          File.write(dom_path, driver.page_source)
+          puts "         DOM Snapshot saved to #{dom_path}"
+
           status = :failed
 
           # Clipboard (Feature parity with legacy ScreenshotTaker)

data/lib/lookbook_visual_tester/services/image_comparator.rb

@@ -37,7 +37,13 @@ module LookbookVisualTester
             pixel1 = baseline[x, y]
             pixel2 = current[x, y]
 
-            if pixel1 == pixel2
+            score = 0.0
+            if pixel1 != pixel2
+              score = ChunkyPNG::Color.euclidean_distance_rgba(pixel1, pixel2) / 510.0
+            end
+
+            if score <= LookbookVisualTester.config.tolerance
+              # Match (including exact match where score is 0.0)
               # Blue context for unchanged pixels to make it easier for humans
               gray_val = ChunkyPNG::Color.r(ChunkyPNG::Color.grayscale_teint(pixel1))
               # Keep intensity in R/G but push blue to make it the dominant tint

data/lib/lookbook_visual_tester/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LookbookVisualTester
-  VERSION = '0.5.7'
+  VERSION = '0.5.8'
 end

data/lib/tasks/lookbook_visual_tester.rake

@@ -253,6 +253,139 @@ namespace :lookbook do
     end
     puts "\n"
   end
+
+  desc 'Get detailed inspection data for a preview (JSON)'
+  task :inspect, [:preview_name] => :environment do |_, args|
+    require 'lookbook'
+    require 'lookbook_visual_tester/scenario_finder'
+    require 'lookbook_visual_tester/json_output_handler'
+
+    preview_name = args[:preview_name]
+    unless preview_name
+      LookbookVisualTester::JsonOutputHandler.print({ error: 'Please provide a preview name' })
+      exit 1
+    end
+
+    scenario_run = LookbookVisualTester::ScenarioFinder.call(preview_name)
+
+    unless scenario_run
+      LookbookVisualTester::JsonOutputHandler.print({ error: "No preview found for #{preview_name}" })
+      exit 1
+    end
+
+    scenario = scenario_run.scenario
+    preview = scenario.preview
+    file_path = preview.file_path
+
+    # Try to find line number
+    line_number = nil
+    if File.exist?(file_path)
+      File.foreach(file_path).with_index do |line, index|
+        if line.match?(/^\s*def\s+#{scenario.name}\b/)
+          line_number = index + 1
+          break
+        end
+      end
+    end
+
+    # Inspect component details if available
+    component_class_name = nil
+    component_file_path = nil
+    template_file_path = nil
+
+    if scenario.respond_to?(:component)
+      comp = scenario.component
+      if comp.respond_to?(:component_class) && comp.component_class
+        component_class_name = comp.component_class.name
+        # Best effort to find component source
+        if comp.component_class.instance_methods(false).include?(:initialize)
+          component_file_path = comp.component_class.instance_method(:initialize).source_location&.first
+        end
+        # Fallback to const_source_location if supported (Ruby 2.7+)
+        if component_file_path.nil? && Object.respond_to?(:const_source_location)
+          component_file_path = Object.const_source_location(component_class_name)&.first
+        end
+      end
+
+      template_file_path = comp.template_file_path if comp.respond_to?(:template_file_path)
+    end
+
+    output = {
+      name: scenario.lookup_path,
+      preview_class: preview.name,
+      file_path: file_path,
+      line_number: line_number,
+      url_path: scenario.url_path,
+      component_class: component_class_name,
+      component_path: component_file_path,
+      template_path: template_file_path
+    }
+
+    LookbookVisualTester::JsonOutputHandler.print(output)
+  end
+
+  desc 'Dump content of preview, component, and template for context'
+  task :context, [:preview_name] => :environment do |_, args|
+    require 'lookbook_visual_tester/json_output_handler'
+
+    require 'lookbook'
+    require 'lookbook_visual_tester/scenario_finder'
+
+    preview_name = args[:preview_name]
+    unless preview_name
+      puts 'Error: Please provide a preview name'
+      exit 1
+    end
+
+    scenario_run = LookbookVisualTester::ScenarioFinder.call(preview_name)
+
+    unless scenario_run
+      puts "Error: No preview found for #{preview_name}"
+      exit 1
+    end
+
+    scenario = scenario_run.scenario
+    preview = scenario.preview
+
+    files_to_dump = []
+
+    # 1. Preview File
+    files_to_dump << { path: preview.file_path, label: "Preview: #{preview.name}" }
+
+    # 2. Template File (if available)
+    if scenario.respond_to?(:component)
+      comp = scenario.component
+      if comp.respond_to?(:template_file_path) && comp.template_file_path
+        files_to_dump << { path: comp.template_file_path, label: 'Template' }
+      end
+
+      # 3. Component File (best effort)
+      if comp.respond_to?(:component_class) && comp.component_class
+        component_file_path = nil
+        if comp.component_class.instance_methods(false).include?(:initialize)
+          component_file_path = comp.component_class.instance_method(:initialize).source_location&.first
+        end
+        if component_file_path.nil? && Object.respond_to?(:const_source_location)
+          component_file_path = Object.const_source_location(comp.component_class.name)&.first
+        end
+
+        if component_file_path
+          files_to_dump << { path: component_file_path, label: "Component: #{comp.component_class.name}" }
+        end
+      end
+    end
+
+    files_to_dump.each do |file|
+      next unless file[:path] && File.exist?(file[:path])
+
+      puts "\n"
+      puts '========================================'
+      puts "#{file[:label]} (#{file[:path]})"
+      puts '========================================'
+      puts File.read(file[:path])
+      puts '========================================'
+    end
+  end
 end
 
 # Compatibility aliases and extra tools

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lookbook_visual_tester
 version: !ruby/object:Gem::Version
-  version: 0.5.7
+  version: 0.5.8
 platform: ruby
 authors:
 - Murilo Vasconcelos
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: cuprite
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: ferrum
   requirement: !ruby/object:Gem::Requirement