golden_child 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3b5bd24b65d42730252fa72b8c65690b45376497
+  data.tar.gz: 764d9fc4dbffc4d99be6deaad9c92b90d5b63802
+SHA512:
+  metadata.gz: 13feb14a993bdb4611918dc97f21e39eff26fab99ed5924de3dad980becdd51c5f5bbd649cf75c941e9504238b4878fab28a1aad5fcf8ba879b835df5a9406cc
+  data.tar.gz: d3c5b0fdd7884fdf710b73d0cf4211520ef96e0f469bb187789bb8c040fa81bfc90eda2878ad55b603b7faecf86e3d8cdb22cb79acc45a3539ae19a0fc3a3cd7

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in golden_child.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Avdi Grimm
+
+MIT License
+
+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,23 @@
+# GoldenChild
+
+Some helpers for doing golden master testing in Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'golden_child'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install golden_child
+
+## Usage
+
+TBD.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/golden_child.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'golden_child/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "golden_child"
+  spec.version       = GoldenChild::VERSION
+  spec.authors       = ["Avdi Grimm"]
+  spec.email         = ["avdi@avdi.org"]
+  spec.summary       = %q{Some helpers for golden master testing in Ruby.}
+  spec.description   = %q{}
+  spec.homepage      = "https://github.com/avdi/golden_master"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/golden_child.rb

@@ -0,0 +1,80 @@
+require "golden_child/version"
+require "golden_child/helpers"
+require "golden_child/scenario"
+require "golden_child/configuration"
+require "fileutils"
+require "pathname"
+require "yaml/store"
+require "forwardable"
+
+module GoldenChild
+  class Error < StandardError;
+  end
+  class UserError < Error;
+  end
+
+  extend FileUtils
+  extend SingleForwardable
+
+  def_delegators :configuration, :golden_path, :project_root, :master_root,
+      :actual_root
+  def_delegators :configuration, :get_path_for_shortcode
+
+  # @return [GoldenChild::Configuration]
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # @yield [GoldenChild::Configuration] the global configuration
+  def self.configure
+    yield configuration
+  end
+
+  # @param [Array<String, Pathname>] paths or shortcodes for files to accept
+  def self.accept(*filenames)
+    filenames.each do |fn|
+      accept_file(fn)
+    end
+  end
+
+  def self.remove(*filenames)
+    filenames.each do |fn|
+      remove_master_file(fn)
+    end
+  end
+
+  def self.accept_file(path_or_shortcode)
+    path = resolve_path(path_or_shortcode)
+    master_path = find_master_for(path)
+    mkpath master_path.dirname
+    cp path, master_path
+  end
+
+
+  def self.remove_master_file(path_or_shortcode)
+    path = resolve_path(path_or_shortcode)
+    master_path = find_master_for(path)
+    rm master_path
+  end
+
+  # @return [Pathname]
+  def self.resolve_path(path_or_shortcode)
+    path = case path_or_shortcode
+    when /^@\d+$/
+      get_path_for_shortcode(path_or_shortcode)
+    else
+      path_or_shortcode
+    end
+    Pathname(path)
+  end
+
+  def self.find_master_for(path)
+    raise UserError, "No such file #{path}" unless path.exist?
+    raise UserError, "Not a file: #{path}" unless path.file?
+    rel_path = path.relative_path_from(actual_root)
+    unless rel_path
+      raise UserError, "File #{path} is not in #{actual_root}"
+    end
+    master_root + rel_path
+  end
+end

data/lib/golden_child/block_content_filter.rb

@@ -0,0 +1,19 @@
+module GoldenChild
+  BlockContentFilter = Struct.new(:patterns, :block) do
+    # @return [true, false] whether any of the patterns match
+    def ===(filename)
+      patterns.any?{|pattern|
+        case pattern
+        when String
+          File.fnmatch(pattern, filename.to_s)
+        else
+          pattern === filename.to_s
+        end
+      }
+    end
+
+    def call(file_content)
+      block.call(file_content)
+    end
+  end
+end

data/lib/golden_child/configuration.rb

@@ -0,0 +1,84 @@
+require "golden_child/block_content_filter"
+
+module GoldenChild
+  class Configuration
+    # @return [Pathname] the directory in which "actual" results will be generated
+    def actual_root
+      golden_path + "actual"
+    end
+
+    # @return [Pathname] the base directory for gold master dirs
+    def master_root
+      golden_path + "master"
+    end
+
+    # @return [Pathname] the root directory for everything GoldenChild does
+    def golden_path
+      Pathname("spec/golden")
+    end
+
+    # @return [Pathname] the root directory of the current project
+    def project_root
+      @project_root ||= Pathname.pwd
+    end
+
+    # @param [String, Pathname] new_root set the project root directory
+    def project_root=(new_root)
+      @project_root = Pathname(new_root).expand_path
+    end
+
+    # @return [Hash] The global, editable set of default env vars
+    def env
+      @env ||= {}
+    end
+
+    # @return [Enumerable<BlockContentFilter>] the configured
+    #   content filters
+    def content_filters
+      @content_filters ||= []
+    end
+
+    # Add a filter for a given file pattern. Filters are useful for removing
+    # volatile information (like timestamps) from the files to be compared.
+    # **NOTE:** filters are currently **not** suitable for removing sensitive
+    # information, since they are only applied when diffing files. The files
+    # on disk are not filtered.
+    #
+    # @param [Array<String, [#===]>] patterns Filename patterns that
+    #   determine which files this filter should be applied to. Strings are
+    #   treated as file glob patterns.
+    # @yieldparam [String] file_content the contents of the file
+    # @yieldreturn [String] the filtered file contents
+    def add_content_filter(*patterns, &filter)
+      content_filters << BlockContentFilter.new(patterns, filter)
+    end
+
+    # @param [String] code
+    # @return [String] path to the corresponding file
+    # @raise [UserError] if the shortcode is not found
+    #
+    # TODO: Move this out of Configuration
+    def get_path_for_shortcode(code)
+      value = code[/\d+/].to_i
+      state_transaction(read_only: true) do |store|
+        store[:shortcode_map].invert.fetch(value) do
+          fail UserError, "Shortcode not found: #{code}"
+        end
+      end
+    end
+
+    # @yield [YAML::Store]
+    #
+    # TODO: Move this out of Configuration
+    def state_transaction(read_only: false)
+      config_dir = project_root + ".golden_child"
+      mkpath config_dir unless config_dir.exist?
+      state_db = config_dir + "state.yaml"
+      store    = YAML::Store.new(state_db)
+      store.transaction(read_only) do
+        yield store
+      end
+    end
+
+  end
+end

data/lib/golden_child/helpers.rb

@@ -0,0 +1,30 @@
+require "fileutils"
+
+module GoldenChild
+  module Helpers
+    include FileUtils
+
+    attr_writer :scenario
+
+    # @return [Scenario] the currently active scenario
+    def scenario
+      @scenario or fail "You must set the scenario first"
+    end
+
+    # (see Scenario#populate_from)
+    def populate_from(source_dir)
+      scenario.populate_from(source_dir, caller)
+    end
+
+    # (see Scenario#run)
+    def run(*args, ** options, &block)
+      scenario.run(*args, caller: caller, ** options)
+    end
+
+    # (see Scenario#within_zip)
+    def within_zip(*args, &block)
+      scenario.within_zip(*args, &block)
+    end
+
+  end
+end

data/lib/golden_child/rspec.rb

@@ -0,0 +1,43 @@
+require "golden_child"
+
+module GoldenChild::RspecMatchers
+  extend RSpec::Matchers::DSL
+
+  matcher :match_master do |**options|
+    match do |actual|
+      @result = scenario.validate(*actual, **options)
+      @result.passed?
+    end
+
+    failure_message do |actual|
+      @result.message
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include GoldenChild::Helpers, golden: true
+  config.include GoldenChild::RspecMatchers, golden: true
+
+  config.before(:example, golden: true) do |example|
+    # If it looks like an RSpec-Given example, use the example group name.
+    #
+    # In RSpec-Given the group names the scenario,and the example names are
+    # messy source code.
+    #
+    # TODO: Determine if this is a problem for nested RSpec-Given groups
+    scenario_name = if example.description =~ /^\s*Then\b/
+                      example.example_group.description
+                    else
+                      example.full_description
+                    end
+    self.scenario = GoldenChild::Scenario.new(name: scenario_name)
+    example.metadata[:golden_child_scenario] = scenario
+    scenario.setup
+  end
+
+  config.after(:example, golden: true) do |example|
+    scenario.teardown
+  end
+end
+

data/lib/golden_child/scenario.rb

@@ -0,0 +1,273 @@
+require "fileutils"
+require "yaml"
+require "open3"
+require "rake/file_list"
+require "forwardable"
+require "rspec/support"
+
+module GoldenChild
+  class Scenario
+    include FileUtils
+    extend Forwardable
+
+    attr_reader :name, :command_history, :configuration
+
+    # @!method project_root
+    #   (see Configuration#project_root)
+    def_delegators :configuration, :golden_path, :actual_root, :project_root,
+                   :content_filters
+
+    # @abstract
+    Validation = Struct.new(:message)
+
+    class FailedValidation < Validation
+      def passed?
+        false
+      end
+    end
+    class PassedValidation < Validation
+      def passed?
+        true
+      end
+    end
+
+    # @param [String] name The name of the scenario (e.g. RSpec example group)
+    def initialize(name:, configuration: ::GoldenChild.configuration)
+      @name            = name
+      @command_history = []
+      @configuration   = configuration
+    end
+
+    # Recursively populate the current scenario with copies of files from
+    # `source_dir`
+    #
+    # @param [String, Pathname] source_dir
+    # @param [Array] caller
+    def populate_from(source_dir, caller=caller)
+      Dir.chdir(project_root) do
+        raise "Scenario has not been set up" unless actual_path.exist?
+        source_dir = Pathname(source_dir)
+        unless source_dir.directory?
+          fail RuntimeError, "No such directory #{source_dir}", caller
+        end
+
+        Dir.foreach(source_dir) do |entry|
+          next if %w[. ..].include?(entry)
+          copy_entry source_dir + entry, actual_path + entry
+        end
+      end
+    end
+
+    # Run a command in the context of the current scenario.
+    #
+    # @param [Array] args The command. See {Process.spawn} for the various
+    #   forms supported. Note that any environment should be passed via the
+    #   `env` option below.
+    # @param [true, false] allow_fail (false) Whether to raise an exception
+    #   if the command fails.
+    # @param [Hash] env Environment variables for the command
+    # @param [Array] caller
+    # @param [Hash] options
+    def run(*args, allow_fail: false, env: self.env, caller: caller, ** options)
+      options[:chdir]        ||= actual_path.to_s
+      env                    = env.map { |k, v| [k.to_s, v.to_s] }.to_h
+      stdout, stderr, status = Open3.capture3(env, *args, ** options)
+      command_history.push(
+          command: args, status: status, stdout: stdout, stderr: stderr)
+      command_log = ""
+      command_log << "\nCommand: #{args}"
+      command_log << "\nEnvironment:"
+      env.each_pair do |key, value|
+        command_log << "\n  #{key}=#{value}"
+      end
+      command_log << "\nExited with status #{status.exitstatus}"
+      command_log << "\n========== Command STDOUT ==========\n"
+      command_log << stdout
+      command_log << "\n========== End STDOUT ==========\n"
+      command_log << "\n========== Command STDERR ==========\n"
+      command_log << stderr
+      command_log << "\n========== End STDERR ==========\n"
+      (control_dir + "commands.log").open("a") do |f|
+        f.write(command_log)
+      end
+      unless status.success? || allow_fail
+        fail RuntimeError, command_log, caller
+      end
+    end
+
+    # Unzip a zip file, and execute commands in the context of the unzipped
+    # directory.
+    #
+    # You must have the `unzip(1)` program installed for this to work.helper
+    #
+    # @param [String, Pathname] relative_filename The path of the zip file
+    def within_zip(relative_filename)
+      relative_filename = Pathname(relative_filename)
+      filename          = actual_path + relative_filename
+      raise "Zip file not found: #{filename}" unless filename.exist?
+      unzip_dir = unzip_dir_for(relative_filename)
+      mkpath unzip_dir
+      unzip_succeeded =
+          system(*%W[unzip -qq #{filename} -d #{unzip_dir}])
+      raise "Could not unzip #{filename}" unless unzip_succeeded
+      push_working_dir(unzip_dir.relative_path_from(current_actual_path)) do
+        yield(unzip_dir)
+      end
+    end
+
+    # @return [Pathname]
+    def unzip_dir_for(relative_filename)
+      current_actual_path + (relative_filename.to_s + ".golden_child_unzip")
+    end
+
+    # Verify that `files` are identical to their corresponding gold master
+    # files.
+    def validate(*files, ** options)
+      paths   = Rake::FileList[*files.map(&:to_s)]
+      pass    = true
+      message = "No files to validate"
+      Dir.chdir(project_root) do
+        paths.each do |path|
+          master_file  = current_master_path + path
+          actual_file  = current_actual_path + path
+          shortcode    = get_shortcode_for(actual_file)
+          approval_cmd = "golden accept #{shortcode}"
+          message      = ""
+          file_pass    = false
+          if !actual_file.exist?
+            message << "Expected file: #{actual_file}"
+            message << "\nto be created, but it was not."
+          elsif !actual_file.file?
+            message << "Expected: #{actual_file}"
+            message << "\n to be a file, but it is a #{actual_file.ftype}."
+          elsif !master_file.exist?
+            message << "Master: #{master_file}"
+            message << "\ndoes not yet exist."
+            message << "\nActual file: #{actual_file}"
+            message << "\nhas the following content:\n\n"
+            message << filter_file(actual_file)
+            message << "\n\nIf this looks correct, run `#{approval_cmd}`"
+          elsif !master_file.file?
+            message << "Master: #{master_file}"
+            message << "must be a file, but it is a #{master_file.ftype}."
+          elsif filtered_files_differ?(master_file, actual_file)
+            message << "Actual: #{actual_file}"
+            message << "\ndiffers from master: #{master_file}"
+            message << "\n"
+            message << diff(master_file, actual_file)
+            message << "\n\nIf the changes look correct, run `#{approval_cmd}`"
+          else
+            message << "Actual file #{actual_file} matches master #{master_file}"
+            file_pass = true
+          end
+          unless file_pass
+            pass = false
+            break
+          end
+        end
+      end
+      if pass
+        PassedValidation.new(message)
+      else
+        FailedValidation.new(message)
+      end
+    end
+
+    def filtered_files_differ?(master_file, actual_file)
+      filter_file(master_file) != filter_file(actual_file)
+    end
+
+    def diff(master_file, actual_file)
+      differ      = RSpec::Support::Differ.new
+      differences = differ.diff(filter_file(actual_file), filter_file(master_file))
+      differences.empty? ? nil : differences
+    end
+
+    def filter_file(filename)
+      @filtered_files ||= {} # memoization
+      @filtered_files.fetch(filename) {
+        @filtered_files[filename] = content_filters.reduce(filename.read) {
+            |content, filter|
+          filter.call(content)
+        }
+      }
+    end
+
+    def get_shortcode_for(actual_file)
+      code = state_transaction do |store|
+        shortcode_map = (store[:shortcode_map] ||= {})
+        shortcode_map.fetch(actual_file.to_s) {
+          new_code                        = shortcode_map.values.max.to_i + 1
+          shortcode_map[actual_file.to_s] = new_code
+        }
+      end
+      "@#{code}"
+    end
+
+    def setup
+      mkpath master_path.parent
+      rmtree actual_path
+      mkpath actual_path
+      mkpath control_dir
+    end
+
+    def teardown
+    end
+
+    def actual_path
+      actual_root + relative_path
+    end
+
+    alias_method :root, :actual_path
+
+    def master_path
+      golden_path + "master" + relative_path
+    end
+
+    def current_actual_path
+      actual_path + current_working_dir
+    end
+
+    def current_master_path
+      master_path + current_working_dir
+    end
+
+    def control_dir
+      actual_path + ".golden_child"
+    end
+
+    def relative_path
+      slug
+    end
+
+    def slug
+      name.downcase.tr_s("^a-z0-9", "-")[0..255]
+    end
+
+    # @return [Hash] editable env var hash, defaults to {#configuration}
+    def env
+      @env ||= configuration.env.dup
+    end
+
+    private
+
+    def_delegators :configuration, :state_transaction, :get_path_for_shortcode
+
+    def push_working_dir(new_dir)
+      dir_stack = working_dir_stack
+      dir_stack.push(new_dir)
+      yield
+    ensure
+      dir_stack.pop
+    end
+
+    def working_dir_stack
+      Thread.current[:golden_child_working_dir] ||= []
+    end
+
+    def current_working_dir
+      last_dir = working_dir_stack.last
+      last_dir || "."
+    end
+  end
+end

data/lib/golden_child/version.rb

@@ -0,0 +1,3 @@
+module GoldenChild
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: golden_child
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Avdi Grimm
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: ''
+email:
+- avdi@avdi.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- golden_child.gemspec
+- lib/golden_child.rb
+- lib/golden_child/block_content_filter.rb
+- lib/golden_child/configuration.rb
+- lib/golden_child/helpers.rb
+- lib/golden_child/rspec.rb
+- lib/golden_child/scenario.rb
+- lib/golden_child/version.rb
+homepage: https://github.com/avdi/golden_master
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Some helpers for golden master testing in Ruby.
+test_files: []