lookalike 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5325c67c97ddff6cc6a8ae7ddbd63542bff28e25e30dc1d23f298b77a4c1ed3
+  data.tar.gz: a795c3d3606217019cc73c87d4cb9c5c5e567d6ee539637d59f0973b38264cc9
+SHA512:
+  metadata.gz: 3c815fec0f33f5d7eae4ce2e9f347f82dc0c5beea29ece38dbe3dc3b5b5bb6ad7b3dbd3c4b566c7b68d3b9ac0596b9f224fbca73d4c25725adebe6d66de5a3bc
+  data.tar.gz: f04613d9fb04478620459412dccdd05d409d4c4cdb78f584216093ecfda67460bf609e18ea39051d93883e0c564dce13375f980e269d332017a93d1629360d6b

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-23
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ydah
+
+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,85 @@
+# Lookalike
+
+[![Gem version](https://badge.fury.io/rb/lookalike.svg)](https://rubygems.org/gems/lookalike)
+[![Downloads](https://img.shields.io/gem/dt/lookalike?label=downloads)](https://rubygems.org/gems/lookalike)
+[![CI](https://github.com/rbgfx/lookalike/actions/workflows/ci.yml/badge.svg)](https://github.com/rbgfx/lookalike/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D3.1-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-750014.svg)](LICENSE.txt)
+
+> Golden image comparison for Ruby graphics.
+
+Lookalike turns rendered images into visual regression tests. It compares
+Tessel images, file paths, and framebuffer-like objects, then writes actionable
+diffs for failed snapshots.
+
+**[Features](#features) · [Installation](#installation) · [Quick start](#quick-start) · [Development](#development)**
+
+## Features
+
+- Channel and YIQ perceptual comparison modes.
+- Per-pixel deltas, allowed-pixel limits, bounding boxes, and diff images.
+- Optional antialiasing detection for cleaner UI and text snapshots.
+- RSpec, Minitest, and Test::Unit assertion helpers.
+- Snapshot approval flow for local development and CI.
+- HTML reports with an expected/actual overlay slider.
+
+## Installation
+
+Add Lookalike to your Gemfile:
+
+~~~ruby
+gem "lookalike"
+~~~
+
+Then run:
+
+~~~sh
+bundle install
+~~~
+
+Or install the released gem:
+
+~~~sh
+gem install lookalike
+~~~
+
+## Quick start
+
+~~~ruby
+require "lookalike"
+
+actual = Tessel.read("actual.png")
+result = Lookalike.compare("expected.png", actual, mode: :channel, max_delta: 1)
+abort result.inspect unless result.match?
+~~~
+
+For snapshot assertions, include <code>Lookalike::Assertions</code> in the test
+context:
+
+~~~ruby
+include Lookalike::Assertions
+
+assert_snapshot(render_scene, "home")
+~~~
+
+Missing snapshots are pending locally. Approve them with:
+
+~~~sh
+LOOKALIKE_UPDATE=1 bundle exec rake
+lookalike approve NAME
+lookalike approve --all
+lookalike report tmp/lookalike
+~~~
+
+Set <code>CI</code> to make missing snapshots fail.
+
+## Development
+
+~~~sh
+bundle install
+bundle exec rake verify
+~~~
+
+## License
+
+[MIT](LICENSE.txt)

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) { |task| task.ruby_opts = ["-I../tessel/lib"] }
+
+task default: :spec
+task verify: :spec

data/exe/lookalike

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "lookalike"
+
+command = ARGV.shift
+case command
+when "report"
+  puts Lookalike::Report.new(ARGV.shift || Lookalike.config.output_dir).write
+when "diff"
+  expected, actual = ARGV.shift(2)
+  output = nil
+  OptionParser.new { |opts| opts.on("-o PATH") { |path| output = path } }.parse!(ARGV)
+  result = Lookalike.compare(expected, actual, mode: :channel)
+  result.diff_image&.write(output) if output
+  puts "#{result.diff_pixels} differing pixels"
+when "approve"
+  name = ARGV.shift
+  store = Lookalike::Store.new
+  names = if name == "--all"
+    Dir[File.join(Lookalike.config.output_dir, "**", "*.actual.png")].map do |file|
+      file.delete_prefix("#{Lookalike.config.output_dir}/").delete_suffix(".actual.png")
+    end
+  else
+    [name]
+  end
+  names.each do |entry|
+    source = store.output_path(entry, "actual")
+    destination = store.path(entry)
+    raise ArgumentError, "actual image is missing: #{source}" unless File.file?(source)
+    FileUtils.mkdir_p(File.dirname(destination))
+    FileUtils.cp(source, destination)
+    puts destination
+  end
+else
+  warn "usage: lookalike report [DIR] | diff EXPECTED ACTUAL [-o PATH] | approve NAME|--all"
+  exit 1
+end

data/lib/lookalike/assertions.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../lookalike"

data/lib/lookalike/config.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../lookalike"

data/lib/lookalike/input.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../lookalike"

data/lib/lookalike/minitest.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "minitest"
+require_relative "../lookalike"
+
+Lookalike::Minitest.include(Lookalike::Assertions)

data/lib/lookalike/report.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../lookalike"

data/lib/lookalike/store.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../lookalike"

data/lib/lookalike/test_unit.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "test/unit"
+require_relative "../lookalike"
+
+Lookalike::TestUnit.include(Lookalike::Assertions)

data/lib/lookalike/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Lookalike
+  VERSION = "0.1.0"
+end

data/lib/lookalike.rb

@@ -0,0 +1,491 @@
+# frozen_string_literal: true
+
+require "json"
+require "erb"
+require "fileutils"
+require "tessel"
+
+require_relative "lookalike/version"
+
+module Lookalike
+  class Error < StandardError; end
+  class Mismatch < Error
+    attr_reader :name, :result, :expected_path, :actual_path, :diff_path
+
+    def initialize(name, result:, expected_path: nil, actual_path: nil, diff_path: nil)
+      @name = name
+      @result = result
+      @expected_path = expected_path
+      @actual_path = actual_path
+      @diff_path = diff_path
+      super(format_message)
+    end
+
+    def format_message
+      "Snapshot mismatch: #{@name}\n" \
+        "  diff pixels : #{@result.diff_pixels}\n" \
+        "  max delta   : #{@result.max_delta}\n" \
+        "  diff bbox   : #{@result.bounding_box.inspect}\n" \
+        "  expected    : #{@expected_path}\n" \
+        "  actual      : #{@actual_path}\n" \
+        "  diff        : #{@diff_path}"
+    end
+  end
+  class Pending < Error; end
+
+  class Result
+    attr_reader :expected, :actual, :diff_pixels, :max_delta, :bounding_box, :diff_image, :mode
+
+    def initialize(expected:, actual:, diff_pixels:, max_delta:, bounding_box:, diff_image:, mode:, matched:)
+      @expected = expected
+      @actual = actual
+      @diff_pixels = diff_pixels
+      @max_delta = max_delta
+      @bounding_box = bounding_box
+      @diff_image = diff_image
+      @mode = mode
+      @matched = matched
+    end
+
+    def match?
+      @matched
+    end
+
+    def to_h
+      { "match" => match?, "diff_pixels" => diff_pixels, "max_delta" => max_delta,
+        "bounding_box" => bounding_box, "mode" => mode.to_s }
+    end
+  end
+
+  class Config
+    attr_accessor :snapshot_dir, :output_dir, :default_mode, :threshold, :max_diff_pixels
+    attr_reader :variants
+
+    def initialize
+      @snapshot_dir = "test/snapshots"
+      @output_dir = "tmp/lookalike"
+      @default_mode = :perceptual
+      @threshold = 0.1
+      @max_diff_pixels = 0
+      @variants = {}
+    end
+
+    def variant(name, **options)
+      @variants[name.to_sym] = options
+    end
+
+    def options_for(name)
+      @variants[name.to_sym] || {}
+    end
+  end
+
+  module Input
+    module_function
+
+    def normalize(value)
+      return value if value.is_a?(Tessel::Image)
+      if value.respond_to?(:width) && value.respond_to?(:height) && value.respond_to?(:to_rgba_bytes)
+        return Tessel::Image.from_rgba(value.width, value.height, value.to_rgba_bytes)
+      end
+      return Tessel.read(value) if value.respond_to?(:to_path) || value.is_a?(String)
+
+      raise TypeError, "unsupported image input: #{value.class}"
+    end
+  end
+
+  module Metrics
+    module Channel
+      module_function
+
+      def compare(expected, actual, max_delta:, allowed_pixels:)
+        diff = 0
+        maximum = 0
+        box = nil
+        each_pixel(expected, actual) do |x, y, a, b|
+          delta = a.zip(b).map { |left, right| (left - right).abs }.max
+          next unless delta > max_delta
+
+          diff += 1
+          maximum = [maximum, delta].max
+          box = expand_box(box, x, y)
+        end
+        [diff <= allowed_pixels, diff, maximum, box]
+      end
+
+      def each_pixel(expected, actual)
+        expected_bytes = expected.bytes
+        actual_bytes = actual.bytes
+        (0...expected.width).each do |x|
+          (0...expected.height).each do |y|
+            offset = (y * expected.width + x) * 4
+            yield x, y, expected_bytes.byteslice(offset, 4).bytes, actual_bytes.byteslice(offset, 4).bytes
+          end
+        end
+      end
+      def expand_box(box, x, y)
+        return [x, y, 1, 1] unless box
+
+        x0 = [box[0], x].min
+        y0 = [box[1], y].min
+        x1 = [box[0] + box[2] - 1, x].max
+        y1 = [box[1] + box[3] - 1, y].max
+        [x0, y0, x1 - x0 + 1, y1 - y0 + 1]
+      end
+      private_class_method :expand_box
+    end
+
+    module YIQ
+      module_function
+
+      def compare(expected, actual, threshold:, allowed_pixels:, ignore_antialiasing: false)
+        diff = 0
+        maximum = 0
+        box = nil
+        Channel.each_pixel(expected, actual) do |x, y, left, right|
+          delta = distance(composite(left), composite(right))
+          maximum = [maximum, (delta * 255).round].max
+          next unless delta > threshold
+          next if ignore_antialiasing && Antialiasing.detect?(expected, x, y, actual)
+
+          diff += 1
+          box = expand_box(box, x, y)
+        end
+        [diff <= allowed_pixels, diff, maximum, box]
+      end
+
+      def distance(left, right)
+        yiq_left = [0.29889531 * left[0] + 0.58662247 * left[1] + 0.11448223 * left[2], 0.59597799 * left[0] - 0.27417610 * left[1] - 0.32180189 * left[2], 0.21147017 * left[0] - 0.52261711 * left[1] + 0.31114694 * left[2]]
+        yiq_right = [0.29889531 * right[0] + 0.58662247 * right[1] + 0.11448223 * right[2], 0.59597799 * right[0] - 0.27417610 * right[1] - 0.32180189 * right[2], 0.21147017 * right[0] - 0.52261711 * right[1] + 0.31114694 * right[2]]
+        Math.sqrt(0.5053 * (yiq_left[0] - yiq_right[0])**2 + 0.299 * (yiq_left[1] - yiq_right[1])**2 + 0.1957 * (yiq_left[2] - yiq_right[2])**2)
+      end
+      private_class_method :distance
+
+      def composite(pixel)
+        alpha = pixel[3] / 255.0
+        pixel.first(3).map { |channel| (channel * alpha + 255 * (1 - alpha)) / 255.0 }
+      end
+      private_class_method :composite
+
+      def expand_box(box, x, y)
+        return [x, y, 1, 1] unless box
+
+        x0 = [box[0], x].min
+        y0 = [box[1], y].min
+        x1 = [box[0] + box[2] - 1, x].max
+        y1 = [box[1] + box[3] - 1, y].max
+        [x0, y0, x1 - x0 + 1, y1 - y0 + 1]
+      end
+      private_class_method :expand_box
+    end
+  end
+
+  module Antialiasing
+    module_function
+
+    def detect?(image, x, y, other)
+      intermediate_edge?(image, x, y) && edge?(other, x, y) ||
+        intermediate_edge?(other, x, y) && edge?(image, x, y)
+    end
+
+    def edge?(image, x, y)
+      values = neighborhood(image, x, y)
+      values.max - values.min > 0.1
+    end
+
+    def intermediate_edge?(image, x, y)
+      values = neighborhood(image, x, y)
+      center = luminance(image[x, y])
+      values.max - values.min > 0.1 && center > values.min + 0.02 && center < values.max - 0.02
+    end
+
+    def neighborhood(image, x, y)
+      (-1..1).flat_map do |dy|
+        (-1..1).filter_map { |dx| pixel = image[x + dx, y + dy]; luminance(pixel) if pixel }
+      end
+    end
+
+    def luminance(pixel)
+      alpha = pixel[3] / 255.0
+      rgb = pixel.first(3).map { |channel| (channel * alpha + 255 * (1 - alpha)) / 255.0 }
+      0.29889531 * rgb[0] + 0.58662247 * rgb[1] + 0.11448223 * rgb[2]
+    end
+    private_class_method :edge?, :intermediate_edge?, :neighborhood, :luminance
+  end
+
+  module DiffRenderer
+    module_function
+
+    def render(expected, actual, mode: :channel, threshold: 0.1, max_delta: 0, ignore_antialiasing: false)
+      result = ImageBuilder.new(expected.width, expected.height)
+      (0...expected.height).each do |y|
+        (0...expected.width).each do |x|
+          left = expected[x, y]
+          right = actual[x, y]
+          different = if mode == :channel
+            left.zip(right).map { |a, b| (a - b).abs }.max > max_delta
+          else
+            Metrics::YIQ.send(:distance, Metrics::YIQ.send(:composite, left), Metrics::YIQ.send(:composite, right)) > threshold
+          end
+          antialias = different && ignore_antialiasing && mode.to_sym == :perceptual && Antialiasing.detect?(expected, x, y, actual)
+          result[x, y] = if antialias
+            [255, 220, 0, 255]
+          elsif different
+            [255, left[1] / 2, 0, 255]
+          else
+            [left[0] / 3, left[1] / 3, left[2] / 3, 255]
+          end
+        end
+      end
+      result
+    end
+
+    class ImageBuilder < Tessel::Image; end
+  end
+
+  module_function
+
+  def config
+    @config ||= Config.new
+  end
+
+  def configure
+    yield config
+  end
+
+  def compare(expected, actual, mode: config.default_mode, max_delta: 0, allowed_pixels: config.max_diff_pixels, max_diff_pixels: nil, threshold: config.threshold, ignore_antialiasing: false)
+    mode = mode.to_sym
+    raise ArgumentError, "unknown comparison mode: #{mode}" unless %i[channel perceptual].include?(mode)
+    allowed_pixels = max_diff_pixels unless max_diff_pixels.nil?
+    allowed_pixels = Integer(allowed_pixels)
+    raise ArgumentError, "allowed pixels must not be negative" if allowed_pixels.negative?
+    max_delta = Integer(max_delta)
+    raise ArgumentError, "max delta must be between 0 and 255" unless max_delta.between?(0, 255)
+    threshold = Float(threshold)
+    raise ArgumentError, "threshold must not be negative" if threshold.negative?
+    expected = Input.normalize(expected)
+    actual = Input.normalize(actual)
+    unless expected.width == actual.width && expected.height == actual.height
+      width = [expected.width, actual.width].max
+      height = [expected.height, actual.height].max
+      padded_expected = Tessel::Image.new(width, height)
+      padded_actual = Tessel::Image.new(width, height)
+      padded_expected.blit(expected, 0, 0, blend: :copy)
+      padded_actual.blit(actual, 0, 0, blend: :copy)
+      _matched, diff, maximum, box = if mode == :channel
+        Metrics::Channel.compare(padded_expected, padded_actual, max_delta: max_delta, allowed_pixels: allowed_pixels)
+      else
+        Metrics::YIQ.compare(padded_expected, padded_actual, threshold: threshold, allowed_pixels: allowed_pixels, ignore_antialiasing: ignore_antialiasing)
+      end
+      dimension_box = nil
+      dimension_diff = 0
+      (0...height).each do |y|
+        (0...width).each do |x|
+          next if x < expected.width && y < expected.height && x < actual.width && y < actual.height
+
+          dimension_diff += 1
+          if dimension_box
+            x0 = [dimension_box[0], x].min
+            y0 = [dimension_box[1], y].min
+            x1 = [dimension_box[0] + dimension_box[2] - 1, x].max
+            y1 = [dimension_box[1] + dimension_box[3] - 1, y].max
+            dimension_box = [x0, y0, x1 - x0 + 1, y1 - y0 + 1]
+          else
+            dimension_box = [x, y, 1, 1]
+          end
+        end
+      end
+      if dimension_diff.positive?
+        diff += dimension_diff
+        maximum = [maximum, 255].max
+        if box
+          x0 = [box[0], dimension_box[0]].min
+          y0 = [box[1], dimension_box[1]].min
+          x1 = [box[0] + box[2] - 1, dimension_box[0] + dimension_box[2] - 1].max
+          y1 = [box[1] + box[3] - 1, dimension_box[1] + dimension_box[3] - 1].max
+          box = [x0, y0, x1 - x0 + 1, y1 - y0 + 1]
+        else
+          box = dimension_box
+        end
+      end
+      diff_image = DiffRenderer.render(padded_expected, padded_actual, mode: mode, threshold: threshold, max_delta: max_delta)
+      return Result.new(expected: expected, actual: actual, diff_pixels: diff, max_delta: maximum, bounding_box: box, diff_image: diff_image, mode: mode, matched: false)
+    end
+    return Result.new(expected: expected, actual: actual, diff_pixels: 0, max_delta: 0, bounding_box: nil, diff_image: nil, mode: mode, matched: true) if expected.bytes == actual.bytes
+
+    matched, diff, maximum, box = if mode == :channel
+      Metrics::Channel.compare(expected, actual, max_delta: max_delta, allowed_pixels: allowed_pixels)
+    elsif mode.to_sym == :perceptual
+      Metrics::YIQ.compare(expected, actual, threshold: threshold, allowed_pixels: allowed_pixels, ignore_antialiasing: ignore_antialiasing)
+    else
+      Metrics::YIQ.compare(expected, actual, threshold: threshold, allowed_pixels: allowed_pixels, ignore_antialiasing: ignore_antialiasing)
+    end
+    Result.new(expected: expected, actual: actual, diff_pixels: diff, max_delta: maximum, bounding_box: box, diff_image: DiffRenderer.render(expected, actual, mode: mode, threshold: threshold, max_delta: max_delta, ignore_antialiasing: ignore_antialiasing), mode: mode, matched: matched)
+  end
+
+  def assert_snapshot(actual, name, **options)
+    actual = Input.normalize(actual)
+    variant = options.delete(:variant)
+    variant_options = config.options_for(variant || :default)
+    options = variant_options.merge(options)
+    store = Store.new(config)
+    expected_path = store.path(name, variant: variant)
+    actual_path = store.output_path(name, "actual", variant: variant)
+    diff_path = store.output_path(name, "diff", variant: variant)
+    FileUtils.mkdir_p(File.dirname(actual_path))
+    actual.write(actual_path)
+    unless File.file?(expected_path)
+      if update?(name)
+        FileUtils.mkdir_p(File.dirname(expected_path))
+        actual.write(expected_path)
+        result = compare(actual, actual, **options)
+        record_result(name, result, status: "updated", variant: variant, expected_path: expected_path, actual_path: actual_path)
+        return result
+      end
+      unless ENV.key?("CI")
+        FileUtils.mkdir_p(File.dirname(expected_path))
+        actual.write(expected_path)
+        record_result(name, compare(actual, actual, **options), status: "pending", variant: variant, expected_path: expected_path, actual_path: actual_path)
+        raise Pending, "created new snapshot: #{expected_path}"
+      end
+
+      result = compare(actual, Tessel::Image.new(actual.width, actual.height))
+      record_result(name, result, status: "failed", variant: variant, expected_path: expected_path, actual_path: actual_path, diff_path: diff_path)
+      raise Mismatch.new(name, result: result, expected_path: expected_path, actual_path: actual_path, diff_path: diff_path)
+    end
+
+    result = compare(expected_path, actual, **options)
+    if result.match?
+      record_result(name, result, status: "passed", variant: variant, expected_path: expected_path, actual_path: actual_path)
+      return result
+    end
+    result.diff_image&.write(diff_path)
+    if update?(name)
+      actual.write(expected_path)
+      record_result(name, result, status: "updated", variant: variant, expected_path: expected_path, actual_path: actual_path, diff_path: diff_path)
+      return compare(actual, actual, **options)
+    end
+    FileUtils.cp(expected_path, store.output_path(name, "expected", variant: variant))
+    record_result(name, result, status: "failed", variant: variant, expected_path: expected_path, actual_path: actual_path, diff_path: diff_path)
+    raise Mismatch.new(name, result: result, expected_path: expected_path, actual_path: actual_path, diff_path: diff_path)
+  end
+
+  def record_result(name, result, status:, variant: nil, expected_path:, actual_path:, diff_path: nil)
+    relative = Store.new(config).send(:safe_name, name).tr("/", "__")
+    relative = "#{relative}@#{variant}" if variant
+    directory = File.join(config.output_dir, "results")
+    FileUtils.mkdir_p(directory)
+    payload = result.to_h.merge("name" => name.to_s, "variant" => variant&.to_s, "status" => status,
+                               "expected" => expected_path, "actual" => actual_path, "diff" => diff_path)
+    File.write(File.join(directory, "#{relative}.json"), JSON.generate(payload))
+  end
+  private_class_method :record_result
+
+  def update?(name)
+    value = ENV["LOOKALIKE_UPDATE"]
+    return false unless value
+    return true if value == "1" || value == "true"
+
+    value.split(",").any? { |pattern| File.fnmatch?(pattern, name) }
+  end
+  private_class_method :update?
+
+  class Store
+    def initialize(config = Lookalike.config)
+      @config = config
+    end
+
+    def path(name, variant: nil)
+      relative = safe_name(name)
+      candidate = variant ? File.join(@config.snapshot_dir, "#{relative}@#{safe_variant(variant)}.png") : nil
+      candidate && File.file?(candidate) ? candidate : File.join(@config.snapshot_dir, "#{relative}.png")
+    end
+
+    def output_path(name, suffix, variant: nil)
+      raise ArgumentError, "invalid output suffix" unless %w[actual expected diff].include?(suffix)
+      File.join(@config.output_dir, "#{safe_name(name)}#{variant ? "@#{safe_variant(variant)}" : ""}.#{suffix}.png")
+    end
+
+    private
+
+    def safe_name(name)
+      name = String(name)
+      raise ArgumentError, "snapshot name must be relative" if name.empty? || name.start_with?("/", "\\") || name.include?("\\") || name.include?("\0") || name.split("/").include?("..") || name.match?(/\A[A-Za-z]:/)
+
+      name
+    end
+
+    def safe_variant(variant)
+      value = variant.to_s
+      raise ArgumentError, "invalid snapshot variant" unless value.match?(/\A[a-zA-Z0-9_-]+\z/)
+      value
+    end
+  end
+
+  module Assertions
+    def assert_snapshot(actual, name, **options)
+      Lookalike.assert_snapshot(actual, name, **options)
+    rescue Pending => e
+      if respond_to?(:pend)
+        pend(e.message)
+      elsif respond_to?(:skip)
+        skip(e.message)
+      else
+        raise
+      end
+    rescue Mismatch => e
+      respond_to?(:flunk) ? flunk(e.message) : raise
+    end
+  end
+
+  module TestUnit
+    def assert_snapshot(actual, name, **options)
+      super
+    rescue Pending => e
+      pend(e.message)
+    rescue Mismatch => e
+      flunk(e.message)
+    end
+  end
+
+  module Minitest
+    def assert_snapshot(actual, name, **options)
+      super
+    rescue Pending => e
+      skip(e.message)
+    rescue Mismatch => e
+      flunk(e.message)
+    end
+  end
+
+  class Report
+    def initialize(output_dir = Lookalike.config.output_dir)
+      @output_dir = output_dir
+    end
+
+    def write(entries = Dir[File.join(@output_dir, "**", "*.actual.png")])
+      path = File.join(@output_dir, "index.html")
+      FileUtils.mkdir_p(@output_dir)
+      body = entries.map do |actual|
+        base = actual.delete_suffix(".actual.png")
+        expected = "#{base}.expected.png"
+        diff = "#{base}.diff.png"
+        relative = ->(file) { ERB::Util.html_escape(file.delete_prefix("#{@output_dir}/")) }
+        "<section><h2>#{ERB::Util.html_escape(File.basename(base))}</h2>" \
+          "<div class='compare'><img src='#{relative.call(expected)}' alt='expected'>" \
+          "<img class='actual' src='#{relative.call(actual)}' alt='actual'></div>" \
+          "<input type='range' min='0' max='100' value='50' aria-label='actual image coverage'>" \
+          "<img src='#{relative.call(diff)}' alt='difference'></section>"
+      end.join
+      File.write(path, "<!doctype html><meta charset='utf-8'><title>Lookalike</title>" \
+        "<style>body{font:14px sans-serif;background:#171923;color:#eee}section{margin:2rem 0}.compare{position:relative;display:inline-block}.compare img{display:block;max-width:100%}.compare .actual{position:absolute;inset:0;clip-path:inset(0 50% 0 0)}</style>" \
+        "#{body}<script>document.querySelectorAll('section').forEach(s=>{const range=s.querySelector('input');range.oninput=()=>s.querySelector('.actual').style.clipPath=`inset(0 ${100-range.value}% 0 0)`;});</script>")
+      results = Dir[File.join(@output_dir, "results", "*.json")].filter_map do |file|
+        JSON.parse(File.read(file))
+      rescue JSON::ParserError
+        nil
+      end
+      File.write(File.join(@output_dir, "results.json"), JSON.generate(results))
+      path
+    end
+  end
+end

data/sig/lookalike.rbs

@@ -0,0 +1,4 @@
+module Lookalike
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: lookalike
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ydah
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tessel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: Channel and perceptual visual regression testing with PNG diffs.
+email:
+- t.yudai92@gmail.com
+executables:
+- lookalike
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/lookalike
+- lib/lookalike.rb
+- lib/lookalike/assertions.rb
+- lib/lookalike/config.rb
+- lib/lookalike/input.rb
+- lib/lookalike/minitest.rb
+- lib/lookalike/report.rb
+- lib/lookalike/store.rb
+- lib/lookalike/test_unit.rb
+- lib/lookalike/version.rb
+- sig/lookalike.rbs
+homepage: https://github.com/rbgfx/lookalike
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rbgfx/lookalike
+  source_code_uri: https://github.com/rbgfx/lookalike/tree/main
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Golden image comparison for Ruby graphics
+test_files: []