RubyGems - happo - Versions diffs - 1.0.0 - Mend

happo 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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