looks_good 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 33bfb614a176498eb6a13180459e40aff96fc328673ab0edd6cbcb2b4b28345f
+  data.tar.gz: 97b7efc3432c0b51b052bad9201e87a900791e57afdc9d2d9ef6444d654891bf
+SHA512:
+  metadata.gz: 629f66d456631f91b36200dd03266c2de827dd6313ded03a49c01f0021b303f93b98f8c9f5525e831ba9412412ed908800fd831fc89282c16c155804ae8d0b79
+  data.tar.gz: 63c9fc8f12c8e25f4230e39298ab623b7b85e5b491679ae0a9c59f4bf6da9122cf1991a750df8376d81e482c8bb3063a7fce8f22b3812ee3fd97e83c3dcd97d7

data/.gitignore

@@ -0,0 +1,18 @@
+*.png
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*.orig
+test*
+.idea*
+.DS_Store
+spec/support/ready_candidate_ref/temp/*
+reports/*
+vendor/*
+/.rbenv*
+.rakeTasks
+*.iml
+*.ipr
+*.iws
+/bin

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,61 @@
+PATH
+  remote: .
+  specs:
+    looks_good (1.0.0)
+      capybara (>= 2.6.0)
+      rmagick (>= 2.15.4)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.8.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    capybara (3.35.3)
+      addressable
+      mini_mime (>= 0.1.3)
+      nokogiri (~> 1.8)
+      rack (>= 1.6.0)
+      rack-test (>= 0.6.3)
+      regexp_parser (>= 1.5, < 3.0)
+      xpath (~> 3.2)
+    childprocess (0.9.0)
+      ffi (~> 1.0, >= 1.0.11)
+    coderay (1.1.3)
+    ffi (1.15.5)
+    method_source (1.0.0)
+    mini_mime (1.1.2)
+    mini_portile2 (2.6.1)
+    nokogiri (1.12.5)
+      mini_portile2 (~> 2.6.1)
+      racc (~> 1.4)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    public_suffix (4.0.7)
+    racc (1.6.0)
+    rack (2.2.4)
+    rack-test (2.0.2)
+      rack (>= 1.3)
+    rake (0.9.2)
+    regexp_parser (2.5.0)
+    rmagick (4.2.6)
+    rubyzip (1.3.0)
+    selenium-webdriver (2.53.4)
+      childprocess (~> 0.5)
+      rubyzip (~> 1.0)
+      websocket (~> 1.0)
+    websocket (1.2.9)
+    xpath (3.2.0)
+      nokogiri (~> 1.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  looks_good!
+  pry (>= 0.10.2)
+  rake (>= 0.9.2)
+  selenium-webdriver (~> 2.53.0)
+
+BUNDLED WITH
+   2.2.5

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Gabriel Rotbart, Amanda Koh
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,123 @@
+# LooksGood
+
+A visual RSpec matcher to ensure the entire page (or specific elements) have not changed. Allows for a tolerance to be set, so you can reuire pixel-perfect or allow for some minor changes. 
+
+-------------------------------------
+
+## Installation:
+
+        gem install looks_good
+
+In rails_helper.rb:
+
+        require 'looks_good'
+        require 'looks_good/matchers/look_like_matcher'
+
+add to your `.gitignore`
+
+        spec/screenshots/tmp/*
+
+### Usage:
+
+Identify an element to match, for example:
+
+        @element = page.find(:css, 'main')
+
+Use LooksGood's custom matcher and specify the reference image:
+        
+        expect(@element).to look_like(:main_section)
+
+LooksGood will take care of cropping the element and try and make a targeted match without the noise of the whole page. 
+The parameter passed to `look_like` is the name that will be used to store the initial screenshot, and will be used in subsequent comparisons. 
+
+`look_like` can also handle the file naming and storage, if you specify a symbol. If the above example is from the spec `system/frontend/login_spec.rb`, then the screenshot will be stored in `spec/screenshots/system/frontend/login/main_section.png`. 
+
+You can ovveride this automatic behavior by specifying the file path as a string. 
+
+        expect(@element).to look_like("frontend/main-screen.png")
+
+which would store the screenshot in `spec/screenshots/frontend/main-screen.png`
+
+If you want to adjust how tolerant the matcher is of differences, specify a float between 0 and 1 to `within`
+
+        expect(@element).to look_like(:main_content, within: 0.05)
+
+If no reference image exits, the test will pass and a reference file will be created for future comparisons.
+
+If you encounter a failure for a desired change, a diff image will be created to visualze the differences as well as a reference to the new version. 
+you can either copy the file provided in the error, or run your test suite again with `LOOKS_GOOD=true` to update it to the new version. 
+
+
+-------------------------------------
+
+### Configuration settings:
+
+you can override any of the defaults with a config block. 
+
+#### Configuration settings are set with the following:
+
+          LooksGood.config do |c|
+            c.reference_image_path = 'spec/screenshots'
+            c.max_no_tries = 1
+            c.default_within = 0.01
+            c.sleep_between_tries = 0.5
+            c.browser_folders = false
+            c.scale_amount = 0.5
+          end
+
+
+#### reference_image_path - sets where the reference and diff images are saved to.
+
+For Rails application, a default images folder will be created at spec/screenshots. This folder is root to all the reference
+images to be compares, but can be changed. 
+
+Also created are subfolders:
+- tmp/ - will hold temporary/transient images. add this to .gitignore. 
+- tmp/candidate/  - will hold candidate images which can be used as the new versions of reference images
+- tmp/diff/ - will hold the visual diff images for inspection when comparison fails
+
+#### max_no_tries 
+- sets how many times looks_good will try and match the element against the reference image. Handy to reduce fragility of tests due to animations and load times. Defaults to 1.
+
+#### default_within
+- a float between 0 and 1 that sets the default tolerance for visual differences. default is 0.01 (1%)
+
+#### scale_amount
+- Retina mac screenshots are 2x actual size, so this scales them to be 1:1. default is 0.5, set to 1 to disable. 
+
+#### Sleep_between_tries 
+- sets the sleep time (in seconds) between match tries (requires max_no_tries > 1). Defaults to 0.5
+
+#### browser_folders 
+- *Currently only available with Selenium-Webdriver / Capybara* - create reference folders based on the current Selenium driver's browser. Allows for cross-browser visual testing.
+
+
+-------------------------------------
+
+#### Non-gem dependencies:
+
+Imagemagick must be installed:
+
+  $sudo apt-get install imagemagick
+
+-------------------------------------
+
+
+## Contributing to `looks_good`
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== History
+looks_good is an expansion of (gatling)[https://github.com/gabrielrotbart/gatling] with added functionality and updated dependecies.
+
+== Copyright
+
+Copyright (c) 2022 Russell Jennings See LICENSE.txt for
+further details.
+

data/lib/looks_good/capture_element.rb

@@ -0,0 +1,47 @@
+require 'fileutils'
+require 'looks_good'
+
+module LooksGood
+  module CaptureElement
+    extend LooksGood::Configuration
+
+    def self.capture(element)
+      # Getting the element position before screenshot because of a side effect
+      # of WebDrivers getLocationOnceScrolledIntoView method which scrolls the page
+      # regardless of whether the object is in view or not
+      element_position = get_element_position(element)
+      screenshot = take_screenshot
+
+      crop_element(screenshot, element, element_position)
+    end
+
+    def self.take_screenshot
+      temp_dir = LooksGood::Configuration.path(:temp)
+      FileUtils.mkdir_p(temp_dir) unless File.exists?(temp_dir)
+      #captures the uncropped full screen
+      begin
+        temp_screenshot_filename = File.join(temp_dir, "temp-#{Process.pid}.png")
+        Capybara.page.driver.browser.save_screenshot(temp_screenshot_filename)
+        temp_screenshot = Magick::Image.read(temp_screenshot_filename).first
+      rescue
+        raise "Could not save screenshot to #{temp_dir}. Please make sure you have permission"
+      end
+    end
+
+    def self.get_element_position(element)
+      element = element.native
+      position = Hash.new{}
+      position[:x] = element.location.x
+      position[:y] = element.location.y
+      position[:width] = element.size.width
+      position[:height] = element.size.height
+      position
+    end
+
+    def self.crop_element(image, element_to_crop, position)
+      cropped_element = image.scale(LooksGood::Configuration.scale_amount).crop(position[:x], position[:y], position[:width], position[:height])
+    end
+
+  end
+end
+

data/lib/looks_good/comparison.rb

@@ -0,0 +1,74 @@
+module LooksGood
+  class Comparison
+
+    attr_accessor :diff_image, :actual_image, :expected_image
+
+    def initialize(actual_image, expected_image, within=LooksGood::Configuration.default_within)
+      @actual_image = actual_image
+      @expected_image = expected_image
+      @comparison = compare_image
+      @within = within
+      # within is a float of % image difference between the two images
+      @match = @comparison[1] <= @within
+      @diff_image =LooksGood::Image.new(@comparison.first, @expected_image.file_name) unless @matches
+    end
+
+    def matches?
+      @match
+    end
+
+    def within
+      @within
+    end
+
+    def percent_difference
+      @comparison[1]
+    end
+
+    def compare_image
+      compare_images_with_same_size? ? compare_images_with_same_size : compare_images_with_different_size
+    end
+
+    def compare_images_with_same_size
+      images_to_compare = prep_images_for_comparison
+      images_to_compare.first.compare_channel(images_to_compare.last, Magick::PeakAbsoluteErrorMetric, Magick::AllChannels) do
+        self.highlight_color = Magick::Pixel.new(65300,100,0,38000)
+        self.lowlight_color = Magick::Pixel.new(0,65300,1000,60000)
+      end
+    end
+
+    def compare_images_with_different_size
+      row = [@actual_image.image.rows, @expected_image.image.rows].max
+      column = [@actual_image.image.columns, @expected_image.image.columns].max
+
+      images_to_compare = prep_images_for_comparison do |image|
+        expanded_image = image.extent(column, row)
+        expanded_image.background_color = 'white'
+        expanded_image
+      end
+    images_to_compare.first.compare_channel(images_to_compare.last, Magick::PeakAbsoluteErrorMetric) do |img|
+        img.highlight_color = Magick::Pixel.new(65300,100,0,38000)
+        img.lowlight_color = Magick::Pixel.new(0,65300,1000,60000)
+      end
+    end
+
+    def compare_images_with_same_size?
+      @actual_image.image.rows == @expected_image.image.rows && @actual_image.image.columns == @expected_image.image.columns
+    end
+
+    def prep_images_for_comparison
+      [
+          @actual_image,
+          @expected_image,
+      ].collect do |looks_good_image|
+        image = looks_good_image.image.clone
+        image = yield image if block_given?
+
+        # Important: ensure the image 0,0 is reset to the top-left of the image before comparison
+        image.offset = 0
+        image
+      end
+    end
+
+  end
+end

data/lib/looks_good/configuration.rb

@@ -0,0 +1,77 @@
+require 'logger'
+
+module LooksGood
+  module Configuration
+
+    class << self
+
+      attr_accessor :reference_image_path, :max_no_tries, :sleep_between_tries, :browser_folders, :default_within
+
+      attr_reader :paths
+
+      def reference_image_path
+        @reference_image_path ||= default_reference_path
+        @browser_folders ? (reference_path_with_browser_folders) : @reference_image_path
+      end
+
+      def default_within
+        @default_within ||= 0.01 # 1%
+      end
+
+      # allows retina mac screenshots to be scaled to expected size
+      def scale_amount
+        @scale_amount ||= 0.5 
+      end
+
+      def max_no_tries
+        @max_no_tries ||= 1
+      end
+
+      def sleep_between_tries
+        @sleep_between_tries ||= 0.1
+      end
+
+      def path(type)
+        paths =  {:reference => reference_image_path,
+                  :temp => File.join(reference_image_path, 'tmp', 'tmp'),
+                  :candidate => File.join(reference_image_path, 'temp', 'candidate'),
+                  :diff => File.join(reference_image_path, 'temp', 'diff')
+                 }
+        paths[type]
+      end
+
+      def default_reference_path
+        begin
+          reference_image_path = File.join(Rails.root, 'spec/screenshots')
+        rescue
+          reference_image_path = 'spec/screenshots'
+          puts "Currently defaulting to #{@reference_image_path}. Overide this by setting reference_image_path=[refpath] in your configuration block"
+        end
+        reference_image_path
+      end
+
+      def reference_path_with_browser_folders
+        begin
+          reference_images_path = File.join(@reference_image_path, browser)
+        rescue
+          reference_images_path = @reference_image_path
+        end
+        reference_images_path
+      end
+
+      def browser
+        begin
+          browser = Capybara.page.driver.browser.browser
+        rescue
+          browser = Selenium.page.driver.browser.browser
+        rescue
+          raise "Currently custom folders are only supported by Capybara"
+          return nil
+        end
+        browser.to_s
+      end
+
+    end
+
+  end
+end

data/lib/looks_good/image.rb

@@ -0,0 +1,73 @@
+module LooksGood
+  class Image
+
+    attr_accessor :file_name, :path, :image
+
+    attr_reader :type
+
+    def initialize image, file_name
+      @file_name = file_name
+      @image = image
+    end
+
+    def save(type = :reference)
+      save_path = path(type)
+      FileUtils::mkdir_p(File.dirname(save_path)) unless File.exists?(save_path)
+      @image.write save_path
+      save_path
+    end
+
+    def exists?
+      File.exists?(path)
+    end
+
+    def path(type = :reference)
+      @path = File.join(LooksGood::Configuration.path(type), @file_name)
+    end
+
+  end
+
+  class ImageFromElement < Image
+
+    def initialize(element, file_name)
+      super(image, file_name)
+      @element = element
+      @image = capture_image
+    end
+
+    def verify_and_save
+      LooksGood::Configuration.max_no_tries.times do
+        comparable = capture_image
+        matches = LooksGood::Comparison.new(self,Image.new(comparable,@file_name)).matches?
+        if matches
+          self.save
+          puts "Saved #{self.path} as reference"
+          return()
+        else
+          @image = comparable  
+        end  
+      end
+      raise 'Could not save a stable image. This could be due to animations or page load times. Saved a reference image, delete it to re-try'
+    end
+
+    private
+    def capture_image
+      LooksGood::CaptureElement.capture(@element)
+    end
+
+    #TODO: make save a relevant subclass method
+  end
+
+  class ImageFromFile < Image
+
+    def initialize(file_name)
+      super(image, file_name)
+
+      @image = Magick::Image.read(path).first
+    end
+
+    #TODO: make save a relevant subclass method
+
+  end
+end
+

data/lib/looks_good/matchers/look_like_matcher.rb

@@ -0,0 +1,22 @@
+require 'looks_good'
+
+RSpec::Matchers.define :look_like do |expected|
+  result = nil
+  match do |actual|
+    if expected.is_a?(Symbol)
+      called_by_file = self.caller.find{|str| str.include?("_spec.rb")}
+      path_to = called_by_file.split("_spec.rb").first.split("spec/").last
+      expected = File.join(path_to, "#{expected}.png")
+    end
+    result = LooksGood.check(expected, actual)
+    result[:result]
+  end
+
+  failure_message do |actual|
+    actual_amount = result[:percent_difference] * 100
+    expected_amount = result[:comparison].within * 100
+    error_message = "expected '#{self.actual.path}' to match previous snapshot #{expected} by #{expected_amount.round(3)}%, but was off by #{actual_amount.round(3)}%\n"
+    error_message += result[:message]
+  end
+end
+

data/lib/looks_good/rspec_config.rb

@@ -0,0 +1,5 @@
+RSpec.configure do |config|
+config.before(:suite) do
+    LooksGood.cleanup
+  end
+end

data/lib/looks_good/version.rb

@@ -0,0 +1,3 @@
+module LooksGood
+  VERSION = "1.0.0"
+end

data/lib/looks_good.rb

@@ -0,0 +1,104 @@
+require 'rmagick'
+require 'capybara'
+require 'capybara/dsl'
+
+require 'looks_good/configuration'
+require 'looks_good/image'
+require 'looks_good/comparison'
+require 'looks_good/capture_element'
+require 'looks_good/rspec_config'
+
+module LooksGood
+  class << self
+
+    def check(expected_reference_filename, actual_element, within: LooksGood::Configuration.default_within)
+       result = match_result(expected_reference_filename, actual_element, within: within)
+       result
+    end
+
+    def match_result(expected_reference_filename, actual_element, within:)
+      result_hash = {}
+      @actual_element = actual_element
+      @expected_reference_filename = expected_reference_filename
+      @expected_reference_file = (File.join(LooksGood::Configuration.path(:reference), expected_reference_filename))
+
+
+      if !File.exists?(@expected_reference_file) || ENV["LOOKS_GOOD"]
+        save_reference
+        result_hash[:result] = true
+        return result_hash
+      else
+        reference_file = LooksGood::ImageFromFile.new(expected_reference_filename)
+        comparison = compare_until_match(actual_element, reference_file, within: within)
+        result_hash[:comparison] = comparison
+        result_hash[:percent_difference] = comparison.percent_difference
+        matches = comparison.matches?
+        if !matches
+          comparison.actual_image.save(:candidate)
+          save_image_as_diff(comparison.diff_image)
+          result_hash[:message] = %Q[view a visual diff image: open #{comparison.diff_image.path(:diff)}\n
+HOW TO FIX:\n 
+- cp #{comparison.diff_image.path(:candidate)} #{@expected_reference_file}
+or
+- LOOKS_GOOD=true rspec ...]
+          result_hash[:result] = false
+          result_hash
+        else
+          result_hash[:result] = true
+          result_hash
+        end
+      end
+    end
+
+    def compare_until_match(actual_element, reference_file, within:, max_no_tries: LooksGood::Configuration.max_no_tries, sleep_time: LooksGood::Configuration.sleep_between_tries)
+      max_no_tries.times do |i|
+        actual_image = LooksGood::ImageFromElement.new(actual_element, reference_file.file_name)
+        @comparison = LooksGood::Comparison.new(actual_image, reference_file, within)
+        match = @comparison.matches?
+        if !match
+          sleep sleep_time
+          #TODO: Send to logger instead of puts
+          i += 1
+          puts "Tried to match #{i} times"
+        else
+          return(@comparison) 
+        end
+      end
+      @comparison
+    end
+
+    def save_image_as_diff(image)
+      image.save(:diff)
+     
+    end
+
+    def save_image_as_candidate(image)
+      image.save(:candidate)
+      raise "The design reference #{image.file_name} does not exist, #{image.path(:candidate)} " +
+      "is now available to be used as a reference. Copy candidate to root reference_image_path to use as reference"
+    end
+
+    def save_reference
+      ImageFromElement.new(@actual_element,@expected_reference_filename).verify_and_save
+    end
+
+    def cleanup
+      FileUtils.remove_dir(LooksGood::Configuration.path(:temp)) if File.directory?(LooksGood::Configuration.path(:temp))
+      FileUtils.remove_dir(LooksGood::Configuration.path(:diff)) if File.directory?(LooksGood::Configuration.path(:diff))
+      FileUtils.remove_dir(LooksGood::Configuration.path(:candidate)) if File.directory?(LooksGood::Configuration.path(:candidate))
+    end
+
+
+    def config(&block)
+      begin
+        config_class = LooksGood::Configuration
+        raise "No block provied" unless block_given?
+        block.call(config_class)
+      rescue
+         raise "Config block has changed. Example: LooksGood.config {|c| c.reference_image_path = 'some/path'}. Please see README"
+      end
+    end
+
+  end
+end
+

data/looks_good.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "looks_good/version"
+
+Gem::Specification.new do |s|
+  s.name        = "looks_good"
+  s.version     = LooksGood::VERSION
+  s.authors     = ["Russell Jennings"]
+  s.email       = ["violentpurr@gmail.com"]
+  s.homepage    = "http://github.com/meesterdude/looks_good"
+  s.summary     = %q{Rspec visual testing}
+  s.description = %q{Rspec visual testing with percent matching tolerance}
+
+  s.rubyforge_project = "looks_good"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency('rmagick', ['>=2.15.4'])
+  s.add_runtime_dependency('capybara',['>=2.6.0'])
+
+  s.add_development_dependency('rake',['>=0.9.2'])
+  s.add_development_dependency('pry',['>=0.10.2'])
+  s.add_development_dependency('selenium-webdriver',['~> 2.53.0'])
+end