lookbook_visual_tester 0.5.4 → 0.5.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52de57eac4b35b3aba43c82000005b796b7bfb405fed5914ffda3ff3d6039b2f
-  data.tar.gz: a6c8e5faf0af703732a0438766299bb1300879997c64d6cc96188e1a2a3ab47b
+  metadata.gz: 5198b58b3f8bffad2cb68f1bce804b1bce9d2ccc3e32513699f68a83e04fb054
+  data.tar.gz: bca7f0aa36413c702b5c65e3ed330ac18c4c05edeeeb36e5cb94b0ec1aaa4831
 SHA512:
-  metadata.gz: 78ee1ea32f42cbf2fe58f4178f03e7db493ab1598d1d80a65918c497bff2cb51778f6413b321ae8cda01248bd1714fd72ec0b44d6a968d33273234de21836d5c
-  data.tar.gz: 945d4767c88ec3121c11c6ea83e87ca286a5f5d8a1feb07b1fb10275b0c9139066047a348f9b6ce2f3d06d25f1ae09645a75aeba5dfdd99497cf2def48dddddf
+  metadata.gz: 7908ba3fb95002233392bc7b570bdf21f7bfd38f25c0206b0521f5fc89a8773173ea2689fbc1ddaca41b1e838d904118d47d4d3a2760dd829265e7e46d8148c9
+  data.tar.gz: ee266274b9ee9bfd9dd24c146bf6537618da8c10490cee78c8a667d072a8c1bb06e5a43d0ac402ca98131de425fe7e5df9ace5c9b015ca8830db35788940f8b6

data/.agent/rules/style_guide.md

@@ -0,0 +1,59 @@
+# Lookbook Visual Tester Style Guide & Best Practices
+
+## Project Overview
+`lookbook_visual_tester` is a Ruby gem designed for visual regression testing of Lookbook previews. It uses `Ferrum` for headless browser interactions and `ChunkyPNG` for image comparison.
+
+## Architecture & patterns
+
+### Service Objects
+- Isolate complex logic in service objects inheriting from `LookbookVisualTester::Service` (if applicable) or plain Ruby classes in `lib/lookbook_visual_tester/services/`.
+- Examples: `ImageComparator`, `ScenarioFinder`.
+
+### Configuration
+- Use `LookbookVisualTester.configure` to set global options.
+- Options are defined in `lib/lookbook_visual_tester/configuration.rb`.
+- Default base path for screenshots is `coverage/screenshots` (as of v0.5.5).
+
+### Path Handling
+- Use `Pathname` for all file system paths.
+- **Screenshot Structure**:
+  - `[base_path]/[baseline|current|diffs]/[folder_name]/[filename].png`
+  - `folder_name` is either the variant slug (e.g., `dark-mode`) or `default` if no variant is present.
+  - Never allow files to be dumped at the root of the screenshot directories; always enforce a subdirectory.
+
+## Visual Testing Logic
+
+### Image Comparison
+- **Dimension Mismatch**: Do not raise errors for images of different sizes.
+  - Create a canvas size equal to the maximum width and height of the two images.
+  - Compare overlapping pixels.
+  - Mark non-overlapping pixels (from the larger image) as differences.
+  - Used in: `LookbookVisualTester::Services::ImageComparator`.
+
+### Screenshot Capture
+- Use `Ferrum` to capture screenshots.
+- Ensure consistent viewport sizes and wait for animations/fonts if necessary (managed in `Runner` logic).
+
+## Testing (`RSpec`)
+
+### Structure
+- **Unit Tests**: `spec/lib/lookbook_visual_tester/...`
+- **Integration Tests**: `spec/integration/...`
+- Use `spec_helper.rb` for common setup.
+
+### Best Practices
+- **Reproduction Scripts**: somewhat complex bugs (like visual mismatches) should be isolated in top-level `repro_*.rb` scripts before fixing.
+- **Mocking**: Be careful with circular dependencies when mocking `Lookbook` objects (e.g., `Scenario` <-> `Preview`). Use `allow(...).to receive(...)` logic in `before` blocks rather than definitions to break cycles.
+
+## Versioning & Changelog
+- **Versioning**: Semantic versioning in `lib/lookbook_visual_tester/version.rb`.
+- **Changelog**: Maintain `CHANGELOG.md` with `[Unreleased]` and version headers. Group changes by `Added`, `Changed`, `Fixed`.
+
+## Coding Style
+- Standard Ruby style (indentation: 2 spaces).
+- Prefer descriptive variable names over short cryptic ones.
+- Use `frozen_string_literal: true` where appropriate (though not strictly enforced everywhere yet).
+
+## Versioning & Changelog
+
+When updating the version, make sure to update the `CHANGELOG.md` file with the new version number and a list of changes since the last release. The changes should be grouped by `Added`, `Changed`, and `Fixed`. Also update `README.md` accordingly.

data/CHANGELOG.md

@@ -1,4 +1,31 @@
 # Changelog
+## [0.5.7] - 2026-01-06
+
+### Fixed
+- **Flaky Screenshots**: Added `wait_time` configuration to `LookbookVisualTester.config` to allow explicit waiting before screenshot capture. This resolves blank or layout-only screenshots in slower environments.
+- **Robust Driver**: Updated `FerrumDriver` to include consistent network idle checks and support the new `wait_time` option.
+
+## [0.5.6] - 2026-01-06
+
+### Fixed
+- **Image Comparison**: Fixed `Dimensions mismatch` error by creating a diff canvas sized to the maximum dimensions of widely differing images.
+- **Missing Action Error**: Resolved `ActionNotFound` for `render_scenario_to_string` by ensuring the preview controller properly includes `Lookbook::PreviewControllerActions`.
+- **Unexpected Headers**: Fixed an issue where the `example_icons` preview in the dummy app included an unwanted `<h1>Icons</h1>` header.
+- **Spec Fix**: Resolved a `SystemStackError` (circular dependency) in `ScenarioFinder` specs.
+
+### Changed
+- **Folder Structure**: Refactored screenshot organization. Non-variant screenshots are now stored in a `default` subfolder within `coverage/screenshots`.
+- **Deep Check**: Enhanced `rake lookbook:deep_check` to validate that the configured preview controller supports required Lookbook actions.
+
+## [0.5.5] - 2026-01-06
+
+### Fixed
+- **Image Comparison**: Fixed `Dimensions mismatch` error. Now, when images have different dimensions, a diff image is generated on a canvas sized to the maximum dimensions, clearly showing the differences and the mismatched areas.
+
+### Changed
+- **Folder Structure**: Screenshots are now saved in `coverage/screenshots` by default (previously `spec/visual_screenshots`).
+- **Default Subfolder**: Non-variant screenshots are now stored in a `default` subfolder to maintain consistency with variant-based runs.
+
 ## [0.5.4] - 2026-01-06
 
 ### Fixed

data/README.md

@@ -4,6 +4,8 @@
 
 A powerful visual regression testing tool for [ViewComponent](https://viewcomponent.org/) via [Lookbook](https://lookbook.build/). It automates the process of capturing screenshots of your components, comparing them against baselines, and highlighting differences with human-friendly aesthetics.
 
+*This tool has been tested "at home". If it doesn't work for you, feel free to open an issue. **It works on my machine!***
+
 ### Key Features
 
 - **Automated Visual Regression**: Captures and compares screenshots of all Lookbook previews.
@@ -45,9 +47,10 @@ You can configure the tester in a Rails initializer:
 ```ruby
 LookbookVisualTester.configure do |config|
   config.lookbook_host = "http://localhost:3000" # Where your rails app is running
-  config.base_path = "spec/visual_regression"    # Root for screenshots
+  config.base_path = "coverage/screenshots"    # Root for screenshots
   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)
 end
 ```
 
@@ -101,7 +104,7 @@ You can run your visual tests against multiple configurations (variants), such a
     * **`{"theme":"dark"}`**: Runs with `_display[theme]=dark`.
     * **`{"width":"Mobile"}`**: Runs with `_display[width]=375px` AND automatically resizes the browser window to 375px width.
 
-    Screenshots for variants are saved in dedicated subfolders (e.g., `spec/visual_regression/baseline/theme-dark/`).
+    Screenshots for variants are saved in dedicated subfolders (e.g., `coverage/screenshots/baseline/theme-dark/`).
 
 
 ### Baseline Management

data/Rakefile

@@ -3,6 +3,8 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
+# Load gem tasks
+Dir.glob('lib/tasks/*.rake').each { |r| import r }
 
 RSpec::Core::RakeTask.new(:spec)
 

data/lib/lookbook_visual_tester/configuration.rb

@@ -1,26 +1,20 @@
 module LookbookVisualTester
   class Configuration
     attr_reader :base_path
-    attr_accessor :lookbook_host,
-                  :baseline_dir, :current_dir, :diff_dir, :history_dir,
-                  :history_keep_last_n, :threads, :copy_to_clipboard,
-                  :components_folder,
-                  :automatic_run,
-                  :mask_selectors, :driver_adapter,
-                  :preview_checker_setup,
-                  :logger
+    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
 
     DEFAULT_THREADS = 4
 
     def initialize
-      @base_path = if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.test?
-                     Pathname.new(Dir.pwd).join('spec/visual_screenshots')
-                   elsif defined?(Rails) && Rails.respond_to?(:root) && Rails.root
-                     Rails.root.join('spec/visual_screenshots')
-                   else
-                     # Fallback for non-Rails environments
-                     Pathname.new(Dir.pwd).join('spec/visual_screenshots')
-                   end
+      root_path = if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+                    Rails.root
+                  else
+                    Pathname.new(Dir.pwd)
+                  end
+      @base_path = root_path.join('coverage/screenshots')
       @baseline_dir = @base_path.join('baseline')
       @current_dir = @base_path.join('current_run')
       @diff_dir = @base_path.join('diff')
@@ -33,6 +27,7 @@ module LookbookVisualTester
       @mask_selectors = []
       @driver_adapter = :ferrum
       @preview_checker_setup = nil
+      @wait_time = 0.5
       @logger = if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
                   Rails.logger
                 else

data/lib/lookbook_visual_tester/drivers/ferrum_driver.rb

@@ -53,22 +53,26 @@ module LookbookVisualTester
         wait_for_network_idle
         wait_for_fonts
         wait_for_custom_selectors
+        # Explicit wait if configured, for robustness against "blank screenshot" issues
+        sleep(config.wait_time) if config.wait_time.positive?
       end
 
       def wait_for_fonts
-        @browser.execute("return document.fonts.ready")
+        @browser.execute('return document.fonts.ready')
       end
 
-      def wait_for_network_idle(timeout: 2, duration: 0.5)
-        # Ferrum has built-in network idle waiting
+      def wait_for_network_idle
+        # Ferrum has built-in network idle waiting.
+        # We rely on default settings or explicit sleep for extra safety.
         @browser.network.wait_for_idle
       rescue Ferrum::TimeoutError
-        # Log warning but proceed?
+        # Log warning but proceed - sometimes long polling or other scripts keep net active
+        config.logger.warn 'LookbookVisualTester: Network idle timeout. Proceeding with screenshot.'
       end
 
       def save_screenshot(path)
         @browser.screenshot(path: path, full: true)
-        # Note: full: true captures the whole page.
+        # NOTE: full: true captures the whole page.
         # If we capture viewport only, we should remove full: true.
         # Usually for visual testing full page is better unless specifically testing viewport.
       end
@@ -86,7 +90,7 @@ module LookbookVisualTester
       end
 
       def disable_animations
-        css = "* { transition: none !important; animation: none !important; caret-color: transparent !important; }"
+        css = '* { transition: none !important; animation: none !important; caret-color: transparent !important; }'
         inject_style(css)
       end
 
@@ -95,15 +99,17 @@ module LookbookVisualTester
         start = Time.now
         until @browser.execute("return document.fonts.status === 'loaded'")
           break if Time.now - start > 5
+
           sleep 0.1
         end
 
         # Also check for images loading attributes if needed
         # "check that no images have loading attributes active"
         # Often checking complete property is enough
-        until @browser.execute("return Array.from(document.images).every(i => i.complete)")
-           break if Time.now - start > 5
-           sleep 0.1
+        until @browser.execute('return Array.from(document.images).every(i => i.complete)')
+          break if Time.now - start > 5
+
+          sleep 0.1
         end
       end
     end

data/lib/lookbook_visual_tester/preview_checker.rb

@@ -18,6 +18,7 @@ module LookbookVisualTester
     def deep_check
       # Ensure custom setup is run before deep checks
       run_setup
+      check_preview_controller_config
       run_checks(:deep_render_check)
     end
 
@@ -204,6 +205,27 @@ module LookbookVisualTester
       end
     end
 
+    def check_preview_controller_config
+      return unless defined?(Rails)
+
+      controller_name = Rails.application.config.view_component.preview_controller
+      return unless controller_name
+
+      begin
+        controller_class = controller_name.constantize
+        unless controller_class.action_methods.include?('render_scenario_to_string')
+          puts "WARNING: Configured preview controller '#{controller_name}' does not have 'render_scenario_to_string' action."
+          puts '         This is required for Lookbook to render previews correctly.'
+          puts "         Please ensure your preview controller inherits from 'Lookbook::PreviewController'."
+          # We could raise an error here to fail deep_check
+          raise "Preview Controller '#{controller_name}' missing required action 'render_scenario_to_string'"
+        end
+      rescue NameError
+        puts "WARNING: Configured preview controller '#{controller_name}' could not be loaded."
+        raise "Preview Controller '#{controller_name}' could not be loaded"
+      end
+    end
+
     def run_setup
       if @config.preview_checker_setup
         @config.preview_checker_setup.call

data/lib/lookbook_visual_tester/runner.rb

@@ -142,16 +142,8 @@ module LookbookVisualTester
         # Determine paths
         current_path = run_data.current_path
         baseline_path = run_data.baseline_path
-        diff_path = @config.diff_dir.join(run_data.diff_filename)
-        # Update diff path to respect variant structure if needed?
-        # Actually ScenarioRun#diff_filename is just flat for now but let's fix that?
-        # ScenarioRun doesn't expose diff_path with slug. Let's fix that manually here if needed or update ScenarioRun.
-        # Wait, ScenarioRun stores baseline/current in folders but diff_filename is just name.
-        # We should probably put diffs in folders too.
-        # Let's adjust diff_path here:
-        if variant_slug.present?
-          diff_path = @config.diff_dir.join(variant_slug, run_data.diff_filename)
-        end
+        folder_name = variant_slug.presence || 'default'
+        diff_path = @config.diff_dir.join(folder_name, run_data.diff_filename)
 
         FileUtils.mkdir_p(File.dirname(current_path))
         FileUtils.mkdir_p(File.dirname(diff_path))

data/lib/lookbook_visual_tester/scenario_run.rb

@@ -40,16 +40,16 @@ module LookbookVisualTester
       "#{preview_name}_#{scenario_name}_diff.png"
     end
 
+    def folder_name
+      variant_slug.presence || 'default'
+    end
+
     def current_path
-      base = LookbookVisualTester.config.current_dir
-      base = base.join(variant_slug) if variant_slug.present?
-      base.join(filename)
+      LookbookVisualTester.config.current_dir.join(folder_name).join(filename)
     end
 
     def baseline_path
-      base = LookbookVisualTester.config.baseline_dir
-      base = base.join(variant_slug) if variant_slug.present?
-      base.join(filename)
+      LookbookVisualTester.config.baseline_dir.join(folder_name).join(filename)
     end
 
     def preview_url

data/lib/lookbook_visual_tester/services/image_comparator.rb

@@ -16,41 +16,45 @@ module LookbookVisualTester
 
     def call
       unless File.exist?(baseline_path)
-        return { diff_path: nil, mismatch: 0.0, error: "Baseline not found" }
+        return { diff_path: nil, mismatch: 0.0, error: 'Baseline not found' }
       end
 
       baseline = ChunkyPNG::Image.from_file(baseline_path)
       current = ChunkyPNG::Image.from_file(current_path)
 
-      if baseline.dimension != current.dimension
-        return {
-          diff_path: nil,
-          mismatch: 100.0,
-          error: "Dimensions mismatch: #{baseline.width}x#{baseline.height} vs #{current.width}x#{current.height}"
-        }
-      end
+      max_width = [baseline.width, current.width].max
+      max_height = [baseline.height, current.height].max
 
       diff_pixels_count = 0
-      diff_image = ChunkyPNG::Image.new(baseline.width, baseline.height, ChunkyPNG::Color::WHITE)
+      diff_image = ChunkyPNG::Image.new(max_width, max_height, ChunkyPNG::Color::WHITE)
+
+      max_height.times do |y|
+        max_width.times do |x|
+          in_baseline = x < baseline.width && y < baseline.height
+          in_current = x < current.width && y < current.height
 
-      baseline.height.times do |y|
-        baseline.width.times do |x|
-          pixel1 = baseline[x, y]
-          pixel2 = current[x, y]
+          if in_baseline && in_current
+            pixel1 = baseline[x, y]
+            pixel2 = current[x, y]
 
-          if pixel1 != pixel2
+            if pixel1 == pixel2
+              # 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
+              diff_image[x, y] = ChunkyPNG::Color.rgba(gray_val, gray_val, 255, 50)
+            else
+              diff_image[x, y] = DIFF_COLOR
+              diff_pixels_count += 1
+            end
+          elsif in_baseline || in_current
+            # Pixel exists in one but not the other -> Mismatch
             diff_image[x, y] = DIFF_COLOR
             diff_pixels_count += 1
-          else
-            # 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
-            diff_image[x, y] = ChunkyPNG::Color.rgba(gray_val, gray_val, 255, 50)
           end
         end
       end
 
-      mismatch_percentage = (diff_pixels_count.to_f / baseline.pixels.size) * 100.0
+      mismatch_percentage = (diff_pixels_count.to_f / (max_width * max_height)) * 100.0
 
       if diff_pixels_count > 0
         FileUtils.mkdir_p(File.dirname(diff_path))

data/lib/lookbook_visual_tester/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lookbook_visual_tester
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.5.7
 platform: ruby
 authors:
 - Murilo Vasconcelos
@@ -172,6 +172,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".agent/rules/style_guide.md"
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md