lookbook_visual_tester 0.1.6 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18c7c1416411fad57a1b3aea4b748cc2d861f24f84d9187e81de98352741e620
-  data.tar.gz: 46ea4cf22145443a9edff07fa0a4e35673e590d628739a70f2d8c2c96c3cce95
+  metadata.gz: 60819c43209d30cab93b22e923f369c0fdb85ae2f0cbc5780a9670ca26571677
+  data.tar.gz: 231ec3a33592037451d4f8a9354c702971314405b4ab13a6332c911baa915681
 SHA512:
-  metadata.gz: 07c1a331af6c9747215ce41c3a7db6e263b474b95ab1ff6eb49d5672ef63e857bc7d53e710e038032dba5e633eec8eb5ba9034b90de69fd13e85f46cbcdcaa6e
-  data.tar.gz: c3c24f9c64bbf4b872e56636205a3fc27f6dcf1439e6f939f8d5aa1c147594d308befb263ef8f4059712f8b490e1d6fd1bb814ad8138570988302ad4e19ecb9d
+  metadata.gz: 782a83e7388499ededdc31453a708969a839b060e09b24de481f55c48f193397d30c873a8137bbec40e4da0f30688cb4485f66d3e93b07ecb19f9d7dc0517bb4
+  data.tar.gz: 699056dca68df2a0961547c639da77b62bda599dd5a44013e4b7717d6dd8afeb02195b34c447bb66a72fb8ef8a0b35168cce7bc12cffaa4570a4b9629b8dbc21

data/.rubocop.yml

@@ -7,7 +7,6 @@ AllCops:
     - "vendor/**/*"
     - "app/assets/**/*"
     - "db/schema.rb"
-  TargetRubyVersion: 3.2.1
   DisplayCopNames: true
   NewCops: enable
 

data/.ruby-version

@@ -1 +1 @@
-3.4.2
+3.4.7

data/CHANGELOG.md

@@ -1,10 +1,46 @@
 # Changelog
+## [0.5.0] - 2026-01-03
 
-Here is the changelog for version **0.1.5** of *LookbookVisualTester*:
+### ✨ 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
 
-# Changelog
+### ✨ 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
+
+### ✨ New Features & Improvements
+- **Concurrent Screenshot Capture**: Speed up your test suite significantly by running screenshot capture in parallel.
+  - Enabled by default with 4 threads.
+  - Configurable via `LOOKBOOK_THREADS` environment variable or Rails configuration.
+- **Configurable Concurrency**: Added `threads` configuration option.
+
+## [0.2.0] - 2026-01-02
+
+### ✨ New Features & Improvements
+- **Visual Diff Aesthetics**: Unchanged context in diff images now rendered with a light blue tint for better human readability.
+- **Standalone Test Harness**: Integrated a dummy Rails application within `spec/dummy` for self-contained development and testing.
+- **Full-Flow Integration Tests**: Added RSpec integration tests that boot a local server and verify the entire screenshot/comparison pipeline.
+- **Lookbook 2.x Compatibility**: Added robust support for Lookbook 2.x `scenarios` while maintaining compatibility with 1.x `examples`.
+- **Filename Normalization**: Improved screenshot naming to handle nested preview paths and avoid directory conflicts.
+
+### Fixed
+- Fixed Ferrum driver compatibility issue with `traffic_factor` argument in `wait_for_idle`.
+- Fixed various unit tests to correctly mock configuration and scenario run state.
 
 ## [0.1.6] - 2025-03-04
 

data/README.md

@@ -2,70 +2,182 @@
 
 # Lookbook Visual Tester
 
-This gem was built to serve as a lookbook regression tester, getting prints from previews, comparing them and generating a report of differences.
+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.
 
+### Key Features
 
-### Features
-
-- Perform visual regression testing on changes.
-- Integrate seamlessly with your Lookbook previews.
-- Automatically generate image differences.
-- Simplify debugging and quality checks.
-- Very useful for AI coding (e.g. aider, etc.)
+- **Automated Visual Regression**: Captures and compares screenshots of all Lookbook previews.
+- **Intelligent Diffing**: High-quality image comparison using `chunky_png`.
+- **Human-Friendly Aesthetics**: Context is rendered with a light blue tint to make red highlights of differences pop.
+- **Robust Capture**: Automatically disables animations, waits for network idle, and allows masking/cropping.
+- **Lookbook Support**: Compatible with both Lookbook 1.x (`examples`) and 2.x (`scenarios`).
+- **Internal Test Harness**: Includes a dummy Rails app for self-contained testing and development.
 
 ## Installation
 
-Tested on linux. A couple of changes to work on mac, etc. You will need tools like xclip, imagemagick
+### System Dependencies
 
-For Ubuntu-based systems, install the necessary dependencies by running:
+The gem requires `imagemagick` for image processing and `xclip` for clipboard integration (Linux).
 
+For Ubuntu-based systems:
 ```bash
-sudo apt-get install xclip imagemagick
+sudo apt-get install imagemagick xclip
+```
+
+### Gem Installation
+
+Add to your application's Gemfile:
+```ruby
+group :test do
+  gem 'lookbook_visual_tester'
+end
+```
+
+Then install:
+```bash
+bundle install
+```
+
+## Configuration
+
+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.copy_to_clipboard = true                # Enable xclip support
+  config.threads = 4                             # Number of parallel threads (default: 4)
+end
 ```
 
+## Usage
 
+### Running Visual Tests
 
-Install the gem and add to the application's Gemfile by executing:
+The gem provides Rake tasks to execute the visual regression suite.
 
+#### Run All Tests
+Runs all Lookbook previews, generates a terminal summary, and creates an HTML report.
 ```bash
-bundle add lookbook_visual_tester
+bundle exec rake lookbook:test
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+#### Test a Specific Preview
+Filter previews by name or label.
+```bash
+bundle exec rake lookbook:screenshot[Button]
+```
 
+#### Configuration Overrides
+You can override the host or other settings inline:
 ```bash
-gem install lookbook_visual_tester
+LOOKBOOK_HOST=http://localhost:5000 LOOKBOOK_THREADS=8 bundle exec rake lookbook:test
 ```
 
-## Usage
+#### Screenshot Variants
 
-To run everything 
-bundle exec rake lookbook_visual_tester:run LOOKBOOK_HOST=https://localhost:5000
+You can run your visual tests against multiple configurations (variants), such as different themes or viewports, by leveraging Lookbook's `preview_display_options`.
 
-### Features 
+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"]]
+    }
+    ```
 
-When installed this gem gets your changes and generates 
+2.  **Run with Variants**:
+    Use the `VARIANTS` environment variable to define a JSON array of option sets to test.
 
-## Development
+    *Example: Run standard tests + Dark Mode + Mobile View*
+    ```bash
+    VARIANTS='[{}, {"theme":"dark"}, {"width":"Mobile"}]' bundle exec rake lookbook:test
+    ```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+    * **`{}`**: 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.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+    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**.
+2. **Subsequent Runs**: New screenshots are compared against the baselines.
+3. **Mismatches**: If a change is detected, a **Diff** image is generated.
+4. **Approval**: To approve a change (update the baseline), simply copy the file from `current_run` to `baseline`. The HTML report provides a convenient "Copy Approval Command" button for this.
+
+### Reporting
+
+After running `rake lookbook:test`, a detailed HTML report is generated at:
+`coverage/visual_report.html`
+
+The report allows you to:
+- See side-by-side comparisons of Baseline vs. Actual.
+- View the diff highlighting changes in neon red.
+- Quickly copy terminal commands to approve changes.
 
-## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/muriloime/lookbook_visual_tester. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/lookbook_visual_tester/blob/main/CODE_OF_CONDUCT.md).
+### Human-Readable Diffs
 
+When a difference is detected, a diff image is generated where:
+- **Neon Red**: Parts of the component that changed.
+- **Blue Tint**: The unchanged context, making it easy to identify where the change occurred.
 
-## Deployment 
+## Internal Testing (Development)
+
+The project includes an internal dummy Rails application for testing the gem itself.
+
+### Running the Test Suite
+```bash
+bundle exec rspec
+```
+
+### Running the Full Flow Integration Test
+```bash
+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
+
+- **CI/CD Integration**: Provide recipes for GitHub Actions to run visual regression on PRs.
+
+## Contributing
 
-Generate artifacts for changelog : 
+Bug reports and pull requests are welcome on GitHub at https://github.com/muriloime/lookbook_visual_tester.
 
-`git log --pretty=format:"%h %ad | %s [%an]" --date=short --no-merges --name-only | xclip -selection clipboard`
+## Deployment
 
-Update changelog 
-`rake realease`
+To release a new version:
+1. Update the version in `lib/lookbook_visual_tester/version.rb`.
+2. Run `bundle exec rake release`.
 
-## Code of Conduct
+## License
 
-Everyone interacting in the LookbookVisualTester project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/lookbook_visual_tester/blob/main/CODE_OF_CONDUCT.md).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/RELEASING.md

@@ -0,0 +1,31 @@
+# Releasing
+
+This gem uses `bundler/gem_tasks` to manage releases.
+
+## Instructions
+
+1.  Make sure your working directory is clean and you are on the `main` branch.
+2.  Update the version in `lib/lookbook_visual_tester/version.rb`.
+3.  Update the `CHANGELOG.md`.
+4.  Run the release task:
+    ```bash
+    bundle exec rake release:otp
+    ```
+    This will:
+    -   Create a git tag for the version.
+    -   Push git commits and tags.
+    -   Build the gem.
+    -   Push the `.gem` file to RubyGems.org.
+
+## Troubleshooting
+
+If you encounter issues with authentication, ensure you are logged in to RubyGems via the `gem` CLI:
+```bash
+gem signin
+```
+
+If you need to supply a 2FA/OTP code manually or for a script, you can use the `release:otp` task or set the `GEM_HOST_OTP_CODE` environment variable:
+
+```bash
+GEM_HOST_OTP_CODE=123456 bundle exec rake release
+```

data/Rakefile

@@ -1,12 +1,23 @@
 # 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'
+  task :otp do
+    require 'io/console'
+    print 'Enter OTP code: '
+    otp = $stdin.noecho(&:gets).strip
+    puts "\n"
+    ENV['GEM_HOST_OTP_CODE'] = otp
+    Rake::Task['release'].invoke
+  end
+end

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

@@ -1,9 +1,14 @@
 module LookbookVisualTester
   class Configuration
-    attr_accessor :base_path, :lookbook_host,
+    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
+                  :components_folder,
+                  :automatic_run,
+                  :mask_selectors, :driver_adapter,
+                  :preview_checker_setup,
+                  :logger
 
     DEFAULT_THREADS = 4
 
@@ -20,12 +25,30 @@ module LookbookVisualTester
       @current_dir = @base_path.join('current_run')
       @diff_dir = @base_path.join('diff')
       @history_dir = @base_path.join('history')
-      @threads = DEFAULT_THREADS
+      @threads = ENV.fetch('LOOKBOOK_THREADS', DEFAULT_THREADS).to_i
       @history_keep_last_n = 5
       @copy_to_clipboard = true
       @components_folder = 'app/components'
+      @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
+                  require 'logger'
+                  Logger.new($stdout).tap { |l| l.level = Logger::INFO }
+                end
 
-      @lookbook_host = ENV.fetch('LOOKBOOK_HOST', 'https://localhost:5000')
+      @lookbook_host = ENV.fetch('LOOKBOOK_HOST', 'http://localhost:5000')
+    end
+
+    def base_path=(value)
+      @base_path = Pathname.new(value)
+      @baseline_dir = @base_path.join('baseline')
+      @current_dir = @base_path.join('current_run')
+      @diff_dir = @base_path.join('diff')
+      @history_dir = @base_path.join('history')
     end
 
     class << self

data/lib/lookbook_visual_tester/driver.rb

@@ -0,0 +1,51 @@
+module LookbookVisualTester
+  class Driver
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    def visit(url)
+      raise NotImplementedError
+    end
+
+    def resize_window(width, height)
+      raise NotImplementedError
+    end
+
+    def inject_style(css)
+      raise NotImplementedError
+    end
+
+    def run_script(script)
+      raise NotImplementedError
+    end
+
+    def mask_elements(selectors)
+      raise NotImplementedError
+    end
+
+    # Smart wait implementation
+    def wait_for_assets
+      wait_for_fonts
+      wait_for_network_idle
+    end
+
+    def wait_for_fonts
+      raise NotImplementedError
+    end
+
+    def wait_for_network_idle
+      raise NotImplementedError
+    end
+
+    def save_screenshot(path)
+      raise NotImplementedError
+    end
+
+    def cleanup
+      raise NotImplementedError
+    end
+  end
+end

data/lib/lookbook_visual_tester/drivers/ferrum_driver.rb

@@ -0,0 +1,111 @@
+require_relative '../driver'
+require 'ferrum'
+
+module LookbookVisualTester
+  module Drivers
+    class FerrumDriver < Driver
+      def initialize(config)
+        super
+        @browser = Ferrum::Browser.new(
+          headless: true,
+          window_size: [1280, 800], # Default, can be resized
+          timeout: 10 # Configurable?
+        )
+      end
+
+      def visit(url)
+        @browser.go_to(url)
+        prepare_page
+      end
+
+      def resize_window(width, height)
+        @browser.resize(width: width, height: height)
+      end
+
+      def inject_style(css)
+        # Ferrum allows adding style tags via JS
+        script = <<~JS
+          const style = document.createElement('style');
+          style.innerHTML = `#{css}`;
+          document.head.appendChild(style);
+        JS
+        @browser.execute(script)
+      end
+
+      def run_script(script)
+        @browser.execute(script)
+      end
+
+      def mask_elements(selectors)
+        return if selectors.empty?
+
+        selectors.each do |selector|
+          script = <<~JS
+            document.querySelectorAll('#{selector}').forEach(el => {
+              el.style.visibility = 'hidden';
+            });
+          JS
+          @browser.execute(script)
+        end
+      end
+
+      def wait_for_assets
+        wait_for_network_idle
+        wait_for_fonts
+        wait_for_custom_selectors
+      end
+
+      def wait_for_fonts
+        @browser.execute("return document.fonts.ready")
+      end
+
+      def wait_for_network_idle(timeout: 2, duration: 0.5)
+        # Ferrum has built-in network idle waiting
+        @browser.network.wait_for_idle
+      rescue Ferrum::TimeoutError
+        # Log warning but proceed?
+      end
+
+      def save_screenshot(path)
+        @browser.screenshot(path: path, full: true)
+        # 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
+
+      def cleanup
+        @browser.quit
+      end
+
+      private
+
+      def prepare_page
+        disable_animations
+        mask_elements(config.mask_selectors || [])
+        wait_for_assets
+      end
+
+      def disable_animations
+        css = "* { transition: none !important; animation: none !important; caret-color: transparent !important; }"
+        inject_style(css)
+      end
+
+      def wait_for_custom_selectors
+        # If we have specific selectors to wait for e.g. document.fonts.status check loop
+        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
+        end
+      end
+    end
+  end
+end

data/lib/lookbook_visual_tester/json_output_handler.rb

@@ -0,0 +1,9 @@
+require 'json'
+
+module LookbookVisualTester
+  class JsonOutputHandler
+    def self.print(data)
+      puts JSON.pretty_generate(data)
+    end
+  end
+end