minispec 0.0.1

data/lib/minispec/helpers.rb

@@ -0,0 +1 @@
+Dir[File.expand_path('../helpers/**/*.rb', __FILE__)].each {|f| require(f)}

data/lib/minispec/helpers/array.rb

@@ -0,0 +1,56 @@
+module Minispec
+
+  # checks whether 2 arrays has same elements.
+  # basically it is an unordered `==`
+  helper :same_elements, with_context: true do |left, right, context|
+    lm, rm = [left, right].map do |a|
+      a.is_a?(Array) ?
+        MiniSpec::Utils.array_elements_map(a) :
+        raise(ArgumentError, 'Is %s an Array?' % a.inspect)
+    end
+    failure = '%s should %%s have same elements as %s' % [left, right].map(&:inspect)
+    context[:negation] ?
+      (lm == rm && fail(failure % 'NOT')) :
+      (lm == rm || fail(failure % ''))
+  end
+  alias_helper :same_elements?,    :same_elements
+  alias_helper :same_elements_as,  :same_elements
+  alias_helper :same_elements_as?, :same_elements
+
+  # checks whether given array contains ALL of given element(s).
+  # if given element is a regexp, at least one element in array should match it.
+  helper :contain?, with_context: true do |left, *args|
+    context = args.pop
+    left.is_a?(Array) || raise(ArgumentError, 'Is %s an Array?' % left.inspect)
+    contain = args.all? do |a|
+      a.is_a?(Regexp)?
+        left.find {|b| b.to_s =~ a} :
+        left.find {|b| b      == a}
+    end
+    failure = '%s should %%s contain %s' % [left, args].map(&:inspect)
+    context[:negation] ?
+      (contain && fail(failure % 'NOT')) :
+      (contain || fail(failure % ''))
+  end
+  alias_helper :contains?, :contain?
+  alias_helper :to_contain, :contain?
+
+  # checks whether given array contains at least one of given element(s).
+  # regular expressions accepted.
+  helper :contain_any?, with_context: true do |left, *args|
+    context = args.pop
+    left.is_a?(Array) || raise(ArgumentError, 'Is %s an Array?' % left.inspect)
+    contain = args.any? do |a|
+      a.is_a?(Regexp)?
+        left.find {|b| b.to_s =~ a} :
+        left.find {|b| b      == a}
+    end
+    failure = '%s should %%s contain any of %s' % [left, args].map(&:inspect)
+    context[:negation] ?
+      (contain && fail(failure % 'NOT')) :
+      (contain || fail(failure % ''))
+  end
+  alias_helper :contains_any?,  :contain_any?
+  alias_helper :to_contain_any, :contain_any?
+
+end

data/lib/minispec/helpers/booleans.rb

@@ -0,0 +1,108 @@
+module Minispec
+
+  # a shortcut for `assert(something) == true`
+  # passes only if `subject == true`
+  #
+  # @example
+  #   describe do
+  #     let(:something) { true }
+  #
+  #     test :something do
+  #       is(something).true?
+  #     end
+  #   end
+  helper :true?, with_context: true do |left_object,context|
+    value, message = if left_object.is_a?(Proc)
+      returned = self.instance_exec(&left_object)
+      [
+        returned,
+        proc {'expected block at "%s" to return true, instead it returned %s' % [
+          MiniSpec::Utils.source(left_object),
+          returned.inspect
+        ]}
+      ]
+    else
+      [left_object, proc {'expected %s to be true' % left_object.inspect}]
+    end
+    context[:negation] ?
+      (value == true && fail('Not ' + message.call)) :
+      (value == true || fail(message.call.capitalize))
+  end
+  alias_helper :is_true, :true?
+
+  # passes if subject is not nil nor false
+  helper :positive, with_context: true do |left_object,context|
+    value, message = if left_object.is_a?(Proc)
+      returned = self.instance_exec(&left_object)
+      [
+        returned,
+        proc {'expected block at "%s" to return a non falsy value, instead it returned %s' % [
+          MiniSpec::Utils.source(left_object),
+          returned.inspect
+        ]}
+      ]
+    else
+      [
+        left_object,
+        proc{'expected %s to be non falsy' % left_object.inspect}
+      ]
+    end
+    context[:negation] ?
+      (value && fail('Not ' + message.call)) :
+      (value || fail(message.call.capitalize))
+  end
+  alias_helper :positive?,   :positive
+  alias_helper :is_positive, :positive
+  alias_helper :truthful?,   :positive
+  alias_helper :non_falsy?,  :positive
+
+  # a shortcut for `assert(something) == false`
+  # passes only if `subject == false`
+  helper :false?, with_context: true do |left_object,context|
+    value, message = if left_object.is_a?(Proc)
+      returned = self.instance_exec(&left_object)
+      [
+        returned,
+        proc {'expected block at "%s" to return false, instead it returned %s' % [
+          MiniSpec::Utils.source(left_object),
+          returned.inspect
+        ]}
+      ]
+    else
+        [
+          left_object,
+          proc{'expected %s to be false' % left_object.inspect}
+        ]
+    end
+    context[:negation] ?
+      (value == false && fail('Not ' + message.call)) :
+      (value == false || fail(message.call.capitalize))
+  end
+  alias_helper :is_false, :false?
+
+  # passes if subject is nil or false
+  helper :negative, with_context: true do |left_object,context|
+    value, message = if left_object.is_a?(Proc)
+      returned = self.instance_exec(&left_object)
+      [
+        returned,
+        proc {'expected block at "%s" to return a falsy value, instead it returned %s' % [
+          MiniSpec::Utils.source(left_object),
+          returned.inspect
+        ]}
+      ]
+    else
+      [
+        left_object,
+        proc {'expected %s to be falsy' % left_object.inspect}
+      ]
+    end
+    context[:negation] ?
+      (value || fail('Not ' + message.call)) :
+      (value && fail(message.call.capitalize))
+  end
+  alias_helper :negative?, :negative
+  alias_helper :falsy?,    :negative
+  alias_helper :is_falsy,  :negative
+
+end

data/lib/minispec/helpers/generic.rb

@@ -0,0 +1,24 @@
+module Minispec
+
+  # checks whether given block produces any output
+  #
+  # @example
+  #   expect { ... }.to_be_silent
+  #
+  helper :silent, with_context: true do |block, context|
+    begin
+      $stdout, $stderr = StringIO.new, StringIO.new
+      self.instance_exec(&block)
+      message = 'Expected block at %s to be silent' % MiniSpec::Utils.source(block)
+      out = [$stdout, $stderr].map {|s| s.rewind; v = s.read; s.close; v}.join
+      context[:negation] ?
+        out.empty? && fail('Not %s' % message) :
+        out.empty? || fail(message + ". Instead it did output:\n" + out)
+    ensure
+      $stdout, $stderr = STDOUT, STDERR
+    end
+  end
+  alias_helper :silent?,       :silent
+  alias_helper :is_silent,     :silent
+  alias_helper :to_be_silent,  :silent
+end

data/lib/minispec/helpers/mocks/expectations.rb

@@ -0,0 +1,29 @@
+module Minispec
+
+  # a helper to add expectations to objects.
+  # expectations will be validated when current test evaluation finished.
+  #
+  # @example
+  #
+  #   expect(some_object).to_receive(:some_method)
+  #
+  # @example expecting multiple messages
+  #
+  #   expect(some_object).to_receive(:some, :method)
+  #
+  helper :receive, with_context: true do |object,*args|
+    context = Hash[args.pop]
+    args.any? || raise(ArgumentError, 'Please provide at least one message')
+
+    args.size > 1 ?
+      context.update(expected_messages: args) :
+      context.update(expected_message:  args.first)
+
+    expectation = MiniSpec::Mocks::Expectations.new(self, object, context, *args)
+    @__ms__expectations.push(expectation)
+    args.each {|m| proxy(object, m)}
+    expectation
+  end
+  alias_helper :receive?,   :receive
+  alias_helper :to_receive, :receive
+end

data/lib/minispec/helpers/mocks/spies.rb

@@ -0,0 +1,36 @@
+module Minispec
+
+  # ensure given object received expected message.
+  # expectations will be validated straight away
+  # so the object should be proxied before this helper used.
+  #
+  # @example  spying on a explicitly "proxified" method
+  #   spy(obj, :a)
+  #   # ...
+  #   assert(obj).received(:a)
+  #
+  # @example  spying on a double
+  #   user = double(:user, :new)
+  #   # ...
+  #   assert(user).received(:new)
+  #
+  # @note  `received` helper works exactly as `to_receive` one,
+  #         that's it, all validations available for expectations
+  #         will work for spies too.
+  #
+  # @example  ensure message received with specific arguments
+  #   # ...
+  #   assert(obj).received(:m).with(:x, :y)
+  #
+  # @example  ensure specific value returned
+  #   # ...
+  #   assert(obj).received(:m).and_returned(:x)
+  #
+  helper :received, with_context: true do |object,*args|
+    context = Hash[args.pop]
+    args.any? || raise(ArgumentError, 'Please provide at least one message')
+    MiniSpec::Mocks::Validations.new(self, object, context, *args)
+  end
+  alias_helper :received?, :received
+
+end

data/lib/minispec/helpers/raise.rb

@@ -0,0 +1,44 @@
+module Minispec
+
+  # checks whether given block raises an exception
+  #
+  # @example
+  #   describe :Exceptions do
+  #     let(:something_bad) { raise Something, 'bad' }
+  #
+  #     should 'raise something bad' do
+  #       does { something_bad }.raise? Something, 'bad'
+  #     end
+  #   end
+  #
+  helper :raise, with_context: true do |obj, *rest|
+    context = Hash[rest.pop]
+
+    # if a block passed to helper, it will be received as last but one argument,
+    # just before context, so popping it out cause we will consume it from context.
+    # normally we would pass no arguments if right block given,
+    # but we need to pass them cause arguments validation happens next in the stream
+    # and validator needs all data provided by user
+    context[:right_proc] && rest.pop
+
+    subject = begin
+      obj.is_a?(Proc) ? self.instance_exec(&obj) : obj
+    rescue Exception => e
+      e
+    end
+
+    result = MiniSpec::Utils.exception_raised?(subject, context, *rest, &context[:right_proc])
+    result.is_a?(MiniSpec::ExceptionError) && fail(result.message)
+    subject
+  end
+  alias_helper :raise?,             :raise
+  alias_helper :raises,             :raise
+  alias_helper :raises?,            :raise
+  alias_helper :raise_error,        :raise
+  alias_helper :raise_error?,       :raise
+  alias_helper :raise_exception,    :raise
+  alias_helper :raise_exception?,   :raise
+  alias_helper :to_raise,           :raise
+  alias_helper :to_raise_error,     :raise
+  alias_helper :to_raise_exception, :raise
+end

data/lib/minispec/helpers/throw.rb

@@ -0,0 +1,29 @@
+module Minispec
+
+  # checks whether given block throws a symbol
+  #
+  # @example
+  #   does { something }.throw? :some_symbol
+  #   does { something }.throw? :some_symbol, 'with some value'
+  #   does { something }.throw? :some_symbol, /with some value/
+  helper :throw, with_context: true do |obj, *rest|
+    context = Hash[rest.pop]
+
+    # if a block passed to helper, it will be received as last but one argument,
+    # just before context, so popping it out cause we will consume it from context.
+    # normally we would pass no arguments if right block given,
+    # but we need to pass them cause arguments validation happens next in the stream
+    # and validator needs all data provided by user
+    context[:right_proc] && rest.pop
+
+    expected_symbol, expected_value = rest
+    obj.is_a?(Proc) || raise(ArgumentError, '`throw` helper works only with blocks')
+    status = MiniSpec::Utils.symbol_thrown?(expected_symbol, expected_value, context, &obj)
+    status.is_a?(MiniSpec::ThrowError) && fail(status.message)
+  end
+  alias_helper :throw?,          :throw
+  alias_helper :throw_symbol,    :throw
+  alias_helper :throw_symbol?,   :throw
+  alias_helper :to_throw,        :throw
+  alias_helper :to_throw_symbol, :throw
+end

data/lib/minispec/mocks.rb

@@ -0,0 +1,11 @@
+module MiniSpec
+  module Mocks
+    class HashedStub
+      def self.with(*)
+        raise(ArgumentError, "`with' can not be used on stubs/mocks defined using a Hash")
+      end
+    end
+  end
+end
+
+Dir[File.expand_path('../mocks/*.rb', __FILE__)].each {|f| require(f)}

data/lib/minispec/mocks/expectations.rb

@@ -0,0 +1,77 @@
+module MiniSpec
+  module Mocks
+    class Expectations
+
+      def initialize base, object, context, *args
+        @base, @object, @context, @args = base, object, context, args
+        @expectations = []
+      end
+
+      def validate!
+        validator = Validations.new(@base, @object, @context, *@args)
+        @expectations.each {|e| e.call(validator)}
+      end
+
+      def with *args, &proc
+        push {|v| proc ? v.with(&proc) : v.with(*args)}
+      end
+
+      def without_arguments
+        push {|v| v.without_arguments}
+      end
+      alias without_any_arguments without_arguments
+
+      def with_caller *args, &proc
+        push {|v| proc ? v.with_caller(&proc) : v.with_caller(*args)}
+      end
+
+      def and_return *args, &proc
+        push {|v| proc ? v.and_return(&proc) : v.and_return(*args)}
+      end
+      alias and_returned and_return
+
+      def and_yield *args, &proc
+        push {|v| proc ? v.and_yield(&proc) : v.and_yield(*args)}
+      end
+
+      def without_yield
+        push {|v| v.without_yield}
+      end
+
+      def and_raise *args, &proc
+        push {|v| v.and_raise(*args, &proc)}
+      end
+
+      def without_raise
+        push {|v| v.without_raise}
+      end
+
+      def and_throw *args, &proc
+        push {|v| v.and_throw(*args, &proc)}
+      end
+
+      def without_throw
+        push {|v| v.without_throw}
+      end
+
+      def count *expected, &proc
+        push {|v| proc ? v.count(&proc) : v.count(*expected)}
+      end
+      alias times count
+
+      def once;  count(1); end
+      def twice; count(2); end
+
+      def ordered n = 1
+        push {|v| v.ordered(n)}
+      end
+
+      private
+      def push &proc
+        @expectations << proc
+        self
+      end
+
+    end
+  end
+end

data/lib/minispec/mocks/stubs.rb

@@ -0,0 +1,178 @@
+module MiniSpec
+  module Mocks
+    class MultipleStubsProxy
+      def initialize stubs
+        @stubs = stubs.freeze
+      end
+
+      def with *a, &b
+        @stubs.each {|s| s.with(*a, &b)}
+        self
+      end
+
+      def with_any *a, &b
+        @stubs.each {|s| s.with_any(*a, &b)}
+        self
+      end
+    end
+
+    class Stub
+
+      def initialize object, messages, stubs = {}
+        @object, @messages, @stubs, @blocks = object, messages, stubs, {}
+      end
+
+      # makes a stub to behave differently depending on given arguments
+      #
+      # @example
+      #   stub(a, :b).
+      #     with(1) { :one }. # `a.b(1)` will return :one
+      #     with(2) { :two }  # `a.b(2)` will return :two
+      #
+      def with *args, &block
+        @blocks[args] = block || proc {}
+        self
+      end
+
+      # defines a catchall block
+      #
+      # @example with a block
+      #   stub(a, :b).
+      #     with(1)  { :one }. # `a.b(1)` will return :one
+      #     with_any { :any }  # `a.b(:any_args, :or_no_args)` will return :any
+      #
+      # @example with a value
+      #   stub(a, :b).
+      #     with(1) { :one }.
+      #     with_any(:any)
+      #
+      def with_any *args, &block
+        # this args mangling needed to be able to accept nil or false as value
+        (value_given = args.size == 1) || args.size == 0 ||
+          raise(ArgumentError, 'Wrong number of arguments, %i instead of 0..1' % args.size)
+        value_given && block && raise(ArgumentError, 'Both a value and a block used. Please use either one')
+        value_given || block || raise(ArgumentError, 'No value nor block provided')
+        @catchall_block = value_given ? proc { args.first } : block
+        self
+      end
+      alias any with_any
+
+      # defines given stub of given visibility on `@object`
+      #
+      # @param stub
+      #   - when stub is a symbol it defines a method.
+      #     if `@object` has a singleton method with stub name or the stub name is :nil?,
+      #     the method are defined using `define_singleton_method`.
+      #     otherwise `@object` are extended with a module containing needed methods(@see #mixin)
+      #   - when given stub contain dots, a chained stub defined(@see #define_chained_stub)
+      #
+      # @param visibility stub visibility, :public(default), :protected, :private
+      # @param [Proc] &proc  block to be yielded when stub called
+      # @raise ArgumentError  if given stub is not a Symbol, String, Hash or Array
+      def stubify stub, visibility, &block
+        stub.is_a?(Symbol) || raise('stubs names should be provided as symbols')
+
+        @catchall_block = block if block # IMPORTANT! update catchall block only if another block given
+
+        @object.singleton_methods.include?(stub) || stub == :nil? ?
+          define_singleton_stub(stub) :
+          define_regular_stub(stub, visibility)
+      end
+
+      def most_relevant_block_for args
+        @blocks[args] || @catchall_block || proc {}
+      end
+
+      private
+      def define_regular_stub stub, visibility
+        @object.extend(mixin(stub, visibility))
+        # defining a singleton if stub can not be inserted via mixin
+        define_singleton_stub(stub) unless MiniSpec::Utils.method_defined?(@object, stub)
+      end
+
+      def define_singleton_stub stub
+        @object.define_singleton_method(stub, &proxy(stub))
+      end
+
+      # defines a new Module that contains given stub method of given visibility
+      #
+      # @param stub  method to be defined
+      # @param visibility  method visibility. default - public
+      # @param &block  block to be yielded when method called
+      # @return [Module]
+      def mixin stub, visibility = nil
+        method = proxy(stub)
+        Module.new do
+          define_method(stub, &method)
+          protected stub.to_sym if visibility == :protected
+          private   stub.to_sym if visibility == :private
+        end
+      end
+
+      # builds a block that will be yielded when given method called.
+      # when yielded,  the block will collect received messages stat.
+      #
+      # the block will receive original method as first argument
+      # and any passed params as rest arguments.
+      #
+      # @param method_name
+      # @param &block
+      # @return [Proc]
+      def proxy method_name
+        method_name.is_a?(Symbol) || raise(ArgumentError, 'method name should be a Symbol')
+        register_stub(method_name)
+        base, object, messages, original = self, @object, @messages, original(method_name)
+
+        Proc.new do |*args,&block|
+          message = {
+            object:    object,
+            method:    method_name,
+            arguments: args,
+            caller:    Array(caller)
+          }
+          messages.push(message)
+
+          method = base.most_relevant_block_for(args)
+
+          proc = block ? Proc.new do |*a,&b|
+            message[:yielded] = a
+            block.call(*a, &b)
+          end : nil
+
+          begin
+            message[:returned] = method.call(original, *args, &proc)
+          rescue Exception => e
+            message[:raised] = e
+          end
+          message.freeze
+          message[:raised] ? raise(message[:raised]) : message[:returned]
+        end
+      end
+
+      # tracking what methods was stubbed on what objects
+      # so they can be unstubbed when current test evaluation finished.
+      #
+      # @param stub  method to be stubbed
+      def register_stub stub
+        stub.is_a?(Symbol) || raise(ArgumentError, 'stub should be a symbol')
+
+        return if originals.has_key?(stub)
+        if stub == :nil? || @object.singleton_methods.include?(stub)
+          return originals.update(stub => [@object.method(stub), :singleton])
+        end
+        if visibility = MiniSpec::Utils.method_visibility(@object, stub)
+          return originals.update(stub => [@object.method(stub), visibility])
+        end
+        originals.update(stub => [])
+      end
+
+      def originals
+        @stubs[@object] ||= {}
+      end
+
+      def original method
+        originals[method] && originals[method].first
+      end
+    end
+  end
+end