simulacrum 0.1.1 → 0.3.0

data/lib/simulacrum/cli/parser.rb

@@ -0,0 +1,152 @@
+# encoding: UTF-8
+require 'optparse'
+require 'ostruct'
+require 'simulacrum'
+
+module Simulacrum
+  module CLI
+    # Option parser for handling options passed into the Simulacrum CLI
+    #
+    # This class is mostly borrowed from Cane's Parser class. Thanks Xav! <3
+    class Parser
+      attr_reader :stdout
+
+      # Exception to indicate that no further processing is required and the
+      # program can exit. This is used to handle --help and --version flags.
+      class OptionsHandled < RuntimeError; end
+
+      def self.parse(args)
+        new.parse(args)
+      end
+
+      def initialize(stdout = $stdout)
+        @stdout = stdout
+
+        add_banner
+        add_runner_options
+        add_format_options
+        add_separator
+        add_version
+        add_help
+      end
+
+      def parse(args, _return = true)
+        parser.parse!(args)
+        options['files'] = args if args.size > 0
+        OpenStruct.new(default_options.merge(options))
+      rescue OptionParser::InvalidOption,
+             OptionParser::AmbiguousOption
+        args = %w(--help)
+        _return = false
+        retry
+      rescue OptionsHandled
+        _return
+      end
+
+      private
+
+      def default_options
+        read_options_from_file.merge(username: ENV['SIMULACRUM_USERNAME'],
+                                     apikey: ENV['SIMULACRUM_APIKEY'])
+      end
+
+      def read_options_from_file
+        if Simulacrum.config_file?
+          filter_file_options(Simulacrum.config_file)
+        else
+          {}
+        end
+      end
+
+      def filter_file_options(file_options)
+        file_options.tap do |hash|
+          hash.delete('username')
+          hash.delete('apikey')
+        end
+      end
+
+      def add_banner
+        parser.banner = 'Usage: simulacrum [options] [files or directories]'
+        add_separator
+      end
+
+      def add_separator
+        parser.separator ''
+      end
+
+      def add_version
+        parser.on_tail('--version', 'Show version') do
+          stdout.puts Simulacrum::VERSION
+          fail OptionsHandled
+        end
+      end
+
+      def add_help
+        parser.on_tail('-h', '--help', 'Show this message') do
+          stdout.puts parser
+          fail OptionsHandled
+        end
+      end
+
+      def add_runner_options
+        parser.on('--runner [RUNNER]',
+                  [:browserstack],
+                  'Runner to use for executing specs (browserstack).') do |runner|
+          options['runner'] = runner
+        end
+
+        parser.on('--username [USERNAME]',
+                  'Username for authenticating when using the Browserstack runner.') do |username|
+          options['username'] = username
+        end
+
+        parser.on('--apikey [APIKEY]',
+                  'API key for authenticating when using the Browserstack runner.') do |apikey|
+          options['apikey'] = apikey
+        end
+
+        parser.on('--max-processes [N]',
+                  Integer,
+                  'Number of parallel proceses the runner should use.') do |max_processes|
+          options['max_processes'] = max_processes.to_i
+        end
+
+        parser.on('--browser [BROWSER]',
+                  'Browser configuration to use') do |browser|
+          options['browser'] = browser.to_sym
+        end
+      end
+
+      def add_format_options
+        add_separator
+
+        parser.on('-c',
+                  '--[no-]color',
+                  '--[no-]colour',
+                  'Enable color in the output.') do |value|
+          options['color'] = value
+        end
+
+        parser.on('-v',
+                  '--verbose',
+                  'Be more shouty.') do |value|
+          options['verbose'] = value
+        end
+      end
+
+      def options
+        @options ||= begin
+          options = {}
+          options['files'] = ['spec/ui']
+          options['color'] = false
+          options['verbose'] = false
+          options
+        end
+      end
+
+      def parser
+        @parser ||= OptionParser.new
+      end
+    end
+  end
+end

data/lib/simulacrum/comparator.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 require 'rspec'
 require_relative './diff/rmagick'
 
@@ -7,20 +8,20 @@ module Simulacrum
   class Comparator
     include RSpec::Core::Pending
 
-    attr_accessor :component, :candidate, :diff
+    attr_reader :component, :diff
 
     def initialize(component)
       @component = component
-      @component.render
+      component.render
     end
 
     def test
       # If the component has a reference then we should diff the candidate
       # image against the reference
-      if @component.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
+        (pass?) ? 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
@@ -30,16 +31,21 @@ module Simulacrum
       end
     end
 
+    def diff
+      @diff ||= Simulacrum::RMagicDiff.new(component.reference_path,
+                                           component.candidate_path)
+    end
+
     private
 
     def pass
-      @component.remove_candidate
-      @component.remove_diff
+      component.remove_candidate
+      component.remove_diff
       true
     end
 
     def fail
-      @diff.save(@component.diff_path)
+      diff.save(component.diff_path)
       false
     end
 
@@ -47,14 +53,8 @@ module Simulacrum
       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_percent < @component.acceptable_delta
+    def pass?
+      diff.delta <= component.delta_threshold
     end
   end
 end

data/lib/simulacrum/component.rb

@@ -1,12 +1,15 @@
+# encoding: UTF-8
 require 'capybara/dsl'
 require 'fileutils'
 require 'RMagick'
 require_relative 'renderer'
 
 module Simulacrum
+  # Component Class is responsible for managing the testing of a component
+  # defined in a test suite
   class Component
-    attr_reader :name, :browser
     attr_accessor :options
+    attr_reader :name
 
     def initialize(name, options = {})
       @name = name
@@ -14,42 +17,47 @@ module Simulacrum
       @renderer = Simulacrum::Renderer.new(options.url)
     end
 
-    # Load up the component url and capture an image, returns a File object
     def render
       ensure_example_path
-      save_candidate(@renderer.render)
+      tmp_path = @renderer.render
+      save_candidate(tmp_path)
       crop_candidate_to_selector
+      true
     ensure
       cleanup
     end
 
     def reference?
-      File.exists?(reference_path)
+      File.exist?(reference_path)
     end
 
     def candidate?
-      File.exists?(candidate_path)
+      File.exist?(candidate_path)
     end
 
     def diff?
-      File.exists?(diff_path)
+      File.exist?(diff_path)
     end
 
-    def acceptable_delta
-      options.acceptable_delta || Simulacrum.configuration.acceptable_delta
+    def delta_threshold
+      # TODO: These should probably be `configuration.defaults....`
+      options.delta_threshold || Simulacrum.configuration.delta_threshold
     end
 
     def reference_path
+      # TODO: These should probably be `configuration.defaults....`
       filename = Simulacrum.configuration.reference_filename
       File.join(root_path, "#{filename}.png")
     end
 
     def candidate_path
+      # TODO: These should probably be `configuration.defaults....`
       filename = Simulacrum.configuration.candidate_filename
       File.join(root_path, "#{filename}.png")
     end
 
     def diff_path
+      # TODO: These should probably be `configuration.defaults....`
       filename = Simulacrum.configuration.diff_filename
       File.join(root_path, "#{filename}.png")
     end
@@ -66,7 +74,6 @@ module Simulacrum
 
     def cleanup
       @renderer.cleanup
-      # FileUtils.remove_entry(root_path) unless reference? || candidate? || diff?
     end
 
     def save_candidate(tmp_image_path)
@@ -75,7 +82,7 @@ module Simulacrum
 
     def crop_candidate_to_selector
       unless capture_selector.nil?
-        candidate_image = Magick::Image::read(candidate_path).first
+        candidate_image = Magick::Image.read(candidate_path).first
         bounds = @renderer.get_bounds_for_selector(capture_selector)
         candidate_image.crop!(*bounds)
         candidate_image.write(candidate_path)
@@ -83,7 +90,11 @@ module Simulacrum
     end
 
     def root_path
-      File.join(Simulacrum.configuration.references_path, name.to_s, driver_path)
+      File.join(
+        Simulacrum.configuration.references_path,
+        name.to_s,
+        driver_path
+      )
     end
 
     def driver_path

data/lib/simulacrum/configuration.rb

@@ -1,36 +1,35 @@
+# encoding: UTF-8
 require 'ostruct'
 
 module Simulacrum
+  # Configuration Class for managing config of the suite
   class Configuration
-
     COMPONENT_DEFAULTS = {
-      acceptable_delta: 1,
+      delta_threshold:  1,
       window_size:      [1024, 768],
       capture_delay:    nil,
-      capture_selector: :html,
+      capture_selector: :html
     }
 
     attr_reader :references_path, :reference_filename, :candidate_filename,
-      :diff_filename, :acceptable_delta, :capture_delay, :window_size,
-      :capture_selector, :default_browser
+                :diff_filename, :delta_threshold, :capture_delay,
+                :window_size, :capture_selector, :default_browser
 
     def initialize
-      @config = OpenStruct.new(defaults: OpenStruct.new(COMPONENT_DEFAULTS))
+      @config = OpenStruct.new(component: OpenStruct.new(COMPONENT_DEFAULTS))
     end
 
     def configure(config)
       @config = OpenStruct.new(@config.to_h.merge!(config))
     end
 
-    def default_browser
-      @config.default_browser || :selenium
-    end
-
     def references_path
       if @config.references_path
         @config.references_path
       elsif defined?(Rails)
         File.join(Rails.root, 'spec/ui/references')
+      else
+        'spec/ui/references'
       end
     end
 
@@ -46,12 +45,20 @@ module Simulacrum
       @config.diff_filename || 'diff'
     end
 
-    def acceptable_delta
-      @config.defaults.acceptable_delta || 0.0
+    def delta_threshold
+      @config.component.delta_threshold || 0.0
     end
 
     def capture_selector
-      @config.defaults.capture_selector || nil
+      @config.component.capture_selector || nil
+    end
+
+    def build_name
+      @config.build_name || ''
+    end
+
+    def project_name
+      @config.project_name || 'Simulacrum'
     end
   end
 end

data/lib/simulacrum/diff.rb

@@ -1,4 +1,6 @@
+# encoding: UTF-8
 module Simulacrum
+  # Base class for implementing diffing strategies
   class Diff
     attr_accessor :a_path, :b_path, :delta, :image
 

data/lib/simulacrum/diff/rmagick.rb

@@ -1,9 +1,11 @@
+# encoding: UTF-8
 require 'RMagick'
 require_relative '../diff'
 
 module Simulacrum
-  class RmagicDiff < Simulacrum::Diff
-    def delta_percent
+  # The RMagicDiff class implements image diffing using ImageMagick
+  class RMagicDiff < Simulacrum::Diff
+    def delta
       @delta * 100
     end
 
@@ -12,15 +14,15 @@ module Simulacrum
     def compare
       a = Magick::Image.read(@a_path)
       b = Magick::Image.read(@b_path)
-      @image, @delta = compare_images(a, b)
+      @image, @delta = square_root_mean_squared(a, b)
     end
 
-    def compare_images(a, b)
+    def square_root_mean_squared(a, b)
       # Calculate the Square Root Mean Squared Error for the comparison of the
       # two images.
       #
-      # Gets the color difference for each pixel, and square it, average all the
-      # squared differences, then return the square root.
+      # Gets the color difference for each pixel, and square it, average all
+      # the squared differences, then return the square root.
       #
       # http://www.imagemagick.org/discourse-server/viewtopic.php?f=1&t=17284
       a[0].compare_channel(b[0], Magick::MeanSquaredErrorMetric)

data/lib/simulacrum/driver.rb

@@ -0,0 +1,45 @@
+# encoding: UTF-8
+module Simulacrum
+  # Base class for Drivers to inherit
+  class Driver
+    def self.use
+      new.use
+    end
+
+    def use
+      register_driver
+      configure_capybara
+      self
+    end
+
+    private
+
+    def capabilities
+    end
+
+    def configuration
+      { browser: :firefox }
+    end
+
+    def register_driver
+      Capybara.register_driver driver_name do |app|
+        Capybara::Selenium::Driver.new(app, configuration)
+      end
+    end
+
+    def configure_capybara
+      Capybara.default_driver    = driver_name
+      Capybara.default_wait_time = 10
+      Capybara.server_host       = 'localhost'
+      Capybara.server_port       = app_server_port
+    end
+
+    def app_server_port
+      ENV['APP_SERVER_PORT'].to_i if ENV['APP_SERVER_PORT']
+    end
+
+    def driver_name
+      'default'
+    end
+  end
+end