caricature 0.3.1 → 0.5.0

data/lib/caricature/clr/descriptor.rb

@@ -0,0 +1,55 @@
+module Caricature
+
+  # describes clr interfaces.
+  # Because CLR interfaces can't have static members this descriptor does not collect any class members
+  class ClrInterfaceDescriptor < TypeDescriptor
+
+    # collects instance members on this interface
+    # it will collect properties, methods and property setters
+    def initialize_instance_members_for(klass)
+      clr_type = klass.to_clr_type
+
+      properties = clr_type.collect_interface_properties
+      methods = clr_type.collect_interface_methods
+
+      @instance_members += methods.collect { |mi| MemberDescriptor.new(mi.name.underscore, mi.return_type) }
+      @instance_members += properties.collect { |pi| MemberDescriptor.new(pi.name.underscore, pi.property_type) }
+      @instance_members += properties.select { |pi| pi.can_write }.collect { |pi| MemberDescriptor.new("#{pi.name.underscore}=", nil) }
+    end
+
+    # this method is empty because an interface can't have static members
+    def initialize_class_members_for(klass); end
+
+  end
+
+
+  # Describes a CLR class type. it collects the properties and methods on an instance as well as on a static level
+  class ClrClassDescriptor < TypeDescriptor
+
+    # collects all the instance members of the provided CLR class type
+    def initialize_instance_members_for(klass)
+      clr_type = klass.to_clr_type
+
+      methods = Workarounds::ReflectionHelper.get_instance_methods(clr_type)
+      properties = Workarounds::ReflectionHelper.get_instance_properties(clr_type)
+
+      @instance_members += methods.collect { |mi| MemberDescriptor.new(mi.name.underscore, mi.return_type) }
+      @instance_members += properties.collect { |pi| MemberDescriptor.new(pi.name.underscore, pi.property_type) }
+      @instance_members += properties.select{|pi| pi.can_write }.collect { |pi| MemberDescriptor.new("#{pi.name.underscore}=", nil) }
+    end
+
+    # collects all the static members of the provided CLR class type
+    def initialize_class_members_for(klass)
+      clr_type = klass.to_clr_type
+
+      methods = Workarounds::ReflectionHelper.get_class_methods(clr_type)
+      properties = Workarounds::ReflectionHelper.get_class_properties(clr_type)
+
+      @class_members += methods.collect  { |mi| MemberDescriptor.new(mi.name.underscore, mi.return_type, false) }
+      @class_members += properties.collect { |pi| MemberDescriptor.new(pi.name.underscore, pi.property_type, false) }
+      @class_members += properties.select{|pi| pi.can_write }.collect { |pi| MemberDescriptor.new("#{pi.name.underscore}=", nil, false) }
+    end
+
+  end
+
+end

data/lib/caricature/clr/isolation.rb

@@ -0,0 +1,33 @@
+module Caricature
+
+  class Isolation
+
+    class << self
+
+      # Creates an isolation object complete with proxy and method call recorder
+      # It works out which isolation it needs to create and provide and initializes the
+      # method call recorder
+      def for(subject, recorder = MethodCallRecorder.new, expectations = Expectations.new)
+        context = IsolatorContext.new subject, recorder, expectations
+        isolation_strategy = subject.is_clr_type? ? get_clr_isolation_strategy(subject) : RubyIsolator
+
+        isolator = isolation_strategy.for context
+        isolation = new(isolator, context)
+        isolator.isolation
+      end
+
+      private
+
+        # decides which startegy to use for mocking a CLR object.
+        # When the provided subject is an interface it will return a +ClrInterfaceIsolator+
+        # otherwise it will return a +ClrIsolator+
+        def get_clr_isolation_strategy(subject)
+          return ClrInterfaceIsolator if subject.respond_to? :class_eval and !subject.respond_to? :new
+          ClrIsolator
+        end
+    end
+    
+
+  end
+
+end

data/lib/caricature/clr/isolator.rb

@@ -0,0 +1,112 @@
+module Caricature
+
+  # A proxy to CLR objects that records method calls.
+  # this implements all the public instance methods of the class when you use it in ruby code
+  # When you use it in a CLR class you're bound to CLR rules and it only overrides the methods
+  # that are marked as virtual. We also can't isolate static or sealed types at the moment.
+  class ClrIsolator < Isolator
+
+
+    # Implementation of the template method that creates
+    # an isolator for a class defined in a CLR language.
+    def initialize(context)
+      super
+      instance = nil
+      sklass = context.subject
+      unless context.subject.respond_to?(:class_eval)
+        sklass = context.subject.class
+        instance = context.subject
+      end
+      @descriptor = ClrClassDescriptor.new sklass
+      build_isolation sklass, (instance || sklass.new)
+    end
+
+    # initializes the messaging strategy for the isolator
+    def initialize_messenger
+      @context.messenger = ClrClassMessenger.new @context.expectations, @subject
+    end
+
+    # builds the Isolator class for the specified subject
+    def  create_isolation_for(subj)
+      members = @descriptor.instance_members
+      class_members = @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
+
+        members.each do |mem|
+          nm = mem.name.to_s.to_sym
+          define_method nm do |*args|
+            b = nil
+            b = Proc.new { yield } if block_given?
+            isolation_context.send_message(nm, mem.return_type, *args, &b)
+          end unless nm == :to_string
+        end
+
+        class_members.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
+
+  # An +Isolator+ for CLR interfaces.
+  # this implements all the methods that are defined on the interface.
+  class ClrInterfaceIsolator < Isolator
+
+    # Implementation of the template method that creates
+    # an isolator for an interface defined in a CLR language.
+    def initialize(context)
+      super
+      sklass = context.subject
+      @descriptor = ClrInterfaceDescriptor.new sklass
+      build_isolation sklass
+    end
+
+    # initializes the messaging strategy for the isolator
+    def initialize_messenger
+      @context.messenger = ClrInterfaceMessenger.new @context.expectations
+    end
+
+    # builds the actual +isolator+ for the CLR interface
+    def create_isolation_for(subj)
+      proxy_members = @descriptor.instance_members
+
+      klass = Object.const_set(class_name(subj), Class.new)
+      klass.class_eval do
+
+        include subj
+        include Interception
+
+        proxy_members.each do |mem|
+          nm = mem.name.to_s.to_sym
+          define_method nm do |*args|
+            b = nil
+            b = Proc.new { yield } if block_given?
+            isolation_context.send_message(nm, mem.return_type, *args, &b)
+          end
+        end
+
+      end
+
+      klass
+    end
+  end
+
+end

data/lib/caricature/clr/messenger.rb

@@ -0,0 +1,46 @@
+module Caricature
+
+  # Encapsulates sending messages to CLR class or instance isolations
+  class ClrClassMessenger < Messenger
+
+    protected
+    
+      # deliver the message to the receiving isolation
+      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
+          rt = nil
+          is_value_type = return_type && return_type != System::Void.to_clr_type && return_type.is_value_type
+          rt = System::Activator.create_instance(return_type) if is_value_type
+          rt
+        end
+      end
+
+  end
+
+  # Encapsulates sending messages to CLR interface isolations
+  class ClrInterfaceMessenger < Messenger
+
+    protected
+
+      # deliver the message to the receiving isolation
+      def internal_deliver(mode, method_name, return_type, *args, &b)
+        exp = expectations.find(method_name, mode, *args)
+        if exp
+          res = exp.execute *args
+          res
+        else
+          rt = nil
+          rt = System::Activator.create_instance(return_type) if return_type && return_type != System::Void.to_clr_type && return_type.is_value_type
+          rt
+        end
+      end
+
+  end
+
+end

data/lib/caricature/clr.rb

@@ -0,0 +1,6 @@
+load_assembly 'Workarounds, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'
+
+require File.dirname(__FILE__) + "/clr/descriptor"
+require File.dirname(__FILE__) + "/clr/messenger"
+require File.dirname(__FILE__) + "/clr/isolator"
+require File.dirname(__FILE__) + "/clr/isolation"

data/lib/caricature/descriptor.rb

@@ -0,0 +1,74 @@
+module Caricature
+
+  # Describes a class/type so it can be proxied more easily
+  # This is the base class from which other more specialised descriptors can be
+  # used to provide the metadata need to generate the proxy classes
+  class TypeDescriptor
+
+    # Gets the instance members of the described type/class
+    attr_reader :instance_members
+
+    # Gets the class members for the described type/class
+    attr_reader :class_members
+
+    # initializes a new instance of a type descriptor
+    def initialize(klass)
+      @instance_members = []
+      @class_members = []
+
+      unless klass == :in_unit_test_for_class
+        initialize_instance_members_for klass
+        initialize_class_members_for klass
+      end
+    end
+
+    # collects the instance members of the provided type
+    def initialize_instance_members_for(klass)
+      raise NotImplementedError.new("Override in implementing class")
+    end
+
+    # collects the class members of the provided type
+    def initialize_class_members_for(klass)
+      raise NotImplementedError.new("Override in implementing class")
+    end
+  end
+
+  # Describes a member of a class
+  # this contains the metadata needed to generate the member
+  # and perhaps a default value for the property type if necessary
+  class MemberDescriptor
+
+    # the return type of this member
+    attr_reader :return_type
+
+    # the name of this member
+    attr_reader :name
+
+    # initializes a nem instance of member descriptor
+    def initialize(name, return_type=nil, is_instance_member=true)
+      @name, @return_type, @instance_member = name, return_type, is_instance_member
+    end
+
+    # indicates whether this member is a class member or an instance member
+    def instance_member?
+      @instance_member
+    end
+
+  end
+
+  # Describes a ruby object.
+  class RubyObjectDescriptor < TypeDescriptor
+
+    # collects all the members that are defined by this class
+    def initialize_instance_members_for(klass)
+      @instance_members += klass.instance_methods(false).collect { |mn| MemberDescriptor.new(mn) }
+    end
+
+    # collects all the members that aren't a member of Object.singleton_methods
+    def initialize_class_members_for(klass)
+      @class_members += klass.methods(false).collect { |mn| MemberDescriptor.new(mn) }
+    end
+
+  end  
+
+end

data/lib/caricature/expectation.rb

@@ -0,0 +1,159 @@
+module Caricature
+
+  # A collection of expectations with some methods to make it easier to work with them.
+  # It allows you to add and find expectations based on certain criteria.
+  class Expectations
+
+    #initializes a new empty instance of the +Expectation+ collection
+    def initialize
+      @instance_expectations = []
+      @class_expectations = []
+    end
+
+    # Adds an expectation to this collection. From then on it can be found in the collection.
+    def add_expectation(expectation, mode=:instance)
+      @instance_expectations << expectation unless mode == :class
+      @class_expectations << expectation if mode == :class
+    end
+
+    # Finds an expectation in the collection. It matches by +method_name+ first.
+    # Then it tries to figure out if you care about the arguments. You can say you don't care by providing
+    # the symbol +:any+ as first argument to this method. When you don't care the first match is being returned
+    # When you specify arguments other than +:any+ it will try to match the specified arguments in addition
+    # to the method name. It will then also return the first result it can find.
+    def find(method_name, mode=:instance, *args)
+      expectations = mode == :class ? @class_expectations : @instance_expectations
+      candidates = expectations.select { |exp| exp.method_name.to_s.to_sym == method_name.to_s.to_sym }
+      is_single = args.empty? || args.first == :any || (candidates.size == 1 && candidates.first.any_args?)
+      return candidates.first if is_single
+
+      second_pass = candidates.select {|exp| exp.args == args }
+      second_pass.first
+    end
+
+  end
+
+  # contains the syntax for building up an expectation
+  # This is shared between the +ExpecationBuilder+ and the +Expectation+
+  module ExpectationSyntax
+    # tell the expection which arguments it needs to respond to
+    # there is a magic argument here +any+ which configures
+    # the expectation to respond to any arguments
+    def with(*args)
+      @any_args = false unless args.first == :any
+      @args = args
+      self
+    end
+
+    # tell the expectation it nees to return this value or the value returned by the block
+    # you provide to this method.
+    def return(value=nil)
+      @return_value = value
+      @return_value ||= yield if block_given?
+      self
+    end
+
+    # tell the expectation it needs to raise an error with the specified arguments
+    def raise(*args)
+      @error_args = args
+      self
+    end
+
+    # tell the expecation it needs to call the super before the expectation exectution
+    def super_before
+      @super = :before
+    end
+
+    # tell the expectation it needs to call the super after the expecation execution
+    def super_after
+      @super = :after
+    end
+
+    # indicates whether this expectation should match with any arguments
+    # or only for the specified arguments
+    def any_args?
+      @any_args
+    end
+  end
+
+  # A description of an expectation.
+  # An expectation has the power to call the proxy method or completely ignore it
+  class Expectation
+
+    include ExpectationSyntax
+
+    # gets the method_name to which this expectation needs to listen to
+    attr_reader :method_name
+
+    # the arguments that this expectation needs to be constrained by
+    attr_reader :args
+
+    # the error_args that this expectation will raise an error with
+    attr_reader :error_args
+
+    # the value that this expecation will return when executed
+    attr_reader :return_value
+
+    # indicator for the mode to call the super +:before+, +:after+ and +nil+
+    attr_reader :super
+
+    # Initializes a new instance of an expectation
+    def initialize(method_name, args, error_args, return_value, super_mode)
+      @method_name, @args, @error_args, @return_value, @super =
+              method_name, args, error_args, return_value, super_mode
+      @any_args = true
+    end
+
+    # indicates whether this expecation will raise an event.
+    def has_error_args?
+      !@error_args.nil?
+    end
+
+    # indicates whether this expectation will return a value.
+    def has_return_value?
+      !@return_value.nil?
+    end
+
+    # call the super before the expectation
+    def super_before?
+      @super == :before
+    end
+
+    # indicates whether super needs to be called somewhere
+    def call_super?
+      !@super.nil?
+    end
+    
+    # executes this expectation with its configuration
+    def execute(*margs)
+      ags = any_args? ? (margs.empty? ? :any : margs) : args
+      raise *@error_args if has_error_args?
+      return return_value if has_return_value?
+      nil
+    end
+  end
+
+  # Constructs the expecation object.
+  # Used as a boundary between the definition and usage of the expectation
+  class ExpectationBuilder
+
+    include ExpectationSyntax
+
+    # initialises a new instance of the expectation builder
+    # this builder is passed into the block to allow only certain
+    # operations in the block.
+    def initialize(method_name)
+      @method_name, @return_value, @super, @block, @error_args, @args, @any_args = 
+              method_name, nil, nil, nil, nil, [], true
+    end
+
+
+
+    # build up the expectation with the provided arguments
+    def build
+      Expectation.new @method_name, @args, @error_args, @return_value, @super
+    end
+
+  end
+
+end

data/lib/caricature/isolation.rb

@@ -0,0 +1,146 @@
+require File.dirname(__FILE__) + '/isolator'
+require File.dirname(__FILE__) + '/method_call_recorder'
+require File.dirname(__FILE__) + '/expectation'
+require File.dirname(__FILE__) + '/verification'
+
+# Caricature - Bringing simple mocking to the DLR
+# ===============================================
+#
+# This project aims to make interop between IronRuby objects and .NET objects easier.
+# The idea is that it integrates nicely with bacon and later rspec and that it transparently lets you mock ironruby ojbects
+# as well as CLR objects/interfaces.
+# Caricature handles interfaces, interface inheritance, CLR objects, CLR object instances, Ruby classes and instances of Ruby classes.
+#
+# From the start I wanted to do away with names like mock, stub, record, replay, verify etc.
+# Instead I took the advice from Roy Osherhove and went with a name of Isolation for creating a mock.
+#
+# An Isolation will create what in Rhino.Mocks would be called a DynamicMock (but can be a partial too) :)
+# In Moq it would be the Loose mocking strategy.
+#
+# The naming of the methods for creating mocks is the one that JP Boodhoo proposed WhenToldTo and WasToldTo.
+# To specify a stub/expectation on an isolation you have one and only one way of doing that with the method called when_receiving.
+# Then only if you're interested in asserting if a method has been called you can use the did_receive? method for this.
+#
+#
+#     isolation = Isolation.for(Ninja)
+#     isolation.when_receiving(:attack) do |exp|
+#       exp.with(:shuriken)
+#       exp.return(3)
+#     end
+#
+#     Battle.new(mock)
+#     battle.combat
+#
+#     isolation.did_receive?(:attack).should.be.true?
+#
+#
+# It may be very important to note that when you're going to be isolating CLR classes to be used in other CLR classes
+# you still need to obide by the CLR rules. That means if you want to redefine a method you'll need to make sure it's
+# marked as virtual. Static types are still governed by static type rules.  I'm working on a solution around those
+# problems but for the time being this is how it has to be.
+module Caricature
+
+  # The context for an isolator. This contains the +subject+, +recorder+, +expectations+ and +messenger+
+  IsolatorContext = Struct.new(:subject, :recorder, :expectations, :messenger)
+
+  # Instead of using confusing terms like Mocking and Stubbing which is basically the same. Caricature tries
+  # to unify those concepts by using a term of *Isolation*.
+  # When you're testing you typically want to be in control of what you're testing. To do that you isolate
+  # dependencies and possibly define return values for methods on them.
+  # At a later stage you might be interested in which method was called, maybe even with which parameters
+  # or you might be interested in the amount of times it has been called.
+  class Isolation
+
+    # the real instance of the isolated subject
+    # used to forward calls in partial mocks
+    attr_reader :instance
+
+    # the method call recorder
+    attr_reader :recorder
+
+    # the expecations set for this isolation
+    attr_reader :expectations
+
+    # Initializes a new instance of this isolation.
+    def initialize(isolator, context)
+      @instance = isolator.subject
+      @recorder = context.recorder
+      @messenger = context.messenger
+      @expectations = context.expectations
+      isolator.isolation.class.instance_variable_set("@___context___", self)
+    end
+
+    # record and send the message to the isolation.
+    # takes care of following expectations rules when sending messages.
+    def send_message(method_name, return_type, *args, &b)
+      recorder.record_call method_name, :instance, *args, &b
+      @messenger.deliver(method_name, return_type, *args, &b)
+    end
+
+    # record and send the message to the isolation.
+    # takes care of following expectations rules when sending messages.
+    def send_class_message(method_name, return_type, *args, &b)
+      recorder.record_call method_name, :class, *args, &b
+      @messenger.deliver_to_class(method_name, return_type, *args, &b)
+    end
+
+    # builds up an expectation for an instance method, allows for overriding the result returned by the method
+    def create_override(method_name, &block)
+      internal_create_override method_name, :instance, &block
+    end
+
+    # builds up an expectation for a class method, allows for overriding the result returned by the class method
+    def create_class_override(method_name, &block)
+      puts "creating override"
+      internal_create_override method_name, :class, &block      
+    end
+
+    # asserts whether the method has been called for the specified configuration
+    def verify(method_name, &block)
+      internal_verify method_name, :instance, &block
+    end
+
+    # asserts whether the method has been called for the specified configuration
+    def class_verify(method_name, &block)
+      internal_verify method_name, :class, &block
+    end
+
+    class << self
+
+      # Creates an isolation object complete with proxy and method call recorder
+      # It works out which isolation it needs to create and provide and initializes the
+      # method call recorder
+      def for(subject, recorder = MethodCallRecorder.new, expectations = Expectations.new)
+        context = IsolatorContext.new subject, recorder, expectations
+
+        isolator = RubyIsolator.for context
+        isolation = new(isolator, context)
+        isolator.isolation
+      end
+            
+    end
+
+    protected
+
+    def internal_create_override(method_name, mode=:instance, &block)
+      builder = ExpectationBuilder.new method_name
+      block.call builder unless block.nil?
+      exp = builder.build
+      expectations.add_expectation exp, mode
+      exp
+    end
+
+    def internal_verify(method_name, mode=:instance, &block)
+      verification = Verification.new(method_name, recorder, mode)
+      block.call verification unless block.nil?
+      verification
+    end
+  end
+
+  # +Mock+ is a synonym for +Isolation+ so you can still use it if you're that way inclined
+  Mock = Isolation unless defined? Mock
+
+  # +Stub+ is a synonym for +Isolation+ so you can still use it if you're that way inclined
+  Stub = Isolation unless defined? Stub
+
+end