lookbook_visual_tester 0.3.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d40b1ba348d95a09c7ea9997d965e00026e9873cf5a8e2faebeed31d6898b6e9
-  data.tar.gz: 725d2b67ae419319e79ac56c52cb74f1d3f5354099fa30e670cf292c2e25b07d
+  metadata.gz: 865c3eeb875ed336338493ccbd620fcfeba15be5410c7d605cf73d94e79e3756
+  data.tar.gz: '081022c43fe54c60a95be903181d956223bb34800700a44a45baf3c69d7cc4a8'
 SHA512:
-  metadata.gz: 1c8fac94fb8e61906506b8dd48f87d9b6bb9cb01ec238a2b805a4f98ceadde02cf8555b45c80f1daef4b1710392b0fcd05a36f7420fe279440cd2491d3f63ad2
-  data.tar.gz: 3025ca8c334a4185dcbcdc8d2c03288fb46bb07c582d8a2c363cc69929a6be2044246c1d7bc313f06787970e49541872bee57e18cf6b800f8a1afb41b5375aec
+  metadata.gz: 4991161dee4f699f25517991abf504cc92ac8c229e4e61a985da90195d0238815423c9129f51cc5abf5ad0818f0bacfdf65a4aea087e93ad309fbe69ed3cbd9d
+  data.tar.gz: 9e3d4f144424de70fc3754b5939d65ee3f327cab3ad2dcecc6dd1923adc77d88db834bfaacbf059deb051fe66546248346f01d90f20593d25cea01e0f1449860

data/CHANGELOG.md

@@ -1,4 +1,30 @@
 # Changelog
+## [0.5.1] - 2026-01-03
+
+### Fixed
+- **Deprecation Warning**: Replaced usage of `examples` with `scenarios` to resolve Lookbook deprecation warnings.
+
+## [0.5.0] - 2026-01-03
+
+### ✨ New Features & Improvements
+- **Preview Health Checks**: Added new Rake tasks to verify preview integrity:
+    - `lookbook:check`: Rapidly checks if previews load and instantiate without errors.
+    - `lookbook:deep_check`: Verified previews by effectively rendering them to catch runtime and template errors.
+    - `lookbook:missing`: Identifies ViewComponents that lack a corresponding preview.
+- **Parallel Preview Checks**: Health checks run in parallel using `concurrent-ruby`.
+- **Comprehensive Reporting**: Checks generate colored terminal output and a detailed HTML report (`coverage/preview_check_report.html`) including timing stats and slowest previews.
+- **Custom Deep Check Setup**: Added `config.preview_checker_setup` to allow defining mocks (e.g., User, Warden) required for deep checking.
+
+## [0.4.0] - 2026-01-03
+
+### ✨ New Features & Improvements
+- **Multiple Screenshot Variants**: Support for defining screenshot variants (e.g., specific viewports, themes) using Lookbook's `preview_display_options`.
+  - Configurable via `VARIANTS` environment variable (JSON array).
+  - Screenshots are saved in subdirectories corresponding to the variant options.
+  - Automatic browser resizing based on `width` options.
+
+### 🧹 Housekeeping
+- **Removed Minitest**: Switched completely to RSpec for internal testing. Deleted unused Minitest files and configuration.
 
 ## [0.3.0] - 2026-01-03
 

data/README.md

@@ -75,6 +75,35 @@ You can override the host or other settings inline:
 LOOKBOOK_HOST=http://localhost:5000 LOOKBOOK_THREADS=8 bundle exec rake lookbook:test
 ```
 
+#### Screenshot Variants
+
+You can run your visual tests against multiple configurations (variants), such as different themes or viewports, by leveraging Lookbook's `preview_display_options`.
+
+1.  **Define Options in Lookbook**:
+    Ensure your Rails app has display options configured:
+    ```ruby
+    # config/lookbook.rb
+    Lookbook.config.preview_display_options = {
+      theme: ["light", "dark"],
+      width: [["Mobile", "375px"], ["Desktop", "1280px"]]
+    }
+    ```
+
+2.  **Run with Variants**:
+    Use the `VARIANTS` environment variable to define a JSON array of option sets to test.
+
+    *Example: Run standard tests + Dark Mode + Mobile View*
+    ```bash
+    VARIANTS='[{}, {"theme":"dark"}, {"width":"Mobile"}]' bundle exec rake lookbook:test
+    ```
+
+    * **`{}`**: Runs the default/standard preview.
+    * **`{"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/`).
+
+
 ### Baseline Management
 
 1. **First Run**: When you run the tests for the first time, all screenshots are saved as **Baselines**.
@@ -113,12 +142,31 @@ bundle exec rspec
 bundle exec rspec spec/integration/full_flow_spec.rb
 ```
 
+### Preview Health Checks
+
+The gem provides tasks to ensure your previews are healthy and up-to-date.
+
+#### Check Load/Syntax
+Checks if all previews can be loaded and instantiated without errors.
+```bash
+bundle exec rake lookbook:check
+```
+
+#### Deep Check (Render)
+effectively renders all previews to catch runtime and template errors.
+```bash
+bundle exec rake lookbook:deep_check
+```
+
+#### Find Missing Previews
+Identifies components that don't have a corresponding preview file.
+```bash
+bundle exec rake lookbook:missing
+```
+
 ## Next Steps
 
-- **Multi-Viewport Support**: Add ability to capture screenshots at different screen widths (Mobile, Tablet, Desktop).
 - **CI/CD Integration**: Provide recipes for GitHub Actions to run visual regression on PRs.
-- **Reporting Dashboard**: Generate a static HTML report to easily browse all diffs in a single view.
-- [x] **Concurrent Captures**: Optimize execution speed by parallelizing screenshot taking across multiple browser instances.
 
 ## Contributing
 

data/Rakefile

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
-require 'minitest/test_task'
-
-Minitest::TestTask.create
-
+require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
 
+RSpec::Core::RakeTask.new(:spec)
+
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+task default: %i[spec rubocop]
 
 namespace :release do
   desc 'Release with OTP (MFA) support'

data/lib/lookbook_visual_tester/check_reporter.rb

@@ -0,0 +1,81 @@
+require 'rainbow'
+require 'thor/group'
+
+module LookbookVisualTester
+  class CheckReporter < Thor::Group
+    include Thor::Actions
+
+    argument :results
+
+    def self.source_root
+      File.dirname(__FILE__)
+    end
+
+    def report
+      @errors = results.select { |r| r.status == :failed }
+      @success_count = results.count { |r| r.status == :passed }
+      @total_duration = results.sum { |r| r.duration.to_f }
+
+      report_terminal
+      report_html
+    end
+
+    def self.report_missing(missing)
+      if missing.any?
+        puts Rainbow("\nFound #{missing.size} components missing previews:").yellow
+        missing.sort_by { |m| m.component_path }.each do |m|
+          puts "  - #{m.component_path}"
+        end
+        puts "\nTotal: #{missing.size} missing previews."
+      else
+        puts Rainbow('All components have previews!').green
+      end
+    end
+
+    private
+
+    attr_reader :errors, :success_count, :total_duration
+
+    def report_terminal
+      puts "\n--- Check Results ---"
+
+      results.each do |result|
+        if result.status == :passed
+          print Rainbow('.').green
+        else
+          print Rainbow('F').red
+        end
+      end
+      puts "\n"
+
+      if errors.any?
+        puts Rainbow("\n#{errors.size} errors found:").red
+        errors.each do |err|
+          puts "\n--------------------------------------------------"
+          puts "Preview: #{err.preview_name}##{err.example_name}"
+          puts "Error: #{err.error}"
+          puts "Time: #{err.duration.to_f.round(4)}s"
+          puts "Backtrace: #{err.backtrace&.first(3)&.join("\n  ")}"
+        end
+      else
+        puts Rainbow("\nAll #{results.size} previews passed!").green
+      end
+
+      puts "\nTotal time: #{total_duration.round(2)}s"
+
+      report_slowest_previews
+    end
+
+    def report_slowest_previews
+      puts "\n--- Top 5 Slowest Previews ---"
+      slowest = results.sort_by { |r| -r.duration.to_f }.first(5)
+      slowest.each do |res|
+        puts "#{Rainbow("#{res.duration.to_f.round(4)}s").yellow} - #{res.preview_name}##{res.example_name}"
+      end
+    end
+
+    def report_html
+      template 'templates/preview_check_report.html.tt', 'coverage/preview_check_report.html'
+    end
+  end
+end

data/lib/lookbook_visual_tester/configuration.rb

@@ -7,6 +7,7 @@ module LookbookVisualTester
                   :components_folder,
                   :automatic_run,
                   :mask_selectors, :driver_adapter,
+                  :preview_checker_setup,
                   :logger
 
     DEFAULT_THREADS = 4
@@ -31,6 +32,7 @@ module LookbookVisualTester
       @automatic_run = ENV.fetch('LOOKBOOK_AUTOMATIC_RUN', false)
       @mask_selectors = []
       @driver_adapter = :ferrum
+      @preview_checker_setup = nil
       @logger = if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
                   Rails.logger
                 else

data/lib/lookbook_visual_tester/preview_checker.rb

@@ -0,0 +1,260 @@
+require 'concurrent'
+require 'benchmark'
+
+module LookbookVisualTester
+  class PreviewChecker
+    CheckResult = Struct.new(:preview_name, :example_name, :status, :error, :backtrace, :duration,
+                             keyword_init: true)
+    MissingResult = Struct.new(:component_path, keyword_init: true)
+
+    def initialize(config = LookbookVisualTester.config)
+      @config = config
+    end
+
+    def check
+      run_checks(:basic_check)
+    end
+
+    def deep_check
+      # Ensure custom setup is run before deep checks
+      run_setup
+      run_checks(:deep_render_check)
+    end
+
+    def missing
+      components_dir = Rails.root.join(@config.components_folder)
+      # Assuming standard structure: test/components/previews for previews
+      # But Lookbook can be configured differently. We should use Lookbook's config if possible to know where previews are.
+      # For now, let's stick to the user's script logic which assumes standard paths or iterate through loaded components.
+
+      # Better approach: Iterate through all known components and check if they have a preview.
+      # However, "all known components" might be hard to get if they aren't loaded.
+      # Let's use the file system approach as in the user script.
+
+      components = Dir.glob(File.join(components_dir, '**', '*_component.rb'))
+      previews_dir = Rails.root.join('test/components/previews') # Default, maybe make configurable?
+
+      # Trying to find where previews are located from Rails config if possible
+      if defined?(Rails) && Rails.application.config.view_component.preview_paths.any?
+        # Use simple heuristic: first path
+        previews_dir = Pathname.new(Rails.application.config.view_component.preview_paths.first)
+      end
+
+      missing = []
+      components.each do |component_path|
+        next if component_path.end_with?('application_component.rb')
+        next if component_path.include?('/concerns/')
+
+        relative_path = Pathname.new(component_path).relative_path_from(components_dir).to_s
+        preview_relative_path = relative_path.sub('_component.rb', '_component_preview.rb')
+        preview_path = File.join(previews_dir, preview_relative_path)
+
+        missing << MissingResult.new(component_path: relative_path) unless File.exist?(preview_path)
+      end
+      missing
+    end
+
+    private
+
+    def run_checks(check_method)
+      previews = Lookbook.previews
+      results = []
+
+      # We want to flatten the work items: (PreviewClass, example_name)
+      work_items = []
+      previews.each do |preview|
+        # preview is a Lookbook::Preview object which wraps the class
+        # But for checking we might want the class directly or iterate scenarios
+        examples = preview.scenarios
+        examples.each do |example|
+          work_items << { preview: preview, example: example }
+        end
+      end
+
+      if @config.threads > 1
+        pool = Concurrent::FixedThreadPool.new(@config.threads)
+        promises = work_items.map do |item|
+          Concurrent::Promises.future_on(pool) do
+            measure_and_send(item[:preview], item[:example], check_method)
+          end
+        end
+        results = Concurrent::Promises.zip(*promises).value
+        pool.shutdown
+        pool.wait_for_termination
+      else
+        results = work_items.map do |item|
+          measure_and_send(item[:preview], item[:example], check_method)
+        end
+      end
+
+      results
+    end
+
+    def measure_and_send(preview, example, method_name)
+      result = nil
+      time = Benchmark.realtime do
+        result = send(method_name, preview, example)
+      end
+      result.duration = time
+      result
+    end
+
+    def basic_check(preview, example)
+      # user script logic:
+      # preview_instance = preview_class.new
+      # component = preview_instance.public_send(preview_example)
+      # if component.respond_to?(:render_in) ...
+
+      # Lookbook::Preview wrapper might help, but let's go to the class
+      preview_class = preview.preview_class
+      example_name = example.name
+
+      begin
+        preview_instance = preview_class.new
+        preview_instance.public_send(example_name)
+
+        # We don't render, just verify we can call it.
+        CheckResult.new(preview_name: preview.name, example_name: example_name, status: :passed)
+      rescue StandardError => e
+        CheckResult.new(preview_name: preview.name, example_name: example_name, status: :failed,
+                        error: e.message, backtrace: e.backtrace)
+      end
+    end
+
+    def deep_render_check(preview, example)
+      preview_class = preview.preview_class
+      example_name = example.name
+
+      begin
+        preview_instance = preview_class.new
+        result = preview_instance.public_send(example_name)
+
+        if result.respond_to?(:render_in)
+          # Mock current_user/pundit if needed on the component itself if possible
+          # But mainly we render it with a view context
+          view_context = setup_view_context
+
+          # Inject mocks into result if it supports it or reliance on global view_context
+          # The user script defines singleton methods on the result.
+          if @mocks
+            @mocks.each do |key, value|
+              if result.respond_to?(key) || !result.respond_to?(key) # Force define
+                result.define_singleton_method(key) { value }
+              end
+            end
+          end
+
+          result.render_in(view_context)
+        elsif result.is_a?(String)
+          # Rendered string, good.
+        end
+
+        CheckResult.new(preview_name: preview.name, example_name: example_name, status: :passed)
+      rescue StandardError => e
+        CheckResult.new(preview_name: preview.name, example_name: example_name, status: :failed,
+                        error: e.message, backtrace: e.backtrace)
+      end
+    end
+
+    def run_setup
+      if @config.preview_checker_setup
+        @config.preview_checker_setup.call
+      else
+        default_setup
+      end
+    end
+
+    def default_setup
+      # Logic from the user's script
+      # We need to set up a controller and view context globally or for use in checks
+
+      # This part is tricky because we need to make these available to the `deep_render_check` method.
+      # We can store the view_context in an instance variable or re-create it.
+
+      # Let's perform the class-level mocks here (User, etc.)
+
+      # Mock User
+      unless defined?(User)
+        # Defining a dummy user if not exists is risky if the app doesn't have User.
+        # But the script assumes User exists or creates a mock.
+        # Let's create a OpenStruct-like mock for typical Devise/Pundit usage.
+      end
+
+      # The script logic:
+      # controller = ApplicationController.new ...
+      # We will do this in `setup_view_context` called per check or once?
+      # `ApplicationController` might not be thread safe if we modify it?
+      # Actually we create a new controller instance.
+
+      # Define @mocks to be injected
+      @mocks = {}
+      @mocks[:current_user] = build_mock_user
+      @mocks[:pundit_user] = @mocks[:current_user]
+    end
+
+    def build_mock_user
+      # Try to load a real user or build a struct
+      if defined?(User) && User.respond_to?(:first) && User.first
+        User.first
+      else
+        # Fallback mock
+        u = Object.new
+        u.define_singleton_method(:email) { 'test@example.com' }
+        u.define_singleton_method(:id) { 1 }
+        # Add other common methods as needed or let them fail/mock dynamic
+        u
+      end
+    end
+
+    def setup_view_context
+      # We need a controller to get a view context
+      controller = if defined?(ApplicationController)
+                     ApplicationController.new
+                   else
+                     ActionController::Base.new
+                   end
+
+      controller.request = ActionDispatch::TestRequest.create
+      if controller.request.env
+        controller.request.env['rack.session'] = {}
+        controller.request.env['rack.session.options'] = { id: SecureRandom.uuid }
+      end
+
+      # Devise mapping
+      if defined?(Devise)
+        controller.request.env['devise.mapping'] = Devise.mappings[:user] if Devise.mappings[:user]
+
+        # Mock warden
+        warden = Object.new
+        warden.define_singleton_method(:authenticate!) { |*| true }
+        warden.define_singleton_method(:authenticate) { |*| true }
+        warden.define_singleton_method(:user) { |*| @mocks[:current_user] }
+        controller.request.env['warden'] = warden
+      end
+
+      view_context = controller.view_context
+
+      # Add helper methods to view_context
+      # We can use `class_eval` on the singleton class of the view context
+      vc_singleton = view_context.singleton_class
+
+      if @mocks
+        @mocks.each do |key, value|
+          vc_singleton.send(:define_method, key) { value }
+        end
+      end
+
+      # Common auth helpers
+      vc_singleton.send(:define_method, :signed_in?) { true }
+
+      # Pundit policy mock
+      vc_singleton.send(:define_method, :policy) do |_record|
+        Struct.new(:show?, :index?, :create?, :update?, :destroy?, :edit?, :new?, :manage?).new(
+          true, true, true, true, true, true, true, true
+        )
+      end
+
+      view_context
+    end
+  end
+end

data/lib/lookbook_visual_tester/railtie.rb

@@ -6,7 +6,8 @@ require 'lookbook_visual_tester/update_previews'
 module LookbookVisualTester
   class Railtie < ::Rails::Railtie
     rake_tasks do
-      load 'tasks/lookbook_visual_tester.rake'
+      path = File.expand_path('../tasks/lookbook_visual_tester.rake', __dir__)
+      load path
     end
 
     initializer 'LookbookVisualTester.lookbook_after_change' do |_app|

data/lib/lookbook_visual_tester/runner.rb

@@ -1,8 +1,10 @@
 require 'lookbook'
+require 'json'
 require_relative 'configuration'
 require_relative 'scenario_run'
 require_relative 'services/image_comparator'
 require_relative 'drivers/ferrum_driver'
+require_relative 'variant_resolver'
 
 module LookbookVisualTester
   class Runner
@@ -15,6 +17,7 @@ module LookbookVisualTester
       @driver_pool = Queue.new
       init_driver_pool
       @results = []
+      @variants = load_variants
     end
 
     def run
@@ -28,11 +31,21 @@ module LookbookVisualTester
       end
 
       puts "Found #{previews.count} previews matching '#{@pattern}'."
+      puts "Running against #{@variants.size} variant(s)."
 
-      if @config.threads > 1
-        run_concurrently(previews)
-      else
-        run_sequentially(previews)
+      @variants.each do |variant_input|
+        resolver = VariantResolver.new(variant_input)
+        variant_options = resolver.resolve
+        variant_slug = resolver.slug
+        width = resolver.width_in_pixels
+
+        puts "  Variant: #{variant_slug.presence || 'Default'}"
+
+        if @config.threads > 1
+          run_concurrently(previews, variant_slug, variant_options, width)
+        else
+          run_sequentially(previews, variant_slug, variant_options, width)
+        end
       end
 
       @results
@@ -42,13 +55,25 @@ module LookbookVisualTester
 
     private
 
-    def run_sequentially(previews)
+    def load_variants
+      variants_json = ENV['VARIANTS'] || ENV.fetch('LOOKBOOK_VARIANTS', nil)
+      return [{}] if variants_json.blank?
+
+      begin
+        JSON.parse(variants_json)
+      rescue JSON::ParserError
+        puts 'Invalid JSON in VARIANTS env var. Defaulting to standard run.'
+        [{}]
+      end
+    end
+
+    def run_sequentially(previews, variant_slug, variant_options, width)
       previews.each do |preview|
         group = preview.respond_to?(:scenarios) ? preview.scenarios : preview.examples
         group.each do |scenario|
           driver = checkout_driver
           begin
-            @results << run_scenario(scenario, driver)
+            @results << run_scenario(scenario, driver, variant_slug, variant_options, width)
           ensure
             return_driver(driver)
           end
@@ -56,7 +81,7 @@ module LookbookVisualTester
       end
     end
 
-    def run_concurrently(previews)
+    def run_concurrently(previews, variant_slug, variant_options, width)
       require 'concurrent-ruby'
       pool = Concurrent::FixedThreadPool.new(@config.threads)
       promises = []
@@ -67,7 +92,7 @@ module LookbookVisualTester
           promises << Concurrent::Promises.future_on(pool) do
             driver = checkout_driver
             begin
-              run_scenario(scenario, driver)
+              run_scenario(scenario, driver, variant_slug, variant_options, width)
             ensure
               return_driver(driver)
             end
@@ -75,19 +100,14 @@ module LookbookVisualTester
         end
       end
 
-      @results = Concurrent::Promises.zip(*promises).value
+      # Zip results from this concurrent batch into results
+      # Note: This aggregates results per variant loop.
+      @results.concat(Concurrent::Promises.zip(*promises).value)
       pool.shutdown
       pool.wait_for_termination
     end
 
     def init_driver_pool
-      # Create N drivers where N = threads
-      # If sequential, we only need 1, but we can just simplify and create as many as updated threads config says
-      # Or just 1 if not concurrent?
-      # Actually, let's just stick to @config.threads.
-      # Even for sequential run, if threads was configured to 4, we might create 4 but only use 1.
-      # Optimization: if sequential, only create 1.
-
       count = @config.threads > 1 ? @config.threads : 1
       count.times do
         @driver_pool << LookbookVisualTester::Drivers::FerrumDriver.new(@config)
@@ -109,20 +129,32 @@ module LookbookVisualTester
       end
     end
 
-    def run_scenario(scenario, driver)
-      run_data = ScenarioRun.new(scenario)
-      puts "Running visual test for: #{run_data.name}"
+    def run_scenario(scenario, driver, variant_slug, variant_options, width)
+      run_data = ScenarioRun.new(scenario, variant_slug: variant_slug,
+                                           display_params: variant_options)
+      puts "Running visual test for: #{run_data.name} #{variant_slug.present? ? "[#{variant_slug}]" : ''}"
 
       begin
-        driver.resize_window(1280, 800) # Default or config
+        driver_width = width || 1280
+        driver.resize_window(driver_width, 800)
         driver.visit(run_data.preview_url)
 
         # 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
 
         FileUtils.mkdir_p(File.dirname(current_path))
+        FileUtils.mkdir_p(File.dirname(diff_path))
 
         driver.save_screenshot(current_path.to_s)
 

data/lib/lookbook_visual_tester/scenario_run.rb

@@ -2,13 +2,15 @@ require 'lookbook_visual_tester/configuration'
 
 module LookbookVisualTester
   class ScenarioRun
-    attr_reader :scenario, :preview
+    attr_reader :scenario, :preview, :variant_slug, :display_params
 
-    def initialize(scenario)
+    def initialize(scenario, variant_slug: nil, display_params: {})
       @scenario = scenario
       @preview = scenario.preview
+      @variant_slug = variant_slug
+      @display_params = display_params
 
-      LookbookVisualTester.config.logger.info "  Scenario: #{scenario_name}"
+      LookbookVisualTester.config.logger.info "  Scenario: #{scenario_name} #{variant_suffix}"
     end
 
     def preview_name
@@ -39,18 +41,34 @@ module LookbookVisualTester
     end
 
     def current_path
-      LookbookVisualTester.config.current_dir.join(filename)
+      base = LookbookVisualTester.config.current_dir
+      base = base.join(variant_slug) if variant_slug.present?
+      base.join(filename)
     end
 
     def baseline_path
-      LookbookVisualTester.config.baseline_dir.join(filename)
+      base = LookbookVisualTester.config.baseline_dir
+      base = base.join(variant_slug) if variant_slug.present?
+      base.join(filename)
     end
 
     def preview_url
+      params = { path: preview.lookup_path + '/' + scenario.name }
+
+      if display_params.any?
+        # Transform display_params { theme: 'dark' } -> { _display: { theme: 'dark' } }
+        params[:_display] = display_params
+      end
+
       Lookbook::Engine.routes.url_helpers.lookbook_preview_url(
-        path: preview.lookup_path + '/' + scenario.name,
-        host: LookbookVisualTester.config.lookbook_host
+        params.merge(host: LookbookVisualTester.config.lookbook_host)
       )
     end
+
+    private
+
+    def variant_suffix
+      variant_slug.present? ? "[#{variant_slug}]" : ''
+    end
   end
 end

data/lib/lookbook_visual_tester/templates/preview_check_report.html.tt

@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Preview Check Report</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; padding: 20px; color: #333; }
+    .summary { margin-bottom: 20px; padding: 15px; background: #f5f5f5; border-radius: 8px; }
+    .passed { color: green; }
+    .failed { color: red; }
+    table { width: 100%; border-collapse: collapse; margin-top: 20px; }
+    th, td { text-align: left; padding: 10px; border-bottom: 1px solid #ddd; }
+    th { background: #f0f0f0; }
+    tr.error { background: #fff0f0; }
+    .backtrace { font-family: monospace; font-size: 0.9em; white-space: pre-wrap; color: #666; }
+  </style>
+</head>
+<body>
+  <h1>Preview Check Report</h1>
+  
+  <div class="summary">
+    <p><strong>Total Checks:</strong> <%= results.size %></p>
+    <p><strong>Passed:</strong> <span class="passed"><%= success_count %></span></p>
+    <p><strong>Failed:</strong> <span class="failed"><%= errors.size %></span></p>
+    <p><strong>Total Duration:</strong> <%= total_duration.round(2) %>s</p>
+  </div>
+
+  <h2>Top 5 Slowest Previews</h2>
+  <ul>
+    <% results.sort_by { |r| -r.duration.to_f }.first(5).each do |res| %>
+      <li><strong><%= res.duration.to_f.round(4) %>s</strong> - <%= res.preview_name %>#<%= res.example_name %></li>
+    <% end %>
+  </ul>
+
+  <h2>Detailed Results</h2>
+  <table>
+    <thead>
+      <tr>
+        <th>Status</th>
+        <th>Preview</th>
+        <th>Example</th>
+        <th>Time (s)</th>
+        <th>Error</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% results.sort_by { |r| r.status == :failed ? 0 : 1 }.each do |result| %>
+        <tr class="<%= 'error' if result.status == :failed %>">
+          <td class="<%= result.status %>"><%= result.status.to_s.upcase %></td>
+          <td><%= result.preview_name %></td>
+          <td><%= result.example_name %></td>
+          <td><%= result.duration.to_f.round(4) %></td>
+          <td>
+            <% if result.error %>
+              <div><strong><%= result.error %></strong></div>
+              <div class="backtrace"><%= result.backtrace&.first(5)&.join("\n") %></div>
+            <% end %>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</body>
+</html>

data/lib/lookbook_visual_tester/variant_resolver.rb

@@ -0,0 +1,62 @@
+module LookbookVisualTester
+  class VariantResolver
+    attr_reader :input_variant
+
+    def initialize(input_variant)
+      @input_variant = input_variant || {}
+    end
+
+    def resolve
+      resolved = {}
+      @input_variant.each do |key, label|
+        resolved[key.to_sym] = resolve_value(key, label)
+      end
+      resolved
+    end
+
+    def slug
+      return '' if @input_variant.empty?
+
+      @input_variant.sort_by { |k, _v| k.to_s }.map do |key, label|
+        "#{key}-#{sanitize(label)}"
+      end.join('_')
+    end
+
+    def width_in_pixels
+      resolved_width = resolve[:width]
+      return nil unless resolved_width
+
+      if resolved_width.to_s.end_with?('px')
+        resolved_width.to_i
+      else
+        nil # Ignore percentages or other units for resizing
+      end
+    end
+
+    private
+
+    def resolve_value(key, label)
+      options = Lookbook.config.preview_display_options[key.to_sym]
+      return label unless options
+
+      # Options can be an array of strings or array of [label, value] arrays
+      found = options.find do |option|
+        if option.is_a?(Array)
+          option[0] == label
+        else
+          option == label
+        end
+      end
+
+      if found
+        found.is_a?(Array) ? found[1] : found
+      else
+        label
+      end
+    end
+
+    def sanitize(value)
+      value.to_s.gsub(/[^a-zA-Z0-9]/, '_').squeeze('_').gsub(/^_|_$/, '')
+    end
+  end
+end

data/lib/lookbook_visual_tester/version.rb

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

data/lib/tasks/lookbook_visual_tester.rake

@@ -3,6 +3,35 @@ require 'lookbook_visual_tester/runner'
 require 'lookbook_visual_tester/report_generator'
 require 'lookbook_visual_tester/json_output_handler'
 
+require 'lookbook_visual_tester/preview_checker'
+require 'lookbook_visual_tester/check_reporter'
+
+namespace :lookbook do
+  desc 'Check previews for load/syntax errors'
+  task check: :environment do
+    puts 'Checking previews...'
+    checker = LookbookVisualTester::PreviewChecker.new
+    results = checker.check
+    LookbookVisualTester::CheckReporter.start([results])
+  end
+
+  desc 'Deep check previews by rendering them'
+  task deep_check: :environment do
+    puts 'Deep checking previews (render)...'
+    checker = LookbookVisualTester::PreviewChecker.new
+    results = checker.deep_check
+    LookbookVisualTester::CheckReporter.start([results])
+  end
+
+  desc 'Find components missing previews'
+  task missing: :environment do
+    puts 'Finding missing previews...'
+    checker = LookbookVisualTester::PreviewChecker.new
+    missing = checker.missing
+    LookbookVisualTester::CheckReporter.report_missing(missing)
+  end
+end
+
 namespace :lookbook do
   desc 'List all available previews'
   task :list, [:format] => :environment do |_, args|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lookbook_visual_tester
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Murilo Vasconcelos
@@ -79,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  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: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -155,11 +169,13 @@ files:
 - lib/lookbook_visual_tester.rb
 - lib/lookbook_visual_tester/baseline_manager.rb
 - lib/lookbook_visual_tester/capybara_setup.rb
+- lib/lookbook_visual_tester/check_reporter.rb
 - lib/lookbook_visual_tester/configuration.rb
 - lib/lookbook_visual_tester/driver.rb
 - lib/lookbook_visual_tester/drivers/ferrum_driver.rb
 - lib/lookbook_visual_tester/image_comparator.rb
 - lib/lookbook_visual_tester/json_output_handler.rb
+- lib/lookbook_visual_tester/preview_checker.rb
 - lib/lookbook_visual_tester/railtie.rb
 - lib/lookbook_visual_tester/report_generator.rb
 - lib/lookbook_visual_tester/runner.rb
@@ -170,8 +186,10 @@ files:
 - lib/lookbook_visual_tester/services/image_comparator.rb
 - lib/lookbook_visual_tester/session_manager.rb
 - lib/lookbook_visual_tester/store.rb
+- lib/lookbook_visual_tester/templates/preview_check_report.html.tt
 - lib/lookbook_visual_tester/templates/report.html.erb
 - lib/lookbook_visual_tester/update_previews.rb
+- lib/lookbook_visual_tester/variant_resolver.rb
 - lib/lookbook_visual_tester/version.rb
 - lib/tasks/lookbook_visual_tester.rake
 - sig/lookbook_visual_tester.rbs