lookout 2.3.0 → 3.0.0

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

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

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

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+
+# Represents expected {::Symbol}s.  A Symbol that’s suffixed by “?” is
+# considered to be a query to be invoked on the actual result.  If such a
+# symbol is prefixed by “not_”, the result of the query is inversed.
+class Lookout::Expected::Symbol < Lookout::Expected::Object
+  def initialize(expected)
+    super
+    @negated, @query = /\A(?:(not)_)?(?:(.+\?)|.*)\z/m.match(expected.to_s)[1..2]
+  end
+
+  # @param [::Symbol, ::Object] actual
+  # @return [Difference::Symbol, nil] A difference report between _actual_ and
+  #   {#expected} if {#expected} is a query and the result of the query doesn’t
+  #   equal what’s expected, {super} otherwise
+  def difference(actual)
+    return super if not @query or Symbol === actual or actual.method(@query).arity != 0
+    Lookout::Difference::Symbol.new(actual, expected, @query, @negated) unless
+      (not not actual.send(@query)) ^ !!@negated
+  end
+end

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

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

data/lib/lookout-3.0/inspect.rb

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+
+# Non-failing inspection of objects.  The inspection is {Lookout::Encode
+# encoded} for output.
+class Lookout::Inspect
+  # Non-failing inspection of OBJECT, using TYPE as a description of the
+  # type of object being inspected for failure outputs.
+  # @param [Object] object
+  # @param [String] type
+  Value(:object, :type)
+
+  class << self
+    # @param [Object, …] args
+    # @return [String] The inspections of ARGS, separated by “, ”’s
+    def args(*args)
+      args.map{ |e| Lookout::Inspect.new(e, 'argument') }.join(', ')
+    end
+  end
+
+  # @return [String] An UTF-8-encoded String inspection of the given object,
+  #   generated by invoking #inspect on it, then {Lookout::Encode encoding} it
+  #   as UTF-8, using #dump if any transcoding that may take place fails
+  def call
+    Lookout::Encode.new(inspection = inspect_object).call
+  rescue => e
+    '(cannot encode inspected %s for output: %s; %s)' %
+      [type,
+       Lookout::Exception.new(e),
+       begin
+         'dumping instead: %s' % [inspection.dump]
+       rescue => inner
+         'dumping also failed: %s' % Lookout::Exception.new(inner)
+       end]
+  end
+
+  alias to_s call
+
+  private
+
+  def inspect_object
+    String(object.inspect)
+  rescue => e
+    '(cannot inspect %s: %s)' % [type, Lookout::Exception.new(e)]
+  end
+end

data/lib/lookout-3.0/interfaces.rb

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+# Namespace for interfaces to Lookout.
+module Lookout::Interfaces
+end

data/lib/lookout-3.0/interfaces/commandline.rb

@@ -0,0 +1,109 @@
+# -*- coding: utf-8 -*-
+
+# Command-line interface to Lookout.
+class Lookout::Interfaces::Commandline
+  # Processes ARGUMENTS, looking for options, running from the directory
+  # PWD and outputting results to IO.
+  #
+  # Valid arguments are
+  #
+  # * --: Stops processing of options, treating remaining arguments as files
+  # * -rFEATURE: Requires _FEATURE_
+  # * -lLINE: Only runs expectation closest before or on _LINE_
+  # * -c: Reports test coverage
+  # * FILENAME: Loads expectations from _FILENAME_, relative to PWD
+  #
+  # @param [Array<String>] arguments
+  # @param [String] pwd
+  # @param [IO] io
+  # @raise [ArgumentError] If an unknown option exists among ARGUMENTS
+  def initialize(arguments = ARGV, pwd = Dir.pwd, io = $stderr)
+    @pwd, @io = pwd, io
+    @line = nil
+    @files = []
+    @requires = []
+    @coverage = false
+    only_load = false
+    arguments.each do |argument|
+      if not only_load and argument == '--'
+        only_load = true
+      elsif not only_load and argument =~ /\A-r(.*)/
+        @requires << $1
+      elsif not only_load and argument =~ /\A-l(.*)/
+        @line = $1.to_i
+      elsif not only_load and argument == '-c'
+        @coverage = true
+      elsif not only_load and argument =~ /\A-/
+        raise ArgumentError, 'unknown option: %s' % argument
+      else
+        @files << [File.expand_path(argument, pwd), argument]
+      end
+    end
+  end
+
+  # Requires requested features, sets up coverage reporting, if desired, and
+  # checks the requested expectations.  Coverage reporting will only be done if
+  # all expectations passed.
+  #
+  # @return [Boolean] True if all expectations passed
+  def call
+    require
+    coverage do
+      return false unless expectations
+    end
+    true
+  end
+
+  private
+
+  def require
+    @requires.each do |feature| super feature end
+  end
+
+  def coverage
+    return yield unless @coverage
+    require 'coverage'
+    Coverage.start
+    yield
+    Coverage.result.
+      select{ |file, _| file.start_with? @pwd }.
+      reject{ |file, _| files.assoc(file) }.
+      sort.
+      each do |file, counts|
+        counts.
+        each_cons(2).
+        with_index.
+        slice_before{ |(c1, c2), _| (c1 != 0 and c2 == 0) or (c1 == 0 and c2 != 0) }.
+        select{ |e| e.first.first.last == 0 }.
+        map{ |e| e.first.last+2..e.last.last+2 }.
+        each do |lines|
+          io.puts '%s:%s: not covered by test' %
+            [relativize(file),
+             lines.one? ? lines.begin : ('%d-%d' % [lines.begin, lines.end])]
+        end
+      end
+  end
+
+  def expectations
+    passed = true
+    @files.each do |expanded, file|
+      expectations = Lookout::Expectations.new(expanded)
+      if @line
+        target = nil.to_lookout_expected.expect(expanded, @line){
+          raise RuntimeError, 'line expectation not found: %s:%d' % [file, @line]
+        }
+        [(expectations.take_while{ |expect| expect <= target }.last or target)]
+      else
+        expectations
+      end.each do |expect|
+        result = expect.call
+        next if Lookout::Results::Success === result
+        passed = false
+        @io.puts relativize(result.to_s)
+      end
+    end
+    passed
+  end
+
+  def relativize(path) path.start_with?(@pwd) ? path[@pwd.length+1..-1] : path end
+end

data/lib/lookout-3.0/literal.rb

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+
+# Proxies objects that should be literally expected.  This is achieved by
+# overriding #to_lookout_expected to wrap the object in a
+# {Lookout::Expected::Object} instead of using whatever #to_lookout_expected on
+# the object would normally return.  This allows us to expect a literal {Range}
+# instead of allowing either a Range or an item included in the range.
+class Lookout::Literal
+  # Proxies the EXPECTED value, allowing it to be expected literally.
+  # @param [Object] expected
+  Value(:expected)
+
+  def inspect; 'literal(%p)' % output end
+
+  # @return [Expected::Object] An expected value wrapper around the expected
+  #   value
+  def to_lookout_expected; Lookout::Expected::Object.new(@expected) end
+end

data/lib/lookout-3.0/mock.rb

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+
+# Object that doesn’t respond to anything except for what’s been explicitly
+# defined on it and throws a mock error whenever it receives a method call.
+class Lookout::Mock < Lookout::Stub
+  def inspect; 'mock' end
+
+  private
+
+  # @param [Symbol] method
+  # @param [Object, …] args
+  # @raise [Reception::Error] When called, including the METHOD that was called
+  #   and with what ARGS in the messaged and with the proper backtrace, making
+  #   it easy to see where things went wrong
+  def method_missing(method, *args)
+    raise Lookout::Reception::Error.
+      from('%p#%s(%s)%s' % [self,
+                            method,
+                            Lookout::Inspect.args(*args),
+                            block_given? ? '{ … }' : ''],
+           1,
+           0..0)
+  end
+end

data/lib/lookout-3.0/object.rb

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+
+# Namespace for extensions to {::Object}.  Implements the “to” and “not”
+# keywords on objects that are used to build {Reception} expectations.
+module Lookout::Object
+end

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

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+
+# The “not” keyword on {::Object}s.
+class Lookout::Object::Not
+  # Wraps OBJECT as a “not”.
+  # @param [::Object] object
+  def initialize(object) @object = object end
+
+  # Method for improving readability of “not” keyword set-up.
+  # @return [self]
+  def to; self end
+
+  # @return [Receive] A wrapper around the object that’ll set up a reception
+  #   expectation on it
+  def receive; Receive.new(@object) end
+end

data/lib/lookout-3.0/object/not/receive.rb

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+
+# The “not to receive” keywords on {::Object}s.
+class Lookout::Object::Not::Receive < Lookout::Aphonic
+  # Stands in for OBJECT, allowing a {Reception} exception that expects the
+  # given method never to be called to be set up.
+  # @param [::Object] object
+  def initialize(object) @object = object end
+
+  private
+
+  # @param (see Reception#initialize)
+  # @return [Reception] A method reception expectation on the object that
+  #   expects METHOD {Reception#never never} to be called
+  def method_missing(method, *args, &body)
+    Lookout::Reception.of(@object, method, *args, &body).never
+  end
+end

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

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+# The “to” keyword on {::Object}s.
+class Lookout::Object::To
+  # Wraps OBJECT as a “to”.
+  # @param [::Object] object
+  def initialize(object) @object = object end
+
+  # @return [Receive] A wrapper around the object that’ll set up a reception
+  #   expectation on it
+  def receive; Receive.new(@object) end
+end

data/lib/lookout-3.0/object/to/receive.rb

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+
+# The “to receive” keywords on {::Object}s.
+class Lookout::Object::To::Receive < Lookout::Aphonic
+  # Stands in for OBJECT, allowing a {Reception} exception that expects the
+  # given method to be called to be set up.
+  # @param [::Object] object
+  def initialize(object) @object = object end
+
+  private
+
+  # @param (see Reception#initialize)
+  # @return [Reception] A method reception expectation on the subject for
+  #   METHOD with _args_, using _body_ as the method definition
+  def method_missing(method, *args, &body)
+    Lookout::Reception.of(@object, method, *args, &body)
+  end
+end

data/lib/lookout-3.0/output.rb

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+
+# Output expectation proxy.  Used to expect output on an IO object during the
+# execution of an {Lookout::Expect expect block}.
+class Lookout::Output
+  # Proxies the EXPECTED output.
+  # @param [String] expected
+  Value(:expected)
+
+  def inspect; 'output(%p)' % expected end
+
+  # @return [Enumerable<String>] An Enumerable over the formatted operations
+  #   that would have to be applied to the actual output to get the expected
+  #   output
+  def diff(other) expected.to_lookout_expected.difference(other.expected).diff end
+
+  # @return [Expected::Lookout::Output] A wrapper around the receiver, making
+  #   it an expected value
+  def to_lookout_expected; Lookout::Expected::Lookout::Output.new(self) end
+end

data/lib/lookout-3.0/plugins.rb

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+
+# Namespace for Lookout plugins.  Plugins should place their top-level
+# class/module under this namespace.  For example, the Rack plugin is named
+# Lookout::Plugins::Rack.
+module Lookout::Plugins
+end

data/lib/lookout-3.0/reception.rb

@@ -0,0 +1,128 @@
+# -*- coding: utf-8 -*-
+
+# Method reception expectation builder.  Method reception expectations can set
+# expectations on what method is going to be called, with what arguments, and
+# how many times it’s to take place.
+class Lookout::Reception
+  Value(:object, :method, :range, :'*args', :'&body')
+  # @return [Range] The range of number of times that the method may be called
+  public :range
+
+  class << self
+    # @param [Symbol] method
+    # @param [Object, …] args
+    # @return [Lookout::Reception] A reception expectation expecting METHOD to
+    #   be called on OBJECT with ARGS, using BODY as the method definition.
+    def of(object, method, *args, &body)
+      new(object, method, 1..1.0/0, *args, &body)
+    end
+
+    private :new
+  end
+
+  # This is an alias for {#exactly}(0).
+  def never; exactly(0) end
+
+  # This is an alias for {#at_most}(1).
+  def at_most_once; at_most(1) end
+
+  # This is an alias for {#exactly}(1).
+  def once; exactly(1) end
+
+  # This is an alias for {#at_least}(1).
+  def at_least_once; at_least(1) end
+
+  # This is an alias for {#exactly}(2).
+  def twice; exactly(2) end
+
+  # @param [Integer] times
+  # @return [Lookout::Reception] A reception expectation with a maximum number
+  #   of TIMES that the method may be called
+  # @raise [ArgumentError] If TIMES < 1
+  def at_most(times)
+    limit('cannot convert upper reception limit to Integer: %s', times){ |i|
+      raise ArgumentError,
+        'upper reception limit must be positive: %d < 1' % i if i < 1
+      0..i
+    }
+  end
+
+  # @param [Integer] times
+  # @return [Lookout::Reception] A reception expectation with a minimum and
+  #   maximum number of TIMES that the method may be called
+  # @raise [ArgumentError] If TIMES < 0
+  def exactly(times)
+    limit('cannot convert reception invocation count to Integer: %s', times){ |i|
+      raise ArgumentError,
+        'expected reception count must be non-negative: %d < 0' % i if i < 0
+      i..i
+    }
+  end
+
+  # Sets the minimum number of times that the method may be called.
+  # @param [Integer] times
+  # @return [Lookout::Reception] A reception expectation with a minimum number
+  #   of TIMES that the method may be called
+  # @raise [ArgumentError] If TIMES < 1
+  def at_least(times)
+    limit('cannot convert lower reception limit to Integer: %s', times){ |i|
+      raise ArgumentError,
+        'lower reception limit must be positive: %d < 1' % i if i < 1
+      i..1.0/0
+    }
+  end
+
+  # @return [Expected::Lookout::Reception] A wrapper around the object that
+  #   represents the expected reception of this method
+  def to_lookout_expected
+    Lookout::Expected::Lookout::Reception.new(self)
+  end
+
+  # @return [Proc] A block to be used by {Expected::Lookout::Reception#expect}
+  #   that’ll set up a stub for the expected method reception that’ll check
+  #   that the call count doesn’t exceed any upper limit imposed upon it and
+  #   verify that any arguments are what they’re expected to be and then invoke
+  #   BLOCK
+  def block(&block)
+    args, calls = Arguments.for(*@args), 0
+    reception, object, method, range, body = self, @object, @method, @range, @body || Nil
+    proc{
+      stub(object, method => proc{ |*mock_args, &mock_block|
+             calls += 1
+             raise Error.from(reception, calls, range) if calls > range.end
+             raise Arguments::Error,
+               '%s: unexpected arguments: [%s]≠[%s]' %
+                 [reception, Arguments::List.new(*mock_args), args] unless
+                   args =~ mock_args
+             body.call(*mock_args, &mock_block)
+           }, &block) if block
+      calls
+    }
+  end
+
+  # @return A String consisting of the inspection of the object, followed by
+  #   either ‘.’ or ‘#’ depending on whether the object is a Class or not, and
+  #   the method name
+  def to_s
+    [Lookout::Inspect.new(object, 'object'),
+     Class === object ? '.' : '#',
+     method].join('')
+  end
+
+  private
+
+  def limit(format, times)
+    self.class.send(:new,
+                    object,
+                    method,
+                    yield(begin
+                            times.to_int
+                          rescue => e
+                            raise e, format % e
+                          end),
+                    *args,
+                    &body)
+  end
+
+  Nil = proc{ Lookout::Stub.new }
+end