lookout 2.3.0 → 3.0.0

data/lib/lookout-3.0/expectations.rb

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+
+# Represents the “Expectations” keyword in expectation files and the
+# expectation files themselves.  Used by {Interfaces::Commandline} and should
+# be used by other interfaces as the main access point to expectation files.
+# Implemented as an Enumerable over the expect blocks found in any of the
+# expectations blocks in the expectation file.
+class Lookout::Expectations
+  # Prepares the enumeration of the expect blocks found in the expectations
+  # file pointed to by the expanded PATH.
+  # @param [String] path
+  Value(:path)
+  include Enumerable
+
+  @@expectations = {}
+
+  class << self
+    def load(path)
+      @@expectations[path] = []
+      begin
+        begin
+          Kernel.load path, true
+        rescue LoadError => e
+          raise e,
+            'cannot load expectations from file: %s' % e,
+            [(Array(e.backtrace).find{ |b| b.start_with? path } or '%s:0' % path)] +
+              Array(e.backtrace) unless e.message.end_with? path
+          raise e,
+            'cannot load expectations from file: no such file or directory',
+            ['%s:0' % path]
+        rescue SyntaxError => e
+          raise unless matches = (/\A(.*?:\d+): (.*)/m.match(e.message) rescue nil)
+          raise SyntaxError, matches[2], [matches[1]] + Array(e.backtrace)
+        end
+        @@expectations[path]
+      ensure
+        @@expectations.delete path
+      end
+    end
+
+    def evaluate(path, &block) @@expectations[path] << block; self end
+  end
+
+  # @overload
+  #   Enumerates the expect blocks.
+  #
+  #   @yieldparam [Expect::Object] expect
+  #   @raise [NoMemoryError, SignalException, SystemExit] If raised; all other
+  #     exceptions are caught and turned into failing expect blocks, located at
+  #     the source of the exception
+  # @overload
+  #   @return [Enumerator<Expect::Object>] An Enumerator over the expect blocks
+  def each
+    return enum_for(__method__) unless block_given?
+    context = Lookout::Expectations::Context.new{ |expect| yield expect }
+    self.class.load(path).each do |expectations|
+      context.instance_eval(&expectations)
+    end
+    self
+  rescue NoMemoryError, SignalException, SystemExit
+    raise
+  rescue Exception => e
+    raise unless location = (Array(e.backtrace).first rescue nil)
+    file, line = Lookout.location(location)
+    raise unless file and line
+    yield nil.to_lookout_expected.expect(file, line){ raise e }
+    self
+  end
+end

data/lib/lookout-3.0/expectations/context.rb

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+
+# Context in which expectations blocks are evaluated.  Plug-ins may add private
+# methods to this class to make them available to expectations blocks.
+class Lookout::Expectations::Context
+  # Sets up a context in which the given block will be passed each expect block
+  # found in the expectations blocks evaluated in this context via
+  #  #instance_eval.
+  # @yieldparam [Expect] expect
+  def initialize(&block) @block = block end
+
+  private
+
+  # Sets up an expect block, expecting EXPECTED and evaluating BLOCK for the
+  # actual result, then passes it to the block given to the constructor.
+  # @param (see Expect.expect)
+  # @return [self]
+  # @see Expect.expect
+  def expect(expected, &block)
+    @block.call Lookout::Expect.expect(expected,
+                                       *(block.respond_to?(:source_location) ?
+                                         block.source_location :
+                                         Lookout.location(caller.first)),
+                                       &block)
+    self
+  end
+
+  # @return [Actual] A result wrapper for explicit query expectations
+  def result; Lookout::Actual.new end
+
+  # @param [Object] expected
+  # @return [Literal] A literal expected value for EXPECTED
+  def literal(expected) Lookout::Literal.new(expected) end
+
+  # @param (see Stub::Object#initialize)
+  # @return [Mock::Object] A mock object set up with METHODS
+  def mock(methods = {}) Lookout::Mock.new(methods) end
+
+  # @return [Mock::Method::Arguments::None] An object representing
+  #   “without arguments” for mock argument expectations
+  def without_arguments; Lookout::Reception::Arguments::None.new end
+
+  # @param (see Stub::Object#initialize)
+  # @return [Stub::Object] A stub object set up with METHODS
+  def stub(methods = {}) Lookout::Stub.new(methods) end
+
+  # @return [Output] An expected output wrapper around STRING
+  def output(string) Lookout::Output.new(string) end
+
+  # @return [Output] An expected warning wrapper around STRING
+  def warning(string) Lookout::Warning.new(string) end
+end

data/lib/lookout-3.0/expected.rb

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+
+# Function-like namespace for type-specific expected values.  Every {::Object}
+# should be convertable to a {Lookout::Expected::Object} when it receives
+#  #to_lookout_expected.  ::Object implements this method, so all objects are
+# covered by default.  If you have a type that would benefit from more specific
+# treatment, implement #to_lookout_expected by returning an instance of a
+# subclass {Lookout::Expected::Object}.
+module Lookout::Expected
+end

data/lib/lookout-3.0/expected/array.rb

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Array}s.
+class Lookout::Expected::Array < Lookout::Expected::Object
+  # @param [::Array] actual
+  # @return [Difference::Array, nil] A difference report between ACTUAL and
+  #   {#expected} unless their content exhibit no {Object differences}
+  def difference(actual)
+    Lookout::Difference::Array.new(actual, expected) unless
+      Array === actual and
+      expected.size == actual.size and
+      expected.enum_for(:none?).with_index{ |v, i|
+        v.to_lookout_expected.difference(actual[i])
+      }
+  end
+end

data/lib/lookout-3.0/expected/classes.rb

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+# Namespace for expected values that are descendants of Class.
+module Lookout::Expected::Classes
+end

data/lib/lookout-3.0/expected/classes/exception.rb

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected values that are descendants of {::Exception}.
+class Lookout::Expected::Classes::Exception < Lookout::Expected::Object
+  # @param (see Object#expect)
+  # @yieldparam [Class] class
+  # @yieldreturn [Class]
+  # @return [Expect::Classes::Exception] An expect block for the receiver at
+  #   LINE in FILE that’ll yield the {#expected} exception class and expect it
+  #   or one of its descendants to be raised
+  def expect(file, line, &block)
+    Lookout::Expect::Classes::Exception.new(self, file, line, &block)
+  end
+end

data/lib/lookout-3.0/expected/exception.rb

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Exception}s.
+class Lookout::Expected::Exception < Lookout::Expected::Object
+  # @param (see Object#expect)
+  # @yieldparam [::Exception] exception
+  # @yieldreturn [::Exception]
+  # @return [Expect::Exception] An expect block for the receiver at LINE in
+  #   FILE that’ll yield the expected EXCEPTION and expect the exception to be
+  #   raised
+  def expect(file, line, &block)
+    Lookout::Expect::Exception.new(self, file, line, &block)
+  end
+
+  # @param [::Exception] actual
+  # @return [Difference::Exception, nil] A difference report between ACTUAL
+  #   and {#expected} unless they’re #equal? or their classes are `#==` and
+  #   their messages match or {#expected}s message is a Regexp that matches
+  #   actual’s message
+  def difference(actual)
+    Lookout::Difference::Exception.new(actual, expected, regexp) unless
+      expected.equal?(actual) or
+      (expected.class == actual.class and
+       (actual.respond_to? :message rescue false) and
+       (m = actual.message rescue nil) and
+       (regexp ? regexp === m : expected.message == m))
+  end
+
+  private
+
+  # The first test works in Ruby 1.8.  In Ruby 1.9, however, #message always
+  # returns a String, unless the conversion raises an error.  Sadly, this
+  # conversion can’t keep track of the ‘e’ and ‘n’ options for encoding
+  # handling.
+  # @private
+  def regexp
+    return @regexp if defined? @regexp
+    return @regexp = expected.message if Regexp === expected.message
+    return @regexp = nil unless expected.message =~ /\A\(\?([mix]*)(-[mix]+)?:(.*)\)\z/
+    @regexp = Regexp.new($3,
+                         0 |
+                         ($1.include?('m') ? Regexp::MULTILINE : 0) |
+                         ($1.include?('i') ? Regexp::IGNORECASE : 0) |
+                         ($1.include?('x') ? Regexp::EXTENDED : 0))
+  end
+end

data/lib/lookout-3.0/expected/falseclass.rb

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected FalseClasses (of which `false` is the only instance).
+class Lookout::Expected::FalseClass < Lookout::Expected::Object
+  # @param [Boolean] actual
+  # @return [Difference::Object] A difference report between ACTUAL and
+  #   {#expected} unless ACTUAL is falseful
+  def difference(actual) super((not not actual)) end
+end

data/lib/lookout-3.0/expected/hash.rb

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Hash}es.
+class Lookout::Expected::Hash < Lookout::Expected::Object
+  # @param [::Hash] actual
+  # @return [Difference::Hash, nil] A difference report between ACTUAL and
+  #   {#expected} unless their content exhibit no {Object differences}
+  def difference(actual)
+    Lookout::Difference::Hash.new(actual, expected) unless
+      Hash === actual and
+      expected.size == actual.size and
+      expected.none?{ |k, v| v.to_lookout_expected.difference(actual[k]) }
+  end
+end

data/lib/lookout-3.0/expected/lookout.rb

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+# Namespace for expected values defined under the {Lookout} namespace.
+module Lookout::Expected::Lookout
+end

data/lib/lookout-3.0/expected/lookout/actual.rb

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+# Namespace for expected values defined under the {Lookout::Actual} namespace.
+module Lookout::Expected::Lookout::Actual
+end

data/lib/lookout-3.0/expected/lookout/actual/method.rb

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Lookout::Actual::Method}s.
+class Lookout::Expected::Lookout::Actual::Method < Lookout::Expected::Object
+  # @param [::Object] actual
+  # @return [Difference::Lookout::Actual::Method, nil] A difference report
+  #   between ACTUAL and {#expected} unless invoking {#expected} on ACTUAL
+  #   returns true
+  def difference(actual)
+    Lookout::Difference::Lookout::Actual::Method.new(actual, expected) unless
+      expected.call(actual)
+  end
+end

data/lib/lookout-3.0/expected/lookout/actual/not.rb

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+
+# Namespace for expected values defined under the {Lookout::Actual::Not}
+# namespace.
+module Lookout::Expected::Lookout::Actual::Not
+end

data/lib/lookout-3.0/expected/lookout/actual/not/method.rb

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Lookout::Actual::Not::Method}s.
+class Lookout::Expected::Lookout::Actual::Not::Method < Lookout::Expected::Object
+  # @param [::Object] actual
+  # @return [Difference::Lookout::Actual::Not::Method, nil] A difference report
+  #   between ACTUAL and {#expected} unless invoking {#expected} on ACTUAL
+  #   returns false
+  def difference(actual)
+    Lookout::Difference::Lookout::Actual::Not::Method.new(actual, expected) if
+      expected.call(actual)
+  end
+end

data/lib/lookout-3.0/expected/lookout/output.rb

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Lookout::Output}s.
+class Lookout::Expected::Lookout::Output < Lookout::Expected::Object
+  # @param (see Object#expect)
+  # @yieldparam [::IO] io
+  # @yieldreturn [::Lookout::Output]
+  # @return [Expect::Lookout::Output] An expect block for the receiver at LINE
+  #   in FILE that’ll yield an IO object that’ll expect to see the {#expected}
+  #   output during the execution of the block
+  def expect(file, line, &block)
+    super(file, line){ |expected|
+      output = StringIO.new
+      block.call output
+      expected.class.new(output.string)
+    }
+  end
+
+  # @param [::Lookout::Output] actual
+  # @return [Difference::Lookout::Output, nil] A difference report between
+  #   ACTUAL and {#expected} unless they’re `#==`
+  def difference(actual)
+    Lookout::Difference::Lookout::Output.new(actual, expected) unless
+      expected == actual
+  end
+end

data/lib/lookout-3.0/expected/lookout/reception.rb

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Lookout::Reception}s.  This is used to check mock
+# method invocation counts and arguments.
+class Lookout::Expected::Lookout::Reception < Lookout::Expected::Object
+  # @param (see Object#expect)
+  # @yieldparam (see Object#expect)
+  # @yieldreturn (see Object#expect)
+  # @return [Expect::Object] An expect block for the receiver at LINE in FILE
+  #   that’ll yield the {#expected} object and expect the block to call the
+  #   method the appropriate number of times
+  def expect(file, line, &block)
+    super file, line, &expected.block(&block)
+  end
+
+  # @param [Integer] actual
+  # @return [Difference::Lookout::Reception, nil] A difference report between
+  #   the ACTUAL number of times the method was received and the range of
+  #   expected number of receptions unless the earlier lay within the latter
+  def difference(actual)
+    Lookout::Difference::Lookout::Reception.
+      new(actual, expected) unless expected.range === actual
+  end
+end

data/lib/lookout-3.0/expected/lookout/warning.rb

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Lookout::Warning}s.
+class Lookout::Expected::Lookout::Warning < Lookout::Expected::Object
+  # @param (see Object#expect)
+  # @yield
+  # @yieldreturn [::Lookout::Warning]
+  # @return [Expected::Output] An expect block for the receiver at LINE in FILE
+  #   that’ll yield and expect the warning to be output to `$stderr` during the
+  #   execution of the block
+  def expect(file, line, &block)
+    super(file, line){ |expected|
+      with_global :$stderr, StringIO.new do
+        with_verbose do
+          block.call
+          expected.class.new($stderr.string)
+        end
+      end
+    }
+  end
+
+  # @param [::Lookout::Warning] actual
+  # @return [Difference::Lookout::Warning, nil] A difference report between
+  #   ACTUAL and {#expected} unless they’re `#===`
+  def difference(actual)
+    Lookout::Difference::Lookout::Warning.new(actual, expected) unless
+      expected === actual
+  end
+end

data/lib/lookout-3.0/expected/module.rb

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Module}s.
+class Lookout::Expected::Module < Lookout::Expected::Object
+  # @param [::Module] actual
+  # @return [Difference::Module, nil] A difference report between ACTUAL and
+  #   {#expected} unless they’re `#==` or ACTUAL is an {#expected}
+  def difference(actual)
+    Lookout::Difference::Module.new(actual, expected) unless
+      expected == actual or expected === actual
+  end
+end

data/lib/lookout-3.0/expected/object.rb

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Object}s.  This is the base expected-value class and
+# may be subclassed if you have a type that would benefit from more specific
+# treatment than what this class affords.  Such a subclass should override
+# {#expect} and/or {#difference} to set up type-specific expect blocks and/or
+# difference checks and difference report generation.
+class Lookout::Expected::Object
+  # Wraps the EXPECTED value.
+  # @param [::Object] expected The expected value
+  Value(:expected)
+  public :expected
+
+  # @param (see Expect::Object#initialize)
+  # @yieldparam (see Expect::Object#initialize)
+  # @yieldreturn (see Expect::Object#initialize)
+  # @return [Expect::Object] An expect block for the receiver at LINE in FILE
+  #   that’ll yield the {#expected} object and expect an object that’ll exhibit
+  #   no {#difference}s from it to be returned
+  def expect(file, line, &block)
+    Lookout::Expect::Object.new(self, file, line, &block)
+  end
+
+  # @param [::Object] actual
+  # @return [Difference::Object, nil] A difference report between ACTUAL and
+  #   {#expected} unless they’re `#==`
+  def difference(actual)
+    Lookout::Difference::Object.new(actual, expected) unless expected == actual
+  end
+end

data/lib/lookout-3.0/expected/range.rb

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Range}s.
+class Lookout::Expected::Range < Lookout::Expected::Object
+  # @param [::Range] actual
+  # @return [Difference::Range, nil] A difference report between ACTUAL and
+  #   {#expected} unless they’re `#==` or ACTUAL lays within {#expected}
+  def difference(actual)
+    Lookout::Difference::Range.new(actual, expected) unless
+      expected == actual or expected === actual
+  end
+end

data/lib/lookout-3.0/expected/regexp.rb

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Regexp}s.
+class Lookout::Expected::Regexp < Lookout::Expected::Object
+  # @param [::Regexp] actual
+  # @return [Difference::Regexp, nil] A difference report between ACTUAL and
+  #   {#expected} unless they’re `#==` or ACTUAL is matched by {#expected}
+  def difference(actual)
+    Lookout::Difference::Regexp.new(actual, expected) unless
+      expected == actual or expected === actual
+  end
+end