caricature 0.3.1 → 0.5.0

data/lib/caricature/isolator.rb

@@ -0,0 +1,287 @@
+require File.dirname(__FILE__) + '/messenger'
+require File.dirname(__FILE__) + '/descriptor'
+
+module Caricature
+
+  # Groups the methods for interception together
+  # this is a mix-in for the created isolations for classes
+  module Interception
+
+    # the class methods of this intercepting object
+    module ClassMethods
+
+      # the context of this isolation instance.
+      # this context takes care of responding to method calls etc.
+      def isolation_context
+        @___context___
+      end
+
+      # Replaces the call to the proxy with the one you create with this method.
+      # You can specify more specific criteria in the block to configure the expectation.
+      #
+      # Example:
+      #
+      #     an_isolation.class.when_receiving(:a_method) do |method_call|
+      #       method_call.with(3, "a").return(5)
+      #     end
+      #
+      # is equivalent to:
+      #
+      #     an_isolation.class.when_receiving(:a_method).with(3, "a").return(5)
+      #
+      # You will most likely use this method when you want your stubs to return something else than +nil+
+      # when they get called during the run of the test they are defined in.
+      def when_receiving(method_name, &block)
+        isolation_context.create_class_override method_name, &block
+      end
+
+      # Verifies whether the specified method has been called
+      # You can specify constraints in the block
+      #
+      # The most complex configuration you can make currently is one that is constrained by arguments.
+      # This is most likely to be extended in the future to allow for more complex verifications.
+      #
+      # Example:
+      #
+      #     an_isolation.class.did_receive?(:a_method) do |method_call|
+      #       method_call.with(3, "a")
+      #     end.should.be.successful
+      #
+      # is equivalent to:
+      #
+      #     an_isolation.class.did_receive?(:a_method).with(3, "a").should.be.successful
+      #
+      # You will probably be using this method only when you're interested in whether a method has been called
+      # during the course of the test you're running.
+      def did_receive?(method_name, &block)
+        isolation_context.class_verify method_name
+      end
+
+    end
+
+    # mixes in the class methods of this module when it gets included in a class.
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # the context of this isolation instance.
+    # this context takes care of responding to method calls etc.
+    def isolation_context
+      self.class.isolation_context
+    end
+
+    # Replaces the call to the proxy with the one you create with this method.
+    # You can specify more specific criteria in the block to configure the expectation.
+    #
+    # Example:
+    #
+    #     an_isolation.when_receiving(:a_method) do |method_call|
+    #       method_call.with(3, "a").return(5)
+    #     end
+    #
+    # is equivalent to:
+    #
+    #     an_isolation.when_receiving(:a_method).with(3, "a").return(5)
+    #
+    # You will most likely use this method when you want your stubs to return something else than +nil+
+    # when they get called during the run of the test they are defined in.
+    def when_receiving(method_name, &block)
+      isolation_context.create_override method_name, &block
+    end
+
+    # Replaces the call to the class of the proxy with the one you create with this method.
+    # You can specify more specific criteria in the block to configure the expectation.
+    #
+    # Example:
+    #
+    #     an_isolation.when_class_receives(:a_method) do |method_call|
+    #       method_call.with(3, "a").return(5)
+    #     end
+    #
+    # is equivalent to:
+    #
+    #     an_isolation.when_class_receives(:a_method).with(3, "a").return(5)
+    #
+    # You will most likely use this method when you want your stubs to return something else than +nil+
+    # when they get called during the run of the test they are defined in.
+    def when_class_receives(method_name, &block)
+      self.class.when_receiving method_name, &block
+    end
+
+    # Verifies whether the specified method has been called
+    # You can specify constraints in the block
+    #
+    # The most complex configuration you can make currently is one that is constrained by arguments.
+    # This is most likely to be extended in the future to allow for more complex verifications.
+    #
+    # Example:
+    #
+    #     an_isolation.did_receive?(:a_method) do |method_call|
+    #       method_call.with(3, "a")
+    #     end.should.be.successful
+    #
+    # is equivalent to:
+    #
+    #     an_isolation.did_receive?(:a_method).with(3, "a").should.be.successful
+    #
+    # You will probably be using this method only when you're interested in whether a method has been called
+    # during the course of the test you're running.
+    def did_receive?(method_name, &block)
+      isolation_context.verify method_name
+    end
+
+    # Verifies whether the specified class method has been called
+    # You can specify constraints in the block
+    #
+    # The most complex configuration you can make currently is one that is constrained by arguments.
+    # This is most likely to be extended in the future to allow for more complex verifications.
+    #
+    # Example:
+    #
+    #     an_isolation.did_class_receive?(:a_method) do |method_call|
+    #       method_call.with(3, "a")
+    #     end.should.be.successful
+    #
+    # is equivalent to:
+    #
+    #     an_isolation.did_class_receive?(:a_method).with(3, "a").should.be.successful
+    #
+    # You will probably be using this method only when you're interested in whether a method has been called
+    # during the course of the test you're running.
+    def did_class_receive?(method_name, &block)
+      self.class.did_receive?(method_name, &block)
+    end
+
+  end
+
+  # A base class for +Isolator+ objects
+  # to stick with the +Isolation+ nomenclature the strategies for creating isolations
+  # are called isolators.
+  # An isolator functions as a barrier between the code in your test and the
+  # underlying type/instance. It allows you to take control over the value
+  # that is returned from a specific method, if you want to pass the method call along to
+  # the underlying instance etc.  It also contains the ability to verify if a method
+  # was called, with which arguments etc.
+  class Isolator
+
+    # holds the isolation created by this isolator
+    attr_reader :isolation
+
+    # holds the subject of this isolator
+    attr_reader :subject
+
+    # holds the descriptor for this type of object
+    attr_reader :descriptor
+
+    # creates a new instance of an isolator
+    def initialize(context)
+      @context = context
+    end
+
+    # builds up the isolation class instance
+    def build_isolation(klass, inst=nil)
+      pxy = create_isolation_for klass
+      @isolation = pxy.new
+      @subject = inst
+      initialize_messenger
+    end
+
+    # initializes the messaging strategy for the isolator
+    def initialize_messenger
+      raise NotImplementedError
+    end
+
+    # Creates the new class name for the isolation
+    def class_name(subj)
+      nm = subj.respond_to?(:class_eval) ? subj.demodulize : subj.class.demodulize
+      @class_name = "#{nm}#{System::Guid.new_guid.to_string('n')}"
+      @class_name
+    end
+
+    # Sets up the necessary instance variables for the isolation
+    def initialize_isolation(klass, context)
+      pxy = klass.new
+      pxy.instance_variable_set("@___context___", context)
+      pxy
+    end
+
+    class << self
+
+      # Creates the actual proxy object for the +subject+ and initializes it with a
+      # +recorder+ and +expectations+
+      # This is the actual isolation that will be used to in your tests.
+      # It implements all the methods of the +subject+ so as long as you're in Ruby
+      # and just need to isolate out some classes defined in a statically compiled language
+      # it should get you all the way there for public instance methods at this point.
+      # when you're going to isolation for usage within a statically compiled language type
+      # then  you're bound to most of their rules. So you need to either isolate interfaces
+      # or mark the methods you want to isolate as virtual in your implementing classes.
+      def for(context)
+        context.recorder ||= MethodCallRecorder.new
+        context.expectations ||= Expectations.new
+        new(context)
+      end
+    end
+  end
+
+  # A proxy to Ruby objects that records method calls
+  # this implements all the instance methods that are defined on the class.
+  class RubyIsolator < Isolator
+
+    # implemented template method for creating Ruby isolations
+    def initialize(context)
+      super
+      klass = @context.subject.respond_to?(:class_eval) ? @context.subject : @context.subject.class
+      inst = @context.subject.respond_to?(:class_eval) ? @context.subject.new : @context.subject
+      @descriptor = RubyObjectDescriptor.new klass
+      build_isolation klass, inst
+    end
+
+    # initializes the messaging strategy for the isolator
+    def initialize_messenger
+      @context.messenger = RubyMessenger.new @context.expectations, @subject
+    end
+
+    # creates the ruby isolator for the specified subject
+    def create_isolation_for(subj)
+      imembers = @descriptor.instance_members
+      cmembers = @descriptor.class_members
+
+      klass = Object.const_set(class_name(subj), Class.new(subj))
+      klass.class_eval do
+
+        include Interception
+
+        # access to the proxied subject
+        def ___super___
+          isolation_context.instance
+        end
+
+        imembers.each do |mn|
+          mn = mn.name.to_s.to_sym
+          define_method mn do |*args|
+            b = nil
+            b = Proc.new { yield } if block_given?
+            isolation_context.send_message(mn, nil, *args, &b)
+          end
+        end
+
+        cmembers.each do |mn|
+          mn = mn.name.to_s.to_sym
+          define_cmethod mn do |*args|
+            b = nil
+            b = Proc.new { yield } if block_given?
+            isolation_context.send_class_message(mn, nil, *args, &b)
+          end
+        end
+
+
+      end
+
+      klass
+    end
+
+
+  end
+
+end

data/lib/caricature/messenger.rb

@@ -0,0 +1,57 @@
+module Caricature
+
+  # A base class to encapsulate method invocation
+  class Messenger
+
+    # the real instance of the isolated subject
+    # used to forward calls in partial mocks
+    attr_reader :instance
+
+    # the expecations that have been set for the isolation
+    attr_reader :expectations
+
+    # creates a new instance of this messaging strategy
+    def initialize(expectations, instance=nil)
+      @instance, @expectations = instance, expectations
+    end
+
+    # deliver the message to the receiving isolation
+    def deliver(method_name, return_type, *args, &b)
+      internal_deliver(:instance, method_name, return_type, *args, &b)
+    end
+
+    # deliver the message to class of the receiving isolation
+    def deliver_to_class(method_name, return_type, *args, &b)
+      internal_deliver(:class, method_name, return_type, *args, &b)
+    end
+
+    protected
+
+      # template method for looking up the expectation and/or returning a value
+      def internal_deliver(mode, method_name, return_type, *args, &b)
+        raise NotImplementedError.new("Override in an implementing class")
+      end
+
+  end
+
+  # Encapsulates sending messages to Ruby isolations
+  class RubyMessenger < Messenger
+
+    protected
+
+      # implementation of the template method for looking up the expectation and/or returning a value
+      def internal_deliver(mode, method_name, return_type, *args, &b)
+        exp = expectations.find(method_name, mode, *args)
+        if exp
+          res = instance.__send__(method_name, *args, &b) if exp.super_before?
+          res = exp.execute *args
+          res = instance.__send__(method_name, *args, &b) if !exp.super_before? and exp.call_super?
+          res
+        else
+          nil
+        end
+      end
+
+  end
+
+end

data/lib/caricature/method_call_recorder.rb

@@ -0,0 +1,130 @@
+module Caricature
+
+  # A recording of an argument variation.
+  # Every time a method is called with different arguments
+  # the method call recorder will create an ArgumentVariation
+  # these variations are used later in the assertion
+  # to verify against specific argument values
+  class ArgumentRecording
+
+    # contains the arguments of the recorded parameters
+    attr_accessor :args
+
+    # contains the block for the recorded parameters
+    attr_accessor :block
+
+    # the number of the call that has the following parameters
+    attr_accessor :call_number
+
+    # initializes a new instance of an argument recording.
+    # configures it with 1 call count and the args as an +Array+
+    def initialize(args=[], call_number=1, block=nil)
+      @args = args
+      @block = block
+      @call_number = call_number
+    end
+
+    # compares one argument variation to another.
+    # Also takes an array as an argument
+    def ==(other)
+      other = self.class.new(other) if other.respond_to?(:each)
+      return true if other.args.first == :any
+      other.args == args
+    end
+  end
+
+  # A recording that represents a method call
+  # it contains argument variations that can be matched too
+  class MethodCallRecording
+
+    # gets or sets the method name
+    attr_accessor :method_name
+
+    # gets or sets the amount of times the method was called
+    attr_accessor :count
+
+    # gets or sets the arguments for this method call
+    attr_accessor :args
+
+    # gets or sets the block for this method call
+    attr_accessor :block
+
+    # Initializes a new instance of a method call recording
+    # every time a method gets called in an isolated object
+    # this gets stored in the method call recorder
+    # It expects a +method_name+ at the very least.
+    def initialize(method_name, count=0)
+      @method_name = method_name
+      @count = count
+      @variations = []
+    end
+
+    # add args
+    def args
+      @variations
+    end
+
+    # indicates if it has an argument variation
+    def has_argument_variations?
+      @variations.size > 1
+    end
+
+    # add an argument variation
+    def add_argument_variation(args, block)
+      variation = find_argument_variations args
+      @variations << ArgumentRecording.new(args, @variations.size+1, block) if variation == []
+    end
+
+    # finds an argument variation that matches the provided +args+
+    def find_argument_variations(args)
+      return @variations if args.first == :any
+      @variations.select { |ar| ar.args == args }
+    end
+  end
+
+  # The recorder that will collect method calls and provides an interface for finding those recordings
+  class MethodCallRecorder
+
+    # gets the collection of method calls. This is a hash with the method name as key
+    attr_reader :method_calls
+
+
+    # Initializes a new instance of a method call recorder
+    # every time a method gets called in an isolated object
+    # this gets stored in the method call recorder
+    def initialize
+      @method_calls = {:instance => {}, :class => {} }      
+    end
+
+    # records a method call or increments the count of how many times this method was called.
+    def record_call(method_name, mode=:instance, *args, &block)
+      mn_sym = method_name.to_s.to_sym
+      method_calls[mode][mn_sym] ||= MethodCallRecording.new method_name
+      mc = method_calls[mode][mn_sym]
+      mc.count += 1
+      mc.add_argument_variation args, block 
+    end
+
+    # returns whether the method was actually called with the specified constraints
+    def was_called?(method_name, mode=:instance, *args)
+      mc = method_calls[mode][method_name.to_s.to_sym]
+      if mc    
+        return mc.find_argument_variations(args).first == args        
+      else
+        return !!mc
+      end
+    end
+
+#    # indexer that gives you access to the recorded method by method name
+#    def [](method_name)
+#      method_calls[:instance][method_name.to_s.to_sym]
+#    end
+
+    # returns the number of different methods that has been recorderd
+    def size
+      @method_calls.size
+    end
+  end
+
+
+end

data/lib/caricature/verification.rb

@@ -0,0 +1,43 @@
+module Caricature
+
+  # Describes a verification of a method call.
+  # This corresponds kind of to an assertion
+  class Verification
+
+    # Initializes a new instance of a +Verification+
+    def initialize(method_name, recorder, mode=:instance)
+      @method_name, @args, @any_args, @recorder, @mode = method_name, [], true, recorder, mode
+    end
+
+    # indicates whether this verification can be for any arguments
+    def any_args?
+      @any_args
+    end
+
+    # constrain this verification to the provided arguments
+    def with(*args)
+      @any_args = false unless args.first == :any
+      @args = args
+      self
+    end
+
+    # allow any arguments ignore the argument constraint
+    def allow_any_arguments
+      @any_args = true
+      self
+    end
+
+    # figure out if this argument variation matches the provided args.
+    def matches?(method_name, *args)
+      @method_name == method_name and any_args? or @args == args
+    end
+
+    # indicate that this method verification is successful
+    def successful?
+      a = any_args? ? [:any] : @args
+      @recorder.was_called?(@method_name, @mode, *a)
+    end
+
+  end
+
+end

data/lib/caricature.rb

@@ -0,0 +1,11 @@
+$: << File.dirname(__FILE__) + "/bin"
+#module Caricature
+#
+#  module Interception
+#
+#  end
+#
+#end
+
+require File.dirname(__FILE__) + '/core_ext/core_ext'
+require File.dirname(__FILE__) + '/caricature/isolation'

data/lib/core_ext/array.rb

@@ -0,0 +1,10 @@
+class Array
+
+  # Converts an array of values to a hash.
+  # the even indexes are the hash keys
+  # the odd indexes are the hash values
+  def to_h
+    h = Hash[*self]
+    h.symbolize_keys!    
+  end
+end

data/lib/core_ext/class.rb

@@ -0,0 +1,15 @@
+class Class
+
+  # removes all the modules from this class name
+  def demodulize
+    self.to_s.gsub(/^.*::/, '')
+  end
+
+  # indicates whether this type has a CLR type in its ancestors
+  def is_clr_type?
+    !self.to_clr_type.nil? ||
+            self.included_modules.any? {|mod| !mod.to_clr_type.nil? } ||
+            self.ancestors.reject {|mod| mod == Object }.any? { |mod| !mod.to_clr_type.nil? }
+  end
+
+end

data/lib/core_ext/core_ext.rb

@@ -0,0 +1,8 @@
+require File.dirname(__FILE__) + '/string'
+require File.dirname(__FILE__) + '/system/string'
+require File.dirname(__FILE__) + '/system/type'
+require File.dirname(__FILE__) + '/class'
+require File.dirname(__FILE__) + '/module'
+require File.dirname(__FILE__) + '/object'
+require File.dirname(__FILE__) + '/array'
+require File.dirname(__FILE__) + '/hash'

data/lib/core_ext/hash.rb

@@ -0,0 +1,13 @@
+class Hash
+
+  # Destructively convert all keys which respond_to?(:to_sym) to symbols. Works recursively if given nested hashes.
+  def symbolize_keys!
+    each do |k,v|
+      sym = k.respond_to?(:to_sym) ? k.to_sym : k
+      self[sym] = Hash === v ? v.symbolize_keys! : v
+      delete(k) unless k == sym
+    end
+    self
+  end
+
+end

data/lib/core_ext/module.rb

@@ -0,0 +1,15 @@
+class Module
+
+  # Removes all but the containing modules from this module's name
+  def demodulize
+    self.to_s.gsub(/^.*::/, '')
+  end
+
+  # indicates whether this type has a CLR type in its ancestors
+  def is_clr_type?
+    !self.to_clr_type.nil? ||
+            self.included_modules.any? {|mod| !mod.to_clr_type.nil? } ||
+            self.ancestors.any? { |mod| !mod.to_clr_type.nil? }
+  end
+
+end

data/lib/core_ext/object.rb

@@ -0,0 +1,19 @@
+class Object
+
+  # returns whether this object is a clr_type.
+  # if it has a CLR type in one of its ancestors
+  def is_clr_type?
+    self.class.is_clr_type?
+  end
+
+  # returns the clr type of this object if any
+  def to_clr_type
+    self.class.to_clr_type
+  end
+
+  # defines a class method on an object
+  def define_cmethod(name, &blk)
+    (class << self; self; end).instance_eval { define_method name, &blk }
+  end
+  
+end

data/lib/core_ext/string.rb

@@ -0,0 +1,17 @@
+class String
+
+  # converts a camel cased word to an underscored word
+  def underscore
+    self.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+  end
+
+  # Gets the constant when it is defined that corresponds to this string
+  def classify
+    Object.const_get self
+  end
+  
+end

data/lib/core_ext/system/string.rb

@@ -0,0 +1,21 @@
+module System
+
+  class String
+
+    # converts a camel cased word to an underscored word
+    def underscore
+      self.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+    end
+
+    # Gets the constant when it is defined that corresponds to this string
+    def classify
+      Object.const_get self
+    end
+    
+  end
+  
+end

data/lib/core_ext/system/type.rb

@@ -0,0 +1,21 @@
+module System
+
+  class Type
+
+    # collects all the methods defined on an interface and its parents
+    def collect_interface_methods
+      iface_methods = []
+      iface_methods += self.get_interfaces.collect { |t| t.collect_interface_methods }
+      self.get_methods + iface_methods.flatten
+    end
+
+    # collects the properties defined on an interface an its parents
+    def collect_interface_properties
+      iface_properties = []
+      iface_properties += self.get_interfaces.collect { |t| t.collect_interface_properties }
+      self.get_properties + iface_properties.flatten
+    end
+
+  end
+
+end