clintegracon 0.4.1

data/lib/CLIntegracon/configuration.rb

@@ -0,0 +1,67 @@
+require 'pathname'
+
+module CLIntegracon
+
+  class << self
+
+    # @return [Configuration]
+    #         Get the shared configuration, set by {self.configure}.
+    attr_accessor :shared_config
+
+    # Set a new shared configuration
+    #
+    # @param  [Block<() -> ()>] block
+    #         the block which is evaluated on the new shared configuration
+    #
+    def configure(&block)
+      self.shared_config ||= Configuration.new
+      shared_config.instance_eval &block
+    end
+
+  end
+
+  class Configuration
+
+    # Get the subject to configure it
+    #
+    # @return [Subject]
+    #
+    def subject
+      @subject ||= Subject.new()
+    end
+
+    # Get the context to configure it
+    #
+    # @return [FileTreeSpecContext]
+    #
+    def context
+      @context ||= FileTreeSpecContext.new()
+    end
+
+    # Hook this gem in a test framework by a supported adapter
+    #
+    # @param  [Symbol] test_framework
+    #         the test framework
+    #
+    def hook_into test_framework
+      adapter = self.class.adapters[test_framework]
+      raise ArgumentError.new "No adapter for test framework #{test_framework}" if adapter.nil?
+      require adapter
+    end
+
+    private
+
+    # Get the file paths of supported adapter implementations by test framework
+    #
+    # @return [Hash<Symbol, String>]
+    #         test framework to adapter implementation files
+    #
+    def self.adapters
+      adapter_dir = Pathname('../adapter').expand_path(__FILE__)
+      @adapters ||= Dir.chdir(adapter_dir) do
+        Hash[Dir['*.rb'].map { |path| [path.gsub(/\.rb$/, '').to_sym, adapter_dir + path] }]
+      end
+    end
+
+  end
+end

data/lib/CLIntegracon/diff.rb

@@ -0,0 +1,81 @@
+require 'pathname'
+require 'colored'
+require 'diffy'
+
+module CLIntegracon
+  class Diff
+    include Enumerable
+
+    # @return [Pathname]
+    #         the expected file
+    attr_reader :expected
+
+    # @return [Pathname]
+    #         the produced file
+    attr_reader :produced
+
+    # @return [Pathname]
+    #         the relative path to the expected file
+    attr_reader :relative_path
+
+    # @return [Proc<(Pathname)->(to_s)>]
+    #         the proc, which transforms the files in a better comparable form
+    attr_accessor :preparator
+
+    # Init a new diff
+    #
+    # @param [Pathname] expected
+    #        the expected file
+    #
+    # @param [Pathname] produced
+    #        the produced file
+    #
+    # @param [Pathname] relative_path
+    #        the relative path to the expected file
+    #
+    # @param [Block<(Pathname)->(to_s)>] preparator
+    #        the block, which transforms the files in a better comparable form
+    #
+    def initialize(expected, produced, relative_path=nil, &preparator)
+      @expected = expected
+      @produced = produced
+      @relative_path = relative_path
+      preparator ||= Proc.new { |x| x } #id
+      self.preparator = preparator
+    end
+
+    def prepared_expected
+      @prepared_expected ||= preparator.call(expected)
+    end
+
+    def prepared_produced
+      @prepared_produced ||= preparator.call(produced)
+    end
+
+    # Check if the produced output equals the expected
+    #
+    # @return [Bool]
+    #         whether the expected is equal to the produced
+    #
+    def is_equal?
+      @is_equal ||= if prepared_expected.is_a? Pathname
+        FileUtils.compare_file(prepared_expected, prepared_produced)
+      else
+        prepared_expected == prepared_produced
+      end
+    end
+
+    # Enumerate all lines which differ.
+    #
+    # @param  [Hash] options
+    #         see Diffy#initialize for help.
+    #
+    # @return [Diffy::Diff]
+    #
+    def each(options = {}, &block)
+      options = { :source => 'files', :context => 3 }.merge options
+      Diffy::Diff.new(prepared_expected.to_s, prepared_produced.to_s, options).each &block
+    end
+
+  end
+end

data/lib/CLIntegracon/file_tree_spec.rb

@@ -0,0 +1,213 @@
+require 'pathname'
+require 'CLIntegracon/diff'
+require 'CLIntegracon/formatter'
+
+module CLIntegracon
+  class FileTreeSpec
+
+    # @return [FileTreeSpecContext]
+    #         The context, which configures path and file behaviors
+    attr_reader :context
+
+    # @return [String]
+    #         The concrete spec folder
+    attr_reader :spec_folder
+
+    # @return [Pathname]
+    #         The concrete spec path
+    def spec_path
+      context.spec_path + spec_folder
+    end
+
+    # @return [Pathname]
+    #         The concrete before directory for this spec
+    def before_path
+      spec_path + context.before_dir
+    end
+
+    # @return [Pathname]
+    #         The concrete after directory for this spec
+    def after_path
+      spec_path + context.after_dir
+    end
+
+    # @return [Pathname]
+    #         The concrete temp directory for this spec
+    def temp_path
+      context.temp_path + spec_folder
+    end
+
+    # Init a spec with a given context
+    #
+    # @param [FileTreeSpecContext] context
+    #        The context, which configures path and file behaviors
+    #
+    # @param [String] spec_folder
+    #        The concrete spec folder
+    #
+    def initialize(context, spec_folder)
+      @context = context
+      @spec_folder = spec_folder
+    end
+
+    # Run this spec
+    #
+    # @param [Block<(FileTreeSpec)->()>] block
+    #        The block, which will be executed after chdir into the created temporary
+    #        directory. In this block you will likely run your modifications to the
+    #        file system and use the received FileTreeSpec instance to make asserts
+    #        with the test framework of your choice.
+    #
+    def run(&block)
+      prepare!
+
+      copy_files!
+
+      Dir.chdir(temp_path) do
+        block.call self
+      end
+    end
+
+    # Compares the expected and produced directory by using the rules
+    # defined in the context
+    #
+    # @param [Block<(Diff)->()>] diff_block
+    #        The block, where you will likely define a test for each file to compare.
+    #        It will receive a Diff of each of the expected and produced files.
+    #
+    def compare(&diff_block)
+      transform_paths!
+
+      glob_all(after_path).each do |relative_path|
+        expected = after_path + relative_path
+
+        next unless expected.file?
+
+        block = special_behavior_for_path relative_path
+        next if block == context.class.nop
+
+        diff = diff_files(expected, relative_path)
+        diff.preparator = block unless block.nil?
+
+        diff_block.call diff
+      end
+    end
+
+    # Compares the expected and produced directory by using the rules
+    # defined in the context for unexpected files.
+    #
+    # This is separate because you probably don't want to define an extra
+    # test case for each file, which wasn't expected at all. So you can
+    # keep your test cases consistent.
+    #
+    # @param [Block<(Array)->()>] diff_block
+    #        The block, where you will likely define a test that no unexpected files exists.
+    #        It will receive an Array.
+    #
+    def check_unexpected_files(&block)
+      expected_files = glob_all after_path
+      produced_files = glob_all
+      unexpected_files = produced_files - expected_files
+
+      # Select only files
+      unexpected_files.reject! { |path| !path.file? }
+
+      # Filter ignored paths
+      unexpected_files.reject! { |path| special_behavior_for_path(path) == context.class.nop }
+
+      block.call unexpected_files
+    end
+
+    # Return a Formatter
+    #
+    # @return [Formatter]
+    #
+    def formatter
+      @formatter ||= Formatter.new(self)
+    end
+
+    protected
+
+      # Prepare the temporary directory
+      #
+      def prepare!
+        context.prepare!
+
+        temp_path.rmtree if temp_path.exist?
+        temp_path.mkdir
+      end
+
+      # Copies the before subdirectory of the given tests folder in the temporary
+      # directory.
+      #
+      def copy_files!
+        source = before_path
+        destination = temp_path
+        FileUtils.cp_r("#{source}/.", destination)
+      end
+
+      # Applies the in the context configured transformations.
+      #
+      def transform_paths!
+        context.transform_paths.each do |path, block|
+          Dir.glob(path) do |produced_path|
+            produced = Pathname(produced_path)
+            block.call(produced)
+          end
+        end
+      end
+
+      # Searches recursively for all files and take care for including hidden files
+      # if this is configured in the context.
+      #
+      # @param [String] path
+      #        The relative or absolute path to search in (optional)
+      #
+      # @return [Array<Pathname>]
+      #
+      def glob_all(path=nil)
+        Dir.chdir path || '.' do
+          Dir.glob("**/*", context.include_hidden_files? ? File::FNM_DOTMATCH : 0).map { |path|
+            Pathname(path)
+          }
+        end
+      end
+
+      # Find the special behavior for a given path
+      #
+      # @return [Block<(Pathname) -> to_s>]
+      #         This block takes the Pathname and transforms the file in a better comparable
+      #         state. If it returns nil, the file is ignored.
+      #
+      def special_behavior_for_path(path)
+        context.special_paths.each do |key, block|
+          matched = if key.is_a?(Regexp)
+            path.to_s.match(key)
+          else
+            File.fnmatch(key, path)
+          end
+          next unless matched
+          return block
+        end
+        return nil
+      end
+
+      # Compares two files to check if they are identical and produces a clear diff
+      # to highlight the differences.
+      #
+      # @param [Pathname] expected
+      #        The file in the after directory
+      #
+      # @param [Pathname] relative_path
+      #        The file in the temp directory
+      #
+      # @return [Diff]
+      #         An object holding a diff
+      #
+      def diff_files(expected, relative_path)
+        produced = temp_path + relative_path
+        Diff.new(expected, produced, relative_path)
+      end
+
+  end
+end

data/lib/CLIntegracon/file_tree_spec_context.rb

@@ -0,0 +1,180 @@
+require 'CLIntegracon/file_tree_spec'
+
+module CLIntegracon
+  class FileTreeSpecContext
+
+    #-----------------------------------------------------------------------------#
+
+    # @!group Attributes
+
+    # @return [Pathname]
+    #         The relative path to the integration specs
+    attr_accessor :spec_path
+
+    # @return [Pathname]
+    #         The relative path from a concrete spec directory to the directory containing the input files,
+    #         which will be available at execution
+    attr_accessor :before_dir
+
+    # @return [Pathname]
+    #         The relative path from a concrete spec directory to the directory containing the expected files after
+    #         the execution
+    attr_accessor :after_dir
+
+    # @return [Pathname]
+    #         The relative path to the directory containing the produced files after the
+    #         execution. This must not be the same as the before_dir or the after_dir.
+    #
+    # @note   **Attention**: This path will been deleted before running to ensure a clean sandbox for testing.
+    #
+    attr_accessor :temp_path
+
+    # @return [Hash<String,Block>]
+    #         the special paths of files, which need to be transformed in a better comparable form
+    attr_accessor :transform_paths
+
+    # @return [Hash<String,Block>]
+    #         the special paths of files, where an individual file diff handling is needed
+    attr_accessor :special_paths
+
+    # @return [Bool]
+    #         whether to include hidden files, when searching directories (true by default)
+    attr_accessor :include_hidden_files
+    alias :include_hidden_files? :include_hidden_files
+
+
+    #-----------------------------------------------------------------------------#
+
+    # @!group Initializer
+
+    # "Designated" initializer
+    #
+    # @param [Hash<Symbol,String>] properties
+    #        The configuration parameter (optional):
+    #        :spec_path   => see self.spec_path
+    #        :before_dir  => see self.before_dir
+    #        :after_dir   => see self.after_dir
+    #        :temp_path   => see self.temp_path
+    #
+    def initialize(properties={})
+      self.spec_path   = properties[:spec_path]   || '.'
+      self.temp_path   = properties[:temp_path]   || 'tmp'
+      self.before_dir  = properties[:before_dir]  || 'before'
+      self.after_dir   = properties[:after_dir]   || 'after'
+      self.transform_paths = {}
+      self.special_paths = {}
+      self.include_hidden_files = true
+    end
+
+
+    #-----------------------------------------------------------------------------#
+
+    # @!group Helper
+
+    # This value is used for ignored paths
+    #
+    # @return [Proc]
+    #         Does nothing
+    def self.nop
+      @nop ||= Proc.new {}
+    end
+
+
+    #-----------------------------------------------------------------------------#
+
+    # @!group Setter
+
+    def spec_path=(spec_path)
+      # Spec dir has to exist.
+      @spec_path= Pathname(spec_path).realpath
+    end
+
+    def temp_path=(temp_path)
+      # Temp dir, doesn't have to exist itself, it will been created, but let's ensure
+      # that at least the last but one path component exist.
+      raise "temp_path's parent directory doesn't exist" unless (Pathname(temp_path) + '..').exist?
+      @temp_path = Pathname(temp_path).realpath
+    end
+
+    def before_dir=(before_dir)
+      @before_dir = Pathname(before_dir)
+    end
+
+    def after_dir=(after_dir)
+      @after_dir = Pathname(after_dir)
+    end
+
+
+    #-----------------------------------------------------------------------------#
+
+    # @!group DSL-like Setter
+
+    # Registers a block for special handling certain files, matched with globs.
+    # Multiple transformers can match a single file.
+    #
+    # @param  [String...] file_paths
+    #         The file path(s) of the files, which were created/changed and need transformation
+    #
+    # @param  [Block<(Pathname) -> ()>] block
+    #         The block, which takes each of the matched files, transforms it if needed
+    #         in a better comparable form in the temporary path, so that the temporary
+    #         will be compared to a given after file, or makes appropriate expects, which
+    #         depend on the used test framework
+    #
+    def transform_produced(*file_paths, &block)
+      file_paths.each do |file_path|
+        self.transform_paths[file_path] = block
+      end
+    end
+
+    # Registers a block for special handling certain files, matched with globs.
+    # Registered file paths will be excluded from default comparison by `diff`.
+    # Multiple special handlers can match a single file.
+    #
+    # @param  [String|Regexp...] file_paths
+    #         The file path(s) of the files, which were created/changed and need special comparison
+    #
+    # @param  [Block<(Pathname) -> (String)>] block
+    #         The block, which takes each of the matched files, transforms it if needed
+    #         in a better comparable form.
+    #
+    def has_special_handling_for(*file_paths, &block)
+      file_paths.each do |file_path|
+        self.special_paths[file_path] = block
+      end
+    end
+
+    # Copies the before subdirectory of the given tests folder in the temporary
+    # directory.
+    #
+    # @param  [String|RegExp...] file_path
+    #         the file path of the files, which were changed and need special comparison
+    #
+    def ignores(*file_path)
+      has_special_handling_for *file_path, &self.class.nop
+    end
+
+
+    #-----------------------------------------------------------------------------#
+
+    # @!group Interaction
+
+    # Prepare the temporary directory
+    #
+    def prepare!
+      temp_path.mkpath
+    end
+
+    # Get a specific spec with given folder to run it
+    #
+    # @param [String] folder
+    #        The name of the folder of the tests
+    #
+    # @return [FileTreeSpec]
+    #
+    def spec(spec_folder)
+      FileTreeSpec.new(self, spec_folder)
+    end
+
+  end
+end