bond-spy 0.1.0

data/lib/bond/spec_helper.rb

@@ -0,0 +1,32 @@
+require_relative '../bond'
+
+# This file defines a shared context which should be included
+# into any RSpec test using Bond via:
+#
+#     include_context :bond
+#
+# within your `describe` statement. It makes the `bond` variable
+# available for you to use (for e.g. `bond.spy` and `bond.deploy_agent`)
+# and automatically initializes Bond to be used in your tests.
+#
+# You may pass all of the same arguments to the `include_context` statement
+# that you can to {Bond#start_test}. For example, to set the test name:
+#
+#     include_context :bond, test_name: 'my_test_name'
+#
+
+shared_context :bond do |**settings|
+
+  let(:bond) { Bond.instance }
+
+  before :each do |example|
+    bond.start_test(example, **settings)
+    true
+  end
+
+  after :each do
+    if bond.send(:finish_test) == :bond_fail
+      fail('BOND_FAIL. Pass BOND_RECONCILE=[kdiff3|console|accept] environment variable to reconcile the observations.')
+    end
+  end
+end

data/lib/bond/targetable.rb

@@ -0,0 +1,210 @@
+# Module which should be `extend`ed into any class or module which you would like
+# to spy on, either via {Bond#spy} or via a {#spy_point}. Within that class/module,
+# the method {#bond} is available to access Bond, i.e. `bond.spy` and `bond.spy_point`.
+#
+# For example, if you would like to spy on MyClass, you would do this:
+#
+#     class MyClass
+#       extend BondTargetable
+#
+#       bond.spy_point(spy_point_name: 'my_name')
+#       def method_to_spy_on
+#         ...
+#         bond.spy(intermediate_state: state_variable)
+#         ...
+#       end
+#     end
+#
+module BondTargetable
+
+  protected
+
+  # Keeps track of the arguments to the last spy_point annotation
+  @__last_annotation_args = nil
+
+  # The annotation which indicates that a method should be spied on. Use like:
+  #
+  #     bond.spy_point(options...)
+  #     def method_being_spied_on()
+  #
+  # This is safe to use in production code; it will have effects only if the function
+  # {Bond#start_test} has been called to initialize Bond.
+  # This will automatically spy every call to the `method_being_spied_on`. By default,
+  # all supplied arguments are logged. For normal arguments and keyword arguments,
+  # they will be logged as `argument_name: value`. For variable arguments,
+  # they are logged as `anonymous_parameter{arg_num}: value` (e.g. `anonymous_parameter0: 'foo'`).
+  # If the call to {Bond#spy} returns anything other than `:agent_result_none` or
+  # `:agent_result_continue` (i.e. through the use of {Bond#deploy_agent}), the spied
+  # method will never be called and the result will be returned in its place. Else, the
+  # method is called as normal.
+  #
+  # @param spy_point_name [String] If supplied, overrides the default spy point name, which is
+  #     `Class.method_name` for class methods and `Class#method_name` for other methods.
+  # @param require_agent_result [Boolean] If true, you *must* supply a return value via
+  #     {Bond#deploy_agent} during testing, else an error is thrown.
+  # @param excluded_keys [String, Symbol, Array<String, Symbol>] An array of key/argument
+  #     names to exclude from the spy. Can be useful if you don't care about the value of some argument.
+  # @param spy_result [Boolean] If true, spy on the return value. The spy point name will be
+  #     `{spy_point_name}.result` and the key name will be `result`.
+  # @api public
+  def spy_point(spy_point_name: nil, require_agent_result: false, excluded_keys: [],
+                spy_result: false)
+    @__last_annotation_args = {
+        spy_point_name: spy_point_name,
+        require_agent_result: require_agent_result,
+        # Allow for a single key or an array of them, and map to_s in case they were passed as symbols
+        excluded_keys: [*excluded_keys].map(&:to_s),
+        spy_result: spy_result
+    }
+  end
+
+  # Simple method to access Bond from within a BondTargetable class/module.
+  # @api public
+  def bond
+    PassthroughClass.new(self)
+  end
+
+  public
+
+  # Hook into method addition, if it was preceded by a call to #spy_point then spy on it.
+  # @param name Name of the method being added
+  # @private
+  def method_added(name)
+    super
+    return if @__last_annotation_args.nil?
+    annotation_args = @__last_annotation_args
+    @__last_annotation_args = nil
+
+    orig_method = instance_method(name)
+
+    if private_method_defined?(name)
+      visibility = :private
+    elsif protected_method_defined?(name)
+      visibility = :protected
+    else
+      visibility = :public
+    end
+
+    point_name = annotation_args.delete(:spy_point_name)
+    point_name = point_name_from_method(orig_method) if point_name.nil?
+
+    this = self
+    define_method(name) do |*args, **kwargs, &blk|
+      this.send(:bond_interceptor, orig_method.bind(self), point_name, annotation_args, *args, **kwargs, &blk)
+    end
+
+    case visibility
+      when :protected
+        protected name
+      when :private
+        private name
+    end
+  end
+
+  # Hook into singleton method addition, if it was preceded by a call to #spy_point then spy on it.
+  # @param name Name of the method being added
+  # @private
+  def singleton_method_added(name)
+    super
+    return if @__last_annotation_args.nil?
+    annotation_args = @__last_annotation_args
+    @__last_annotation_args = nil
+
+    orig_method = method(name)
+
+    point_name = annotation_args.delete(:spy_point_name)
+    point_name = point_name_from_method(orig_method) if point_name.nil?
+
+    this = self
+    this.define_singleton_method(name) do |*args, **kwargs, &blk|
+      this.send(:bond_interceptor, orig_method, point_name, annotation_args, *args, **kwargs, &blk)
+    end
+
+  end
+
+  private
+
+  # Method that gets wrapped around methods being spied on. Should never be called directly.
+  #
+  # @param method [Method] The method that is being spied on
+  # @param spy_point_name [String] The name of the spy point
+  # @param options [Hash] Hash of options, which should be any of the arguments to {#spy_point}
+  #                except for `spy_point_name`
+  def bond_interceptor(method, spy_point_name, options, *args, **kwargs, &blk)
+    return kwargs.empty? ? method.call(*args, &blk) : method.call(*args, **kwargs, &blk) unless Bond.instance.active?
+    param_list = method.parameters.select { |type, _| type == :opt || type == :req }.map { |_, name| name }
+
+    observation = {}
+    anon_param_cnt = 0
+    args.zip(param_list) do |value, name|
+      if name.nil?
+        observation["anonymous_parameter#{anon_param_cnt}".to_sym] = value
+      else
+        observation[name] = value unless options[:excluded_keys].include?(name.to_s)
+      end
+    end
+    kwargs.each do |name, value|
+      observation[name] = value unless options[:excluded_keys].include?(name.to_s)
+    end
+
+    ret = Bond.instance.spy(spy_point_name, observation)
+    if options[:require_agent_result] && ret == :agent_result_none
+      raise "#{spy_point_name} requires mocking but received :agent_result_none"
+    end
+
+    if ret == :agent_result_none || ret == :agent_result_continue
+      if kwargs.empty?
+        ret = method.call(*args, &blk)
+      else
+        ret = method.call(*args, **kwargs, &blk)
+      end
+    end
+    Bond.instance.spy("#{spy_point_name}.result", result: ret) if options[:spy_result]
+    ret
+  end
+
+  # Extract the default point name from the method object, which is `Class.method_name`
+  # for class methods and `Class#method_name` for other methods.
+  def point_name_from_method(method)
+    method.inspect.to_s.sub(/#<[^:]+: ([^>]+)>/, '\1')
+  end
+
+  # A class that acts as if it was Bond by passing through all method calls
+  # *except* for `spy_point`, which it sends back to whatever object was passed
+  # in upon initialization (which should be something that `extend`s BondTargetable).
+  # This is used since calls to `spy_point` should be directed to BondTargetable
+  # and other calls should be directed to Bond, but we want this to happen
+  # transparently to the end-user.
+  # @private
+  class PassthroughClass
+    def initialize(parent)
+      @parent = parent
+    end
+
+    def spy_point(**kwargs)
+      @parent.send(:spy_point, **kwargs)
+    end
+
+    def method_missing(meth, *args)
+      Bond.instance.send(meth, *args)
+    end
+  end
+
+  # A module to export the `bond` method as an instance method in addition to
+  # a class method (which it will already appear as due to the `extend` statement)
+  # @private
+  module BondTargetableInstanceMethods
+    protected
+    def bond
+      PassthroughClass.new(self)
+    end
+  end
+
+  public
+  # Used to mix in BondTargetableInstanceMethods, allowing for `bond` to appear as both
+  # an instance method and a class method.
+  # @private
+  def self.extended(base)
+    base.include(BondTargetableInstanceMethods)
+  end
+end

data/lib/bond/version.rb

@@ -0,0 +1,3 @@
+class Bond
+  VERSION = '0.1.0'
+end

data/spec/bond_spec.rb

@@ -0,0 +1,158 @@
+require 'spec_helper'
+
+describe Bond do
+  include_context :bond
+
+  context 'without any agents' do
+    it 'should correctly log some normal arguments with a spy point name' do
+      bond.spy('my_point_name', spy_key: 1, spy_key_2: 'string value', spy_key_3: 1.4)
+      bond.spy('second_point', spy_key: 'string value 2')
+    end
+
+    it 'should correctly log some normal arguments without a spy point name' do
+      bond.spy(spy_key: 1, spy_key_2: 'string value', spy_key_3: 1.4)
+      bond.spy(spy_key: 'string value 2')
+    end
+
+    it 'should correctly log nested hashes and arrays with hash sorting' do
+      bond.spy(key1: {h1key1: %w(hello world), h1key2: 'hi'},
+               key2: [{key2: 'foo', key3: 'bar', key1: 'baz'}, 'array3', 'array2'])
+      bond.spy('point_name', key3: {key2: 'foo', key1: 'bar', key3: {hkey: 'hello world'}},
+               key1: 'value 1')
+    end
+  end
+
+  context 'with agents' do
+    it 'should work with multiple agents for different spy points' do
+      bond.deploy_agent('my_point_1', result: 'mock result')
+      bond.deploy_agent('my_point_2', result: 'mock result 2')
+
+      bond.spy('point_1_return', return_value: bond.spy('my_point_1'))
+      bond.spy('point_2_return', return_value: bond.spy('my_point_2'))
+      bond.spy('point_1_return_2', return_value: bond.spy('my_point_1'))
+    end
+
+    context 'with filters' do
+      it 'should respect single key/value filters of all types' do
+        bond.deploy_agent('my_point', obs_name: 'value', result: 'mocked')
+        bond.spy(result: bond.spy('my_point', obs_name: 'value'))
+        bond.spy(result: bond.spy('my_point', obs_name: 'not value'))
+
+        bond.deploy_agent('my_point_eq', obs_name__eq: 'value', result: 'mocked')
+        bond.spy(result: bond.spy('my_point_eq', obs_name: 'value'))
+        bond.spy(result: bond.spy('my_point_eq', obs_name: 'not value'))
+
+        bond.deploy_agent('my_point_exact', obs_name__exact: 'value', result: 'mocked')
+        bond.spy(result: bond.spy('my_point_exact', obs_name: 'value'))
+        bond.spy(result: bond.spy('my_point_exact', obs_name: 'not value'))
+
+        bond.deploy_agent('my_point_startswith', obs_name__startswith: 'value', result: 'mocked')
+        bond.spy(result: bond.spy('my_point_startswith', obs_name: 'value'))
+        bond.spy(result: bond.spy('my_point_startswith', obs_name: 'not value'))
+        bond.spy(result: bond.spy('my_point_startswith', obs_name: 'value not'))
+
+        bond.deploy_agent('my_point_endswith', obs_name__endswith: 'value', result: 'mocked')
+        bond.spy(result: bond.spy('my_point_endswith', obs_name: 'value'))
+        bond.spy(result: bond.spy('my_point_endswith', obs_name: 'not value'))
+        bond.spy(result: bond.spy('my_point_endswith', obs_name: 'value not'))
+
+        bond.deploy_agent('my_point_contains', obs_name__contains: 'value', result: 'mocked')
+        bond.spy(result: bond.spy('my_point_contains', obs_name: 'value'))
+        bond.spy(result: bond.spy('my_point_contains', obs_name: 'not value'))
+        bond.spy(result: bond.spy('my_point_contains', obs_name: 'value not'))
+        bond.spy(result: bond.spy('my_point_contains', obs_name: 'not value not'))
+        bond.spy(result: bond.spy('my_point_contains', obs_name: 'foobar'))
+      end
+
+      it 'should respect function filters' do
+        bond.deploy_agent('my_point', filter: lambda { |obs| obs[:my_key].even? }, result: 'mocked')
+        bond.spy(result: bond.spy('my_point', my_key: 5))
+        bond.spy(result: bond.spy('my_point', my_key: 10))
+      end
+
+      it 'should override old agents with newer agents unless they are filtered out' do
+        bond.deploy_agent('my_point', result: 'first mock')
+        bond.deploy_agent('my_point', result: 'second mock')
+        bond.deploy_agent('my_point', obs_name: 'foobar', result: 'third mock')
+
+        bond.spy(result: bond.spy('my_point'))
+        bond.spy(result: bond.spy('my_point', obs_name: 'foobar'))
+        bond.spy(result: bond.spy('my_point', obs_name: 'baz'))
+      end
+
+      it 'should respect combinations of filters' do
+        bond.deploy_agent('my_point', result: 'mocked',
+                          filter: lambda { |obs| obs.has_key?(:req_key) },
+                          req_key2: 'value', req_key3__contains: 'value')
+        bond.spy(result: bond.spy('my_point', req_key: 'foo', req_key2: 'bar', req_key3: 'value'))
+        bond.spy(result: bond.spy('my_point', req_key: 'foo', req_key2: 'value', req_key3: 'foovaluebar'))
+        bond.spy(result: bond.spy('my_point', req_key: 'foo', req_key2: 'value', req_key3: 'lacking'))
+        bond.spy(result: bond.spy('my_point', req_key2: 'value', req_key3: 'value'))
+      end
+    end
+
+    it 'should call the function passed as result if it is callable' do
+      mocked_value = 1
+      bond.deploy_agent('my_point', result: lambda { |_| mocked_value += 1 }, obs_name: 'foo')
+      bond.spy(result: bond.spy('my_point', obs_name: 'foo'))
+      bond.spy(result: bond.spy('my_point', obs_name: 'bar'))
+      bond.spy(result: bond.spy('my_point', obs_name: 'foo'))
+    end
+
+    it 'should throw an exception if specified by agent' do
+      bond.deploy_agent('my_point', exception: TypeError.new('TypeError exception!'))
+      begin
+        bond.spy('my_point')
+      rescue TypeError => e
+        bond.spy('rescue_point', except: e.to_s)
+      end
+    end
+
+    it 'should throw the result of the value passed to exception if callable' do
+      bond.deploy_agent('my_point', exception: lambda { |obs| ArgumentError.new(obs[:key]) })
+      begin
+        bond.spy('my_point', key: 'Value passed to exception')
+      rescue ArgumentError => e
+        bond.spy('rescue_point', except: e.to_s)
+      end
+    end
+
+    it 'should correctly call a single doer if filter criteria are met' do
+      bond.deploy_agent('my_point', my_key__contains: '',
+                        do: lambda { |obs| bond.spy('internal', val: obs[:my_key]) })
+      bond.spy('my_point', my_key: 'value')
+    end
+
+    it 'should correctly call multiple doers' do
+      side_effect_value = 0
+      doers = [
+          lambda { |obs| bond.spy('internal', val: obs[:my_key]) },
+          lambda { |obs| side_effect_value += obs[:my_key] }
+      ]
+      bond.deploy_agent('my_point', do: doers)
+      bond.spy('my_point', my_key: 10)
+      bond.spy(side_effect_value: side_effect_value)
+    end
+
+    it 'should not call doers of overriden agents' do
+      bond.deploy_agent('my_point', do: lambda { |_| bond.spy('bad_agent') })
+      bond.deploy_agent('my_point', do: lambda { |_| bond.spy('valid_agent') })
+      bond.spy('my_point')
+    end
+
+    it 'should call doers before returning result' do
+      bond.deploy_agent('my_point', do: lambda { |_| bond.spy('internal_doer') },
+                        result: lambda { |_| bond.spy('internal_result'); 'mocked' })
+      bond.spy(result: bond.spy('my_point'))
+    end
+
+  end
+
+  # TODO
+  # overriding settings using Bond#settings
+  # some different start_test parameters
+
+  # finish test: creating output dir,
+  # some tests for SpyAgent and SpyAgentFilter - break out into separate files?
+
+end

data/spec/bond_targetable_spec.rb

@@ -0,0 +1,202 @@
+require 'spec_helper'
+
+describe BondTargetable do
+  include_context :bond
+
+  class TestClass
+    extend BondTargetable
+
+    bond.spy_point
+    def annotated_standard_method(arg1, arg2) end
+
+    bond.spy_point
+    def self.annotated_class_method(arg1, arg2) end
+
+    bond.spy_point
+    def annotated_method_var_args(arg1, arg2, *args) end
+
+    bond.spy_point
+    def annotated_method_kw_params_mixed(arg1:, arg2: 'default', arg3: 'default') end
+
+    bond.spy_point
+    def annotated_method_kw_params_optional(arg1: 'default', arg2: 'default') end
+
+    bond.spy_point
+    def annotated_method_variable_kw_args(arg1:, arg2: 'default', **kwargs) end
+
+    bond.spy_point
+    def annotated_method_mixed_params(arg1, arg2, arg3: 'default', arg4: 'foobar') end
+
+    bond.spy_point
+    def annotated_method_mixed_variable_params(arg1, *args, arg_n1:, arg_n2: 'default', **kwargs) end
+
+    bond.spy_point(spy_point_name: 'my_name')
+    def annotated_method_with_name; end
+
+    bond.spy_point(excluded_keys: :arg1)
+    def annotated_method_single_exclude(arg1, arg2) end
+
+    bond.spy_point(excluded_keys: ['arg1', 'arg3'])
+    def annotated_method_multiple_exclude(arg1, arg2:, arg3: 'default') end
+
+    bond.spy_point(spy_point_name: 'mock_required', require_agent_result: true)
+    def annotated_method_mocking_required(arg1) 'return' end
+
+    bond.spy_point(spy_point_name: 'spy_return', spy_result: true)
+    def annotated_method_spy_return(arg1) 'return' end
+
+    bond.spy_point
+    def annotated_method_with_block(arg1, &blk) yield; end
+
+    def method_calling_protected; annotated_protected_method('value') end
+
+    def method_calling_private; annotated_private_method('value') end
+
+    protected
+    spy_point
+    def annotated_protected_method(arg1) end
+
+    private
+    spy_point
+    def annotated_private_method(arg1) end
+  end
+
+  let (:tc) { TestClass.new }
+
+  context 'with different argument types' do
+    it 'correctly spies on a normal method' do
+      tc.annotated_standard_method(1, 2)
+    end
+
+    it 'correctly spies on a class method' do
+      TestClass.annotated_class_method(1, 2)
+    end
+
+    it 'correctly spies on a method with variable arguments' do
+      tc.annotated_method_var_args('value1', 'value2')
+      tc.annotated_method_var_args('value1', 'value2', 'value3', 'value4')
+    end
+
+    it 'correctly spies on a mix of required and optional keyword arguments' do
+      tc.annotated_method_kw_params_mixed(arg1: 'value')
+      tc.annotated_method_kw_params_mixed(arg1: 'value', arg3: 'new value')
+      tc.annotated_method_kw_params_mixed(arg1: 'value', arg3: 'new value3', arg2: 'new value2')
+    end
+
+    it 'correctly spies on all optional keyword arguments' do
+      tc.annotated_method_kw_params_optional
+      tc.annotated_method_kw_params_optional(arg1: 'value1', arg2: 'value2')
+    end
+
+    it 'correctly spies on variable keyword arguments' do
+      tc.annotated_method_variable_kw_args(arg1: 'value1')
+      tc.annotated_method_variable_kw_args(arg1: 'value1', arg2: 'value2')
+      tc.annotated_method_variable_kw_args(arg1: 'value1', arg3: 'value3')
+      tc.annotated_method_variable_kw_args(arg1: 'value1', arg4: 'value4', arg3: 'value3')
+    end
+
+    it 'correctly spies on a mix of positional and named arguments' do
+      tc.annotated_method_mixed_params('foo', 'bar')
+      tc.annotated_method_mixed_params('foo', 'bar', arg4: 'new value4')
+      tc.annotated_method_mixed_params('foo', 'bar', arg3: 'new value3', arg4: 'new value4')
+    end
+
+    it 'correctly spies on a mix of positional and named arguments, both variable' do
+      tc.annotated_method_mixed_variable_params('value1', arg_n1: 'value_n1')
+      tc.annotated_method_mixed_variable_params('value1', arg_n1: 'value_n1', arg_n2: 'value_n2')
+      tc.annotated_method_mixed_variable_params('value1', 'value2', 'value3', arg_n1: 'value_n1', arg_n2: 'value_n2')
+      tc.annotated_method_mixed_variable_params('value1', 'value2', 'value3', arg_n1: 'value_n1')
+      tc.annotated_method_mixed_variable_params('value1', 'value2', 'value3', arg_n1: 'value_n1', arg_n3: 'value_n3')
+    end
+  end
+
+  context 'with different spy_point parameters' do
+    it 'correctly changes the spy point name if it is specified' do
+      tc.annotated_method_with_name
+    end
+
+    it 'correctly ignores excluded keys' do
+      tc.annotated_method_single_exclude('value1', 'value2')
+      tc.annotated_method_multiple_exclude('value1', arg2: 'value2', arg3: 'value3')
+    end
+
+    it 'correctly errors when mocking is required and none is specified' do
+      begin
+        tc.annotated_method_mocking_required(2)
+        fail
+      rescue RuntimeError
+      end
+    end
+
+    it 'correctly mocks when one is specified' do
+      bond.deploy_agent('mock_required', result: 'new return')
+      ret = tc.annotated_method_mocking_required(5)
+      bond.spy('return_value', return: ret)
+    end
+
+    it 'correctly spies the return value when not mocking' do
+      tc.annotated_method_spy_return('arg_value')
+    end
+
+    it 'correctly spies the return value when mocking' do
+      bond.deploy_agent('spy_return', result: 'new return')
+      tc.annotated_method_spy_return('arg_value')
+    end
+  end
+
+  it 'correctly spies protected methods' do
+    tc.method_calling_protected
+  end
+
+  it 'correctly spies private methods' do
+    tc.method_calling_private
+  end
+
+  it 'correctly continues to the method when agent_result_continue is returned' do
+    bond.deploy_agent('mock_required', result: :agent_result_continue)
+    ret = tc.annotated_method_mocking_required('value1')
+    bond.spy('return value', ret: ret)
+  end
+
+  it 'correctly continues to the method when agent_result_none is returned' do
+    bond.deploy_agent('spy_return', result: :agent_result_none)
+    ret = tc.annotated_method_spy_return('value')
+    bond.spy('return value', ret: ret)
+  end
+
+  it 'correctly passes through blocks' do
+    ret = tc.annotated_method_with_block('foo') { 'value' }
+    bond.spy('return value', ret: ret)
+  end
+
+  it 'correctly returns nil (and mocks) when an agent returns nil' do
+    arr = [0]
+    bond.deploy_agent('TestClass#annotated_method_with_block', result: nil)
+    ret = tc.annotated_method_with_block('foo') { arr[0] = 1 }
+    bond.spy('return value', ret: ret, arr_val: arr[0])
+  end
+
+  context 'with modules' do
+    module TestModule
+      extend BondTargetable
+
+      bond.spy_point
+      def self.annotated_class_method(arg1, arg2) end
+
+      bond.spy_point
+      def annotated_standard_method(arg1) end
+
+    end
+
+    class TestClassWithMixin; include TestModule; end
+
+    it 'correctly spies on module methods' do
+      TestModule.annotated_class_method('value1', 'value2')
+    end
+
+    it 'correctly spies on included module methods' do
+      TestClassWithMixin.new.annotated_standard_method('value')
+    end
+
+  end
+end