happo 1.0.0

data/lib/happo/snapshot_comparer.rb

@@ -0,0 +1,91 @@
+require 'oily_png'
+require 'diff-lcs'
+require_relative 'snapshot_comparison_image/base'
+require_relative 'snapshot_comparison_image/gutter'
+require_relative 'snapshot_comparison_image/before'
+require_relative 'snapshot_comparison_image/overlayed'
+require_relative 'snapshot_comparison_image/after'
+
+module Happo
+  # This class is responsible for comparing two Snapshots and generating a diff.
+  class SnapshotComparer
+    # @param png_before [ChunkyPNG::Image]
+    # @param png_after  [ChunkyPNG::Image]
+    def initialize(png_before, png_after)
+      @png_after  = png_after
+      @png_before = png_before
+    end
+
+    # @return [Hash]
+    def compare!
+      no_diff = {
+        diff_in_percent: 0,
+        diff_image: nil,
+      }
+
+      # If these images are totally identical, we don't need to do any more
+      # work.
+      return no_diff if @png_before == @png_after
+
+      array_before = to_array_of_arrays(@png_before)
+      array_after = to_array_of_arrays(@png_after)
+
+      # If the arrays of arrays of colors are identical, we don't need to do any
+      # more work. This might happen if some of the headers are different.
+      return no_diff if array_before == array_after
+
+      sdiff = Diff::LCS.sdiff(array_before, array_after)
+      number_of_different_rows = 0
+
+      sprite, all_comparisons = initialize_comparison_images(
+        [@png_after.width, @png_before.width].max, sdiff.size)
+
+      sdiff.each_with_index do |row, y|
+        # each row is a Diff::LCS::ContextChange instance
+        all_comparisons.each { |image| image.render_row(y, row) }
+        number_of_different_rows += 1 unless row.unchanged?
+      end
+
+      percent_changed = number_of_different_rows.to_f / sdiff.size * 100
+      {
+        diff_in_percent: percent_changed,
+        diff_image:      (sprite if percent_changed > 0),
+      }
+    end
+
+    private
+
+    # @param [ChunkyPNG::Image]
+    # @return [Array<Array<Integer>>]
+    def to_array_of_arrays(chunky_png)
+      array_of_arrays = []
+      chunky_png.height.times do |y|
+        array_of_arrays << chunky_png.row(y)
+      end
+      array_of_arrays
+    end
+
+    # @param canvas [ChunkyPNG::Image] The output image to draw pixels on
+    # @return [Array<SnapshotComparisonImage>]
+    def initialize_comparison_images(width, height)
+      gutter_width = Happo::SnapshotComparisonImage::Gutter::WIDTH
+      total_width = (width * 3) + (gutter_width * 3)
+
+      sprite = ChunkyPNG::Image.new(total_width, height)
+      offset, comparison_images = 0, []
+      comparison_images << Happo::SnapshotComparisonImage::Gutter.new(offset, sprite)
+      offset += gutter_width
+      comparison_images << Happo::SnapshotComparisonImage::Before.new(offset, sprite)
+      offset += width
+      comparison_images << Happo::SnapshotComparisonImage::Gutter.new(offset, sprite)
+      offset += gutter_width
+      comparison_images << Happo::SnapshotComparisonImage::Overlayed.new(offset, sprite)
+      offset += width
+      comparison_images << Happo::SnapshotComparisonImage::Gutter.new(offset, sprite)
+      offset += gutter_width
+      comparison_images << Happo::SnapshotComparisonImage::After.new(offset, sprite)
+
+      [sprite, comparison_images]
+    end
+  end
+end

data/lib/happo/snapshot_comparison_image/after.rb

@@ -0,0 +1,21 @@
+module Happo
+  module SnapshotComparisonImage
+    # This subclass of `SnapshotComparisonImage` knows how to draw the
+    # representation of the "after" image.
+    class After < SnapshotComparisonImage::Base
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_changed_row(y, row)
+        render_added_row(y, row)
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_added_row(y, row)
+        row.new_element.each_with_index do |pixel_after, x|
+          render_pixel(x, y, pixel_after)
+        end
+      end
+    end
+  end
+end

data/lib/happo/snapshot_comparison_image/base.rb

@@ -0,0 +1,108 @@
+require 'chunky_png'
+
+module Happo
+  module SnapshotComparisonImage
+    # This model represents a "comparison image". Basically it's just a wrapper
+    # around a ChunkyPNG image with some nice methods to make life easier in the
+    # world of diffs.
+    #
+    # This model is never persisted.
+    class Base
+      include ChunkyPNG::Color
+
+      BASE_OPACITY    = 0.1
+      BASE_ALPHA      = (255 * BASE_OPACITY).round
+      BASE_DIFF_ALPHA = BASE_ALPHA * 2
+
+      MAGENTA = ChunkyPNG::Color.from_hex '#b33682'
+      RED     = ChunkyPNG::Color.from_hex '#dc322f'
+      GREEN   = ChunkyPNG::Color.from_hex '#859900'
+
+      # @param offset [Integer] the x-offset that this comparison image should
+      #   use when rendering on the canvas image.
+      # @param canvas [ChunkyPNG::Image] The canvas image to render pixels on.
+      def initialize(offset, canvas)
+        @offset = offset
+        @canvas = canvas
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_row(y, row)
+        if row.unchanged?
+          render_unchanged_row(y, row)
+        elsif row.deleting?
+          render_deleted_row(y, row)
+        elsif row.adding?
+          render_added_row(y, row)
+        else # changing?
+          render_changed_row(y, row)
+        end
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_unchanged_row(y, row)
+        row.new_element.each_with_index do |pixel, x|
+          # Render the unchanged pixel as-is
+          render_pixel(x, y, pixel)
+        end
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_changed_row(y, row)
+        # no default implementation
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_added_row(y, row)
+        # no default implementation
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_deleted_row(y, row)
+        # no default implementation
+      end
+
+      # Compute a score that represents the difference between 2 pixels
+      #
+      # This method simply takes the Euclidean distance between the RGBA channels
+      # of 2 colors over the maximum possible Euclidean distance. This gives us a
+      # percentage of how different the two colors are.
+      #
+      # Although it would be more perceptually accurate to calculate a proper
+      # Delta E in Lab colorspace, we probably don't need perceptual accuracy for
+      # this application, and it is nice to avoid the overhead of converting RGBA
+      # to Lab.
+      #
+      # @param pixel_after [Integer]
+      # @param pixel_before [Integer]
+      # @return [Float] number between 0 and 1 where 1 is completely different
+      #   and 0 is no difference
+      def pixel_diff_score(pixel_after, pixel_before)
+        ChunkyPNG::Color::euclidean_distance_rgba(pixel_after, pixel_before) /
+          ChunkyPNG::Color::MAX_EUCLIDEAN_DISTANCE_RGBA
+      end
+
+      # @param diff_score [Float]
+      # @return [Integer] a number between 0 and 255 that represents the alpha
+      #   channel of of the difference
+      def diff_alpha(diff_score)
+        (BASE_DIFF_ALPHA + ((255 - BASE_DIFF_ALPHA) * diff_score)).round
+      end
+
+      # Renders a pixel on the specified x and y position. Uses the offset that
+      # the comparison image has been configured with.
+      #
+      # @param x [Integer]
+      # @param y [Integer]
+      # @param pixel [Integer]
+      def render_pixel(x, y, pixel)
+        @canvas.set_pixel(x + @offset, y, pixel)
+      end
+    end
+  end
+end

data/lib/happo/snapshot_comparison_image/before.rb

@@ -0,0 +1,21 @@
+module Happo
+  module SnapshotComparisonImage
+    # This subclass of `SnapshotComparisonImage` knows how to draw the
+    # representation of the "before" image.
+    class Before < SnapshotComparisonImage::Base
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_changed_row(y, row)
+        render_deleted_row(y, row)
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_deleted_row(y, row)
+        row.old_element.each_with_index do |pixel_before, x|
+          render_pixel(x, y, pixel_before)
+        end
+      end
+    end
+  end
+end

data/lib/happo/snapshot_comparison_image/gutter.rb

@@ -0,0 +1,34 @@
+module Happo
+  module SnapshotComparisonImage
+    # This class renders a gutter-column with a color representing the type of
+    # change that has happened.
+    class Gutter < SnapshotComparisonImage::Base
+      WIDTH = 10
+      GRAY  = ChunkyPNG::Color.from_hex '#cccccc'
+
+      def render_row(y, row)
+        WIDTH.times do |x|
+          render_pixel(x, y, gutter_color(row))
+        end
+        # render a two-pixel empty column
+        2.times do |x|
+          render_pixel(WIDTH - 1 - x, y, WHITE)
+        end
+      end
+
+      private
+
+      def gutter_color(row)
+        if row.unchanged?
+          WHITE
+        elsif row.deleting?
+          RED
+        elsif row.adding?
+          GREEN
+        else # changed?
+          GRAY
+        end
+      end
+    end
+  end
+end

data/lib/happo/snapshot_comparison_image/overlayed.rb

@@ -0,0 +1,88 @@
+module Happo
+  module SnapshotComparisonImage
+    # This subclass of `SnapshotComparisonImage` knows how to overlay the
+    # after-image on top of the before-image, and render the difference in a
+    # scaled magenta color.
+    class Overlayed < SnapshotComparisonImage::Base
+      WHITE_OVERLAY = ChunkyPNG::Color.fade(WHITE, 1 - BASE_ALPHA)
+
+      # @param offset [Integer]
+      # @param canvas [ChunkyPNG::Image]
+      # @see SnapshotComparisonImage::Base
+      def initialize(offset, canvas)
+        @diff_pixels  = {}
+        @faded_pixels = {}
+        super
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_unchanged_row(y, row)
+        # Render translucent original pixels
+        row.new_element.each_with_index do |pixel, x|
+          render_faded_pixel(x, y, pixel)
+        end
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_deleted_row(y, row)
+        row.old_element.each_with_index do |pixel_before, x|
+          render_faded_magenta_pixel(TRANSPARENT, pixel_before, x, y)
+        end
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_added_row(y, row)
+        row.new_element.each_with_index do |pixel_after, x|
+          render_faded_magenta_pixel(pixel_after, TRANSPARENT, x, y)
+        end
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_changed_row(y, row)
+        row.old_element.zip(row.new_element).each_with_index do |pixels, x|
+          pixel_before, pixel_after = pixels
+          render_faded_magenta_pixel(
+            pixel_after  || TRANSPARENT,
+            pixel_before || TRANSPARENT,
+            x, y)
+        end
+      end
+
+      private
+
+      # @param pixel_after [Integer]
+      # @param pixel_before [Integer]
+      # @param x [Integer]
+      # @param y [Integer]
+      def render_faded_magenta_pixel(pixel_after, pixel_before, x, y)
+        score = pixel_diff_score(pixel_after, pixel_before)
+        if score > 0
+          render_diff_pixel(x, y, score)
+        else
+          render_faded_pixel(x, y, pixel_after)
+        end
+      end
+
+      # @param x [Integer]
+      # @param y [Integer]
+      # @param score [Float]
+      def render_diff_pixel(x, y, score)
+        @diff_pixels[score] ||= compose_quick(fade(MAGENTA, diff_alpha(score)),
+                                              WHITE)
+        render_pixel(x, y, @diff_pixels[score])
+      end
+
+      # @param x [Integer]
+      # @param y [Integer]
+      # @param pixel [Integer]
+      def render_faded_pixel(x, y, pixel)
+        @faded_pixels[pixel] ||= compose_quick(WHITE_OVERLAY, pixel)
+        render_pixel(x, y, @faded_pixels[pixel])
+      end
+    end
+  end
+end

data/lib/happo/uploader.rb

@@ -0,0 +1,70 @@
+require 's3'
+require 'securerandom'
+
+module Happo
+  class Uploader
+    def initialize
+      @s3_access_key_id = Happo::Utils.config['s3_access_key_id']
+      @s3_secret_access_key = Happo::Utils.config['s3_secret_access_key']
+      @s3_bucket_name = Happo::Utils.config['s3_bucket_name']
+    end
+
+    def upload_diffs
+      result_summary = YAML.load(File.read(File.join(
+        Happo::Utils.config['snapshots_folder'], 'result_summary.yaml')))
+
+      return [] if result_summary[:diff_examples].empty? &&
+                   result_summary[:new_examples].empty?
+
+      bucket = find_or_build_bucket
+      dir = SecureRandom.uuid
+
+      diff_images = result_summary[:diff_examples].map do |diff|
+        image = bucket.objects.build(
+          "#{dir}/#{diff[:description]}_#{diff[:viewport]}.png")
+        image.content = open(Happo::Utils.path_to(diff[:description],
+                                                     diff[:viewport],
+                                                     'diff.png'))
+        image.content_type = 'image/png'
+        image.save
+        diff[:url] = image.url
+        diff
+      end
+
+      new_images = result_summary[:new_examples].map do |example|
+        image = bucket.objects.build(
+          "#{dir}/#{example[:description]}_#{example[:viewport]}.png")
+        image.content = open(Happo::Utils.path_to(example[:description],
+                                                     example[:viewport],
+                                                     'baseline.png'))
+        image.content_type = 'image/png'
+        image.save
+        example[:url] = image.url
+        example
+      end
+
+      html = bucket.objects.build("#{dir}/index.html")
+      path = File.expand_path(
+        File.join(File.dirname(__FILE__), 'diffs.html.erb'))
+      html.content = ERB.new(File.read(path)).result(binding)
+      html.content_type = 'text/html'
+      html.save
+      html.url
+    end
+
+    private
+
+    def find_or_build_bucket
+      service = S3::Service.new(access_key_id: @s3_access_key_id,
+                                secret_access_key: @s3_secret_access_key)
+      bucket = service.buckets.find(@s3_bucket_name)
+
+      if bucket.nil?
+        bucket = service.buckets.build(@s3_bucket_name)
+        bucket.save(location: :us)
+      end
+
+      bucket
+    end
+  end
+end

data/lib/happo/utils.rb

@@ -0,0 +1,81 @@
+require 'yaml'
+require 'erb'
+require 'uri'
+require 'base64'
+
+module Happo
+  class Utils
+    def self.config
+      @@config ||= {
+        'snapshots_folder' => './snapshots',
+        'source_files' => [],
+        'stylesheets' => [],
+        'public_directories' => [],
+        'port' => 4567,
+        'driver' => :firefox,
+        'viewports' => {
+          'large' => {
+            'width' => 1024,
+            'height' => 768
+          },
+          'medium' => {
+            'width' => 640,
+            'height' => 888
+          },
+          'small' => {
+            'width' => 320,
+            'height' => 444
+          }
+        }
+      }.merge(config_from_file)
+    end
+
+    def self.config_from_file
+      config_file_name = ENV['HAPPO_CONFIG_FILE'] || '.happo.yaml'
+      YAML.load(ERB.new(File.read(config_file_name)).result)
+    end
+
+    def self.normalize_description(description)
+      Base64.strict_encode64(description).strip
+    end
+
+    def self.path_to(description, viewport_name, file_name)
+      File.join(
+        config['snapshots_folder'],
+        normalize_description(description),
+        "@#{viewport_name}",
+        file_name
+      )
+    end
+
+    def self.construct_url(absolute_path, params = {})
+      query = URI.encode_www_form(params) unless params.empty?
+
+      URI::HTTP.build(host: 'localhost',
+                      port: config['port'],
+                      path: absolute_path,
+                      query: query).to_s
+    end
+
+    def self.current_snapshots
+      prepare_file = lambda do |file|
+        viewport_dir = File.expand_path('..', file)
+        description_dir = File.expand_path('..', viewport_dir)
+        {
+          description: Base64.decode64(File.basename(description_dir)),
+          viewport: File.basename(viewport_dir).sub('@', ''),
+          file: file
+        }
+      end
+
+      snapshots_folder = Happo::Utils.config['snapshots_folder']
+      diff_files = Dir.glob("#{snapshots_folder}/**/diff.png")
+      baselines = Dir.glob("#{snapshots_folder}/**/baseline.png")
+
+      {
+        diffs: diff_files.map(&prepare_file),
+        baselines: baselines.map(&prepare_file)
+      }
+    end
+  end
+end

data/lib/happo/version.rb

@@ -0,0 +1,4 @@
+# Defines the gem version.
+module Happo
+  VERSION = '1.0.0'
+end

data/lib/happo/views/debug.erb

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Happo Debug Tool</title>
+    <link rel="stylesheet" href="/happo-styles.css"></link>
+    <script src="/happo-runner.js"></script>
+    <% @config['source_files'].each do |source_file| %>
+      <script src="/resource?file=<%= ERB::Util.url_encode(source_file) %>"></script>
+    <% end %>
+    <script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
+  </head>
+  <body>
+    <h1>Happo Debug Tool</h1>
+    <p>Click on an item to render that example in isolation.</p>
+    <script>
+      (function() {
+        var ul = $('<ul>');
+        $('body').append(ul);
+        $.each(happo.defined, function(_, example) {
+          ul.append($('<li>').append(
+            $('<a>', {
+              href: '/?description=' + encodeURIComponent(example.description)
+            }).text(example.description)
+          ));
+        });
+      }());
+    </script>
+  </body>
+</html>

data/lib/happo/views/index.erb

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Happo</title>
+    <style type="text/css">
+      * {
+        -webkit-transition: none !important;
+        -moz-transition: none !important;
+        transition: none !important;
+        -webkit-animation-duration: 0 !important;
+        -moz-animation-duration: 0s !important;
+        animation-duration: 0s !important;
+      }
+    </style>
+
+    <% @config['stylesheets'].each do |stylesheet| %>
+      <link rel="stylesheet" type="text/css"
+        href="/resource?file=<%= ERB::Util.url_encode(stylesheet) %>">
+    <% end %>
+    <script src="/happo-runner.js"></script>
+    <% @config['source_files'].each do |source_file| %>
+      <script src="/resource?file=<%= ERB::Util.url_encode(source_file) %>"></script>
+    <% end %>
+  </head>
+  <body style="background-color: #fff; margin: 0; pointer-events: none;">
+  </body>
+</html>

data/lib/happo/views/review.erb

@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Happo Review Tool</title>
+    <link rel="stylesheet" href="/happo-styles.css"></link>
+  </head>
+  <body>
+    <h1>Happo Review Tool</h1>
+    <h2>DIFFS</h2>
+    <% @snapshots[:diffs].each do |diff| %>
+      <h3>
+        <%= h diff[:description] %> @ <%= diff[:viewport] %>
+      </h3>
+      <p><img src="/resource?file=<%= ERB::Util.url_encode(diff[:file]) %>"></p>
+      <form style="display: inline-block"
+            action="/approve?description=<%= diff[:description] %>&viewport=<%= diff[:viewport] %>"
+            method="POST">
+        <button type="submit">Approve</button>
+      </form>
+      <form style="display: inline-block"
+            action="/reject?description=<%= diff[:description] %>&viewport=<%= diff[:viewport] %>"
+            method="POST">
+        <button type="submit">Reject</button>
+      </form>
+    <% end %>
+
+    <hr>
+
+    <h2>BASELINES</h2>
+    <% @snapshots[:baselines].each do |baseline| %>
+      <h3>
+        <%= h baseline[:description] %> @ <%= baseline[:viewport] %>
+      </h3>
+      <p><img src="/resource?file=<%= ERB::Util.url_encode(baseline[:file]) %>"></p>
+    <% end %>
+  </body>
+</html>

data/lib/happo.rb

@@ -0,0 +1,6 @@
+require 'happo/utils'
+require 'happo/action'
+require 'happo/uploader'
+require 'happo/version'
+require 'happo/logger'
+require 'happo/snapshot_comparer'