delegate_matcher 0.3 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b01a0155696471c53b2e5d758ee3acfb321fe843
-  data.tar.gz: 5c153cefb6be729954baf5f1a71251f929ab7d15
+  metadata.gz: 5e342a7ea43c74991c773ae7093fd017383dd22e
+  data.tar.gz: f9b3cec53a47692c6b65ca529b46a59bc89a8a68
 SHA512:
-  metadata.gz: d2bbb26693117c40694240b49c5f1ecc192aaa0d6bdd5a3b1dbecb6e5c1bfc4b4b6e40a6a462143139001f036726dea5ff865ffb90a2b394f15107ee411f2c9e
-  data.tar.gz: a52c23c8dea9252b407dc9aead40ace210095d19de17ab469547bd8514589f1e0c2ccfbf9e8c2648f43820ab533b2a4d23a4212908c50a4e25b6b12a89ac6419
+  metadata.gz: 4a91f85a9c888ea5e659c1dbdeeac00a0395eabf55149beba29a3d123bd22d38e6e5d1a209df6e3a747483b1a6e22dfe158aea9834f7c62e79d44e00c57bf6b7
+  data.tar.gz: f2c93b90808e178b51b6ac52bffc6e7ff62473397618371c258b5f1c6421683b652a3cac70a4128213f7ad9544b1df1f51956492498f68530406ffd2304d177a

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    delegate_matcher (0.3)
-      proc_extensions (~> 0.1)
+    delegate_matcher (0.4)
+      proc_extensions (~> 0.2)
 
 GEM
   remote: https://rubygems.org/
@@ -66,7 +66,7 @@ GEM
     parser (2.2.3.0)
       ast (>= 1.1, < 3.0)
     powerpack (0.1.1)
-    proc_extensions (0.1.2)
+    proc_extensions (0.2)
       sourcify (~> 0.5)
     pry (0.10.3)
       coderay (~> 1.1.0)

data/README.md

@@ -41,6 +41,7 @@ This matcher allows you to validate delegation to:
 * class variables
 * constants
 * arbitrary objects
+* multiple targets
 
 ```ruby
 describe Post do
@@ -112,13 +113,29 @@ describe Post do
 end
 ```
 
-Also, in some cases the delegator might make minor changes to the arguments. While this is arguably no
+Also, in some cases, the delegator change 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')
+  it { should delegate(:name).with('Ms.').to(:author).with('Miss') }  # name('Ms.')  => author.name('Miss')
+end
+```
+You can use the `with(no_args).` rather than `with.` or `with().` to test delegation with no arguments passed
+to the delegator.
+
+```ruby
+describe Post do
+  it { should delegate(:name).with(no_args).to(:author) }  # name()  => author.name()
+end
+```
+
+For the second `with` you can use any RSpec argument matcher.
+
+```ruby
+describe Post do
+  it { should delegate(:name).with('Ms.').to(:author).with(anything) }  # name('Ms.')  => author.name(*)
 end
 ```
 
@@ -144,6 +161,11 @@ describe Post do
 end
 ```
 
+If the `proc` passed to `with_block` is not the same `proc` used y the delegator
+then the sources of the `proc`'s will be compared for equality using the `proc_extensions` gem.
+For this comparison to work the `proc` must not be not have been created via an `eval` of a string
+and must be the only `proc` declared on that line of source code.
+
 See [proc_extensions](https://github.com/dwhelan/proc_extensions/) for more details on how the source for procs is compared.
 
 ### Return Value
@@ -156,10 +178,55 @@ describe Post do
 end
 ```
 
+### Multiple Targets
+You can test delegation to more than one target by specifing more than one target via `to`.
+```ruby
+require 'spec_helper'
+
+module RSpec
+  module Matchers
+    module DelegateMatcher
+      module Composite
+        describe 'delegation to multiple targets' do
+          class Post
+            include PostMethods
+
+            attr_accessor :authors, :catherine_asaro, :isaac_asimov
+
+            def initialize
+              self.catherine_asaro = Author.new('Catherine Asaro')
+              self.isaac_asimov    = Author.new('Isaac Asimov')
+              self.authors         = [catherine_asaro, isaac_asimov]
+            end
+
+            def name
+              authors.map(&:name)
+            end
+          end
+
+          subject { Post.new }
+
+          it { should delegate(:name).to(*subject.authors) }
+          it { should delegate(:name).to(subject.catherine_asaro, subject.isaac_asimov) }
+          it { should delegate(:name).to(:catherine_asaro, :isaac_asimov) }
+          it { should delegate(:name).to(:@catherine_asaro, :@isaac_asimov) }
+        end
+      end
+    end
+  end
+end
+
+```
+
 ### 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
+require 'spec_helper'
+require 'active_support/core_ext/module/delegation'
+
+module ActiveSupportDelegation
+  # rubocop:disable Style/ClassVars
   class Post
     attr_accessor :author
 
@@ -172,15 +239,24 @@ You can test delegation based on the [delegate](http://api.rubyonrails.org/class
     delegate :name,  to: :class,  prefix: true
     delegate :count, to: :@@authors
     delegate :first, to: :GENRES
+    delegate :length, to: :'author.name', prefix: :name
 
     def initialize
       @author = Author.new
     end
+
+    def inspect
+      'post'
+    end
   end
 
   class Author
-    def name
-      @name ||= 'Catherine Asaro'
+    def initialize
+      @name = 'Catherine Asaro'
+    end
+
+    def name(*)
+      @name
     end
   end
 
@@ -197,6 +273,7 @@ You can test delegation based on the [delegate](http://api.rubyonrails.org/class
     it { should delegate(:name).to(:author).with_prefix(:writer) }
     it { should delegate(:name).to(:author).with_block }
     it { should delegate(:name).to(:author).with('Ms.') }
+    it { should delegate(:name).to(:author).with('Ms.').with_block }
 
     it { should delegate(:name).to(:class).with_prefix   }
     it { should delegate(:count).to(:@@authors)   }
@@ -205,15 +282,19 @@ You can test delegation based on the [delegate](http://api.rubyonrails.org/class
     it { should delegate(:name_length).to(:'author.name').as(:length) }
     it { should delegate(:length).to(:'author.name').with_prefix(:name) }
   end
+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
+require 'spec_helper'
+
+module ForwardableDelegation
   class Post
     extend Forwardable
 
@@ -226,11 +307,21 @@ You can test delegation based on the [Forwardable](http://ruby-doc.org/stdlib-2.
     def_delegator :author, :name
     def_delegator :author, :name, :author_name
     def_delegator :author, :name, :writer
+
+    def_delegator :'author.name', :length, :name_length
+
+    def inspect
+      'post'
+    end
   end
 
   class Author
-    def name
-      @name ||= 'Catherine Asaro'
+    def initialize
+      @name = 'Catherine Asaro'
+    end
+
+    def name(*)
+      @name
     end
   end
 
@@ -244,19 +335,21 @@ You can test delegation based on the [Forwardable](http://ruby-doc.org/stdlib-2.
     it { should delegate(:name).to(:author) }
     it { should delegate(:name).to(:author).with('Ms.') }
     it { should delegate(:name).to(:author).with_block }
+    it { should delegate(:name).to(:author).with('Ms.').with_block }
     it { should delegate(:name).to(:author).with_prefix }
     it { should delegate(:writer).to(:author).as(:name) }
 
     it { should delegate(:name_length).to(:'author.name').as(:length) }
     it { should delegate(:length).to(:'author.name').with_prefix(:name) }
   end
+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 the delegate
 
 ## Contributing
 1. Fork it ( https://github.com/dwhelan/delegate_matcher/fork )

data/README.md.erb

@@ -0,0 +1,216 @@
+[![Gem Version](https://badge.fury.io/rb/delegate_matcher.png)](http://badge.fury.io/rb/delegate_matcher)
+[![Build Status](https://travis-ci.org/dwhelan/delegate_matcher.png?branch=master)](https://travis-ci.org/dwhelan/delegate_matcher)
+[![Code Climate](https://codeclimate.com/github/dwhelan/delegate_matcher/badges/gpa.svg)](https://codeclimate.com/github/dwhelan/delegate_matcher)
+[![Coverage Status](https://coveralls.io/repos/dwhelan/delegate_matcher/badge.svg?branch=master&service=github)](https://coveralls.io/github/dwhelan/delegate_matcher?branch=master)
+
+# 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
+* multiple targets
+
+```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
+```
+
+**Note**: if you are delegating to an object (i.e. `to` is not a string or symbol) then a prefix of `''` will be used:
+
+```ruby
+describe Post do
+  it { should delegate(:name).to(author).with_prefix }          # an error will be raised
+  it { should delegate(:name).to(author).with_prefix(:writer) } # writer_name  => author.name
+end
+```
+
+You can test delegation to a chain of objects by using a `to` that can be `eval`'d.
+
+```ruby
+describe Post do
+  it { should delegate(:name_length).to(:'author.name').as(:length) }   # name_length => author.name.length
+  it { should delegate(:length).to(:'author.name').with_prefix(:name) } # name_length => author.name.length
+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 the matcher will raise an error if you use this when checking delegation to an
+object since the matcher cannot validate `nil` handling as it cannot gain access to the subject
+reference to the object to set it `nil`.
+
+### Arguments
+If the method being delegated takes arguments you can supply them with the `with` method. The matcher
+will check 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 change 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
+```
+You can use the `with(no_args).` rather than `with.` or `with().` to test delegation with no arguments passed
+to the delegator.
+
+```ruby
+describe Post do
+  it { should delegate(:name).with(no_args).to(:author) }  # name()  => author.name()
+end
+```
+
+For the second `with` you can use any RSpec argument matcher.
+
+```ruby
+describe Post do
+  it { should delegate(:name).with('Ms.').to(:author).with(anything) }  # name('Ms.')  => author.name(*)
+end
+```
+
+### Blocks
+You can check that a block passed is in turn passed to the delegate via the `with_block` method.
+By default, block delegation is only checked if `with_a_block` or `without_a_block` is specified.
+
+```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
+```
+You can also pass an explicit block in which case the block passed will be compared against
+the block received by the delegate. The comparison is based on having equivalent source for the blocks.
+
+```ruby
+describe Post do
+  it { should delegate(:tainted?).to(authors).as(:all?).with_block { |a| a.tainted? } } # tainted? => authors.all? { |a| a.tainted? }
+end
+```
+
+If the `proc` passed to `with_block` is not the same `proc` used y the delegator
+then the sources of the `proc`'s will be compared for equality using the `proc_extensions` gem.
+For this comparison to work the `proc` must not be not have been created via an `eval` of a string
+and must be the only `proc` declared on that line of source code.
+
+See [proc_extensions](https://github.com/dwhelan/proc_extensions/) for more details on how the source for procs is compared.
+
+### Return Value
+Normally the matcher will check that the value return is the same as the value
+returned from the delegate. You can skip this check by using `without_return`.
+
+```ruby
+describe Post do
+  it { should delegate(:name).to(:author).without_return }
+end
+```
+
+### Multiple Targets
+You can test delegation to more than one target by specifing more than one target via `to`.
+```ruby
+<%= File.open('./spec/to_multiple_targets_spec.rb', 'rb') { |f| f.read } %>
+```
+
+### 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
+<%= File.open('./spec/examples/active_support_delegation_spec.rb', 'rb') { |f| f.read } %>
+```
+However, don't use the following features as they are not supported by the delegate method:
+* delegation to objects
+
+### 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
+<%= File.open('./spec/examples/forwardable_delegation_spec.rb', 'rb') { |f| f.read } %>
+```
+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
+
+## 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

@@ -7,4 +7,9 @@ RuboCop::RakeTask.new do |task|
   task.options << '--display-cop-names'
 end
 
-task default: [:spec, :rubocop, :build]
+desc 'Updates README with code examples'
+task :readme do
+  `erb README.md.erb > README.md`
+end
+
+task default: [:spec, :rubocop, :readme, :build]

data/delegate_matcher.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^spec/})
   gem.require_paths = ['lib']
 
-  gem.add_runtime_dependency 'proc_extensions', '~>  0.1'
+  gem.add_runtime_dependency 'proc_extensions', '~>  0.2'
 
   gem.add_development_dependency 'activesupport',   '~>  4.2'
   gem.add_development_dependency 'bundler',         '~>  1.7'

data/lib/delegate_matcher/delegate.rb

@@ -6,10 +6,11 @@ module RSpec
 
         RSpec::Mocks::Syntax.enable_expect(self)
 
-        attr_reader :received, :args
+        attr_reader :to, :received, :args
 
-        def initialize(expected)
+        def initialize(expected, to)
           self.expected = expected
+          self.to       = to
           self.received = false
         end
 
@@ -33,26 +34,18 @@ module RSpec
         end
 
         def argument_description
-          args ? "(#{args.map { |a| format('%p', a) }.join(', ')})" : ''
-        end
-
-        def return_value
-          self
+          args ? "(#{args.map(&:inspect).join(', ')})" : ''
         end
 
         private
 
         attr_accessor :expected
-        attr_writer :received, :args, :block
+        attr_writer :to, :received, :args, :block
 
         def subject
           expected.subject
         end
 
-        def to
-          expected.to
-        end
-
         def name
           to.to_s
         end

data/lib/delegate_matcher/delegate_matcher.rb

@@ -4,7 +4,9 @@ module RSpec
   module Matchers
     define(:delegate) do |method_name|
       match do |subject|
-        delegation_ok?(method_name, subject)
+        fail 'need to provide a "to"' unless expected.to
+        expected.subject = subject
+        delegation.ok?
       end
 
       description do
@@ -19,7 +21,7 @@ module RSpec
         delegation.failure_message(true) || super
       end
 
-      chain(:to)              { |to|               expected.to           = to }
+      chain(:to)              { |*to|              expected.to           = *to; expected.method_name = method_name }
       chain(:as)              { |as|               expected.as           = as }
       chain(:allow_nil)       { |allow_nil = true| expected.allow_nil    = allow_nil }
       chain(:with_prefix)     { |prefix = nil|     expected.prefix       = prefix }
@@ -27,6 +29,7 @@ module RSpec
       chain(:with_a_block)    { |&block|           expected.block        = block || true  }
       chain(:without_a_block) {                    expected.block        = false }
       chain(:without_return)  {                    expected.check_return = false }
+      chain(:and_return)      { |value|            expected.return_value = value }
 
       alias_method :with_block,    :with_a_block
       alias_method :without_block, :without_a_block
@@ -40,18 +43,6 @@ module RSpec
       def expected
         @expected ||= DelegateMatcher::Expected.new
       end
-
-      def delegation_ok?(method_name, subject)
-        fail 'need to provide a "to"' unless expected.to
-
-        expected.method_name = method_name
-        expected.subject     = subject
-
-        delegation.ok?
-      end
     end
   end
 end
-
-# TODO: Handle nested delegation strings "a.b.c"
-# TODO: Test SingleForwardable