golly-utils 0.0.1 → 0.6.0

data/lib/golly-utils/testing/file_helpers.rb

@@ -0,0 +1,117 @@
+require 'golly-utils/testing/helpers_base'
+require 'tmpdir'
+
+module GollyUtils::Testing::Helpers
+
+  # Creates an empty, temporary directory and changes the current directory into it.
+  #
+  # @example
+  #   puts Dir.pwd        # => /home/david/my_project
+  #   inside_empty_dir {
+  #     puts Dir.pwd      # => /tmp/abcdef123567
+  #   }
+  #                       # Empty directory now removed
+  #   puts Dir.pwd        # => /home/david/my_project
+  #
+  # @param [nil|String] dir_name If not `nil`, then the empty directory name will be set to the provided value.
+  # @overload inside_empty_dir(dir_name = nil, &block)
+  #   When a block is given, after yielding, the current directory is restored and the temp directory deleted.
+  #   @yieldparam [String] dir The newly-created temp dir.
+  #   @return The result of yielding.
+  # @overload inside_empty_dir(dir_name = nil)
+  #   When no block is given the current directory is *not* restored and the temp directory *not* deleted.
+  #   @return [String] The newly-created temp dir.
+  def inside_empty_dir(dir_name=nil)
+    if block_given?
+      Dir.mktmpdir {|dir|
+        if dir_name
+          dir= File.join dir, dir_name
+          Dir.mkdir dir
+        end
+        Dir.chdir(dir) {
+          (@tmp_dir_stack ||= [])<< :inside_empty_dir
+          begin
+            return yield dir
+          ensure
+            @tmp_dir_stack.pop
+          end
+        }
+      }
+    else
+      x= {}
+      x[:old_dir]= Dir.pwd
+      x[:tmp_dir]= Dir.mktmpdir
+      if dir_name
+        x[:tmp_dir]= File.join x[:tmp_dir], dir_name
+        Dir.mkdir x[:tmp_dir]
+      end
+      Dir.chdir x[:tmp_dir]
+      (@tmp_dir_stack ||= [])<< x
+      x[:tmp_dir]
+    end
+  end
+
+  # Indicates whether the current directory is one made by {#inside_empty_dir}.
+  #
+  # @return [Boolean]
+  def in_tmp_dir?
+    @tmp_dir_stack && !@tmp_dir_stack.empty? or false
+  end
+
+  # To be used in conjunction with {#inside_empty_dir}.
+  #
+  # @example
+  #   inside_empty_dir
+  #   begin
+  #     # Do stuff in empty dir
+  #   ensure
+  #     step_out_of_tmp_dir
+  #   end
+  #
+  # @return [nil]
+  def step_out_of_tmp_dir
+    if @tmp_dir_stack
+      x= @tmp_dir_stack.pop
+      raise "You cannot call step_out_of_tmp_dir() within the yield block of #{x}()" if x.is_a?(Symbol)
+      Dir.chdir x[:old_dir]
+      FileUtils.rm_rf x[:tmp_dir]
+    end
+    nil
+  end
+
+  # Returns a list of all files in a directory tree.
+  #
+  # @param [String, nil] dir The directory to inspect, or `nil` to indicate the current directory.
+  # @return [Array<String>] A sorted array of files. Filenames will be relative to the provided directory.
+  def get_files(dir=nil)
+    get_dir_entries(dir){|f| File.file? f }
+  end
+
+  # Returns a list of all subdirectories in a directory.
+  #
+  # @param [String, nil] dir The directory to inspect, or `nil` to indicate the current directory.
+  # @return [Array<String>] A sorted array of dirs. Filenames will be relative to the provided directory. `.` and `..`
+  #   will never be returned.
+  def get_dirs(dir=nil)
+    get_dir_entries(dir){|f| File.directory? f }
+  end
+
+  # Returns a list of all files, directories, symlinks, etc in a directory tree.
+  #
+  # @param [String, nil] dir The directory to inspect, or `nil` to indicate the current directory.
+  # @param select_filter An optional filter to be applied to each entry where negative calls result in the entry being
+  #   discarded.
+  # @return [Array<String>] A sorted array of dir entries. Filenames will be relative to the provided directory. `.` and
+  #   `..` will never be returned.
+  def get_dir_entries(dir=nil, &select_filter)
+    if dir
+      Dir.chdir(dir){ get_dir_entries &select_filter }
+    else
+      Dir.glob('**/*',File::FNM_DOTMATCH)
+        .reject{|f| /(?:^|[\\\/]+)\.{1,2}$/ === f } # Ignore:  .  ..  dir/.  dir/..
+        .select{|f| select_filter ? select_filter.call(f) : true }
+        .sort
+    end
+  end
+
+end

data/lib/golly-utils/testing/helpers_base.rb

@@ -0,0 +1,20 @@
+module GollyUtils
+  # This module is the parent module for utility code that client may find useful when writing tests.
+  #
+  # (This has nothing to do with GollyUtils' own, internal tests.)
+  module Testing
+    module Helpers
+
+      # @!visibility private
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        # @!visibility private
+        SELF= self
+      end
+
+    end
+  end
+end

data/lib/golly-utils/testing/rspec/arrays.rb

@@ -0,0 +1,85 @@
+require 'golly-utils/testing/rspec/base'
+require 'golly-utils/ruby_ext/enumerable'
+
+module GollyUtils::Testing::RSpecMatchers
+
+  #-----------------------------------------------------------------------------------------------------------------
+
+  # @!visibility private
+  class EqualsArray
+
+    def initialize(expected)
+      raise "Array expected, not #{expected.inspect}" unless expected.is_a?(Array)
+      @expected= expected
+    end
+
+    def matches?(tgt)
+      raise "Array expected, not #{tgt.inspect}" unless tgt.is_a?(Array)
+      @tgt= tgt
+      tgt == @expected
+    end
+
+    def failure_message_for_should
+      @common= @tgt & @expected
+      @missing= @expected - @common - @tgt
+      @extra= @tgt - @common - @expected
+
+      msg= unless @missing.empty? and @extra.empty?
+          # Element mismatch
+          m("Missing",@missing) + m("Unexpected",@extra)
+        else
+          # Check freq differences
+          tgt_freq= @tgt.frequency_map
+          expected_freq= @expected.frequency_map
+          freq_diff= tgt_freq.inject({}){|h,kv|
+            e,a = kv
+            diff= a - expected_freq[e]
+            h[e]= diff unless diff == 0
+            h
+          }
+          if !freq_diff.empty?
+            # Freq differences
+            "Both arrays contain the same elements but have different frequencies of occurrance.\nFrequency differences: (neg=not enough, pos=too many)\n  #{freq_diff.inspect}"
+          elsif @tgt.sort_by(&:to_s) == @expected.sort_by(&:to_s)
+            # Order difference
+            "They're in different orders." + m("Actual",@tgt,false) + m("Expected",@expected,false)
+          else
+            # Unknown difference
+            m("Actual",@tgt,false) + m("Expected",@expected,false)
+          end
+        end
+
+      "expected that arrays would match. #{msg}"
+    end
+
+    def failure_message_for_should_not
+      "expected that arrays would not match." + m("Contents",@expected)
+    end
+
+    private
+    def m(name, array, sort=true)
+      return '' if array.empty?
+      array= array.sort_by(&:to_s) if sort
+      "\n#{name} elements: #{array.inspect}"
+    end
+  end
+
+  # Passes if an array is the same as the target array.
+  #
+  # The advantage of calling this rather than `==` is that the error messages on failure here are customised for array
+  # comparison and will provide much more useful description of why the arrays don't match.
+  #
+  # @note The order and frequency of elements matters; call `sort` or `uniq` first if required.
+  #
+  # @example
+  #   %w[a a b].should equal_array %w[a a b]
+  #   %w[b a b].should_not equal_array %w[a a b]
+  #   files.should equal_array(expected)
+  def equal_array(expected)
+    return be_nil if expected.nil?
+    EqualsArray.new(expected)
+  end
+
+  #-----------------------------------------------------------------------------------------------------------------
+
+end

data/lib/golly-utils/testing/rspec/base.rb

@@ -0,0 +1,9 @@
+require 'golly-utils/testing/helpers_base'
+
+module GollyUtils::Testing::RSpecMatchers
+end
+
+RSpec::configure do |config|
+  config.include GollyUtils::Testing::Helpers
+  config.include GollyUtils::Testing::RSpecMatchers
+end

data/lib/golly-utils/testing/rspec/deferrable_specs.rb

@@ -0,0 +1,111 @@
+module GollyUtils
+  module Testing
+
+    # With this module you can create specs that don't start running until manually started elsewhere in another spec.
+    #
+    # This is only really useful when writing integration tests in spec format, where specs (aka examples) are not
+    # isolated tests but single components of a larger-scale test. This is especially the case when checking
+    # asynchronous events, or managing dependencies on state of an external entity.
+    #
+    # ## Usage
+    # * Extend (not include) {DeferrableSpecs}.
+    # * Create specs/examples using {ClassMethods#deferrable_spec deferrable_spec}.
+    # * In other specs/examples, call {InstanceMethods#start_deferred_tests start_deferred_tests} to start deferred tests.
+    #
+    # @example
+    #     describe 'Integration test #2' do
+    #       extend GollyUtils::Testing::DeferrableSpecs
+    #
+    #       it("Register client, notices and default prefs") do
+    #         scenario.register_client
+    #         scenario.register_notification_groups
+    #         scenario.register_notices
+    #         scenario.set_default_preferences
+    #
+    #         start_deferred_test :email1
+    #         start_deferred_test :email2
+    #         start_deferred_test :mq
+    #       end
+    #
+    #       # Deferred until registration of client, notices and preferences are complete
+    #       deferrable_spec(:email1, "Sends emails (to unregistered contacts)") do
+    #         assert_sends_email ...
+    #       end
+    #
+    #       ...
+    #
+    #     end
+    module DeferrableSpecs
+
+      # @!visibility private
+      def self.extended(base)
+        base.send :include, InstanceMethods
+        base.extend ClassMethods
+        base.instance_eval{ @deferrable_specs= {} }
+      end
+
+      module ClassMethods
+        # @!visibility private
+        attr_reader :deferrable_specs
+
+        # Declares a test case that will start paused and not run until allowed within another test case.
+        #
+        # @param [Symbol] key A unique key that will later be used to refer back to this test case.
+        # @param [String] name The name of the test case.
+        # @raise If the given key has already been used.
+        # @see InstanceMethods#start_deferred_tests
+        def deferrable_spec(key, name, &block)
+          raise "Invalid test key; please pass a Symbol." unless key.is_a?(Symbol)
+          raise "Invalid test name; please pass a String." unless name.is_a?(String)
+          raise "You must provide a block of test code. This test needs to do something." if block.nil?
+          raise "The key #{key.inspect} has already been used." if deferrable_specs[key]
+          deferrable_specs[key]= {block: block}
+          class_eval <<-EOB
+            it(#{name.inspect}){ deferred_join #{key.inspect} }
+          EOB
+        end
+
+      end
+
+      module InstanceMethods
+
+
+        # Triggers one or more deferred tests to start running in the background.
+        #
+        # @param [Symbol] first_key The identifying key of the deferred test to start. (The name must match that given
+        #     in {ClassMethods#deferrable_spec}).
+        # @param [Array<Symbol>] other_keys Keys of additional tests to start.
+        # @raise If a test name is invalid (i.e. hasn't been declared).
+        # @raise If a test has already been started.
+        # @return [true]
+        def start_deferred_tests(first_key,*other_keys)
+          ([first_key]+other_keys).flatten.uniq.each do |key|
+            raise "Unknown defferable test: #{key}" unless d= self.class.deferrable_specs[key]
+            raise "Test already started: #{key}" if d[:thread]
+            s= self.dup
+            d[:thread]= Thread.new{ s.instance_eval &b }
+          end
+          true
+        end
+
+        alias start_deferred_test start_deferred_tests
+
+        private
+
+        # Waits for a deferred test to run in the background and complete.
+        def deferred_join(key)
+          raise "Unknown defferable test: #{key}" unless d= self.class.deferrable_specs[key]
+          if t= d[:thread]
+            t.join
+          else
+            #raise "Test hasn't started: #{key}"
+            warn "Deferrable spec #{key.inspect} wasn't deferred. Start it elsewhere with start_deferred_test #{key.inspect}"
+            raise "Test block missing." unless b= d[:block]
+            b.call
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/golly-utils/testing/rspec/files.rb

@@ -0,0 +1,262 @@
+require 'golly-utils/testing/rspec/base'
+require 'golly-utils/testing/file_helpers'
+
+module GollyUtils::Testing::Helpers::ClassMethods
+
+  # Runs each RSpec example in a new, empty directory.
+  #
+  # Old directories are deleted at the end of each example, and the original current-directory restored.
+  #
+  # @param [nil|String] dir_name If not `nil`, then the empty directory name will be set to the provided value.
+  # @return [void]
+  def run_each_in_empty_dir(dir_name=nil)
+    eval <<-EOB
+      around :each do |ex|
+        inside_empty_dir(#{dir_name.inspect}){ ex.run }
+      end
+    EOB
+  end
+
+  # Runs each RSpec example in a new, empty directory unless the context has already put it in one (for example, via
+  # {#run_all_in_empty_dir}).
+  #
+  # @param [nil|String] dir_name If not `nil`, then the empty directory name will be set to the provided value.
+  # @return [void]
+  # @see #in_tmp_dir?
+  def run_each_in_empty_dir_unless_in_one_already(dir_name=nil)
+    eval <<-EOB
+      around :each do |ex|
+        in_tmp_dir? ? ex.run : inside_empty_dir(#{dir_name.inspect}){ ex.run }
+      end
+    EOB
+  end
+
+
+  # Runs all RSpec examples (in the current context) in a new, empty directory.
+  #
+  # The directory is deleted after all examples have run, and the original current-directory restored.
+  #
+  # @param [nil|String] dir_name If not `nil`, then the empty directory name will be set to the provided value.
+  # @yield Invokes the given block (if one given) once before any examples run, inside the empty dir, to perform any
+  #   additional initialisation required.
+  # @return [void]
+  def run_all_in_empty_dir(dir_name=nil, &block)
+    block ||= Proc.new{}
+    @@around_all_in_empty_dir_count ||= 0
+    @@around_all_in_empty_dir_count += 1
+    block_name= :"@@around_all_in_empty_dir_#@@around_all_in_empty_dir_count"
+    SELF.class_variable_set block_name, block
+    eval <<-EOB
+      before(:all){
+        inside_empty_dir(#{dir_name.inspect})
+        block= ::#{SELF}.class_variable_get(:"#{block_name}")
+        instance_exec &block
+      }
+      after(:all){ step_out_of_tmp_dir }
+    EOB
+  end
+
+end
+
+#-----------------------------------------------------------------------------------------------------------------------
+
+module GollyUtils::Testing::RSpecMatchers
+
+  # @!visibility private
+  class ExistAsFile
+    def matches?(tgt)
+      @tgt= tgt
+      File.exists? tgt and File.file? tgt
+    end
+
+    def failure_message_for_should
+      m "expected that '#@tgt' would be an existing file."
+    end
+
+    def failure_message_for_should_not
+      m "expected that '#@tgt' would not exist."
+    end
+
+    private
+    def m(msg)
+      dir= File.dirname(@tgt)
+      if Dir.exists? dir
+        Dir.chdir(dir) {
+          files= Dir.glob('*',File::FNM_DOTMATCH).select{|f| File.file? f }.sort
+          indir= dir == '.' ? '' : " in #{dir}"
+          "#{msg}\nFiles found#{indir}: #{files.join '  '}"
+        }
+      else
+        "#{msg}\nDirectory doesn't exist: #{dir}"
+      end
+    end
+  end
+
+  # Passes if a file exists (relative to the current directory) with a name specified by the target string.
+  #
+  # Note: This only passes if a file is found; a directory with the same name will fail.
+  #
+  # @example
+  #   'Gemfile'.should exist_as_a_file
+  #   '/tmp/stuff'.should_not exist_as_a_file
+  def exist_as_a_file
+    ExistAsFile.new
+  end
+  alias :exist_as_file :exist_as_a_file
+
+  #---------------------------------------------------------------------------------------------------------------------
+
+  # @!visibility private
+  class ExistAsDir
+    def matches?(tgt)
+      @tgt= tgt
+      Dir.exists? tgt
+    end
+
+    def failure_message_for_should
+      m "expected that '#@tgt' would be an existing directory."
+    end
+
+    def failure_message_for_should_not
+      m "expected that '#@tgt' would not exist."
+    end
+
+    private
+    def m(msg)
+      dir= File.expand_path('..',@tgt).sub(Dir.pwd+'/','')
+      if Dir.exists? dir
+        Dir.chdir(dir) {
+          dirs= Dir.glob('*',File::FNM_DOTMATCH).select{|f| File.directory? f }.sort - %w[. ..]
+          indir= dir == '.' ? '' : " in #{dir}"
+          "#{msg}\nDirs found#{indir}: #{dirs.join '  '}"
+        }
+      else
+        "#{msg}\nDirectory doesn't exist: #{dir}"
+      end
+    end
+  end
+
+  # Passes if a directory exists (relative to the current directory) with a name specified by the target string.
+  #
+  # @example
+  #   'lib'.should exist_as_a_dir
+  #   'cache/z01'.should_not exist_as_a_dir
+  def exist_as_a_dir
+    ExistAsDir.new
+  end
+  alias :exist_as_dir :exist_as_a_dir
+
+  #---------------------------------------------------------------------------------------------------------------------
+
+  # @!visibility private
+  class FileWithContents
+    def initialize
+      @contents= []
+      @not_contents= []
+      @normalisation_fns= []
+    end
+
+    def and(c1,*cn)
+      @contents.concat [c1]+cn
+      self
+    end
+
+    def and_not(c1,*cn)
+      @not_contents.concat [c1]+cn
+      self
+    end
+
+    def _and_normalisation_fn(&fn)
+      @normalisation_fns<< fn
+      self
+    end
+
+    def when_normalised_with(&fn)
+      instance_eval <<-EOB
+        alias :and :_and_normalisation_fn
+        def and_not(*) raise "and_not() cannot be called after when_normalised_with()." end
+      EOB
+      self.and &fn
+    end
+    alias :when_normalized_with :when_normalised_with
+
+    def matches?(file)
+      @contents= @contents.flatten.compact.uniq
+      @not_contents= @not_contents.flatten.compact.uniq
+      file.should ExistAsFile.new
+      @filename= file
+      @file_content= File.read(file)
+
+      @normalisation_fns.each do |fn|
+        @file_content= fn.(@file_content)
+        @contents.map!     {|c| c.is_a?(String) ? fn.(c) : c}
+        @not_contents.map! {|c| c.is_a?(String) ? fn.(c) : c}
+      end
+
+      @failures= []
+      @not_failures= []
+      @contents.each     {|c| @failures<< c unless c === @file_content }
+      @not_contents.each {|c| @not_failures<< c if c === @file_content }
+
+      @failures.empty? and @not_failures.empty?
+    end
+
+    def failure_message_for_should
+      if !@failures.empty?
+        expected_msg @failures
+      else
+        unexpected_msg @not_failures
+      end
+    end
+
+    def failure_message_for_should_not
+      inv= @contents - @failures
+      if !inv.empty?
+        unexpected_msg inv
+      else
+        expected_msg @not_contents - @not_failures
+      end
+    end
+
+    private
+
+    def expected_msg(expected)
+      "expected that '#@filename' would have certain content.\n" \
+        + expected.map{|f| "      Expected: #{f.inspect}" }.join("\n") \
+        + "\nActual Content: #{@file_content.inspect}"
+    end
+
+    def unexpected_msg(unexpected)
+      "expected that '#@filename' would not have certain content.\n" \
+        + unexpected.map{|f| "Unexpected: #{f.inspect}" }.join("\n") \
+        + "\nActual Content: #{@file_content.inspect}"
+    end
+  end
+
+  # Checks that a file exists and has expected content.
+  #
+  # @example
+  #   # Specify a single string to for a straight 1:1 comparison.
+  #   'version.txt'.should be_file_with_contents "2\n"
+  #
+  #   # Use regex and the and() method to add multiple expectations
+  #   'Gemfile'.should be_file_with_contents(/['"]rspec['"]/).and(/['"]golly-utils['"]/)
+  #
+  #   # Negative checks can be added too
+  #   'Gemfile'.should be_file_with_contents(/gemspec/).and_not(/rubygems/)
+  #
+  # @example With normalisation
+  #   # You can specify functions to normalise both the file and expectation.
+  #   'version.txt'.should be_file_with_contents("2").when_normalised_with(&:chomp)
+  #
+  #   # You can add multiple normalisation functions by specifying and() after the first
+  #   'stuff.txt'.should be_file_with_contents(/ABC/)
+  #                      .and(/DEF/)
+  #                      .and(/123\n/)
+  #                      .when_normalised_with(&:upcase)
+  #                      .and(&:chomp)
+  def be_file_with_contents(contents, *extra)
+    FileWithContents.new.and(contents).and(extra)
+  end
+  alias :be_file_with_content :be_file_with_contents
+end