pixage 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 52d34826bb6e2ef1a6082661f16303ca8f46a8f3
+  data.tar.gz: 38dcd13502b36e1c36b04b6b3ce4c9722b52dc65
+SHA512:
+  metadata.gz: 5b575bfbffeb7dbac743eb0f4ce04e072ba8369f6bea694266ffe4a74536fcf63c566a1b1a1b8f6b4485dea2c3968ee8970e74344c00533b0f0ce955c2df0bc9
+  data.tar.gz: edc6b627e69626ffaa78f69647ad732f4c88226c00bc2bb00406f535a61028ab0d08b4d512ca50f5f96ec06eed58208076e2ae7ca627358bdc0c5aaf7de13817

data/LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2015-2016 Kaushal Rupani
+
+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,107 @@
+# pixage
+
+**PIX**el perfect application using visual regression testing with help of im**AGE**-magick gives birth to **PIXAGE**    
+Pixels + Image = Pixage    
+    
+A utility which can be used manually or be integrated with an existing selenium-ruby or appium-ruby automation framework to perform __*visual regression testing*__ of screenshots.
+
+
+## Table of contents
+- [Installation](#installation)  
+    - [Install using gem command](#gem)    
+    - [Install using bundler](#bundler)
+- [Dependency](#dependency)
+- [Usage](#usage)
+    - [CLI Usage](#cli)
+    - [Automation Usage](#automation)
+- [Contributing](#contributing)   
+- [Issues](#issues)     
+    
+
+## Installation  
+There are multiple ways in which you can install and use pixage gem.
+You must have Ruby installed before you can install this gem.   
+
+### <a name="gem" /> 1. Install using gem command 
+Just use following command from you Terminal.   
+``` 
+gem install pixage 
+```
+   
+### <a name="bundler" /> 2. Install using bundler    
+You can include it in your Gemfile and run bundle install.     
+``` 
+gem 'pixage' 
+```   
+then run following   
+```   
+bundle install   
+```  
+
+## Dependency   
+This gem is dependent on ImageMagick. Please install latest verison of ImageMagick before you start using pixage.   
+To verify if imagemagick is successfully installed, please run the following command (After installaing pixage).   
+```   
+pixage diagnosis 
+```    
+   
+## Usage   
+There are 2 ways this gem can be used. 
+1. CLI usage which can be really helpful for testers and designers to do visual regression testing manually.
+2. Can be integrated with automation suite to compare run time screenshots with pre-saved baseline images.  
+
+### <a name="cli"></a> 1. CLI Usage
+Following are the list of commands :  
+    
+![help, diagnosis, compare, resize_n_compare, version](https://github.com/krupani/pixage/blob/master/images/pixage_commands.png)    
+
+Basic usage in case of compare 2 images which are similar size and resolution:   
+```   
+# Basic usage with default options    
+pixage compare images/expected.png images/actual.png    
+
+# Basic usage with custom options
+pixage compare images/expected.png images/actual.png --threshold=1 --fuzz=25 --color=red
+
+```   
+    
+For further commmand usage [documentation](https://github.com/krupani/pixage/wiki), please refer the [wiki](https://github.com/krupani/pixage/wiki) section.    
+
+### <a name="automation"></a> 2. Automation Usage    
+Apart from CLI usage, pixage gem can also be integrated with automation suite be it a selenium-webdriver-ruby for web application or appium-ruby for mobile applications or just a ruby script acheieving some fine purpose.     
+Below is the code snippet to be used in case of automation integration:
+
+```
+# First, as mentioned in installation step, include gem in Gemfile
+gem 'pixage'        
+    
+# Next, require and include it in your project
+require 'pixage'    
+include 'Pixage'     
+
+# Finally use the commands in your code:    
+# Assuming you have your baseline/expected image previously stored
+@driver.save_screenshot(actual.png)
+resize_n_compare(expected.png, actual.png)
+
+# Also you can compare 2 runtime images like:
+@driver.save_screenshot(first.png)
+@driver.save_screenshot(second.png)
+compare(first.png, second.png)
+
+```
+
+_NOTE: To see a working example on how to integrate pixage with a Ruby-Cucumber-Selenium tests, please see the examples directory. It also has a sample report stored for reference._    
+    
+To execute the example, do the following:
+- Clone the repo `git clone https://github.com/krupani/pixage.git`   
+- get into the examples folder `cd pixage/examples`    
+- install dependent gems or just run `bundle install`
+    - if you dont have bundler installed then first run `gem install bundler` and then repeat above step   
+- execute the tests `cucumber features BROWSER=chrome` , provided you have chromedriver in your PATH    
+
+## Contributing   
+Ideas and suggestions are always always most welcome. Please fork this gem and feel free to add any updates, suggestions etc and create a pull request.  
+
+## Issues
+If you face any problem related to syntax, usability, documentation then please raise an [issue](https://github.com/krupani/pixage/issues)    

data/bin/pixage

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+
+require "pixage/diagnosis"
+require "pixage/cli"
+include Pixage
+
+def show_help
+  puts <<HELP
+
+    Commands        :
+
+      help        
+      ----
+      Description   : Prints help information
+      Usage         : pixage help
+
+
+      diagnosis
+      ---------
+      Description   : Performs a check to see all dependecies match for smooth execution of pixage gem commands
+      Usage         : pixage diagnosis 
+
+
+      compare
+      -------
+      Description   : Compares 2 images and generates diff (compares original images and just generates a diff image)
+      Usage         : pixage compare <expected_image_path> <actual_image_path> <--option=value>
+      Options       : 1. --threshold (optional) : maximum distortion allowed while matching (default = 1)
+                      2. --fuzz (optional)      : fuzz distance between colours (default = 20)
+                      3. --color (optional)     : highlight pixel difference with this color (default = blue)
+
+
+      resize_n_compare 
+      ----------------
+      Description   : Resizes the images and then compares (makes a copy of original images before resizing)
+                      (By default the larger images is resized to the smaller image to avoid pixelating.)
+      Usage         : pixage resize_n_compare <expected_image_path> <actual_image_path> <--option=value>
+      options       : 1. --threshold (optional) : maximum distortion allowed while matching (default = 1)
+                      2. --fuzz (optional)      : fuzz distance between colours (default = 20)
+                      3. --color (optional)     : highlight pixel difference with this color (default = blue)
+                      4. --resize (optional)    : a. desc (default) : for resizing larger image to smaller one
+                                                  b. asc : for resizing smaller image to larger one (image can pixelate)
+                      5. --force (options)      : force=true will ignore aspect ratio while resizing (default=false)
+
+
+      version
+      -------
+      Description : Shows the version of pixage gem
+      Usage       : pixage version | pixage --version | pixage -v
+
+HELP
+end
+
+def arg_to_hash(args)
+  arg_hash = {}
+  args.each do |arg|
+    arg_arr = arg.gsub("-","").split("=")
+    arg_hash[arg_arr.first.downcase.to_sym] = arg_arr.last.downcase
+  end
+  arg_hash
+end
+
+
+if ARGV.length == 0
+    show_help
+else
+  cmd = ARGV.shift
+  case cmd
+  
+  when 'version', '--version', '-v'
+    puts File.read(File.expand_path("../../lib/pixage/version", __FILE__))
+  
+  when 'diagnosis'
+    Pixage::Diagnosis.new().perform_diagnosis
+
+  when 'compare'
+    if ARGV.size<2
+      show_help 
+    elsif ARGV.size==2
+      compare(ARGV.shift, ARGV.shift)
+    else
+      compare(ARGV.shift, ARGV.shift, arg_to_hash(ARGV))
+    end
+  
+  when 'resize_n_compare'
+    if ARGV.size<2
+      show_help
+    elsif ARGV.size==2
+      resize_n_compare(ARGV.shift, ARGV.shift)
+    else
+      resize_n_compare(ARGV.shift, ARGV.shift, arg_to_hash(ARGV))
+    end
+
+  else
+    show_help
+  end
+
+end
+
+
+
+
+
+

data/data/defaults.yml

@@ -0,0 +1,5 @@
+:fuzz: 20
+:threshold: 1
+:color: "blue"
+:resize: "desc"
+:force: false

data/lib/pixage.rb

@@ -0,0 +1 @@
+require 'pixage/cli'

data/lib/pixage/cli.rb

@@ -0,0 +1,32 @@
+require_relative 'params'
+require_relative 'images/compare'
+
+module Pixage
+
+	# @method compare(expected_image_file_path, actual_image_file_path, options={})
+    # @param expected_image_file_path [String] 
+    # @param actual_image_file_path [String]
+    # @parm args [Hash]
+    # @return [String] -- file path of the diff.png file
+
+	def compare(expected, actual, args={})
+		images = manage_paths(expected,actual)
+		options = manage_options(args)
+		create_pixage_report_dir
+  		Compare.new.compare_images(images,options)
+	end
+
+
+	# @method resize_n_compare(expected_image_file_path, actual_image_file_path, options={})
+    # @param expected_image_file_path [String] 
+    # @param actual_image_file_path [String]
+    # @params args [Hash]
+    # @return [String] -- file path of the diff.png file
+
+	def resize_n_compare(expected, actual, args={})
+		images = manage_paths(expected,actual)
+		options = manage_options(args)
+		create_pixage_report_dir
+  		Compare.new.resize_n_compare_images(images,options)
+	end
+end

data/lib/pixage/diagnosis.rb

@@ -0,0 +1,29 @@
+require 'logger'
+
+module Pixage
+
+	class Diagnosis
+
+		def perform_diagnosis
+  			check_image_magick_installation
+  			# check_idevice_installation
+  			# check_adb_installation
+		end
+
+		def check_image_magick_installation
+			puts "Checking ImageMagick installation.."
+			version = `magick -version | grep -i version`
+			if version.class == String and version.include?("ImageMagick")
+				console_log("ImageMagick is INSTALLED", :pass)
+			else
+				console_log("ImageMagick is NOT INSTALLED", :error)
+			end
+		end
+
+		private :check_image_magick_installation 
+
+	end
+
+end
+
+

data/lib/pixage/images/compare.rb

@@ -0,0 +1,52 @@
+require 'mini_magick'
+require 'fileutils'
+require 'pathname'
+require_relative 'convert'
+require_relative '../params'
+require_relative '../logger'
+
+module Pixage
+
+	class Compare
+
+		def compare_images(images,options)
+			convert = Convert.new()
+			if convert.check_sizes(images)
+				console_log("Warning: Image sizes are not equal, the generated diff might be misleading, please use : ", :warning)
+				console_log("pixage resize_n_compare\n", :pass)
+			end
+			execution_dir = Time.now.strftime("%d-%b-%y-%H-%M-%S")
+			create_compare_execution_dir(execution_dir)
+			cmd = "compare -dissimilarity-threshold #{options[:threshold]} -fuzz #{options[:fuzz]} -metric AE -highlight-color #{options[:color]} #{images[:expected]} #{images[:actual]} pixage_report/#{execution_dir}/diff.png"
+			execute_command(cmd)
+			Pathname.new("pixage_report/#{execution_dir}/diff.png").realpath.to_s
+		end
+
+		def resize_n_compare_images(images,options)
+			convert = Convert.new()
+			execution_dir = Time.now.strftime("%d-%b-%y-%H-%M-%S")
+			create_compare_execution_dir(execution_dir)
+			images = make_copies(images, "pixage_report/#{execution_dir}")
+			convert.resize_images(images,options)
+			cmd = "compare -dissimilarity-threshold #{options[:threshold]} -fuzz #{options[:fuzz]} -metric AE -highlight-color #{options[:color]} #{images[:expected]} #{images[:actual]} pixage_report/#{execution_dir}/diff.png"
+			execute_command(cmd)
+			Pathname.new("pixage_report/#{execution_dir}/diff.png").realpath.to_s
+		end
+
+		def execute_command(cmd)
+			require 'open3'
+			cmd_out = Open3.popen3(cmd)[2].read
+		end
+
+		def make_copies(images,path)
+			ts = Time.now.to_i
+			expected = Pathname.new(path+"/expected_#{ts}#{File.extname(images[:expected])}")
+			actual = Pathname.new(path+"/actual_#{ts}#{File.extname(images[:actual])}")
+			FileUtils.cp(images[:expected], expected)
+			FileUtils.cp(images[:actual], actual)
+			{:expected => expected.realpath, :actual => actual.realpath}
+		end
+
+		private :execute_command, :make_copies
+	end
+end

data/lib/pixage/images/convert.rb

@@ -0,0 +1,42 @@
+require 'mini_magick'
+require_relative '../logger'
+
+module Pixage
+
+	class Convert
+
+		def check_sizes(images)
+			expected = MiniMagick::Image.new(images[:expected])
+			actual = MiniMagick::Image.new(images[:actual])
+			expected.dimensions != actual.dimensions
+		end
+
+		def resize_images(images,options={:resize => "desc", :force => "false"})
+			expected = MiniMagick::Image.new(images[:expected])
+			actual = MiniMagick::Image.new(images[:actual])
+			switch = 0
+			if options[:resize]=="desc"
+				switch = expected.dimensions <=> actual.dimensions
+			elsif options[:resize]=="asc"
+				switch = actual.dimensions <=> expected.dimensions
+			end
+
+			case switch
+			when 1
+				if options[:force]=="true"
+					expected.resize(actual.dimensions.join('x')+"!")
+				else
+					expected.resize(actual.dimensions.join('x'))
+				end
+			when -1
+				if options[:force]=="true"
+					actual.resize(expected.dimensions.join('x')+"!")
+				else
+					actual.resize(expected.dimensions.join('x'))
+				end
+			end
+		end
+		
+	end	
+
+end

data/lib/pixage/logger.rb

@@ -0,0 +1,19 @@
+require 'colorize'
+
+module Pixage
+
+	def console_log(text, status, loud=false)
+		text=text.upcase if loud
+		case status.downcase.to_sym
+		when :warning
+			puts text.yellow
+		when :error, :exception
+			puts text.red
+		when :pass, :success
+			puts text.green
+		else
+			puts text
+		end
+	end
+
+end

data/lib/pixage/params.rb

@@ -0,0 +1,48 @@
+require 'pathname'
+require 'yaml'
+
+module Pixage
+
+	def manage_paths(expected,actual)
+		images = {}
+		expected = Pathname.new(expected)
+		actual = Pathname.new(actual)
+		if expected.relative?
+			images[:expected] = expected.realpath
+		end
+		if actual.relative?
+			images[:actual] = actual.realpath
+		end
+		images
+	end
+
+	def manage_options(args={})
+		options = YAML.load_file(File.join(File.dirname(__FILE__) + "/../../data/defaults.yml"))
+		args.each do |key,val|
+			if key.downcase == :fuzz
+				options[:fuzz] = val.to_i
+			elsif key.downcase == :threshold
+				options[:threshold] = val.to_i
+			elsif key.downcase == :color
+				options[:color] = val.to_s.downcase
+			elsif key.downcase == :resize
+				options[:resize] = val.to_s.downcase
+			elsif key.downcase == :force
+				options[:force] = val.to_s.downcase
+			else
+				console_log("Unrecognised option `--#{key}=#{val}`, defaults will be applied.", :warning)
+			end
+		end
+		return options
+	end
+
+	def create_pixage_report_dir
+		Dir.mkdir("pixage_report") unless Dir.exists?("pixage_report")
+	end
+
+	def create_compare_execution_dir(dir_name)
+		create_pixage_report_dir
+		Dir.mkdir("pixage_report/#{dir_name}")
+	end
+
+end

data/lib/pixage/version

@@ -0,0 +1 @@
+0.1

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: pixage
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Kaushal Rupani
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-03-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mini_magick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: colorize
+  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'
+description: A visual regression utility with options to do single and bulk operations
+  both manually and integrable with Selenium automated tests in Ruby.
+email:
+- kushrupani@live.com
+executables:
+- pixage
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENCE
+- README.md
+- bin/pixage
+- data/defaults.yml
+- lib/pixage.rb
+- lib/pixage/cli.rb
+- lib/pixage/diagnosis.rb
+- lib/pixage/images/compare.rb
+- lib/pixage/images/convert.rb
+- lib/pixage/logger.rb
+- lib/pixage/params.rb
+- lib/pixage/version
+homepage: https://github.com/krupani/pixage
+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:
+- You must have ImageMagick installed on your system.
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: A visual regression utility with options to do single and bulk operations
+  both manually and integrable with Selenium automated tests in Ruby.
+test_files: []