lookbook_visual_tester 0.5.3 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61d8ae85e5897ffcb0dd53078b753a02cfc118e9cf5990ebbf27b40c5778bc4a
-  data.tar.gz: afcd716247590085bf7dbb99c36e146f45a350f349c1c2fda5dad9d7c8441192
+  metadata.gz: c4dcc1d8c929065528b1f5ad9ee02dac8a2b0520e72d110ec105f954fcdfcf65
+  data.tar.gz: ce57354faceb6b0035fd89ef6bfbe6c394c0cc616bd8093929d68a26cd323b88
 SHA512:
-  metadata.gz: e22889eacb81f638d7ba65ab1e8682d0e1ec7e22903f67b950912ef5f670eb3ec13dca31ba21e52ef6cac3e73ce6da11179a7ec35e37eb44b5392e4f99ac6004
-  data.tar.gz: e5f18347bff022b59a7b6504c2a2cd0b64e279b587b9dc92f4a0001f7056cc63e8affa58167799cac8ef2fa434718d973ea6fbd375f54a6697240f5b1bc050bf
+  metadata.gz: cc7e7d15b48f2d4aef69244851d1bba41dd8b40dc0709562bcdf764485dee2846ec69848891671701fc89ea1f001555627aed0fe631fd823cc527a1e3ead108a
+  data.tar.gz: 593a40641363733cffbc4c578b3e9ef94c25491ccb6f48a2230ddb12e91290baaea9738387225adfe7b45a36fb95c8002ea63d098e37be8d12a2815f82990939

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,5 +1,29 @@
 # Changelog
-## [0.5.3] - 2026-01-04
+## [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
+- **Variants URL Generation**: Fixed a bug where setting `VARIANTS` caused a `JSON::ParserError` in Lookbook. Variant parameters are now correctly serialized to JSON in the preview URL.
 
 ### Fixed
 - **Deep Check**: `rake lookbook:deep_check` now correctly detects and fails when a preview returns `nil` (implicit rendering) but the corresponding template is missing (`ViewComponent::MissingPreviewTemplateError`).

data/README.md

@@ -28,8 +28,8 @@ sudo apt-get install imagemagick xclip
 
 Add to your application's Gemfile:
 ```ruby
-group :test do
-  gem 'lookbook_visual_tester', '~> 0.5.3'
+group :test, :development do
+  gem 'lookbook_visual_tester', '~> 0.5.4'
 end
 ```
 
@@ -45,7 +45,7 @@ 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)
 end
@@ -101,7 +101,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
@@ -166,7 +166,13 @@ bundle exec rake lookbook:missing
 
 ## Next Steps
 
-- **CI/CD Integration**: Provide recipes for GitHub Actions to run visual regression on PRs.
+- **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.
+- **CI/CD Blueprints**: Detailed guides and reusable actions/steps for integrating with GitHub Actions, GitLab CI, etc.
+- **Multiple Browsers**: Expand driver support beyond Chrome/Ferrum (e.g. Firefox, Safari/Webkit) for cross-browser visual testing.
 
 ## Contributing
 

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

@@ -13,14 +13,12 @@ module LookbookVisualTester
     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')

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
@@ -57,7 +57,7 @@ module LookbookVisualTester
 
       if display_params.any?
         # Transform display_params { theme: 'dark' } -> { _display: { theme: 'dark' } }
-        params[:_display] = display_params
+        params[:_display] = display_params.to_json
       end
 
       Lookbook::Engine.routes.url_helpers.lookbook_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.3'
+  VERSION = '0.5.6'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lookbook_visual_tester
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.6
 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