watircats 0.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b5df83a0e30799d0a3c844005316edd2e0d5f87d
+  data.tar.gz: b7b07badae0c4ff54e8266afc594eac5cd3f6905
+SHA512:
+  metadata.gz: 3285222f1d6dfcd699340ed5ddfddf4f83e1cab0c1be9ebe20d0b43758728fd0e0cd1cecba3db9c6c19315f7d956afe2034157cb742c1a93270a18b2bcc50560
+  data.tar.gz: bad339c10f794b8d610daeb67cc9e6c932ffcfacc4afcda6bc94c1df5267951f5e456e992b72ac1fe5c8756da68ab3367f96a24bd4fabe275479eb24df6ae59c

data/.autotest

@@ -0,0 +1,5 @@
+require 'autotest/restart'
+
+Autotest.add_hook :initialize do |at|
+  at.order = :random
+end

data/Gemfile

@@ -0,0 +1,14 @@
+ruby "2.0.0"
+
+source "http://rubygems.org"
+
+# Currently not specifying versions, but probably should
+
+gem "require_all"
+gem "xml-simple"
+gem "watir-webdriver"
+gem "thor"
+gem "haml"
+gem "psych"
+gem "awesome_print"
+gem "minitest"

data/Gemfile.lock

@@ -0,0 +1,38 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    awesome_print (1.2.0)
+    childprocess (0.3.9)
+      ffi (~> 1.0, >= 1.0.11)
+    ffi (1.9.0)
+    haml (4.0.3)
+      tilt
+    minitest (5.0.6)
+    multi_json (1.8.2)
+    psych (2.0.0)
+    require_all (1.3.1)
+    rubyzip (0.9.9)
+    selenium-webdriver (2.35.1)
+      childprocess (>= 0.2.5)
+      multi_json (~> 1.0)
+      rubyzip (< 1.0.0)
+      websocket (~> 1.0.4)
+    thor (0.18.1)
+    tilt (1.4.1)
+    watir-webdriver (0.6.4)
+      selenium-webdriver (>= 2.18.0)
+    websocket (1.0.7)
+    xml-simple (1.1.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print
+  haml
+  minitest
+  psych
+  require_all
+  thor
+  watir-webdriver
+  xml-simple

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Clockwork Active Media Systems
+
+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,74 @@
+# WatirCats
+
+WatirCats began as a simple fork of Wraith, from the developers at BBC News.
+
+Orignally, Wraith used Phantom.js as its browser, but it was too darned slow, so the browsing engine was converted to Watir-Webdriver. There were also several other limitations to Wraith that hampered its use at Clockwork, so it was enhanced to support a number of unique features. 
+
+Wraith's original comparison command lies at the heart of the comparison functionality of WatirCats. 
+
+Some of the features:
+- Responsive Screenshots
+- Multiple sources for URLs, but most rely on /sitemap.xml for use
+- Multiple Browsing engines. Chrome, Firefox, FirefoxESR, and support for IE
+- Proxy and custom binary path support for Firefox
+
+## What is it?
+
+WatirCats uses Watir-Webdriver to grab screenshots of pages at multiple widths.  It also grabs and parses a site's sitemap, assuming the site map is hosted at the site_root/sitemap.xml
+
+## Requirements
+
+- ImageMagick
+- Ruby 1.9.3 or greater
+- Firefox
+
+## Installation
+
+`gem install WatirCats`
+
+or
+
+- Checkout this repository
+- `bundle install`
+- `gem build watircats.gemspec`
+- `gem install WatirCats-0.2.0.gem`
+
+## Usage
+
+- Compare And Take Screenshots:
+ - `watircats compare http://my.example.com http://my-other.example.com` 
+- Compare two folders of screenshots:
+ - `watircats folders folder_a folder_b`
+- Take screenshots at several widths:
+ - `watircats screenshots http://my.example.com --widths 1024 800 320`
+
+## Configuration
+
+Configuration can be done at the command line or via a config file. See 'sample_config.yml' for the available parameters. 
+
+Specify a config file at runtime with `--config_file my_config_file.yml`
+
+
+If you want to add functionality to this project, pull requests are welcome.
+
+ * Create a branch based off master and do all of your changes with in it.
+ * If it you have to pause to add a 'and' anywhere in the title, it should be two pull requests.
+ * Make commits of logical units and describe them properly
+ * Check for unnecessary whitespace with git diff --check before committing.
+ * If possible, submit tests to your patch / new feature so it can be tested easily.
+ * Assure nothing is broken by running all the test
+ * Please ensure that it complies with coding standards.
+
+**Please raise any issues with this project as a GitHub issue.**
+
+
+## License
+
+WatirCats is available to everyone under the terms of the MIT open source
+licence. Take a look at the LICENSE file in the code.
+
+## Credits
+
+ * [Andrew Leaf](http://clockwork.net/people/andrew_leaf/)
+ * [Wraith from BBC News](http://github.com/bbc-news/wraith)
+

data/bin/watircats

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.push File.expand_path('../../lib/', __FILE__)
+
+require 'watircats/cli'
+
+WatirCats::CLI.start(ARGV)

data/lib/watircats/cli.rb

@@ -0,0 +1,201 @@
+require 'thor'
+require 'watircats'
+require 'yaml'
+
+# CLI for WatirCats. Options and commands for any of the available utilities
+# available through the watircats executable
+
+module WatirCats
+  class CLI < Thor
+
+    # Options that are common for comparison operations
+    common_compare_options = {
+      [:output_dir, '-o']             => "comparison",
+      [:screenshot_dir, '-s']         => "screenshots",
+      [:working_dir, '-w']            => :string,
+      [:images_dir, '-i']             => :string,
+      [:reporting_enabled, '-r']      => :boolean,
+      [:csv_output]                   => :boolean,
+      [:verbose, '-v']                => :boolean,
+      [:strip_zero_differences, '-z'] => :boolean,
+      [:config_file, '-c']            => :string,
+      [:skip_existing, '-e']          => :boolean,
+    }
+
+    # Options that are common for screenshot operations
+    common_screenshot_options = {
+      [:browser, '-b']           => "firefox",
+      [:widths]                  => :array, 
+      [:limit, '-l']             => :numeric,
+      [:url_list]                => :string,
+      [:limit]                   => :string,
+      [:custom_body_class_tests] => :string,
+      [:proxy, '-p']             => :string,
+      [:limited_path]            => :string,
+      [:avoided_path]            => :string
+    }
+
+    # Description for the next-to-be-defined 'compare' task
+    desc 'compare http://SITE_A http://SITE_B', 'Compare Screenshots from two sites'
+    
+    # Add the options for comparison and screenshot operations to the next task
+    method_options common_compare_options
+    method_options common_screenshot_options
+
+    def compare(*source_arguments)
+      ensure_imagemagick
+
+      # Configure options      
+      handle_configuration( options )
+
+      # Setting an exit status to track for altered screens
+      @exit_status = 0 
+
+      # Create an empty array of sources
+      sources = []
+
+      # Populate the sources array with each command line argument
+      source_arguments.each { |s| sources << s }
+
+      # Handle a working directory by calling the private method 'handle_working_dir'
+      handle_working_dir
+      
+      # Run the comparison
+      WatirCats::Runner.new( :compare, sources )
+
+      # Handle the reporting functionality
+      handle_reporting
+
+      # Exit based on the exit status of the application
+      exit @exit_status
+    end
+
+    desc 'folders FOLDER_A FOLDER_B', 'Compare two folders of screenshots'
+
+    # Add the options for comparison operations
+    method_options common_compare_options
+
+    def folders(*source_arguments)     
+      ensure_imagemagick
+
+      handle_configuration( options )
+      # Setting an exit status to track for altered screens
+      @exit_status = 0 
+      
+      # Create an empty array of sources
+      sources = [ ]
+
+      # Populate the sources array with each command line argument
+      source_arguments.each { |s| sources << s }
+
+      # Handle a working directory
+      handle_working_dir
+
+      # Run the folders command
+      WatirCats::Runner.new( :folders, sources )
+
+      # Handle reporting
+      handle_reporting
+
+      exit @exit_status
+    end
+
+    desc 'screenshots SITE_A [SITE_B SITE_C ...]', 'Take Screenshots of any number of sites'
+ 
+    method_options common_compare_options
+    method_options common_screenshot_options
+
+    def screenshots(*source_arguments)
+      ensure_imagemagick
+
+      handle_configuration( options )
+      # Setting an exit status to track for altered screens
+      @exit_status = 0 
+
+      # Create an empty array of sources
+      sources = [ ]
+
+      # Populate the sources array with each command line argument
+      source_arguments.each { |s| sources << s }
+
+      # Handle a working directory
+      handle_working_dir
+
+      # Run the screenshots command
+      WatirCats::Runner.new( :screenshots_only, sources )
+
+      # Handle Reporting
+      handle_reporting
+
+      exit @exit_status
+    end
+
+    private
+
+    def handle_working_dir
+      # Handle a working directory
+      working_dir = WatirCats.config.working_dir
+      if working_dir
+        unless File.directory? working_dir
+          FileUtils.mkdir working_dir
+        end
+        Dir.chdir working_dir
+      end
+    end
+
+    def handle_reporting
+      # Handle standard reporting
+      reporting = WatirCats.config.reporting_enabled
+
+      if reporting
+        data       = WatirCats::Comparer.the_results
+        data.each { |e| @exit_status = 1 unless e[:result].match(/0/) }
+
+        report = WatirCats::Reporter.new( data ).build_html
+        File.open("#{WatirCats.config.output_dir}/index.html", 'w') do |f|
+          f.write report
+        end
+      end
+
+      # Handle custom reporting
+      custom_tests = WatirCats.config.custom_body_class_tests
+
+      if custom_tests
+        results = WatirCats::Snapper.custom_test_results
+        report  = WatirCats::Reporter.build_custom_results( results )
+
+        File.open("#{WatirCats.config.output_dir}/custom_report.html", 'w') do |f|
+          f.write report
+        end
+      end
+
+    end
+
+    def handle_configuration(options)
+      # Parse the command line options. If a config file if specified, merge 
+      # those values into the options hash as long as keys don't collide.
+      # Command line options override the config file.
+      
+      cloned_options = options.dup
+      if cloned_options[:config_file]
+        config = YAML::load_file cloned_options[:config_file]
+        config.each do |key,value|
+          cloned_options[key.to_sym] = value 
+        end
+      end
+      merged_opts = cloned_options.merge(options)
+      WatirCats.configure merged_opts
+    end
+
+    def ensure_imagemagick
+      # Ensure that Imagemagick's compare is installed
+      begin
+        `compare --version`
+      rescue
+        puts "Please ensure ImageMagick is in your system path to use WatirCats. \nPlease visit http://www.imagemagick.org."
+        exit 
+      end
+    end
+    
+  end
+end

data/lib/watircats/comparer.rb

@@ -0,0 +1,136 @@
+module WatirCats
+  class Comparer 
+
+    NO_CHANGE = "Snow"
+    ERROR     = "Crimson"
+    CHANGE    = "Khaki"
+
+
+    def initialize(source_a, source_b)
+
+      @@results    = [ ]
+      @@strip_zero = WatirCats.config.strip_zero_differences || nil
+     
+      @comparison_dir = WatirCats.config.output_dir.chomp("/")
+      # Get the last two directories that were created
+      
+      previous_shots_folder = source_a.chomp("/")
+      latest_shots_folder   = source_b.chomp("/")
+
+      # Cleanup the comparison folder
+      reset_comparison_folder
+
+      # Compare the directories
+      compare_directories(latest_shots_folder, previous_shots_folder)
+
+      # Return self
+      self
+    end
+   
+    def reset_comparison_folder
+      if File.directory? @comparison_dir
+        dir_contents = Dir.glob("#{@comparison_dir}/*_compared.png")
+        if dir_contents.size > 0
+          dir_contents.each do |shot|
+            FileUtils.rm(shot)  
+          end
+        end
+      else
+        FileUtils.mkdir_p(@comparison_dir)
+      end
+    end
+
+    def compare_directories(latest, previous)
+      # Grab the list of screenshots
+      old_shots = Dir.glob(previous + "/*.png")
+
+      old_shots.each do |old_shot|
+        new_shot = old_shot.gsub(previous, latest)
+      
+        next unless File.exists? new_shot
+        # Set a file prefix for output and info
+        base_name     = old_shot.split("/").last.split(".").first
+        output_file   = base_name + "_compared.png"
+
+        comparison = compare_images(new_shot, old_shot, output_file)
+        status = NO_CHANGE
+        if comparison.match(/error/)
+          status = ERROR
+        elsif comparison.match(/^[1-9]/)
+          status = CHANGE
+        end
+        @@results << { :compared_shot => output_file, 
+                       :result => comparison, :status_color => status }
+
+        # Remove the file if there is no change to be concerned with
+        if @@strip_zero == true 
+          begin 
+            FileUtils.rm "#{@comparison_dir}/#{output_file}" if status == NO_CHANGE
+          rescue Exception => msg
+            print msg
+            print "\n"
+          end
+        end
+
+      end
+      # Run the generate thumbs
+      generate_thumbs if WatirCats.config.reporting_enabled
+    end
+    
+    def generate_thumbs  
+    
+      unless results.size < 1
+        unless File.directory? "#{@comparison_dir}/thumbs"
+          FileUtils.mkdir "#{@comparison_dir}/thumbs"
+        end
+
+        # Generate thumbnails
+        `mogrify -format png -path #{@comparison_dir}/thumbs -thumbnail 50x100 #{@comparison_dir}/*.png`
+      end
+    end
+
+
+    def compare_images(latest_grab, previous_grab, output_file)
+      data = `compare -fuzz 20% -metric AE -highlight-color blue #{previous_grab} #{latest_grab} #{@comparison_dir}/#{output_file} 2>&1`.chomp
+      # Handle logging
+      return data if ( @@strip_zero == true && data.match(/^0/) )
+      csv     = WatirCats.config.csv
+      verbose = WatirCats.config.verbose
+      print "#{output_file}" if ( csv || verbose )
+      print ",#{data}" if csv
+      print "\n" if ( csv || verbose )
+      # Return data
+      data
+    end
+
+    def results
+      sorted = @@results.sort_by { |k| k[:status] }
+      if @@strip_zero == true
+        return sorted.reject { |capture| true if capture[:result] == "0" }
+      else
+        return sorted
+      end
+    end
+
+
+    def self.sanitize_results(data)
+      data.each do | hash |
+        hash[:result] = 'image mismatch' if hash[:result].match(/compare/)
+      end
+    end
+
+    def self.the_results
+      sorted = @@results.sort_by { |k| k[:status] }
+
+      sanitize_results(sorted)
+
+      if @@strip_zero
+        return sorted.reject { |cap| true if cap[:result] == "0" }
+      else
+        return sorted
+      end
+
+    end
+
+  end
+end

data/lib/watircats/config.rb

@@ -0,0 +1,58 @@
+module WatirCats
+  
+  @@config = nil
+
+  # Create a new Config object to store our settings
+  def self.configure( options_hash )
+    # Only allows for one time creation of the config
+    if @@config.is_a? Config
+      update_config( options_hash )
+    else
+      @@config = Config.new( options_hash )
+    end
+    # Return the @@config for chaining
+    @@config
+  end
+
+  # This allows us to get the config setting from anywhere within WatirCats
+  # by using WatirCats.config.setting_name
+  def self.config
+    # Return the @@config class var to allow chaining for values
+    @@config
+  end
+
+  def self.update_config( options_hash )
+    # Instantiate a new Config unless @@config already is a Config object
+    @@config = Config.new({ }) unless @@config.is_a? Config
+    options_hash.each do |key, value| 
+      @@config.new_key( key, value )
+    end
+  end
+
+  # Create a configuration object
+  class Config
+
+    def initialize( options_hash )
+      # Iterate through the options hash, setting each key as an instance
+      # variable, and creating a getter method with the same name
+      options_hash.each do |key, value|
+        new_key(key, value)
+      end
+    end
+
+    def new_key(key, value)
+      # define getter
+      instance_eval( "def #{key}; @#{key}; end" ) unless self.respond_to? "#{key}"
+      # define setter
+      instance_eval( "def #{key}= (v); @#{key} = v; end" ) unless self.respond_to? "#{key}="
+      # Set the value on the instance variable, creating if necessary
+      instance_variable_set( "@#{key}".to_sym, value )
+    end
+
+    def method_missing( meth, *args, &blk )
+      # Return nil if an expected parameter isn't here. No need to die.
+      nil
+    end
+
+  end
+end