RubyGems - happo - Versions diffs - 1.0.0 - Mend

happo 1.0.0

Files changed (23) hide show

checksums.yaml +7 -0
data/bin/happo +60 -0
data/lib/happo/action.rb +33 -0
data/lib/happo/diffs.html.erb +29 -0
data/lib/happo/logger.rb +40 -0
data/lib/happo/public/happo-runner.js +223 -0
data/lib/happo/public/happo-styles.css +8 -0
data/lib/happo/runner.rb +215 -0
data/lib/happo/server.rb +68 -0
data/lib/happo/snapshot_comparer.rb +91 -0
data/lib/happo/snapshot_comparison_image/after.rb +21 -0
data/lib/happo/snapshot_comparison_image/base.rb +108 -0
data/lib/happo/snapshot_comparison_image/before.rb +21 -0
data/lib/happo/snapshot_comparison_image/gutter.rb +34 -0
data/lib/happo/snapshot_comparison_image/overlayed.rb +88 -0
data/lib/happo/uploader.rb +70 -0
data/lib/happo/utils.rb +81 -0
data/lib/happo/version.rb +4 -0
data/lib/happo/views/debug.erb +29 -0
data/lib/happo/views/index.erb +27 -0
data/lib/happo/views/review.erb +37 -0
data/lib/happo.rb +6 -0
metadata +191 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 73690fa08fbd1338fc72d65f287329375b2a57ef
+  data.tar.gz: 8ff2614642f52154b7dbf7faccb75f01d98acdd5
+SHA512:
+  metadata.gz: aa3ca88236618c91bad015f6d44188bf8799a1b5952d1f1e2c10745d2fcf425911605d089785bd6f1527d0b242615200d85ea7e076c4942379ef2ba8f8d6489c
+  data.tar.gz: ad36897001417b3dfe313e2c6ebf3448b9a6c42064c23ccf14a571c16c290505ec4d8ae2387aa4c7642b99e27431eb11eb74f1c7098e1d85232cbed65c01a203

data/bin/happo ADDED Viewed

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+require 'happo'
+require 'fileutils'
+help_text = <<-EOS
+Commands:
+  run (default)
+  debug
+  review
+  clean
+  approve
+  reject
+  upload_diffs
+  --help
+  --version
+  EOS
+action = ARGV[0] || 'run'
+case action
+when 'run'
+  Thread.abort_on_exception = true
+  Thread.new do
+    require 'happo/runner'
+    exit
+  end
+  require 'happo/server'
+when 'debug'
+  system 'open', Happo::Utils.construct_url('/debug')
+  require 'happo/server'
+when 'review'
+  system 'open', Happo::Utils.construct_url('/review')
+  require 'happo/server'
+when 'clean'
+  if File.directory? Happo::Utils.config['snapshots_folder']
+    FileUtils.remove_entry_secure Happo::Utils.config['snapshots_folder']
+  end
+when 'approve', 'reject'
+  example_description = ARGV[1]
+  abort 'Missing example description' unless example_description
+  viewport_name = ARGV[2]
+  abort 'Missing viewport name' unless viewport_name
+  Happo::Action.new(example_description, viewport_name).send(action)
+when 'upload_diffs'
+  # `upload_diffs` returns a URL to a static html file
+  puts Happo::Uploader.new.upload_diffs
+when '--version'
+  puts "happo version #{Happo::VERSION}"
+when '--help'
+  puts help_text
+else
+  abort "Unknown action \"#{action}\"\n\n#{help_text}"
+end

data/lib/happo/action.rb ADDED Viewed

@@ -0,0 +1,33 @@
+require 'happo/utils'
+require 'fileutils'
+module Happo
+  class Action
+    def initialize(example_description, viewport_name)
+      @example_description = example_description
+      @viewport_name = viewport_name
+    end
+    def approve
+      diff_path = Happo::Utils.path_to(
+        @example_description, @viewport_name, 'diff.png')
+      baseline_path = Happo::Utils.path_to(
+        @example_description, @viewport_name, 'baseline.png')
+      candidate_path = Happo::Utils.path_to(
+        @example_description, @viewport_name, 'candidate.png')
+      FileUtils.rm(diff_path, force: true)
+      FileUtils.mv(candidate_path, baseline_path) if File.exist? candidate_path
+    end
+    def reject
+      diff_path = Happo::Utils.path_to(
+        @example_description, @viewport_name, 'diff.png')
+      candidate_path = Happo::Utils.path_to(
+        @example_description, @viewport_name, 'candidate.png')
+      FileUtils.rm(diff_path, force: true)
+      FileUtils.rm(candidate_path, force: true)
+    end
+  end
+end

data/lib/happo/diffs.html.erb ADDED Viewed

@@ -0,0 +1,29 @@
+<% require 'rack' %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Happo diffs</title>
+  </head>
+  <body>
+    <h1>Happo diffs</h1>
+    <p>File generated: <%= Time.now %></p>
+    <h2>Diffs</h2>
+    <% diff_images.each do |diff| %>
+      <h3>
+        <%= Rack::Utils.escape_html(diff[:description]) %> @ <%= diff[:viewport] %>
+      </h3>
+      <p><img src="<%= diff[:url] %>"></p>
+    <% end %>
+    <hr>
+    <h2>New examples</h2>
+    <% new_images.each do |image| %>
+      <h3>
+        <%= Rack::Utils.escape_html(image[:description]) %> @ <%= image[:viewport] %>
+      </h3>
+      <p><img src="<%= image[:url] %>"></p>
+    <% end %>
+  </body>
+</html>

data/lib/happo/logger.rb ADDED Viewed

@@ -0,0 +1,40 @@
+module Happo
+  # Used for all CLI output
+  class Logger
+    # @param out [IO] the output destination
+    def initialize(out = STDOUT)
+      @out = out
+    end
+    # Print the specified output
+    # @param str [String] the output to send
+    # @param newline [Boolean] whether to append a newline
+    def log(str, newline = true)
+      @out.print(str)
+      @out.print("\n") if newline
+    end
+    # Mark the string in cyan
+    # @param str [String] the str to format
+    def cyan(str)
+      color(36, str)
+    end
+    private
+    # Whether this logger is outputting to a TTY
+    #
+    # @return [Boolean]
+    def tty?
+      @out.respond_to?(:tty?) && @out.tty?
+    end
+    # Mark the string in a color
+    # @see http://ascii-table.com/ansi-escape-sequences.php
+    # @param color_code [Number] the ANSI color code
+    # @param str [String] the str to format
+    def color(color_code, str)
+      tty? ? str : "\033[#{color_code}m#{str}\033[0m"
+    end
+  end
+end

data/lib/happo/public/happo-runner.js ADDED Viewed

@@ -0,0 +1,223 @@
+'use strict';
+window.happo = {
+  defined: {},
+  fdefined: [],
+  currentRenderedElement: undefined,
+  errors: [],
+  define: function(description, func, options) {
+    // Make sure we don't have a duplicate description
+    if (this.defined[description]) {
+      throw 'Error while defining "' + description +
+        '": Duplicate description detected'
+    }
+    this.defined[description] = {
+      description: description,
+      func: func,
+      options: options || {}
+    };
+  },
+  fdefine: function(description, func, options) {
+    this.define(description, func, options); // add the example
+    this.fdefined.push(description);
+  },
+  /**
+   * @return {Array.<Object>}
+   */
+  getAllExamples: function() {
+    var descriptions = this.fdefined.length ?
+      this.fdefined :
+      Object.keys(this.defined);
+    return descriptions.map(function(description) {
+      var example = this.defined[description];
+      // We return a subset of the properties of an example (only those relevant
+      // for happo_runner.rb).
+      return {
+        description: example.description,
+        options: example.options,
+      };
+    }.bind(this));
+  },
+  handleError: function(currentExample, error) {
+    console.error(error.stack);
+    return {
+      description: currentExample.description,
+      error: error.message
+    };
+  },
+  /**
+   * @param {Function} func The happo.describe function from the current
+   *   example being rendered. This function takes a callback as an argument
+   *   that is called when it is done.
+   * @return {Promise}
+   */
+  tryAsync: function(func) {
+    return new Promise(function(resolve, reject) {
+      // Safety valve: if the function does not finish after 3s, then something
+      // went haywire and we need to move on.
+      var timeout = setTimeout(function() {
+        reject(new Error('Async callback was not invoked within timeout.'));
+      }, 3000);
+      // This function is called by the example when it is done executing.
+      var doneCallback = function(elem) {
+        clearTimeout(timeout);
+        if (!arguments.length) {
+          return reject(new Error(
+            'The async done callback expects the rendered element as an ' +
+            'argument, but there were no arguments.'
+          ));
+        }
+        resolve(elem);
+      };
+      func(doneCallback);
+    });
+  },
+  /**
+   * Clean up the DOM for a rendered element that has already been processed.
+   * This can be overridden by consumers to define their own clean out method,
+   * which can allow for this to be used to unmount React components, for
+   * example.
+   *
+   * @param {Object} renderedElement
+   */
+  cleanOutElement: function(renderedElement) {
+    renderedElement.parentNode.removeChild(renderedElement);
+  },
+  /**
+   * This function is called from Ruby asynchronously. Therefore, we need to
+   * call doneFunc when the method has completed so that Ruby knows to continue.
+   *
+   * @param {String} exampleDescription
+   * @param {Function} doneFunc injected by driver.execute_async_script in
+   *   happo/runner.rb
+   */
+  renderExample: function(exampleDescription, doneFunc) {
+    try {
+      var currentExample = this.defined[exampleDescription];
+      if (!currentExample) {
+        throw new Error(
+          'No example found with description "' + exampleDescription + '"');
+      }
+      // Clear out the body of the document
+      if (this.currentRenderedElement) {
+        this.cleanOutElement(this.currentRenderedElement);
+      }
+      while (document.body.firstChild) {
+        document.body.removeChild(document.body.firstChild);
+      }
+      var func = currentExample.func;
+      if (func.length) {
+        // The function takes an argument, which is a callback that is called
+        // once it is done executing. This can be used to write functions that
+        // have asynchronous code in them.
+        this.tryAsync(func).then(function(elem) {
+          doneFunc(this.processElem(currentExample, elem));
+        }.bind(this)).catch(function(error) {
+          doneFunc(this.handleError(currentExample, error));
+        }.bind(this));
+      } else {
+        // The function does not take an argument, so we can run it
+        // synchronously.
+        var result = func();
+        if (result instanceof Promise) {
+          // The function returned a promise, so we need to wait for it to
+          // resolve before proceeding.
+          result.then(function(elem) {
+            doneFunc(this.processElem(currentExample, elem));
+          }.bind(this)).catch(function(error) {
+            doneFunc(this.handleError(currentExample, error));
+          }.bind(this));
+        } else {
+          // The function did not return a promise, so we assume it gave us an
+          // element that we can process immediately.
+          doneFunc(this.processElem(currentExample, result));
+        }
+      }
+    } catch (error) {
+      doneFunc(this.handleError(currentExample, error));
+    }
+  },
+  processElem: function(currentExample, elem) {
+    try {
+      this.currentRenderedElement = elem;
+      var rect;
+      if (currentExample.options.snapshotEntireScreen) {
+        rect = {
+          width: window.innerWidth,
+          height: window.innerHeight,
+          top: 0,
+          left: 0,
+        };
+      } else {
+        // We use elem.getBoundingClientRect() instead of offsetTop and its ilk
+        // because elem.getBoundingClientRect() is more accurate and it also
+        // takes CSS transformations and other things of that nature into
+        // account whereas offsetTop and company do not.
+        //
+        // Note that this method returns floats, so we need to round those off
+        // to integers before returning.
+        rect = elem.getBoundingClientRect();
+      }
+      return {
+        description: currentExample.description,
+        width: Math.ceil(rect.width),
+        height: Math.ceil(rect.height),
+        top: Math.floor(rect.top),
+        left: Math.floor(rect.left),
+      };
+    } catch (error) {
+      return this.handleError(currentExample, error);
+    }
+  }
+};
+window.addEventListener('load', function() {
+  var matches = window.location.search.match(/description=([^&]*)/);
+  if (!matches) {
+    return;
+  }
+  var example = decodeURIComponent(matches[1]);
+  window.happo.renderExample(example, function() {});
+});
+// We need to redefine a few global functions that halt execution. Without this,
+// there's a chance that the Ruby code can't communicate with the browser.
+window.alert = function(message) {
+  console.log('`window.alert` called', message);
+};
+window.confirm = function(message) {
+  console.log('`window.confirm` called', message);
+  return true;
+};
+window.prompt = function(message, value) {
+  console.log('`window.prompt` called', message, value);
+  return null;
+};
+window.onerror = function(message, url, lineNumber) {
+  window.happo.errors.push({
+    message: message,
+    url: url,
+    lineNumber: lineNumber
+  });
+}

data/lib/happo/public/happo-styles.css ADDED Viewed

@@ -0,0 +1,8 @@
+body {
+  background-color: #f0f0f0;
+  font-family: helvetica, arial;
+}
+form {
+  display: inline-block;
+}

data/lib/happo/runner.rb ADDED Viewed

@@ -0,0 +1,215 @@
+require 'selenium-webdriver'
+require 'oily_png'
+require 'happo'
+require 'fileutils'
+require 'yaml'
+def resolve_viewports(example)
+  configured_viewports = Happo::Utils.config['viewports']
+  viewports =
+    example['options']['viewports'] || [configured_viewports.first.first]
+  viewports.map do |viewport|
+    configured_viewports[viewport].merge('name' => viewport)
+  end
+end
+def init_driver
+  tries = 0
+  begin
+    driver = Selenium::WebDriver.for Happo::Utils.config['driver'].to_sym
+  rescue Selenium::WebDriver::Error::WebDriverError => e
+    # "unable to obtain stable firefox connection in 60 seconds"
+    #
+    # This seems to happen sporadically for some versions of Firefox, so we want
+    # to retry a couple of times it in case it will work the second time around.
+    tries += 1
+    retry if tries <= 3
+    raise e
+  end
+  driver.manage.timeouts.script_timeout = 3 # move to config?
+  driver
+end
+log = Happo::Logger.new(STDOUT)
+driver = init_driver
+begin
+  driver.navigate.to Happo::Utils.construct_url('/')
+  # Check for errors during startup
+  errors = driver.execute_script('return window.happo.errors;')
+  unless errors.empty?
+    fail "JavaScript errors found during initialization: \n#{errors.inspect}"
+  end
+  # Initialize a hash to store a summary of the results from the run
+  result_summary = {
+    new_examples: [],
+    diff_examples: [],
+    okay_examples: []
+  }
+  all_examples = driver.execute_script('return window.happo.getAllExamples()')
+  # To avoid the overhead of resizing the window all the time, we are going to
+  # render all examples for each given viewport size all in one go.
+  examples_by_viewport = {}
+  all_examples.each do |example|
+    viewports = resolve_viewports(example)
+    viewports.each do |viewport|
+      examples_by_viewport[viewport['name']] ||= {}
+      examples_by_viewport[viewport['name']][:viewport] ||= viewport
+      examples_by_viewport[viewport['name']][:examples] ||= []
+      examples_by_viewport[viewport['name']][:examples] << example
+    end
+  end
+  examples_by_viewport.each do |_, example_by_viewport|
+    viewport = example_by_viewport[:viewport]
+    examples = example_by_viewport[:examples]
+    log.log "#{viewport['name']} (#{viewport['width']}x#{viewport['height']})"
+    # Resize window to the right size before rendering
+    driver.manage.window.resize_to(viewport['width'], viewport['height'])
+    examples.each do |example|
+      if example == examples.last
+        log.log '└─ ', false
+      else
+        log.log '├─ ', false
+      end
+      description = example['description']
+      log.log " #{description} ", false
+      log.log '.', false
+      # Render the example
+      # WebDriver's `execute_async_script` takes a string that is executed in
+      # the context of a function. `execute_async_script` injects a callback
+      # function as this function's argument here. WebDriver will wait until
+      # this callback is called (if it is passed a value it will pass that
+      # through to Rubyland), or until WebDriver's `script_timeout` is reached,
+      # before continuing. Since we don't define the signature of this function,
+      # we can't name the argument so we access it using JavaScript's magic
+      # arguments object and pass it down to `renderExample()` which calls it
+      # when it is done--either synchronously if our example doesn't take an
+      # argument, or asynchronously via the Promise and `done` callback if it
+      # does.
+      script = <<-EOS
+        var doneFunc = arguments[arguments.length - 1];
+        window.happo.renderExample(arguments[0], doneFunc);
+      EOS
+      rendered = driver.execute_async_script(script, description)
+      log.log '.', false
+      if rendered['error']
+        fail <<-EOS
+          Error while rendering "#{description}" @#{viewport['name']}:
+            #{rendered['error']}
+          Debug by pointing your browser to
+          #{Happo::Utils.construct_url('/', description: description)}
+        EOS
+      end
+      # Crop the screenshot to the size of the rendered element
+      screenshot = ChunkyPNG::Image.from_blob(driver.screenshot_as(:png))
+      log.log '.', false
+      # In our JavaScript we are rounding up, which can sometimes give us a
+      # dimensions that are larger than the screenshot dimensions. We need to
+      # guard against that here.
+      crop_width = [
+        [rendered['width'], 1].max,
+        screenshot.width - rendered['left']
+      ].min
+      crop_height = [
+        [rendered['height'], 1].max,
+        screenshot.height - rendered['top']
+      ].min
+      if crop_width < screenshot.width || crop_height < screenshot.height
+        screenshot.crop!(rendered['left'],
+                         rendered['top'],
+                         crop_width,
+                         crop_height)
+        log.log '.', false
+      end
+      # Run the diff if needed
+      baseline_path = Happo::Utils.path_to(
+        description, viewport['name'], 'baseline.png')
+      if File.exist? baseline_path
+        # A baseline image exists, so we want to compare the new snapshot
+        # against the baseline.
+        comparison = Happo::SnapshotComparer.new(
+          ChunkyPNG::Image.from_file(baseline_path),
+          screenshot
+        ).compare!
+        log.log '.', false
+        if comparison[:diff_image]
+          # There was a visual difference between the new snapshot and the
+          # baseline, so we want to write the diff image and the new snapshot
+          # image to disk. This will allow it to be reviewed by someone.
+          diff_path = Happo::Utils.path_to(
+            description, viewport['name'], 'diff.png')
+          comparison[:diff_image].save(diff_path, :fast_rgba)
+          log.log '.', false
+          candidate_path = Happo::Utils.path_to(
+            description, viewport['name'], 'candidate.png')
+          screenshot.save(candidate_path, :fast_rgba)
+          log.log '.', false
+          percent = comparison[:diff_in_percent].round(1)
+          log.log log.cyan(" #{percent}% (#{candidate_path})")
+          result_summary[:diff_examples] << {
+            description: description,
+            viewport: viewport['name']
+          }
+        else
+          # No visual difference was found, so we don't need to do any more
+          # work.
+          log.log ' No diff.'
+          result_summary[:okay_examples] << {
+            description: description,
+            viewport: viewport['name']
+          }
+        end
+      else
+        # There was no baseline image yet, so we want to start by saving a new
+        # baseline image.
+        # Create the folder structure if it doesn't already exist
+        unless File.directory?(dirname = File.dirname(baseline_path))
+          FileUtils.mkdir_p(dirname)
+        end
+        screenshot.save(baseline_path, :fast_rgba)
+        log.log '.', false
+        log.log " First snapshot created (#{baseline_path})"
+        result_summary[:new_examples] << {
+          description: description,
+          viewport: viewport['name']
+        }
+      end
+    end
+  end
+  result_summary_file = File.join(Happo::Utils.config['snapshots_folder'],
+                                  'result_summary.yaml')
+  File.open(result_summary_file, 'w') do |file|
+    file.write result_summary.to_yaml
+  end
+ensure
+  driver.quit
+end

data/lib/happo/server.rb ADDED Viewed

@@ -0,0 +1,68 @@
+require 'sinatra/base'
+require 'yaml'
+module Happo
+  class Server < Sinatra::Base
+    configure do
+      enable :static
+      set :port, Happo::Utils.config['port']
+    end
+    helpers do
+      def h(text)
+        Rack::Utils.escape_html(text)
+      end
+    end
+    get '/' do
+      @config = Happo::Utils.config
+      erb :index
+    end
+    get '/debug' do
+      @config = Happo::Utils.config
+      erb :debug
+    end
+    get '/review' do
+      @snapshots = Happo::Utils.current_snapshots
+      erb :review
+    end
+    get '/resource' do
+      file = params[:file]
+      if file.start_with? 'http'
+        redirect file
+      else
+        send_file file
+      end
+    end
+    get '/*' do
+      config = Happo::Utils.config
+      file = params[:splat].first
+      if File.exist?(file)
+        send_file file
+      else
+        config['public_directories'].each do |pub_dir|
+          filepath = File.join(Dir.pwd, pub_dir, file)
+          if File.exist?(filepath)
+            send_file filepath
+          end
+        end
+      end
+    end
+    post '/reject' do
+      Happo::Action.new(params[:description], params[:viewport]).reject
+      redirect back
+    end
+    post '/approve' do
+      Happo::Action.new(params[:description], params[:viewport]).approve
+      redirect back
+    end
+    run!
+  end
+end