lookout 2.3.0 → 3.0.0

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

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+
+# Arguments that should be passed to a method reception expectation.  Sets
+# things up based on what kind of arguments were passed to it and may then be
+# used to {List#=~ verify} that arguments that don’t {Lookout::Difference
+# differ} from them are subsequently passed to the method.
+module Lookout::Reception::Arguments
+  class << self
+    # @param [Object, …] args
+    # @return [Any, List, None] {Any} if ARGS is #empty?, {Any} or {None} if
+    #   ARGS contain either, or a {List} wrapping ARGS
+    def for(*args)
+      if args.empty? then Any.new
+      elsif any = args.find{ |e| Any === e } then any
+      elsif none = args.find{ |e| None === e } then none
+      else List.new(*args)
+      end
+    end
+  end
+end

data/lib/lookout-3.0/reception/arguments/any.rb

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+
+# Arguments matcher matching any arguments.
+class Lookout::Reception::Arguments::Any
+  # @param [Array<Object>] other
+  # @return [true]
+  def =~(other) true end
+
+  # @return True if the receiver’s class `#==` that of OTHER
+  def ==(other) self.class == other.class end
+  alias eql? ==
+  def hash; self.class.hash end
+
+  # @return The receiver as a String argument list
+  def to_s; '*args, &block' end
+end

data/lib/lookout-3.0/reception/arguments/error.rb

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+# Error raised when the passed arguments differ from the expected ones.
+class Lookout::Reception::Arguments::Error < StandardError
+end

data/lib/lookout-3.0/reception/arguments/list.rb

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+# Arguments matcher matching a list of arguments.  It uses
+# {Lookout::Difference} to do the actual work.
+class Lookout::Reception::Arguments::List
+  # Expects ARGS.
+  # @param [Object, …] args
+  Value(:'*args')
+
+  # @param [Array<Object>] other
+  # @return True if there are no {Expected::Object#difference
+  #   differences} between the expected arguments and OTHER
+  def =~(other) not args.to_lookout_expected.difference(other) end
+
+  # @return The receiver as a String argument list
+  def to_s; Lookout::Inspect.args(*args) end
+end

data/lib/lookout-3.0/reception/arguments/none.rb

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+
+# Arguments matcher matching an empty list of arguments.
+class Lookout::Reception::Arguments::None < Lookout::Reception::Arguments::List
+  def initialize; super end
+end

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

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+
+# Error raised when a method is received too many times.
+class Lookout::Reception::Error < StandardError
+  class << self
+    # @param [Reception] reception
+    # @param [Integer] calls
+    # @return [Error] A new error with a suitable error message for the
+    #   RECEPTION of a method, where CALLS is outside the RANGE of expected
+    #   calls.
+    def from(reception, calls, range)
+      new('%s: unexpected number of invocations (%d for %s)' %
+          [reception,
+           calls,
+           if range.begin == range.end
+             range.begin
+           elsif range.end == 1.0/0
+             '%d..' % range.begin
+           else
+             range
+           end])
+    end
+  end
+end

data/lib/lookout-3.0/result.rb

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+
+# Base module for {Results}.
+module Lookout::Result
+  # Initializes the result pertaining to the expect block defined on LINE in
+  # the expanded path to FILE.
+  # @param [String] file The expanded path of the file containing the expect
+  #   block that this result pertains to
+  # @param [Integer] line The line in FILE on which the expectation that this
+  #   result pertains to is defined
+  Value(:file, :line, :comparable => true)
+  public :file, :line
+
+  # @return A String formatted according to the GNU standard for error messages
+  def to_s; '%s:%d' % [file, line] end
+end

data/lib/lookout-3.0/results.rb

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+# Namespace for {Result} types.
+module Lookout::Results
+end

data/lib/lookout-3.0/results/error.rb

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+
+# An error result used when the evalution of an {Expect expect block} failed.
+class Lookout::Results::Error
+  include Lookout::Result
+
+  # (see Result#initialize)
+  # An additional MESSAGE may also be associated with the result, which was
+  # caused by EXCEPTION.
+  # @param (see Result#initialize)
+  # @param [String, nil] message Any additional message associated with this
+  #   error
+  # @param [Exception] exception The raised exception
+  Value(:file, :line, :message, :exception, :comparable => [:file, :line])
+  public :message, :exception
+
+  def to_s; [super, message, exception.format].compact.join(': ') end
+end

data/lib/lookout-3.0/results/failure.rb

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+
+# A failed result used when the actual result of an expect block exhibits
+# differences from the expected value.
+class Lookout::Results::Failure
+  include Lookout::Result
+
+  # (see Result#initialize)
+  # The DIFFERENCE report between the actual result and the expected value
+  # will be used to display this information to the user.
+  # @param [Difference::Object] difference
+  Value(:file, :line, :difference, :comparable => [:file, :line])
+
+  def to_s; [super, difference].join(': ') end
+end

data/lib/lookout-3.0/results/success.rb

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+
+# A successful result used when the actual result of an expect block exhibits
+# no differences from the expected value.
+class Lookout::Results::Success
+  include Lookout::Result
+end

data/lib/lookout-3.0/stub.rb

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+
+# Object that only responds to a given set of methods and returns itself
+# whenever it receives a method call it doesn’t know anything about.
+class Lookout::Stub
+  class << self
+    # Defines METHOD on an objects META object to VALUE.  If _value_ is a Proc
+    # it’ll be used as a method definition with rules that depend on if whether
+    # it’s a lambda or not.  Otherwise, the method definition will be set up to
+    # return VALUE.
+    # @param [Object] meta
+    # @param [Symbol] method
+    # @param [Object] value
+    def define(meta, method, value)
+      meta.instance_eval{
+        case value
+        when Proc
+          if (value.lambda? rescue false)
+            define_method method, value
+          else
+            define_method method do |*args, &block|
+              value.call(*args, &block)
+            end
+          end
+        else
+          define_method method do |*|
+            value
+          end
+        end
+      }
+    end
+  end
+
+  # Maps each method name key in METHODS to its value definition.  If the value
+  # of the key is a Proc it’ll be used as the method definition.  Otherwise,
+  # the method definition will be set up to return VALUE.
+  # @param [Hash<Symbol,Object>] methods
+  def initialize(methods = {})
+    (class << self; self; end).module_eval do
+      methods.each do |name, value|
+        Lookout::Stub.define self, name, value
+      end
+    end unless methods.empty?
+  end
+
+  def inspect; 'stub' end
+
+  private
+
+  # Ignores any method calls that it doesn’t know anything about.
+  # @param [Symbol] method
+  # @param [Object, …] args
+  # @return [self]
+  def method_missing(method, *args) self end
+end

data/lib/lookout-3.0/version.rb

@@ -0,0 +1,133 @@
+# -*- coding: utf-8 -*-
+
+require 'inventory-1.0'
+
+module Lookout
+  Version = Inventory.new(3, 0, 0){
+    def dependencies
+      super + Inventory::Dependencies.new{
+        development 'inventory-rake', 1, 4, 0
+        development 'inventory-rake-tasks-yard', 1, 3, 0
+        development 'lookout-rake', 3, 0, 0
+        development 'yard', 0, 8, 0
+        development 'yard-heuristics', 1, 1, 0
+        development 'yard-value', 1, 2, 0
+
+        runtime 'value', 1, 1, 0
+      }
+    end
+
+    def requires
+      %w[stringio]
+    end
+
+    def package_libs
+      %w[object.rb
+         aphonic.rb
+         actual.rb
+         actual/method.rb
+         actual/not.rb
+         actual/not/method.rb
+         diff.rb
+         diff/slice.rb
+         diff/algorithms.rb
+         diff/algorithms/difflib.rb
+         diff/algorithms/difflib/position.rb
+         diff/algorithms/difflib/position/new.rb
+         diff/formats.rb
+         diff/formats/inline.rb
+         diff/formats/set.rb
+         diff/formats/unified.rb
+         diff/group.rb
+         diff/groups.rb
+         diff/match.rb
+         diff/operation.rb
+         diff/operations.rb
+         diff/operations/delete.rb
+         diff/operations/copy.rb
+         diff/operations/insert.rb
+         diff/operations/replace.rb
+         difference.rb
+         difference/object.rb
+         difference/array.rb
+         difference/exception.rb
+         difference/hash.rb
+         difference/range.rb
+         difference/lookout.rb
+         difference/lookout/actual.rb
+         difference/lookout/actual/method.rb
+         difference/lookout/actual/not.rb
+         difference/lookout/actual/not/method.rb
+         difference/lookout/output.rb
+         difference/lookout/reception.rb
+         difference/lookout/warning.rb
+         difference/module.rb
+         difference/regexp.rb
+         difference/string.rb
+         difference/symbol.rb
+         encode.rb
+         exception.rb
+         exception/backtrace.rb
+         exception/unknown.rb
+         expect.rb
+         expect/object.rb
+         expect/object/context.rb
+         expect/classes.rb
+         expect/classes/exception.rb
+         expect/exception.rb
+         expected.rb
+         expected/object.rb
+         expected/array.rb
+         expected/classes.rb
+         expected/classes/exception.rb
+         expected/exception.rb
+         expected/falseclass.rb
+         expected/hash.rb
+         expected/lookout.rb
+         expected/lookout/actual.rb
+         expected/lookout/actual/method.rb
+         expected/lookout/actual/not.rb
+         expected/lookout/actual/not/method.rb
+         expected/lookout/output.rb
+         expected/lookout/reception.rb
+         expected/lookout/warning.rb
+         expected/module.rb
+         expected/range.rb
+         expected/regexp.rb
+         expected/string.rb
+         expected/symbol.rb
+         expected/trueclass.rb
+         expectations.rb
+         expectations/context.rb
+         inspect.rb
+         interfaces.rb
+         interfaces/commandline.rb
+         literal.rb
+         stub.rb
+         mock.rb
+         output.rb
+         plugins.rb
+         reception.rb
+         reception/arguments.rb
+         reception/arguments/any.rb
+         reception/arguments/error.rb
+         reception/arguments/list.rb
+         reception/arguments/none.rb
+         reception/error.rb
+         object/not.rb
+         object/not/receive.rb
+         object/to.rb
+         object/to/receive.rb
+         result.rb
+         results.rb
+         results/error.rb
+         results/failure.rb
+         results/success.rb
+         warning.rb]
+    end
+
+    def additional_unit_tests
+      %w[examples.rb]
+    end
+  }
+end

data/lib/lookout-3.0/warning.rb

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+
+# Warning expectation proxy.  Used to expect warning outputs during the
+# execution of the {Lookout::Expect expect block}.  Warnings are matched by
+# ignoring any trailing newlines and by removing any file/line warning
+# prefixes.  This is done as Ruby internally uses two different functions to
+# generate warnings (rb_warn() and rb_warning()).
+class Lookout::Warning < Lookout::Output
+  # Proxies the EXPECTED warning output.
+  # @param (see Output#initialize)
+  def initialize(expected) super expected.chomp end
+
+  # @return True if the receiver `#==` OTHER or if their classes and normalized
+  #   expected output `#==` each other
+  def ===(other)
+    self == other or
+      (self.class == other.class and normalized == other.normalized)
+  end
+
+  def inspect; 'warning(%p)' % expected end
+
+  # @return [Enumerable<String>] An Enumerable over the formatted operations
+  #   that would have to be applied to the actual warning output to get the
+  #   expected warning output after any normalization of the warning outputs
+  #   have been performed
+  def diff(other)
+    self == normalized ? super(other.normalized) : normalized.diff(other)
+  end
+
+  # @return [Expected::Lookout::Warning] A wrapper around the receiver, making
+  #   it an expected value
+  def to_lookout_expected; Lookout::Expected::Lookout::Warning.new(self) end
+
+  protected
+
+  def normalized
+    normalized = expected.sub(/\A.*?:\d+: warning: /, '')
+    expected == normalized ? self : self.class.new(normalized)
+  end
+end

data/test/unit/examples.rb

@@ -8,42 +8,62 @@ Expectations do
     1 + 1
   end
 
-  # Determine if the result, retrieved through a stub, equals a value.
-  expect 2 do
-    Object.new.tap{ |o| stub(o).two{ 2 } }.two
+  # Verify that an exception is raised.
+  expect ArgumentError do
+    Integer('1 + 1')
   end
 
-  # Match against a Regexp.  Please note the use of parentheses to silence
-  # warnings.
-  expect(/a string/) do
-    'a string'
+  # Verify that the result is an Array.
+  expect Array do
+    [1, 2, 3].select{ |i| i % 2 == 0 }
+  end
+
+  # Verify that the result is what we expect it to be.
+  expect [2, 4, 6] do
+    [1, 2, 3].map{ |i| i * 2 }
+  end
+
+  # Check that the result is within a given range.
+  expect 0.099..0.101 do
+    0.4 - 0.3
   end
 
-  # Match inside a Range.
-  expect 1..5 do
-    3
+  # Check an explicit result.
+  expect 'ab' do
+    'abc'[0..1]
   end
 
-  # Verify that the result is an Enumerable.
+  # Match against a regexp (using %r{…} syntax to avoid a warning).
+  expect %r{a substring} do
+    'a string with a substring'
+  end
+
+
+  # Modules and Classes
+
+  # Check that the result includes a given module.
   expect Enumerable do
     []
   end
 
-  # Verify that the result is a String.
+  # Check that the result is of a given class.
   expect String do
     'a string'
   end
 
-  # Determine equality of modules.
+  # Verify the equality of modules.
   expect Enumerable do
     Enumerable
   end
 
-  # Determine equality of classes.
+  # Verify the equality of classes.
   expect String do
     String
   end
 
+
+  # Booleans
+
   # Verify that the result is truthful.
   expect true do
     1
@@ -54,43 +74,53 @@ Expectations do
     nil
   end
 
-  # Verify that the result is actually true.
+  # Verify that the result is literally true.
   expect TrueClass do
     true
   end
 
-  # Verify that the result is actually false.
+  # Verify that the result is literally false.
   expect FalseClass do
     false
   end
 
-  # Match XML contents, ignoring whitespace between tags.
-  expect xml('<a><foo>bar</foo></a>') do
-    "<a>\n\t<foo>bar</foo>  \n</a>"
-  end
 
-  # Match XML contents, ignoring whitespace between tags.
-  expect xml(<<-EOX) do
-    <one>
-      <two>
-        <three>4</three>
-        <five> 6 </five>
-      </two>
-    </one>
-  EOX
-    '<one><two><three>4</three>
-     <five> 6 </five>
-     </two></one>'
-  end
+  # Output
 
   # Verify that the given text is output.
   expect output("abc\ndef\n") do |io|
     io.puts 'abc', 'def'
   end
 
+
+  # Warnings
+
+  # Expect a warning to be output.
+  expect warning('this is your final one!') do
+    warn 'this is your final one!'
+  end
+
+  # Expect a warning to be output; the “header” is automatically ignored.
+  expect warning('this is your final one!') do
+    warn '%s:%d: warning: this is your final one!' % [__FILE__, __LINE__]
+  end
+
+
+  # Verbosity
+
+  # Use #with_verbose to set $VERBOSE during the execution of a block.
+  expect nil do
+    with_verbose nil do
+      $VERBOSE
+    end
+  end
+
+
+  # Exceptions
+
   # Verify that an exception is raised.
-  expect NoMethodError do
-    Object.no_method
+  expect ArgumentError do
+    Integer('1 + 1')
   end
 
   # Verify that an exception with a specific message is raised.
@@ -103,90 +133,185 @@ Expectations do
     raise StandardError.new('message')
   end
 
-  # State-based Fluent Boolean Expectations
 
-  # Expect an object to “be” something.
-  expect(Class.new{ attr_accessor :running }.new.to.be.running) do |process|
-    process.running = true
+  # Query Expectations
+
+  # Expect #empty? on the result to be true.
+  expect :empty? do
+    []
+  end
+
+  # Equivalently, but less explicitly, expect #empty? on the result to be true.
+  expect true do
+    []
+  end
+
+  # Expect #empty? on the result to be false.
+  expect :not_empty? do
+    [1, 2, 3]
+  end
+
+  # Equivalently, but less explicitly, expect #empty? on the result to be false.
+  expect false do
+    [1, 2, 3].empty?
+  end
+
+
+  # Explicit Query Expectations
+
+  # Expect [1, 2, 3] with all even integers removed to include 1.
+  expect result.to.include? 1 do
+    [1, 2, 3].reject{ |e| e.even? }
+  end
+
+  # Expect [1, 2, 3] with all even integers removed not to include 2.
+  expect result.not.to.include? 2 do
+    [1, 2, 3].reject{ |e| e.even? }
   end
 
-  # Expect an object to “have” something.
-  expect(Class.new{ attr_accessor :finished }.new.to.have.finished) do |process|
-    process.finished = true
+  # Equivalently, but less explicitly, though marginally faster, expect [1, 2,
+  # 3] with all even integers not to include 2.
+  expect false do
+    [1, 2, 3].reject{ |e| e.even? }.include? 2
   end
 
-  # Expect nil to respond to #nil?.
-  expect nil.to.respond_to? :nil?
 
-  # Expect nil to be nil.
-  expect nil.to.be.nil?
+  # Literal Expectations
+
+  # Expect the symbol :empty?, not #empty? on the result to be true.
+  expect literal(:empty?) do
+    :empty?
+  end
+
 
-  # Expect Object not to be nil.
-  expect Object.not.to.be.nil?
 
   # Behavior-based Expectations
 
   # Use a mock to verify that a method is called appropriately.
-  expect mock.to.receive.dial('2125551212').twice do |phone|
-    phone.dial('2125551212')
-    phone.dial('2125551212')
+  expect mock.to.receive.to_str(without_arguments){ '123' } do |o|
+    o.to_str
   end
 
-  # Use a stub that ignores all calls to verify that a method is called
-  # appropriately.  Any other calls made are ignored.
-  expect stub.to.receive.dial('2125551212').twice do |phone|
-    phone.dial('2125551212')
-    phone.hangup
-    phone.dial('2125551212')
+  # Use a stub that returns stub objects for unknown methods to only verify
+  # that a method of interest is called appropriately.
+  expect stub.to.receive.to_str(without_arguments){ '123' } do |o|
+    o.to_str if o.convertable?
   end
 
-  # Use a stub that’s set up with a set of methods.
+  # Use a contrete mock to verify that a method is called.
+  expect Object.to.receive.name do
+    Object.name
+  end
+
+  # Expect the reception of #a with any number of arguments.
+  expect mock.to.receive.a do |m|
+    m.a
+  end
+
+  # Expect the reception of #a with one argument.
+  expect mock.to.receive.a(Object) do |m|
+    m.a 0
+  end
+
+  # Expect the reception of #a with either 1 or 2.
+  expect mock.to.receive.a(1..2) do |m|
+    m.a 1
+  end
+
+  # Expect the reception of #a without any arguments.
+  expect mock.to.receive.a(without_arguments) do |m|
+    m.a
+  end
+
+  # Expect the reception of #a with three arguments, the second being 1.
+  expect mock.to.receive.a(Object, 2, Object) do |m|
+    m.a nil, 2, '3'
+  end
+
+  # Expect the reception of #a and return 1 so that other code works.
+  expect mock.to.receive.a{ 1 } do |m|
+    raise 'not 1' unless m.a == 1
+  end
+
+  # Expect the reception of #a and call the block with 1.
+  expect mock.to.receive.a{ |&b| b.call(1) } do |m|
+    j = 0
+    m.a{ |i| j = i }
+    raise 'not 1' unless j == 1
+  end
+
+  # Stub out a specific method on an object.
+  expect 6 do |m|
+    stub(Class.new{
+           def slips
+             raise 'database not available'
+           end
+
+           def total
+             slips.reduce(0){ |m, n| m.to_i + n.to_i }
+           end
+         }.new, :slips => [1, 2, 3]){ |account| account.total }
+  end
+
+
+  # Create a stub object that responds to specific methods.
   expect 3 do
     s = stub(:a => 1, :b => 2)
     s.a + s.b
   end
 
+  # Expect the reception of #a on a stub object that responds to specific methods.
+  expect stub(:a => 1, :b => 2).to.receive.a do |o|
+    o.a + o.b
+  end
+
+  # Expect the reception of #a on a mock object that responds to specific methods.
+  expect mock(:a => 2, :b => 2).to.receive.a do |o|
+    o.a + o.b
+  end
+
   # Use a stub that’s set up with a set of procs as methods.
   expect 3 do
     s = stub(:a => proc{ |a, b| a + b })
     s.a(1, 2)
   end
 
-  # Use a contrete mock to verify that a method is called.
-  expect Object.to.receive.deal do
-    Object.deal
+  # Stub out a specific method on an object.
+  expect 'def' do
+    stub('abc', :to_str => 'def'){ |a| a.to_str }
   end
 
-  # Expect a new object to receive #deal with any arguments.
-  expect Object.new.to.receive.deal do |o|
-    o.deal(1, 2, 3)
-  end
 
-  # Expect a new object to receive #deal without arguments.
-  expect Object.new.to.receive.deal(without_arguments) do |o|
-    o.deal
-  end
 
-  # Expect a new object to receive #deal with any argument, 1, and any
-  # argument.
-  expect Object.new.to.receive.deal(arg, 1, arg) do |o|
-    o.deal :a, 1, :b
-  end
 
   # Utilities
-  
-  # Use #with_verbose to set $VERBOSE during the execution of a block.
-  expect nil do
-    with_verbose(nil) do
-      $VERBOSE
+
+  # Override the value of a constant during the execution of a block.
+  expect 'hello' do
+    with_const 'A::B::C', 'hello' do
+      A::B::C
     end
   end
 
-  expect warning('this is your final one!') do
-    warn 'this is your final one!'
+  # Override/add environment keys/values during the execution of a block.
+  expect 'hello' do
+    with_env 'INTRO' => 'hello' do
+      ENV['INTRO']
+    end
   end
 
-  expect warning('this is your final one!') do
-    warn '%s:%d: warning: this is your final one!' % [__FILE__, __LINE__]
+  # Override the value of a global during the execution of a block.
+  expect 'hello' do
+    with_global :$stdout, StringIO.new do
+      print 'hello'
+      $stdout.string
+    end
+  end
+
+  # Use the overridden value of a global during the execution of a block.
+  expect true do
+    with_global :$stdout, StringIO.new do |overridden|
+      $stdout != overridden
+    end
   end
 end