ul-wukong 4.1.0

data/lib/wukong/spec_helpers/integration_tests/integration_test_runner.rb

@@ -0,0 +1,97 @@
+require 'open3'
+
+module Wukong
+  module SpecHelpers
+    
+    # A runner for running commands in a subprocess.
+    class IntegrationTestRunner
+
+      # The command to execute
+      attr_accessor :cmd
+      
+      # The directory in which to execute the command.
+      attr_accessor :cwd
+
+      # The ID of the spawned subprocess (while it was running).
+      attr_accessor :pid
+
+      # The STDOUT of the spawned process.
+      attr_accessor :stdout
+
+      # The STDERR of the spawned process.
+      attr_accessor :stderr
+
+      # The exit code of the spawned process.
+      attr_accessor :exit_code
+
+      # Run the command and capture its outputs and exit code.
+      #
+      # @return [true, false]
+      def run!
+        return false if ran?
+        FileUtils.cd(cwd) do
+          Open3.popen3(env, cmd) do |i, o, e, wait_thr|
+            self.pid = wait_thr.pid
+            
+            @inputs.each { |input| i.puts(input) }
+            i.close
+            
+            self.stdout    = o.read
+            self.stderr    = e.read
+            self.exit_code = wait_thr.value.to_i
+          end
+        end
+        @ran = true
+      end
+
+      # Initialize a new IntegrationTestRunner to run a given command.
+      def initialize args, options
+        @args   = args
+        @env    = options[:env]
+        @cwd    = options[:cwd]
+        @inputs = []
+      end
+
+      def cmd
+        @args.compact.map(&:to_s).join(' ')
+      end
+
+      def on *events
+        @inputs.concat(events)
+        self
+      end
+      alias_method :<, :on
+
+      def in dir
+        @cwd = dir
+        self
+      end
+
+      def using env
+        @env = env
+        self
+      end
+
+      def env
+        ENV.to_hash.merge(@env || {})
+      end
+
+      def ran?
+        @ran
+      end
+      
+      def cmd_summary
+        [
+         cmd,
+         "with env #{env_summary}",
+         "in dir #{cwd}"
+        ].join("\n")
+      end
+
+      def env_summary
+        { "PATH" => env["PATH"], "RUBYLIB" => env["RUBYLIB"] }.inspect
+      end
+      
+    end
+  end
+end

data/lib/wukong/spec_helpers/shared_examples.rb

@@ -0,0 +1,22 @@
+shared_examples_for 'a processor' do |options = {}|
+  it 'is registered' do
+    Wukong.registry.retrieve(options[:named].to_sym).should_not be_nil
+  end
+  it{ processor(options[:named]).processor.should respond_to(:setup)    }
+  it{ processor(options[:named]).processor.should respond_to(:process)  }
+  it{ processor(options[:named]).processor.should respond_to(:finalize) }
+  it{ processor(options[:named]).processor.should respond_to(:stop)     }
+end
+
+shared_examples_for 'a plugin' do |options = {}|
+  it "is registered as a Wukong plugin " do
+    Wukong::PLUGINS.should include(subject)
+  end
+  it { should respond_to(:configure) }
+  it { should respond_to(:boot)      }
+end
+
+shared_examples_for 'a model class' do |options = {}|
+  it        { should respond_to(:receive) }
+  its(:new) { should respond_to(:to_wire) }
+end

data/lib/wukong/spec_helpers/unit_tests.rb

@@ -0,0 +1,135 @@
+require_relative('unit_tests/unit_test_driver')
+require_relative('unit_tests/unit_test_runner')
+require_relative('unit_tests/unit_test_matchers')
+
+module Wukong
+  module SpecHelpers
+
+    # This module defines helpers that are useful when running unit
+    # tests for processors.
+    module UnitTests
+
+      # Create and boot up a runner of the given `klass`.
+      #
+      # Options to the runner class are given in the `args` Array.
+      # The last element of this Array can be a Hash of options to
+      # directly pass to the runner (especially useful in unit tests).
+      # The rest of the elements are strings that will be parsed as
+      # though they were command-line arguments.
+      #
+      # @example Create a runner that simulates `wu-local` with a set of arguments
+      #
+      #   runner Wukong::Local::LocalRunner, 'wu-local', '--foo=bar', '--baz=boof', wof: 'bing'
+      #
+      # A passed block will be eval'd in the context of the newlyl
+      # created runner instance.  This can be used to interact with
+      # the runner's insides after initialization.
+      #
+      # @example Create a custom runner and set a property on it
+      #
+      #   runner(CustomRunner, 'wu-custom', '--foo=bar') do
+      #     # eval'd in scope of new runner instance
+      #     do_some_special_thing!
+      #   end
+      #
+      # @param [Class] klass
+      # @param [String] program_name
+      # @param [Array<String>, Hash] args
+      def runner klass, program_name, *args, &block
+        settings = args.extract_options!
+        
+        ARGV.replace(args.map(&:to_s))
+
+        klass.new.tap do |the_runner|
+          the_runner.program_name = program_name
+          the_runner.instance_eval(&block) if block_given?
+          the_runner.boot!(settings)
+        end
+      end
+
+      # Create a runner for unit tests in a variety of convenient
+      # ways.
+      #
+      # Most simply, called without args, will return a UnitTestRunner
+      # a the klass named in the containing `describe` or `context`:
+      #
+      #   context MyApp::Tokenizer do
+      #     it "uses whitespace as the default separator between tokens" do
+      #       processor.separator.should == /\s+/
+      #     end
+      #   end
+      #
+      # if your processor has been registered (you created it with the
+      # <tt>Wukong.processor</tt> helper method or otherwise
+      # registered it yourself) then you can use its name:
+      #
+      #   context :tokenizer do
+      #     it "uses whitespace as the default separator between tokens" do
+      #       processor.separator.should == /\s+/
+      #     end
+      #   end
+      #
+      # The `processor` method can also be used inside RSpec's
+      # `subject` and `let` methods:
+      #
+      #   context "with no arguments" do
+      #     subject { processor }
+      #       it "uses whitespace as the default separator between tokens" do
+      #         separator.should == /\s+/
+      #       end
+      #     end
+      #   end
+      #
+      # and you can easily pass arguments, just like you would on the
+      # command line or in a dataflow definition:
+      # 
+      #   context "with arguments" do
+      #     subject { processor(separator: ' ') }
+      #       it "uses whitespace as the default separator between tokens" do
+      #         separator.should == ' '
+      #       end
+      #     end
+      #   end
+      #
+      # You can even name the processor directly if you want to:
+      #
+      #   context "tokenizers" do
+      #     let(:default_tokenizer) { processor(:tokenizer)                                          }
+      #     let(:complex_tokenizer) { processor(:complex_tokenizer, stemming: true)                  }
+      #     let(:french_tokenizer)  { processor(:complex_tokenizer, stemming: true, language: 'fr')  }
+      #     ...
+      #   end
+      def unit_test_runner *args, &block
+        settings = args.extract_options!
+        name     = (args.first || self.class.description)
+        UnitTestRunner.new(name, settings).tap do |the_runner|
+          the_runner.program_name = 'wu-local'
+          yield the_runner.driver.processor if block_given?
+          the_runner.boot!(settings)
+        end.driver
+      end
+      alias_method :processor, :unit_test_runner
+
+      def emit *expected
+        UnitTestMatcher.new(*expected)
+      end
+
+      def emit_json *expected
+        JsonMatcher.new(*expected)
+      end
+
+      def emit_delimited delimiter, *expected
+        DelimiterMatcher.new(delimiter, *expected)
+      end
+
+      def emit_tsv *expected
+        TsvMatcher.new(*expected)
+      end
+
+      def emit_csv *expected
+        CsvMatcher.new(*expected)
+      end
+    end
+    
+  end
+end

data/lib/wukong/spec_helpers/unit_tests/unit_test_driver.rb

@@ -0,0 +1,132 @@
+module Wukong
+  module SpecHelpers
+    class UnitTestDriver < Array
+      
+      include Wukong::DriverMethods
+      
+      def initialize label, settings={}
+        super()
+        construct_dataflow(label, settings)
+        setup_dataflow
+      end
+      
+      def process output
+        self << output
+      end
+      
+      def run
+        return false unless dataflow
+        given_records.each do |input|
+          send_through_dataflow(input)
+        end
+        finalize_and_stop_dataflow
+        self
+      end
+      
+      def processor
+        dataflow.root
+      end
+      
+      # An array of accumulated records to process come match-time.
+      attr_reader :given_records
+
+      # Give a collection of records to the processor.
+      #
+      # @param [Array] records
+      def given *records
+        @given_records ||= []
+        @given_records.concat(records)
+        self                    # for chaining
+      end
+
+      # Give a collection of records to the processor but turn each
+      # to JSON first.
+      #
+      # @param [Array] records
+      def given_json *records
+        self.given(*records.map { |record| MultiJson.dump(record) })
+      end
+      
+      # Give a collection of records to the processor but join each
+      # in a delimited format first.
+      #
+      # @param [Array] records
+      def given_delimited delimiter, *records
+        self.given(*records.map do |record|
+                     record.map(&:to_s).join(delimiter)
+                   end.join("\n"))
+      end
+
+      # Give a collection of records to the processor but join each
+      # in TSV format first.
+      #
+      # @param [Array] records
+      def given_tsv *records
+        self.given_delimited("\t", *records)
+      end
+
+      # Give a collection of records to the processor but join each
+      # in CSV format first.
+      #
+      # @param [Array] records
+      def given_csv *records
+        self.given_delimited(",", *records)
+      end
+
+      # Return the output of the processor on the given records.
+      #
+      # Calling this method, like passing the processor to an `emit`
+      # matcher, will trigger processing of all the given records.
+      #
+      # Returns a UnitTestDriver, which is a subclass of array, so the
+      # usual matchers like `include` and so on should work, as well
+      # as explicitly indexing to introspect on particular records.
+      #
+      # @return [UnitTestDriver]
+      def output
+        run
+        self
+      end
+
+      # Return the output of the processor on the given records,
+      # parsing as a string with the given `delimiter` first.
+      #
+      # @param [String] delimiter
+      # @see #output
+      # @return [Array<String>]
+      def delimited_output(delimiter)
+        output.map { |record| record.split(delimiter) }
+      end
+      
+      # Return the output of the processor on the given records,
+      # parsing as TSV first.
+      #
+      # @see #output
+      # @see #delimited_output
+      # @return [Array<String>]
+      def tsv_output
+        delimited_output("\t")
+      end
+      
+      # Return the output of the processor on the given records,
+      # parsing as CSV first.
+      #
+      # @see #output
+      # @see #delimited_output
+      # @return [Array<String>]
+      def csv_output
+        delimited_output(",")
+      end
+
+      # Return the output of the processor on the given records,
+      # parsing as JSONS first.
+      #
+      # @see #output
+      # @return [Hash,Array]
+      def json_output
+        output.map { |record| MultiJson.load(record) }
+      end
+      
+    end
+  end
+end

data/lib/wukong/spec_helpers/unit_tests/unit_test_matchers.rb

@@ -0,0 +1,169 @@
+module Wukong
+  module SpecHelpers
+    class UnitTestMatcher
+
+      attr_accessor :driver, :expected, :reason, :expected_record, :actual_record, :mismatched_index
+
+      def matches?(driver)
+        self.driver = driver
+        driver.run
+        if actual_size != expected_size
+          self.reason = :size
+          return false
+        end
+        return true if just_count?
+        expected.each_with_index do |expectation, index|
+          actual = output[index]
+          if actual != expectation
+            self.reason           = :element
+            self.expected_record  = expectation
+            self.actual_record    = actual
+            self.mismatched_index = index
+            return false
+          end
+        end
+        true
+      end
+      
+      def initialize *expected
+        self.expected = expected
+      end
+
+      def failure_message
+        if reason == :size
+          "Expected #{expected_size} records, got #{actual_size}:\n\n#{pretty_output}"
+        else
+          "Expected the #{ordinalize(mismatched_index)} record to be#{parse_modifier}\n\n#{expected_record}\n\nbut got\n\n#{pretty_output}"
+        end
+      end
+
+      def negative_failure_message
+        if reason == :size
+          "Expected to NOT get #{expected_size} records:\n\n#{output}"
+        else
+          "Expected the #{ordinalize(mismatched_index)} record to NOT be#{parse_modifier}\n\n#{pretty_output}"
+        end
+      end
+      
+      def records
+        @just_count = true
+        self                    # chaining
+      end
+      alias_method :record, :records
+
+      private
+      
+      def just_count?
+        @just_count
+      end
+
+      def actual_size
+        driver.size
+      end
+
+      def expected_size
+        just_count? ? expected.first.to_i : expected.size
+      end
+
+      def output
+        driver
+      end
+
+      def parse_modifier
+      end
+
+      def pretty_output
+        [].tap do |pretty|
+          output.each_with_index do |record, index|
+            s      = (record.is_a?(String) ? record : record.inspect)
+            prefix = case
+            when output.size > 1 && index == mismatched_index
+              " => "
+            when output.size > 1
+              "    "
+            else
+              ''
+            end
+            pretty << [prefix,s].join('')
+          end
+        end.join("\n")
+      end
+
+      # http://stackoverflow.com/questions/1081926/how-do-i-format-a-date-in-ruby-to-include-rd-as-in-3rd
+      def ordinalize array_index
+        n = array_index + 1
+        if (11..13).include?(n % 100)
+          "#{n}th"
+        else
+          case n % 10
+          when 1; "#{n}st"
+          when 2; "#{n}nd"
+          when 3; "#{n}rd"
+          else    "#{n}th"
+          end
+        end
+      end
+    end
+
+    class JsonMatcher < UnitTestMatcher
+      def output
+        driver.map do |record|
+          begin
+            MultiJson.load(record)
+          rescue => e
+            raise Error.new("Could not parse output of dataflow as JSON: \n\n#{record}")
+          end
+        end
+      end
+      def parse_modifier
+        ' (after parsing as JSON)'
+      end
+    end
+
+    class DelimitedMatcher < UnitTestMatcher
+
+      attr_accessor :delimiter
+      
+      def initialize delimiter, *expected
+        self.delimiter = delimiter
+        super(*expected)
+      end
+      
+      def output
+        driver.map do |record|
+          begin
+            record.to_s.split(delimiter)
+          rescue => e
+            raise Error.new("Could not parse as #{delimited_type}': \n\n#{record}")
+          end
+        end
+      end
+
+      def delimited_type
+        "'#{delimiter}-delimited'"
+      end
+      
+      def parse_modifier
+        " (after parsing as #{delimited_type})"
+      end
+    end
+
+    class TsvMatcher < DelimitedMatcher
+      def initialize *expected
+        super("\t", *expected)
+      end
+      def delimited_type
+        "TSV"
+      end
+    end
+
+    class CsvMatcher < DelimitedMatcher
+      def initialize *expected
+        super(",", *expected)
+      end
+      def delimited_type
+        "CSV"
+      end
+    end
+  end
+end