simulacrum 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c310ede91a08d7f1f3dc4a8117b2c819cbae6106
+  data.tar.gz: 0baa8198be24a7d440e3c18bc1f2cc3dcf7a155c
+SHA512:
+  metadata.gz: 73c02e295c5a64c54b5698b9ab635b13949e539f0acbaa246be388b7179c90faf369ea90812e2e7ef0372c66efca1f12a513beba83b7c316efcd72a4d2ffab75
+  data.tar.gz: 43d26d53bbb8562d4bdf036a45206fd09830dc892661244d848f73537e40ba9e1566201d7d01781fdf4a780ca9956755ea4c5d3611e5444aae8e7b284741ad69

data/README.md

@@ -0,0 +1,40 @@
+## Simulacrum
+
+An opinionated UI component regression testing tool built to be tightly integrated with RSpec, Selenium and tools you already use.
+
+***
+
+### Installing
+`gem 'simulacrum'`
+
+### Configuring
+
+```ruby
+RSpec.configure do |config|
+  config.include Simulacrum
+end
+```
+
+Simulacrum can also be configured once included;
+
+```ruby
+Simulacrum.configure do |config|
+	config.images_path = 'somewhere/example/spec/ui_specs'
+	config.acceptable_delta = 2 # allow a maximum of 2% difference
+end
+```
+
+### Opinions
+
+### Usage
+
+Simulacrum provides a small DSL for configuring and managing UI tests from within Rspec. Basically it boils down to these three methods;
+
+- `component`
+- `configure_browser`
+- `look_the_same`
+
+#### Inspiration
+
+- Huxley
+- Green Onion

data/lib/simulacrum/browser.rb

@@ -0,0 +1,7 @@
+require 'capybara'
+require 'capybara/dsl'
+
+module Simulacrum
+  class Browser
+  end
+end

data/lib/simulacrum/comparator.rb

@@ -0,0 +1,59 @@
+require_relative 'diff/rmagick'
+
+module Simulacrum
+  # The Comparator class is responsible for comparing and handling
+  # processing of screenshots and candidates
+  class Comparator
+    include RSpec::Core::Pending
+
+    attr_accessor :component, :candidate, :diff
+
+    def initialize(component)
+      @component = component
+    end
+
+    def test
+      @candidate = @component.capture_candidate
+
+      # If the component has a reference then we should diff the candidate
+      # image against the reference
+      if @component.reference?
+        # If there is a diff between the candidate and the reference then we
+        # should save both the candidate and diff images and fail the test
+        perform_diff ? pass : fail
+
+      # Otherwise we should just write the captured candidate to disk, and mark
+      # the spec as being pending until the user works out if the candidate is
+      # OK by renaming candidate.png to reference.png
+      else
+        skip
+      end
+    end
+
+    private
+
+    def pass
+      @component.remove_candidate
+      true
+    end
+
+    def fail
+      @diff.save(@component.diff_path)
+      false
+    end
+
+    def skip
+      nil
+    end
+
+    def perform_diff()
+      @diff = Simulacrum::RmagicDiff.new(@component.reference_path,
+                                    @component.candidate_path)
+      diff_delta_percent_is_acceptable
+    end
+
+    def diff_delta_percent_is_acceptable
+      (@diff.delta * 1000) < @component.acceptable_delta
+    end
+  end
+end

data/lib/simulacrum/component.rb

@@ -0,0 +1,66 @@
+require 'capybara'
+
+module Simulacrum
+  class Component
+    include Capybara::DSL
+    Capybara.default_driver = :selenium
+
+    attr_reader :name
+
+    def initialize(name, options)
+      @name = name
+      @options = options
+    end
+
+    # Load up the component url and capture an image, returns a File object
+    def capture_candidate
+      ensure_example_path
+      visit(@options.url)
+      within(capture_selector) do
+        page.save_screenshot(candidate_path)
+      end
+    end
+
+    def remove_candidate
+      FileUtils.rm(candidate_path) if candidate?
+    end
+
+    def root_path
+      File.join(Simulacrum.configuration.images_path, name.to_s)
+    end
+
+    def reference_path
+      File.join(root_path, Simulacrum.configuration.reference_filename)
+    end
+
+    def candidate_path
+      File.join(root_path, Simulacrum.configuration.candidate_filename)
+    end
+
+    def diff_path
+      File.join(root_path, Simulacrum.configuration.diff_filename)
+    end
+
+    def reference?
+      File.exists?(reference_path)
+    end
+
+    def candidate?
+      File.exists?(candidate_path)
+    end
+
+    def acceptable_delta
+      @options.acceptable_delta || Simulacrum.configuration.acceptable_delta
+    end
+
+    private
+
+    def ensure_example_path
+      FileUtils.mkdir_p(root_path)
+    end
+
+    def capture_selector
+      @options.capture_selector || Simulacrum.configuration.capture_selector
+    end
+  end
+end

data/lib/simulacrum/configuration.rb

@@ -0,0 +1,40 @@
+require 'ostruct'
+
+module Simulacrum
+  class Configuration
+    attr_reader :images_path, :reference_filename, :candidate_filename,
+      :diff_filename, :capture_selector, :acceptable_delta
+
+    def initialize
+      @config = OpenStruct.new
+    end
+
+    def configure(config)
+      @config = OpenStruct.new(@config.to_h.merge!(config))
+    end
+
+    def images_path
+      @config.images_path
+    end
+
+    def reference_filename
+      @config.reference_filename || 'reference.png'
+    end
+
+    def candidate_filename
+      @config.candidate_filename || 'candidate.png'
+    end
+
+    def diff_filename
+      @config.diff_filename || 'diff.png'
+    end
+
+    def capture_selector
+      @config.capture_selector || 'html'
+    end
+
+    def acceptable_delta
+      @config.acceptable_delta || 0.0
+    end
+  end
+end

data/lib/simulacrum/diff/pdiff.rb

@@ -0,0 +1,47 @@
+require 'chunky_png'
+require_relative '../diff'
+
+module Simulacrum
+  class Pdiff < Simulacrum::Diff
+    include ChunkyPNG::Color
+
+    def compare
+      a_image = ChunkyPNG::Image.from_file(@a_path)
+      b_image = ChunkyPNG::Image.from_file(@b_path)
+    end
+  end
+end
+
+# require 'chunky_png'
+# include ChunkyPNG::Color
+
+
+# images = [
+#   ChunkyPNG::Image.from_file('1.png'),
+#   ChunkyPNG::Image.from_file('2.png')
+# ]
+
+# output = ChunkyPNG::Image.new(images.first.width, images.last.width, WHITE)
+
+# diff = []
+
+# images.first.height.times do |y|
+#   images.first.row(y).each_with_index do |pixel, x|
+#     unless pixel == images.last[x,y]
+#       score = Math.sqrt(
+#         (r(images.last[x,y]) - r(pixel)) ** 2 +
+#         (g(images.last[x,y]) - g(pixel)) ** 2 +
+#         (b(images.last[x,y]) - b(pixel)) ** 2
+#       ) / Math.sqrt(MAX ** 2 * 3)
+
+#       output[x,y] = grayscale(MAX - (score * MAX).round)
+#       diff << score
+#     end
+#   end
+# end
+
+# puts "pixels (total):     #{images.first.pixels.length}"
+# puts "pixels changed:     #{diff.length}"
+# puts "image changed (%): #{(diff.inject {|sum, value| sum + value} / images.first.pixels.length) * 100}%"
+
+# output.save('diff.png')

data/lib/simulacrum/diff/rmagick.rb

@@ -0,0 +1,18 @@
+require 'rmagick'
+require_relative '../diff'
+
+module Simulacrum
+  class RmagicDiff < Simulacrum::Diff
+    private
+
+    def compare
+      a_image = Magick::Image.read(@a_path)
+      b_image = Magick::Image.read(@b_path)
+      @image, @delta = compare_images(a_image, b_image)
+    end
+
+    def compare_images(a_image, b_image)
+      a_image[0].compare_channel(b_image[0], Magick::MeanSquaredErrorMetric)
+    end
+  end
+end

data/lib/simulacrum/diff.rb

@@ -0,0 +1,20 @@
+module Simulacrum
+  class Diff
+    attr_accessor :a_path, :b_path, :delta, :image
+
+    def initialize(a_path, b_path)
+      @a_path = a_path
+      @b_path = b_path
+
+      compare
+    end
+
+    def save(path)
+      @image.write(path)
+    end
+
+    def percent_change
+      (@delta * 1000).round(2)
+    end
+  end
+end

data/lib/simulacrum/matchers.rb

@@ -0,0 +1,42 @@
+require_relative 'comparator'
+
+module Simulacrum
+  module Matchers
+    extend RSpec::Matchers::DSL
+
+    matcher :look_the_same do
+      match do |component|
+        comparator = Simulacrum::Comparator.new(component)
+        case comparator.test
+        when true
+          true
+        when false
+          fail <<-eos
+The pixel change percentage exceeded the maximum threshold of #{component.acceptable_delta}%.
+
+There was a #{comparator.diff.percent_change}% pixel difference found between \
+the reference and the candidate.
+
+Reference: #{component.reference_path}
+Candidate: #{component.candidate_path}
+Diff:      #{component.diff_path}
+
+Please review the diff and resolve manually.
+          eos
+        when nil
+          pending <<-eos
+No reference image found! New candidate created:
+
+      #{component.candidate_path}
+
+      Please inspect this candidate image and if it looks OK then;
+
+        - mark it as a reference image by renaming it to 'reference.png'
+        - commit 'reference.png' file to your SCM of choice
+        - rerun this spec making sure it passes using the new reference image
+          eos
+        end
+      end
+    end
+  end
+end

data/lib/simulacrum/methods.rb

@@ -0,0 +1,25 @@
+require 'ostruct'
+require_relative 'browser'
+require_relative 'component'
+
+module Simulacrum
+  # Rspec utility methods for defining components, browser environments and
+  module Methods
+    def component(name, &block)
+      options = OpenStruct.new
+      yield options
+      component = Simulacrum::Component.new(name, options)
+      Simulacrum.components[name] = component
+
+      subject do
+        component
+      end
+    end
+
+    def configure_browser(name, &block)
+      options = OpenStruct.new
+      yield options
+      @browser = Simulacrum::Browser.new(name, options)
+    end
+  end
+end

data/lib/simulacrum/version.rb

@@ -0,0 +1,5 @@
+# Package information
+module Simulacrum
+  PACKAGE = 'simulacrum'
+  VERSION = '0.0.2'
+end

data/lib/simulacrum.rb

@@ -0,0 +1,29 @@
+require 'ostruct'
+require_relative 'Simulacrum/methods'
+require_relative 'Simulacrum/matchers'
+require_relative 'Simulacrum/configuration'
+
+# Gem module
+module Simulacrum
+  @components = {}
+  @configuration = Simulacrum::Configuration.new
+
+  def self.components
+    @components
+  end
+
+  def self.configuration
+    @configuration
+  end
+
+  def self.configure(&block)
+    options = OpenStruct.new
+    yield options
+    @configuration.configure(options.to_h)
+  end
+
+  def self.included(receiver, &block)
+    receiver.extend         Simulacrum::Methods
+    receiver.send :include, Simulacrum::Matchers
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+if ENV['COVERAGE']
+  require_relative 'use_coveralls' if ENV['TRAVIS']
+  require_relative 'use_simplecov' unless ENV['TRAVIS']
+end
+
+require 'bundler/setup'
+require 'Simulacrum'
+require 'rspec/autorun'
+
+RSpec.configure do |config|
+  config.order = "random"
+end

data/spec/use_coveralls.rb

@@ -0,0 +1,2 @@
+require 'coveralls'
+Coveralls.wear!

data/spec/use_simplecov.rb

@@ -0,0 +1,14 @@
+puts "[Simplecov] enabled"
+require 'simplecov'
+
+class SimpleCov::Formatter::QualityFormatter
+  def format(result)
+    SimpleCov::Formatter::HTMLFormatter.new.format(result)
+    File.open("coverage/covered_percent", "w") do |f|
+      f.puts result.source_files.covered_percent.to_f
+    end
+  end
+end
+
+SimpleCov.formatter = SimpleCov::Formatter::QualityFormatter
+SimpleCov.start

metadata

@@ -0,0 +1,221 @@
+--- !ruby/object:Gem::Specification
+name: simulacrum
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Justin Morris
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capybara
+  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: rspec
+  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: rmagick
+  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: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-nc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: An opinionated UI component regression testing tool built to be tightly
+  integrated with RSpec, Selenium and tools you already use.
+email:
+- desk@pixelbloom.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/simulacrum/browser.rb
+- lib/simulacrum/comparator.rb
+- lib/simulacrum/component.rb
+- lib/simulacrum/configuration.rb
+- lib/simulacrum/diff/pdiff.rb
+- lib/simulacrum/diff/rmagick.rb
+- lib/simulacrum/diff.rb
+- lib/simulacrum/matchers.rb
+- lib/simulacrum/methods.rb
+- lib/simulacrum/version.rb
+- lib/simulacrum.rb
+- README.md
+- spec/fixtures/a.png
+- spec/fixtures/a2.png
+- spec/spec_helper.rb
+- spec/use_coveralls.rb
+- spec/use_simplecov.rb
+homepage: https://github.com/plasticine/simulacrum
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.1.11
+signing_key: 
+specification_version: 4
+summary: A gem for visually testing and inspecting user interface components.
+test_files:
+- spec/fixtures/a.png
+- spec/fixtures/a2.png
+- spec/spec_helper.rb
+- spec/use_coveralls.rb
+- spec/use_simplecov.rb