lookbook_visual_tester 0.1.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a29c54b1403f4faeaea71ef267faf9aba07d033c3c0bfc79617c0bf0cf77a490
-  data.tar.gz: 2d8cb90e20f1ad2dd92ca6c677bb4e8185c62a16b0b070721551e789575de219
+  metadata.gz: d40b1ba348d95a09c7ea9997d965e00026e9873cf5a8e2faebeed31d6898b6e9
+  data.tar.gz: 725d2b67ae419319e79ac56c52cb74f1d3f5354099fa30e670cf292c2e25b07d
 SHA512:
-  metadata.gz: 8328f592622c337d11dca1c10811834e85f0a00cecc92eeb6f6a62c04cf2e1df50e9eed9700ac1b11041e39373710c371454c19d71db0b17c95b2790a67ebaeb
-  data.tar.gz: 3dba60c0c0d2867b185e45c53d68569b29e87c4ac57bf649767aa6c17ada5405d1cf0f493c6b96d75a1755405c70d050b165a72fe58a9f39648609ea703adecb
+  metadata.gz: 1c8fac94fb8e61906506b8dd48f87d9b6bb9cb01ec238a2b805a4f98ceadde02cf8555b45c80f1daef4b1710392b0fcd05a36f7420fe279440cd2491d3f63ad2
+  data.tar.gz: 3025ca8c334a4185dcbcdc8d2c03288fb46bb07c582d8a2c363cc69929a6be2044246c1d7bc313f06787970e49541872bee57e18cf6b800f8a1afb41b5375aec

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.2.1
+3.4.7

data/CHANGELOG.md

@@ -1,10 +1,32 @@
 # Changelog
 
-Here is the changelog for version **0.1.5** of *LookbookVisualTester*:
+## [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
+
+### Better search
+
+- better search logic, add components_folder config
 
-# Changelog
 
 ## [0.1.5] - 2025-02-26
 

data/README.md

@@ -2,70 +2,134 @@
 
 # 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
+```
 
-Install the gem and add to the application's Gemfile by executing:
+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
+
+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
+### Baseline Management
 
-To run everything 
-bundle exec rake lookbook_visual_tester:run LOOKBOOK_HOST=https://localhost:5000
+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.
 
-### Features 
+### Reporting
 
-When installed this gem gets your changes and generates 
+After running `rake lookbook:test`, a detailed HTML report is generated at:
+`coverage/visual_report.html`
 
-## Development
+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.
 
-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.
 
-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).
+### Human-Readable Diffs
 
-## Contributing
+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.
+
+## 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
+```
 
-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).
+## 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.
 
-## Deployment 
+## 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

@@ -10,3 +10,15 @@ require 'rubocop/rake_task'
 RuboCop::RakeTask.new
 
 task default: %i[test 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/configuration.rb

@@ -1,8 +1,13 @@
 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
+                  :history_keep_last_n, :threads, :copy_to_clipboard,
+                  :components_folder,
+                  :automatic_run,
+                  :mask_selectors, :driver_adapter,
+                  :logger
 
     DEFAULT_THREADS = 4
 
@@ -19,11 +24,29 @@ 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
+      @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

data/lib/lookbook_visual_tester/railtie.rb

@@ -1,6 +1,6 @@
 # lib/lookbook_visual_tester/railtie.rb
 
-require 'lookbook_visual_tester/capybara_setup'
+# require 'lookbook_visual_tester/capybara_setup'
 require 'lookbook_visual_tester/update_previews'
 
 module LookbookVisualTester
@@ -12,6 +12,8 @@ module LookbookVisualTester
     initializer 'LookbookVisualTester.lookbook_after_change' do |_app|
       Rails.logger.info "LookbookVisualTester initialized with host: #{LookbookVisualTester.config.lookbook_host}"
       Lookbook.after_change do |app, changes|
+        next unless LookbookVisualTester.config.automatic_run
+
         # get hash of content of modified files to see if has changed
         modified = changes[:modified]
         my_hash = modified.sort.map { |f| File.read(f) }.hash

data/lib/lookbook_visual_tester/report_generator.rb

@@ -1,57 +1,34 @@
+require 'erb'
+require 'fileutils'
+
 module LookbookVisualTester
   class ReportGenerator
-    attr_reader :report_path, :baseline_dir, :current_dir, :diff_dir, :base_path
-
-    def initialize
-      @baseline_dir, @current_dir, @diff_dir, @base_path = LookbookVisualTester.config.then do |config|
-        [config.baseline_dir, config.current_dir, config.diff_dir, config.base_path]
-      end
-
-      @report_path = base_path.join('report.html')
+    TEMPLATE_PATH = File.expand_path("../templates/report.html.erb", __FILE__)
+    OUTPUT_PATH = "coverage/visual_report.html"
+
+    def initialize(results)
+      @results = results
+      @stats = {
+        total: results.size,
+        failed: results.count { |r| r.status == :failed },
+        new: results.count { |r| r.status == :new },
+        passed: results.count { |r| r.status == :passed }
+      }
     end
 
-    def generate
-      File.open(report_path, 'w') do |file|
-        file.puts '<!DOCTYPE html>'
-        file.puts "<html lang='en'>"
-        file.puts "<head><meta charset='UTF-8'><title>Visual Regression Report</title></head>"
-        file.puts '<body>'
-        file.puts '<h1>Visual Regression Report</h1>'
-        file.puts '<ul>'
-
-        diff_files = Dir.glob(diff_dir.join('*_diff.png'))
-        diff_files.each do |diff_file|
-          filename = File.basename(diff_file)
-          # Extract preview and scenario names
-          preview_scenario = filename.sub('_diff.png', '')
-          preview, scenario = preview_scenario.split('_', 2)
-
-          baseline_image = baseline_dir.join("#{preview}_#{scenario}.png")
-          current_image = current_dir.join("#{preview}_#{scenario}.png")
+    def call
+      template = File.read(TEMPLATE_PATH)
+      renderer = ERB.new(template)
+      html = renderer.result(binding)
 
-          file.puts '<li>'
-          file.puts "<h2>#{preview.titleize} - #{scenario.titleize}</h2>"
-          file.puts "<div style='display: flex; gap: 10px;'>"
-
-          baseline_image_path = Pathname.new(baseline_image)
-          current_image_path = Pathname.new(current_image)
-          diff_file_path = Pathname.new(diff_file)
-
-          file.puts "<div><h3>Baseline</h3><img src='#{baseline_image_path.relative_path_from(base_path)}' alt='Baseline'></div>"
-          file.puts "<div><h3>Current</h3><img src='#{current_image_path.relative_path_from(base_path)}' alt='Current'></div>"
-          file.puts "<div><h3>Diff</h3><img src='#{diff_file_path.relative_path_from(base_path)}' alt='Diff'></div>"
-          file.puts '</div>'
-          file.puts '</li>'
-        end
-
-        file.puts '<li>No differences found!</li>' if diff_files.empty?
-
-        file.puts '</ul>'
-        file.puts '</body>'
-        file.puts '</html>'
-      end
+      FileUtils.mkdir_p("coverage")
+      File.write(OUTPUT_PATH, html)
+      puts "📊 Report generated at: #{OUTPUT_PATH}"
+    end
 
-      @report_path
+    # Helper to generate the terminal command for the user
+    def approve_command(result)
+      "cp \"#{result.current_path}\" \"#{result.baseline_path}\""
     end
   end
 end