delegate_matcher 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0ec0997475eaaee1d410562d34021316d878821a
+  data.tar.gz: ec92634564aabfac3448516ba0cdfd16051df08b
+SHA512:
+  metadata.gz: 51ffc33cf2e980067e1647af487efc778ba776e5224e651d02a4d46edb6abdb7b071da44465847e8222eff8f77dd1aea1428837cd324c8c30e40821cc6cb2856
+  data.tar.gz: a5e1996cf241039408c03f2e3ffd69e132aeb563ecc9e684b5df2d889d30c586d4814be6f0a69711fc1bca6b736a8683d390d3611a100437c3217d45c2dc6f44

data/.gitignore

@@ -0,0 +1,3 @@
+/.idea/
+/coverage/
+/pkg/

data/.rubocop.yml

@@ -0,0 +1,23 @@
+Metrics/LineLength:
+  Max: 160
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/MethodLength:
+  Max: 15
+
+Style/SingleSpaceBeforeFirstArg:
+  Enabled: false
+
+Style/ExtraSpacing:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/Semicolon:
+  Enabled: false
+
+Lint/Eval:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,87 @@
+PATH
+  remote: .
+  specs:
+    delegate_matcher (0.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.2.3)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    ast (2.1.0)
+    astrolabe (1.3.1)
+      parser (~> 2.2)
+    coveralls (0.7.2)
+      multi_json (~> 1.3)
+      rest-client (= 1.6.7)
+      simplecov (>= 0.7)
+      term-ansicolor (= 1.2.2)
+      thor (= 0.18.1)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    i18n (0.7.0)
+    json (1.8.3)
+    mime-types (2.4.3)
+    minitest (5.7.0)
+    multi_json (1.10.1)
+    parser (2.2.2.6)
+      ast (>= 1.1, < 3.0)
+    powerpack (0.1.1)
+    rainbow (2.0.0)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rspec (3.3.0)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+    rspec-core (3.3.2)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-its (1.1.0)
+      rspec-core (>= 3.0.0)
+      rspec-expectations (>= 3.0.0)
+    rspec-mocks (3.3.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+    rubocop (0.33.0)
+      astrolabe (~> 1.3)
+      parser (>= 2.2.2.5, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.4)
+    ruby-progressbar (1.7.5)
+    simplecov (0.9.1)
+      docile (~> 1.1.0)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    term-ansicolor (1.2.2)
+      tins (~> 0.8)
+    thor (0.18.1)
+    thread_safe (0.3.5)
+    tins (0.13.2)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 4.2)
+  bundler (~> 1.7)
+  coveralls (~> 0.7)
+  delegate_matcher!
+  rspec (~> 3.0)
+  rspec-its (~> 1.1)
+  rubocop (~> 0.30)
+  simplecov (~> 0.9)
+
+BUNDLED WITH
+   1.10.6

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Declan Whelan
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,237 @@
+# Delegate Matcher
+
+An RSpec matcher for validating delegation. This matcher works with delegation based on the [Forwardable](http://ruby-doc.org/stdlib-2.0.0/libdoc/forwardable/rdoc/Forwardable.html) module,
+the [delegate](http://api.rubyonrails.org/classes/Module.html#method-i-delegate) method in the Active Support gem or with
+simple custom delegation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'delegate_matcher'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install delegate_matcher
+```
+
+Then add the following to your ```spec_helper.rb``` file:
+
+
+```ruby
+require 'delegate_matcher'
+```
+
+## Usage
+
+This matcher allows you to validate delegation to:
+* instance methods
+* class methods
+* instance variables
+* class variables
+* constants
+* arbitrary objects
+
+```ruby
+describe Post do
+  it { should delegate(:name).to(:author)   } # name  => author().name    instance method
+  it { should delegate(:name).to(:class))   } # name  => self.class.name  class method
+  it { should delegate(:name).to(:@author)  } # name  => @author.name     instance variable
+  it { should delegate(:name).to(:@@author) } # name  => @@author.name    class variable
+  it { should delegate(:first).to(:GENRES)  } # first => GENRES.first     constant
+  it { should delegate(:name).to(author)    } # name  => author.name      object
+end
+```
+
+### Delegate Method Name
+
+If the name of the method being invoked on the delegate is different from the method being called you
+can check this using the ```with_prefix``` method (based on Active Support ```delegate``` method) or the
+```as``` method.
+
+```ruby
+describe Post do
+  it { should delegate(:name).to(author).with_prefix }          # author_name  => author.name
+  it { should delegate(:name).to(author).with_prefix(:writer) } # writer_name  => author.name
+  it { should delegate(:writer).to(author).as(:name) }          # writer       => author.name
+end
+```
+
+### Handling Nil Delegates
+
+If you expect the delegate to return ```nil``` when the delegate is ```nil``` rather than raising an error
+then you can check this using the ```allow_nil``` method.
+
+```ruby
+describe Post do
+  it { should delegate(:name).to(:author).allow_nil        } # name => author && author.name
+  it { should delegate(:name).to(:author).allow_nil(true)  } # name => author && author.name
+  it { should delegate(:name).to(:author).allow_nil(false) } # name => author.name
+end
+```
+
+Nil handling is only checked if ```allow_nil``` is specified.
+
+Note that matcher will raise an error if you use this when checking delegation to a constant or an
+object since the matcher cannot validate ```nil``` handling in these cases.
+
+### Arguments
+
+If the method being delegated takes arguments then you can supply them with the ```with``` method. The matcher
+will ensure that the provided arguments are in turn passed to the delegate.
+
+```ruby
+describe Post do
+  it { should delegate(:name).with('Ms.')to(:author) }  # name('Ms.')  => author.name('Ms.')
+end
+```
+
+Also, in some cases the delegator might make minor changes to the arguments. While this is arguably no
+longer true delegation you can still check that arguments are correctly passed by using a second ```with```
+method to specify the arguments expected by the delegate.
+
+```ruby
+describe Post do
+  it { should delegate(:name).with('Ms.')to(author).with('Miss') }  # name('Ms.')  => author.name('Miss')
+end
+```
+
+### Blocks
+
+You can check that a block passed is in turn passed to the delegate via the ```with_block``` method.
+
+```ruby
+describe Post do
+  it { should delegate(:name).to(author).with_a_block }    # name(&block) => author.name(&block)
+  it { should delegate(:name).to(author).with_block }      # name(&block) => author.name(&block) alias for with_a_block
+
+  it { should delegate(:name).to(author).without_a_block } # name(&block) => author.name
+  it { should delegate(:name).to(author).without_block }   # name(&block) => author.name         alias for without_a_block
+end
+```
+
+By default, block delegated is only check if ```with_a_block``` or ```without_a_block``` is specified.
+
+### Active Support
+
+You can test delegation based on the [delegate](http://api.rubyonrails.org/classes/Module.html#method-i-delegate) method in the Active Support gem.
+
+```ruby
+class Post
+  attr_accessor :author
+
+  class_variable_set(:@@authors, ['Ann Rand', 'Catherine Asaro'])
+  GENRES ||= ['Fiction', 'Science Fiction']
+
+  delegate :name,                to: :author
+  delegate :name,                to: :author, prefix: true
+  delegate :name,                to: :author, prefix: :writer
+  delegate :name_with_nil_check, to: :author, allow_nil: true
+  delegate :name_with_arg,       to: :author
+  delegate :name_with_block,     to: :author
+  delegate :count,               to: :@@authors
+  delegate :first,               to: :GENRES
+  delegate :name,                to: :class, prefix: true
+end
+
+class Author
+  def name
+    'Catherine Asaro'
+  end
+
+  def name_with_nil_check
+    name
+  end
+
+  def name_with_arg(arg)
+    "#{arg} #{name}"
+  end
+
+  def name_with_block(&block)
+    "#{block.call} #{name}"
+  end
+end
+
+describe Post do
+  it { should delegate(:name).to(:author) }
+  it { should delegate(:name).to(:@author) }
+  it { should delegate(:name_with_nil_check).to(:author).allow_nil }
+  it { should delegate(:name).to(:author).with_prefix }
+  it { should delegate(:name).to(:author).with_prefix(:writer) }
+
+  it { should delegate(:name_with_arg).to(:author).with('Ms.') }
+  it { should delegate(:name_with_block).to(:author).with_block }
+  it { should delegate(:count).to(:@@authors)   }
+  it { should delegate(:first).to(:GENRES)   }
+  it { should delegate(:name).to(:class).with_prefix   }
+end
+```
+However, don't use the following features as they are not supported by the delegate method:
+* delegation to objects
+* different arguments passed to delegate
+
+### Forwardable Module
+
+You can test delegation based on the [Forwardable](http://ruby-doc.org/stdlib-2.0.0/libdoc/forwardable/rdoc/Forwardable.html) module.
+
+```ruby
+class Post
+  extend Forwardable
+
+  attr_accessor :author
+
+  def_delegator :author, :name
+  def_delegator :author, :name, :writer
+  def_delegator :author, :name_with_arg
+  def_delegator :author, :name_with_block
+end
+
+class Author
+  def name
+    'Catherine Asaro'
+  end
+
+  def name_with_arg(arg)
+    "#{arg} #{name}"
+  end
+
+  def name_with_block(&block)
+    "#{block.call} #{name}"
+  end
+end
+
+describe Post do
+  it { should delegate(:name).to(:author) }
+  it { should delegate(:name).to(:@author) }
+  it { should delegate(:writer).to(:author).as(:name) }
+  it { should delegate(:name_with_arg).to(:author).with('Ms.') }
+  it { should delegate(:name_with_block).to(:author).with_block }
+end
+```
+However, don't use the following features as they are not supported by the Forwardable module:
+* allow_nil
+* delegation to class variables
+* delegation to constants
+* delegation to objects
+* different arguments passed to delegate
+
+## Contributing
+
+1. Fork it ( https://github.com/dwhelan/delegate_matcher/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## Notes
+
+This matcher was inspired by [Alan Winograd](https://github.com/awinograd) via the gist https://gist.github.com/awinograd/6158961

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: [:spec, :rubocop, :build]

data/delegate_matcher.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'delegate_matcher/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'delegate_matcher'
+  gem.version       = DelegateMatcher::VERSION
+  gem.authors       = ['Declan Whelan']
+  gem.email         = ['declan@pleanintuit.com']
+  gem.summary       = 'A matcher for testing ruby delegation.'
+  gem.description   = 'A matcher for testing ruby delegation.'
+  gem.homepage      = 'https://github.com/dwhelan/delegate_matcher'
+  gem.license       = 'MIT'
+
+  gem.files         = `git ls-files -z`.split("\x0")
+  gem.executables   = gem.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^spec/})
+  gem.require_paths = ['lib']
+
+  gem.add_development_dependency 'activesupport', '~> 4.2'
+  gem.add_development_dependency 'bundler',       '~> 1.7'
+  gem.add_development_dependency 'coveralls',     '~> 0.7'
+  gem.add_development_dependency 'rspec',         '~> 3.0'
+  gem.add_development_dependency 'rspec-its',     '~> 1.1'
+  gem.add_development_dependency 'rubocop',       '~> 0.30'
+  gem.add_development_dependency 'simplecov',     '~> 0.9'
+end

data/lib/delegate_matcher/delegate_matcher.rb

@@ -0,0 +1,281 @@
+RSpec::Matchers.define(:delegate) do |method|
+  match do |delegator|
+    fail 'need to provide a "to"' unless delegate
+
+    @method    = method
+    @delegator = delegator
+
+    allow_nil_ok? && delegate? && arguments_ok? && block_ok?
+  end
+
+  description do
+    "delegate #{delegator_description} to #{delegate_description}#{nil_description}#{block_description}"
+  end
+
+  def failure_message
+    message = failure_message_details(false)
+    message.empty? ? super : message
+  end
+
+  def failure_message_when_negated
+    message = failure_message_details(true)
+    message.empty? ? super : message
+  end
+
+  chain(:to)              { |delegate|         @delegate           = delegate }
+  chain(:as)              { |delegate_method|  @delegate_method    = delegate_method }
+  chain(:allow_nil)       { |allow_nil = true| @expected_nil_check = allow_nil }
+  chain(:with_prefix)     { |prefix = nil|     @prefix             = prefix || delegate.to_s.sub(/@/, '') }
+  chain(:with)            { |*args|            @expected_args      = args; @args ||= args }
+  chain(:with_a_block)    {                    @expected_block     = true  }
+  chain(:without_a_block) {                    @expected_block     = false }
+
+  alias_method :with_block,    :with_a_block
+  alias_method :without_block, :without_a_block
+
+  private
+
+  attr_reader :method, :delegator, :delegate, :prefix, :args
+  attr_reader :expected_nil_check, :actual_nil_check
+  attr_reader :expected_args,      :actual_args
+  attr_reader :expected_block,     :actual_block
+  attr_reader :actual_return_value
+
+  def delegate?(test_delegate = delegate_double)
+    case
+    when delegate_is_a_class_variable?
+      delegate_to_class_variable(test_delegate)
+    when delegate_is_an_instance_variable?
+      delegate_to_instance_variable(test_delegate)
+    when delegate_is_a_constant?
+      delegate_to_constant
+    when delegate_is_a_method?
+      delegate_to_method(test_delegate)
+    else
+      delegate_to_object
+    end
+
+    return_value_ok?
+  end
+
+  def delegate_is_a_class_variable?
+    delegate.to_s.start_with?('@@')
+  end
+
+  def delegate_is_an_instance_variable?
+    delegate.to_s[0] == '@'
+  end
+
+  def delegate_is_a_constant?
+    (delegate.is_a?(String) || delegate.is_a?(Symbol)) && (delegate.to_s =~ /^[A-Z]/)
+  end
+
+  def delegate_is_a_method?
+    delegate.is_a?(String) || delegate.is_a?(Symbol)
+  end
+
+  def delegate_to_class_variable(test_delegate)
+    actual_delegate = delegator.class.class_variable_get(delegate)
+    delegator.class.class_variable_set(delegate, test_delegate)
+    call
+  ensure
+    delegator.class.class_variable_set(delegate, actual_delegate)
+  end
+
+  def delegate_to_instance_variable(test_delegate)
+    actual_delegate = delegator.instance_variable_get(delegate)
+    delegator.instance_variable_set(delegate, test_delegate)
+    call
+  ensure
+    delegator.instance_variable_set(delegate, actual_delegate)
+  end
+
+  def delegate_to_constant
+    ensure_allow_nil_is_not_specified_for('a constant')
+    stub_delegation(delegator.class.const_get(delegate))
+    call
+  end
+
+  def delegate_to_method(test_delegate)
+    ensure_delegate_method_is_valid
+    allow(delegator).to receive(delegate) { test_delegate }
+    call
+  end
+
+  def delegate_to_object
+    ensure_allow_nil_is_not_specified_for('an object')
+    stub_delegation(delegate)
+    call
+  end
+
+  def ensure_allow_nil_is_not_specified_for(target)
+    fail %(cannot verify "allow_nil" expectations when delegating to #{target}) unless expected_nil_check.nil?
+  end
+
+  def ensure_delegate_method_is_valid
+    fail "#{delegator} does not respond to #{delegate}"          unless delegator.respond_to?(delegate, true)
+    fail "#{delegator}'s' #{delegate} method expects parameters" unless [0, -1].include?(delegator.method(delegate).arity)
+  end
+
+  def delegator_method
+    @delegator_method || (prefix ? :"#{prefix}_#{method}" : method)
+  end
+
+  def delegate_method
+    @delegate_method || method
+  end
+
+  def call
+    @actual_return_value = delegator.send(delegator_method, *args, &block)
+  end
+
+  def block
+    @block ||= proc {}
+  end
+
+  def delegate_double
+    double('delegate').tap { |delegate| stub_delegation(delegate) }
+  end
+
+  def stub_delegation(delegate)
+    @delegated = false
+    allow(delegate).to(receive(delegate_method)) do |*args, &block|
+      @actual_args  = args
+      @actual_block = block
+      @delegated    = true
+      expected_return_value
+    end
+  end
+
+  def expected_return_value
+    self
+  end
+
+  def allow_nil_ok?
+    return true if expected_nil_check.nil?
+    return true unless delegate.is_a?(String) || delegate.is_a?(Symbol)
+
+    begin
+      actual_nil_check = true
+      delegate?(nil)
+      @return_value_when_delegate_nil = actual_return_value
+    rescue NoMethodError
+      actual_nil_check = false
+    end
+
+    expected_nil_check == actual_nil_check && @return_value_when_delegate_nil.nil?
+  end
+
+  def arguments_ok?
+    expected_args.nil? || actual_args.eql?(expected_args)
+  end
+
+  def block_ok?
+    case
+    when expected_block.nil?
+      true
+    when expected_block
+      actual_block == block
+    else
+      actual_block.nil?
+    end
+  end
+
+  def return_value_ok?
+    actual_return_value == expected_return_value
+  end
+
+  def delegator_description
+    "#{delegator_method}#{argument_description(args)}"
+  end
+
+  def delegate_description
+    case
+    when !args.eql?(expected_args)
+      "#{delegate}.#{delegate_method}#{argument_description(expected_args)}"
+    when delegate_method.eql?(delegator_method)
+      "#{delegate}"
+    else
+      "#{delegate}.#{delegate_method}"
+    end
+  end
+
+  def argument_description(args)
+    args ? "(#{args.map { |a| format('%p', a) }.join(', ')})" : ''
+  end
+
+  def nil_description
+    case
+    when expected_nil_check.nil?
+      ''
+    when expected_nil_check
+      ' with nil allowed'
+    else
+      ' with nil not allowed'
+    end
+  end
+
+  def block_description
+    case
+    when expected_block.nil?
+      ''
+    when expected_block
+      ' with a block'
+    else
+      ' without a block'
+    end
+  end
+
+  def failure_message_details(negated)
+    [
+      argument_failure_message(negated),
+      block_failure_message(negated),
+      return_value_failure_message(negated),
+      allow_nil_failure_message(negated)
+    ].reject(&:empty?).join(' and ')
+  end
+
+  def argument_failure_message(negated)
+    case
+    when expected_args.nil? || negated ^ arguments_ok?
+      ''
+    else
+      "was called with #{argument_description(actual_args)}"
+    end
+  end
+
+  def block_failure_message(negated)
+    case
+    when expected_block.nil? || (negated ^ block_ok?)
+      ''
+    when negated
+      "a block was #{expected_block ? '' : 'not '}passed"
+    when expected_block
+      actual_block.nil? ? 'a block was not passed' : "a different block #{actual_block} was passed"
+    else
+      'a block was passed'
+    end
+  end
+
+  def return_value_failure_message(_negated)
+    case
+    when !@delegated || return_value_ok?
+      ''
+    else
+      format('a return value of %p was returned instead of the delegate return value', actual_return_value)
+    end
+  end
+
+  def allow_nil_failure_message(negated)
+    case
+    when expected_nil_check.nil? || negated ^ allow_nil_ok?
+      ''
+    when !@return_value_when_delegate_nil.nil?
+      'did not return nil'
+    when negated
+      "#{delegate} was #{expected_nil_check ? '' : 'not '}allowed to be nil"
+    else
+      "#{delegate} was #{expected_nil_check ? 'not ' : ''}allowed to be nil"
+    end
+  end
+end