Module: SnapDiff::Drivers

Defined in:
lib/snap_diff/drivers.rb,
lib/snap_diff/drivers/vips_driver.rb,
lib/snap_diff/drivers/chunky_png_driver.rb

Overview

Compare two images and determine if they are equal, different, or within some comparison range considering color values and difference area size.

Defined Under Namespace

Classes: ChunkyPNGDriver, VipsDriver

Constant Summary collapse

AVAILABLE_DRIVERS =

Canonical home of the detected-drivers list (3.0 readiness: it used to live only on Capybara::Screenshot::Diff::AVAILABLE_DRIVERS, so require "snap_diff/drivers" alone left .available raising NameError). Detection runs HERE, at this file's load, and the legacy constant is now an eager same-object alias of this one.

detect_available.freeze

Class Method Summary collapse

Class Method Details

.available ⇒ Object

Canonical read API for the list above. Reads the constant live rather than caching, because the constant is the published stubbing point (image_compare_test stubs it to [] to exercise the no-drivers error path).

Detection only exists because there is a choice of backend to detect; 2.1 removes the choice, so it warns. The gem's own callers read AVAILABLE_DRIVERS directly -- same value, same stubbing point, no warning at itself.



106
107
108
109
110
111
112
113
114
 
# File 'lib/snap_diff/drivers.rb', line 106

def self.available
  Removal.warn_once(
    :drivers_available,
    "`SnapDiff::Drivers.available` is REMOVED in 2.1: with libvips the only backend there " \
    "is nothing left to detect. Require the `ruby-vips` gem instead of branching on this " \
    "list. See docs/drivers.md."
  )
  AVAILABLE_DRIVERS
end

.detect_available ⇒ Object

Which image drivers this process can actually load, in preference order. Tries the gem first and falls back to require, cleaning up the half-defined constant a failed native load leaves behind.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/snap_diff/drivers.rb', line 57

def self.detect_available
  result = []
  begin
    result << :vips if defined?(Vips) || require("vips")
  rescue LoadError
    # vips not present
    Object.send(:remove_const, :Vips) if defined?(Vips)
  end
  begin
    result << :chunky_png if defined?(ChunkyPNG) || require("chunky_png")
  rescue LoadError
    # chunky_png not present
    Object.send(:remove_const, :ChunkyPNG) if defined?(ChunkyPNG)
  end
  result
end

.for(driver_options = {}) ⇒ Object 



17
18
19
20
21
22
 
# File 'lib/snap_diff/drivers.rb', line 17

def self.for(driver_options = {})
  driver_option = driver_options.is_a?(Hash) ? driver_options.fetch(:driver, :chunky_png) : driver_options
  return driver_option unless driver_option.is_a?(Symbol)

  Utils.find_driver_class_for(driver_option).new
end

.loaded ⇒ Object

Canonical driver-class cache (ADR-008 step 5b, ex Capybara::Screenshot::Diff::LOADED_DRIVERS): driver name => driver class. Mutated in place -- including by user registration through the legacy constant, which legacy_shims pins as an EAGER same-object alias of this hash (a lazy copy would silently drop such registrations).

THE documented custom-driver registration point (docs/snapdiff.md), so a custom-driver author has to hear that 2.1 takes it away.



43
44
45
46
47
48
49
50
51
52
 
# File 'lib/snap_diff/drivers.rb', line 43

def self.loaded
  Removal.warn_once(
    :drivers_loaded,
    "`SnapDiff::Drivers.loaded` is REMOVED in 2.1 together with the rest of the driver " \
    "abstraction (`SnapDiff::Driver`, `SnapDiff::Drivers.available`, `driver: :auto`): " \
    "libvips becomes the only backend and custom drivers are no longer supported. " \
    "See docs/drivers.md."
  )
  registry
end

.registry ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The registry itself, unannounced: driver name => driver class, filled lazily by Utils.find_driver_class_for and mutated in place. The gem's own reads go through HERE rather than through .loaded, so the removal warning below stays a signal about USER code -- a gem that warns at itself teaches people to ignore its warnings.



31
32
33
 
# File 'lib/snap_diff/drivers.rb', line 31

def self.registry
  @registry ||= {}
end