kontrast 0.2.1

data/lib/kontrast/config/template.rb

@@ -0,0 +1,27 @@
+# This should get you up and running
+# Check out the full list of config options at:
+# https://github.com/harrystech/kontrast
+
+Kontrast.configure do |config|
+    # This is the address of your local server
+    config.test_domain = "http://localhost:3000"
+
+    # This is the address of your production server
+    config.production_domain = "http://www.example.com"
+
+    # Set this to true if you want Kontrast to return
+    # an exit code of 1 if any diffs are found
+    config.fail_build = false
+
+    # These tests will open in a 1280px-wide browser window
+    config.pages(1280) do |page|
+        page.home "/"
+        page.about "/about"
+    end
+
+    # These tests will open in a 320px-wide browser window
+    config.pages(320) do |page|
+        page.home "/"
+        page.about "/about"
+    end
+end

data/lib/kontrast/configuration.rb

@@ -0,0 +1,124 @@
+module Kontrast
+    class << self
+        attr_accessor :configuration, :test_suite
+
+        def configure
+            self.configuration ||= Configuration.new
+            yield(configuration)
+        end
+
+        def tests
+            self.test_suite ||= TestBuilder.new
+        end
+    end
+
+    class Configuration
+        attr_accessor :run_parallel, :total_nodes, :current_node
+        attr_accessor :_before_run, :_after_run, :_before_gallery, :_after_gallery, :_before_screenshot, :_after_screenshot
+        attr_accessor :distortion_metric, :highlight_color, :lowlight_color
+        attr_accessor :local_path, :remote_path, :aws_bucket, :aws_key, :aws_secret
+        attr_accessor :test_domain, :production_domain
+        attr_accessor :browser_driver, :browser_profile
+        attr_accessor :fail_build
+
+        def initialize
+            # Set defaults
+            @browser_driver = "firefox"
+            @browser_profile = {}
+
+            @run_parallel = false
+            @total_nodes = 1
+            @current_node = 0
+
+            @distortion_metric = "MeanAbsoluteErrorMetric"
+            @highlight_color = "blue"
+            @lowlight_color = "rgba(255, 255, 255, 0.3)"
+
+            @fail_build = false
+        end
+
+        def validate
+            # Check that Kontrast has everything it needs to proceed
+            check_nil_vars(["test_domain", "production_domain"])
+            if Kontrast.test_suite.nil?
+                raise ConfigurationException.new("Kontrast has no tests to run.")
+            end
+
+            # If remote, check for more options
+            if @run_parallel
+                check_nil_vars(["aws_bucket", "aws_key", "aws_secret"])
+                check_nil_vars(["local_path", "remote_path"])
+
+                # Make sure total nodes is >= 1 so we don't get divide by 0 errors
+                if @total_nodes < 1
+                    raise ConfigurationException.new("total_nodes cannot be less than 1.")
+                end
+            end
+        end
+
+        def pages(width)
+            if !block_given?
+                raise ConfigurationException.new("You must pass a block to the pages config option.")
+            end
+            Kontrast.tests.add_width(width)
+            yield(Kontrast.tests)
+        end
+
+        def before_run(&block)
+            if block_given?
+                @_before_run = block
+            else
+                @_before_run.call if @_before_run
+            end
+        end
+
+        def after_run(&block)
+            if block_given?
+                @_after_run = block
+            else
+                @_after_run.call if @_after_run
+            end
+        end
+
+        def before_gallery(&block)
+            if block_given?
+                @_before_gallery = block
+            else
+                @_before_gallery.call if @_before_gallery
+            end
+        end
+
+        def after_gallery(diffs = nil, gallery = nil, &block)
+            if block_given?
+                @_after_gallery = block
+            else
+                @_after_gallery.call(diffs, gallery) if @_after_gallery
+            end
+        end
+
+        def before_screenshot(test_driver = nil, production_driver = nil, current_test = nil, &block)
+            if block_given?
+                @_before_screenshot = block
+            else
+                @_before_screenshot.call(test_driver, production_driver, current_test) if @_before_screenshot
+            end
+        end
+
+        def after_screenshot(test_driver = nil, production_driver = nil, current_test = nil, &block)
+            if block_given?
+                @_after_screenshot = block
+            else
+                @_after_screenshot.call(test_driver, production_driver, current_test) if @_after_screenshot
+            end
+        end
+
+        private
+            def check_nil_vars(vars)
+                vars.each do |var|
+                    if instance_variable_get("@#{var}").nil?
+                        raise ConfigurationException.new("Kontrast config is missing the #{var} option.")
+                    end
+                end
+            end
+    end
+end

data/lib/kontrast/exceptions.rb

@@ -0,0 +1,5 @@
+module Kontrast
+    class ConfigurationException < Exception; end
+    class GalleryException < Exception; end
+    class RunnerException < Exception; end
+end

data/lib/kontrast/gallery/template.erb

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css">
+        <style type="text/css">
+            .short-screenshot {
+                height: 200px;
+                width: 200px;
+            }
+        </style>
+    </head>
+    <body>
+        <div class="container">
+            <div class="row page-header">
+                <h1>Kontrast Gallery</h1>
+            </div>
+            <div class="row">
+                <div class="col-lg-2">
+                    <div class="panel">
+                        <div class="panel-heading">Screenshots:</div>
+                        <ul class="list-group list-group-flush">
+                            <% directories.keys.sort.each do |size| %>
+                                <li class="list-group-item"><strong><%=size%></strong></li>
+                                <% directories[size].keys.each do |name| %>
+                                    <li class="list-group-item"><a href="#<%= "#{size}_#{name}" %>"><%=name%></a></li>
+                                <% end %>
+                            <% end %>
+                        </ul>
+                    </div>
+                </div>
+                <div class="col-lg-10">
+                    <% if diffs.any? %>
+                        <div class="row">
+                            <div class="alert alert-warning" role="alert">
+                                Tests with diffs:
+                                <ul>
+                                    <% diffs.each do |test, diff| %>
+                                        <li>
+                                            <a href="#<%= test %>"><%= test %></a>
+                                        </li>
+                                    <% end %>
+                                </ul>
+                            </div>
+                        </div>
+                    <% end %>
+
+                    <% directories.keys.sort.each do |size| %>
+                        <div class="row">
+                            <a name="<%= size %>"></a>
+                            <h2><%= size %></h2>
+                        </div>
+
+                        <% directories[size].each do |comparison| %>
+                            <div id="<%= "#{size}_#{comparison.first}" %>" class="row">
+                                <div class="row">
+                                    <h2><%= comparison.first %></h2>
+                                </div>
+                                <% comparison.last[:variants].each do |file| %>
+                                    <div class="col-lg-3">
+                                        <a href="<%=file[:image]%>">
+                                            <img class="short-screenshot img-thumbnail" src="<%=file[:thumb]%>">
+                                        </a>
+                                        <p class="text-center"><%=file[:domain]%></p>
+                                        <% if file[:diff_amt] %>
+                                            <p class="text-center text-muted"><%=file[:diff_amt]%></p>
+                                        <% end %>
+                                    </div>
+                                <% end %>
+                            </div>
+                        <% end %>
+                    <% end %>
+                </div>
+            </div>
+        </div>
+    </body>
+</html>

data/lib/kontrast/gallery_creator.rb

@@ -0,0 +1,164 @@
+require "erb"
+require "json"
+
+module Kontrast
+    class GalleryCreator
+        def initialize(path)
+            @path = path || Kontrast.path
+        end
+
+        # This gets run only once per suite. It collects the manifests from all nodes
+        # and uses them to generate a nice gallery of images.
+        def create_gallery(output_dir)
+            begin
+                @gallery_dir = FileUtils.mkdir_p("#{output_dir}/gallery").join('')
+            rescue Exception => e
+                raise GalleryException.new("An unexpected error occurred while trying to create the gallery's output directory: #{e.inspect}")
+            end
+
+            # Get and parse manifests
+            parsed_manifests = parse_manifests(get_manifests)
+            files = parsed_manifests[:files]
+            diffs = parsed_manifests[:diffs]
+
+            # Generate HTML
+            html = generate_html(files, diffs)
+
+            # Write file
+            File.open("#{@gallery_dir}/gallery.html", 'w') do |outf|
+                outf.write(html)
+            end
+
+            # Upload file
+            if Kontrast.configuration.run_parallel
+                Kontrast.fog.directories.get(Kontrast.configuration.aws_bucket).files.create(
+                    key: "#{Kontrast.configuration.remote_path}/gallery/gallery.html",
+                    body: File.open("#{@gallery_dir}/gallery.html")
+                )
+            end
+
+            # Return diffs and gallery path
+            return {
+                diffs: diffs,
+                path: "#{@gallery_dir}/gallery.html"
+            }
+        end
+
+        def generate_html(files, diffs)
+            # Template variables
+            directories = parse_directories(files, diffs)
+
+            # HTML
+            template = File.read(Kontrast.root + '/lib/kontrast/gallery/template.erb')
+            return ERB.new(template).result(binding)
+        end
+
+        def get_manifests
+            if Kontrast.configuration.run_parallel
+                # Download manifests
+                files = Kontrast.fog.directories.get(Kontrast.configuration.aws_bucket, prefix: "#{Kontrast.configuration.remote_path}/manifest").files
+                files.each do |file|
+                    filename = "#{@path}/" + file.key.split('/').last
+                    File.open(filename, 'w') do |local_file|
+                        local_file.write(file.body)
+                    end
+                end
+            end
+            manifest_files = Dir["#{@path}/manifest_*.json"]
+            return manifest_files
+        end
+
+        def parse_manifests(manifest_files)
+            files = []
+            diffs = {}
+            manifest_files.each do |manifest|
+                manifest = JSON.parse(File.read(manifest))
+                files.concat(manifest['files'])
+                diffs.merge!(manifest["diffs"])
+            end
+
+            return {
+                files: files,
+                diffs: diffs
+            }
+        end
+
+        # This function just turns the list of files and diffs into a hash that the gallery
+        # creator can insert into a template. See an example of the created hash below.
+        def parse_directories(files, diffs)
+            files.sort!
+
+            dirs = {}
+            directories = files.map { |f| f.split('/').first }.uniq
+
+            # Get all sizes
+            sizes = directories.map { |d| d.split('_').first }
+            sizes.each { |size|
+                dirs[size] = {}
+
+                # Get all directories for this size
+                tests_for_size = directories.select { |d| d.index(size + "_") == 0 }
+                tests_for_size.each do |dir|
+                    array = dir.split('_')
+                    array.delete_at(0)
+                    test_name = array.join('_')
+                    dirs[size][test_name] = {
+                        variants: []
+                    }
+                end
+            }
+
+            # This determines where to display images from in the gallery
+            if Kontrast.configuration.run_parallel
+                # Build the remote path to S3
+                base_path = "https://#{Kontrast.configuration.aws_bucket}.s3.amazonaws.com/#{Kontrast.configuration.remote_path}"
+            else
+                base_path = ".."
+            end
+
+            # Fill in the files as variants
+            directories.each do |directory|
+                array = directory.split('_')
+                size = array.first
+                array.delete_at(0)
+                test_name = array.join('_')
+
+                # Add variations
+                ['test', 'production', 'diff'].each_with_index do |type, i|
+                    dirs[size][test_name][:variants] << {
+                        image: "#{base_path}/#{size}_#{test_name}/" + type + ".png",
+                        thumb: "#{base_path}/#{size}_#{test_name}/" + type + "_thumb.png",
+                        domain: type
+                    }
+                    if type == 'diff'
+                        dirs[size][test_name][:variants][i][:diff_amt] = (diffs["#{size}_#{test_name}"]) ? diffs["#{size}_#{test_name}"]["diff"] : 0
+                    end
+                end
+            end
+
+            return dirs
+
+            # For reference
+            # gallery_format = {
+            #     "1080" => {
+            #         "name" => {
+            #             variants: [{
+            #                 image: "full_img_src",
+            #                 thumb: "thumb_src",
+            #                 domain: "production"
+            #             }, {
+            #                 image: "foo_src",
+            #                 thumb: "thumb_src",
+            #                 domain: "test"
+            #             }, {
+            #                 image: "diff_src",
+            #                 thumb: "diff_thumb_src",
+            #                 domain: "diff",
+            #                 size: 0.1
+            #             }]
+            #         }
+            #     }
+            # }
+        end
+    end
+end

data/lib/kontrast/image_handler.rb

@@ -0,0 +1,119 @@
+require "RMagick"
+require "workers"
+
+module Kontrast
+    class ImageHandler
+        include Magick
+        attr_reader :diffs, :path
+
+        def initialize
+            @path = Kontrast.path
+
+            # This is where failed diffs will be stored
+            @diffs = {}
+        end
+
+        # In order for images to be diff'ed, they need to have the same dimensions
+        def crop_images(width, name)
+            # Load images
+            test_image = Image.read("#{@path}/#{width}_#{name}/test.png").first
+            production_image = Image.read("#{@path}/#{width}_#{name}/production.png").first
+
+            # Let's not do anything if the images are already the same size
+            return if test_image.rows == production_image.rows
+
+            # Get max height of both images
+            max_height = [test_image.rows, production_image.rows].max
+
+            # Crop
+            Workers.map([test_image, production_image]) do |image|
+                image.extent(width, max_height).write(image.filename)
+            end
+        end
+
+        # Uses the compare_channel function to highlight the differences between two images
+        # Docs: http://www.imagemagick.org/RMagick/doc/image1.html#compare_channel
+        def diff_images(width, name)
+            # Load images
+            test_image = Image.read("#{@path}/#{width}_#{name}/test.png").first
+            production_image = Image.read("#{@path}/#{width}_#{name}/production.png").first
+
+            # Compare and save diff
+            diff = test_image.compare_channel(production_image, Magick.const_get(Kontrast.configuration.distortion_metric)) do |options|
+                options.highlight_color = Kontrast.configuration.highlight_color
+                options.lowlight_color = Kontrast.configuration.lowlight_color
+            end
+            diff.first.write("#{@path}/#{width}_#{name}/diff.png")
+
+            # If the images are different, let the class know about it so that it gets added to the manifest
+            if diff.last > 0
+                @diffs["#{width}_#{name}"] = {
+                    width: width,
+                    name: name,
+                    diff: diff.last
+                }
+            end
+        end
+
+        # For the gallery. Not sure if this is really necessary.
+        def create_thumbnails(width, name)
+            # Load images
+            test_image = Image.read("#{@path}/#{width}_#{name}/test.png").first
+            production_image = Image.read("#{@path}/#{width}_#{name}/production.png").first
+            diff_image = Image.read("#{@path}/#{width}_#{name}/diff.png").first
+
+            # Crop images
+            Workers.map([test_image, production_image, diff_image]) do |image|
+                filename = image.filename.split('/').last.split('.').first + "_thumb"
+                image.resize_to_fill(200, 200, NorthGravity).write("#{@path}/#{width}_#{name}/#{filename}.png")
+            end
+        end
+
+        # We upload the images per test
+        def upload_images(width, name)
+            Workers.map(Dir.entries("#{@path}/#{width}_#{name}")) do |file|
+                next if ['.', '..'].include?(file)
+                Kontrast.fog.directories.get(Kontrast.configuration.aws_bucket).files.create(
+                    key: "#{Kontrast.configuration.remote_path}/#{width}_#{name}/#{file}",
+                    body: File.open("#{@path}/#{width}_#{name}/#{file}"),
+                    public: true
+                )
+            end
+        end
+
+        # The manifest is a per-node .json file that is used to create the gallery
+        # without having to download all assets from S3 to the test environment
+        def create_manifest(current_node, build = nil)
+            # Set up structure
+            manifest = {
+                diffs: @diffs,
+                files: []
+            }
+
+            # Dump directories
+            Dir.foreach(@path) do |subdir|
+                next if ['.', '..'].include?(subdir)
+                next if subdir.index('manifest_')
+                Dir.foreach("#{@path}/#{subdir}") do |img|
+                    next if ['.', '..'].include?(img)
+                    manifest[:files] << "#{subdir}/#{img}"
+                end
+            end
+
+            if Kontrast.configuration.run_parallel
+                # Upload manifest
+                Kontrast.fog.directories.get(Kontrast.configuration.aws_bucket).files.create(
+                    key: "#{build}/manifest_#{current_node}.json",
+                    body: manifest.to_json
+                )
+            else
+                # Write manifest
+                File.open("#{@path}/manifest_#{current_node}.json", 'w') do |outf|
+                    outf.write(manifest.to_json)
+                end
+            end
+
+            return manifest
+        end
+    end
+end