rspecproxies 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4b3a0b1c4a48a2cea5b58e1c967c5a15d23f68c2
-  data.tar.gz: eca395f2f3c1aa00361a83b117b77f010770a236
+  metadata.gz: 8780bd0b36987621f35cb6060457f7d3216aca83
+  data.tar.gz: 65c3c13a0cbc60e9ed35b69a50e64cf6261aa639
 SHA512:
-  metadata.gz: 0237c662bc25f4ccd32906389a8e7a55ebf133a8985d1f431496a134780ad6c4f2d36ccc08a64e658f8f593b6f4cba161774dcfffe6e179ec7c8cb37d8b7271e
-  data.tar.gz: ebd24e274002755e08bb7f0d2a1979d5c31652d5b4effa4df151585000d9258deff6fe32cddaff94e2e82763878fb3e3f769e4de248ecabff17f5ad1701faf3e
+  metadata.gz: fd406ed228f3415dd4dd3a36273b5573175a0ef2f06c97dfc0e0bd5cb3f24cea8cfbb7fcdae21756cd694e823cd4e803a1448997c34b36fda9edd944236ae6b8
+  data.tar.gz: 86591baa5eda35111672aa25c036e84f73f196e054ba09e2b5e1dc5cfb04ece12d9c58a8daeae0cf0d3ffbdde1e486bee372b15fb70c5cc78ad4c3e8be61d77f

data/.travis.yml

@@ -1,7 +1,7 @@
 language: ruby
 rvm:
-  - 2.1.1
-  - 2.0.0
+  - 2.3.1
+  - 2.2.5
 script: bundle exec rake
 addons:
   code_climate:

data/DayBook.org

@@ -0,0 +1,12 @@
+* DONE update the code
+* DONE increase the version to 1.0.0
+* DONE update the Readme
+** DONE new syntax (use mock-experiments)
+** DONE how to do with docker*
+** DONE update the links
+* TODO Create a github page
+** DONE copy the readme into a page in my blog
+** DONE move open source projects pages from navigation to an aside
+** TODO check the links
+* TODO release and bump a new version
+* TODO add code snipets from mock-experiments to the google pres

data/Dockerfile

@@ -0,0 +1 @@
+FROM ruby:2.3

data/README.md

@@ -2,13 +2,26 @@
 
 # RSpecProxies
 
-Special RSpec extensions to simplify mocking by providing proxies.
+Simplify [RSpec](http://rspec.info) mocking with test proxies !
 
-Here are the goals of mock proxies :
+## Why ?
 
-* simplify mock setup
-* minimize method calls verifications
-* capture return values and calls
+As you might know after the [Is TDD Dead ?](http://martinfowler.com/articles/is-tdd-dead/) debate, [Mockists are dead, long live to classicists](https://www.thoughtworks.com/insights/blog/mockists-are-dead-long-live-classisists). Heavy mocking is getting out of fashion because it makes tests unreliable and difficult to maintain.
+
+Test proxies mix the best of both worlds, they behave like the real objects but also provide hooks to perform assertions or to inject test code. RSpec now features minimal supports for proxies with partial mocks, spies and the ```and_call_original``` and ```and_wrap_original``` expectations. RSpecProxies goes one step further with more specific expectations. Using RSpecProxies should help you to use as little mocking as possible.
+
+More specifically, RSpecProxies helps to :
+
+* Simplify the setup of mocks by relying on the real objects
+* Write reliable tests that use the real code
+* Capture return values and arguments to the real calls
+* Setup nested proxies when needed
+
+RSpecProxies will not make your tests as fast as heavy mocking, but for that you can :
+
+* Use in-memory databases to run your tests (such as [SQLite](http://www.sqlite.org))
+* Split your system in sub-systems
+* Write in-memory fakes of your sub-systems to use in your tests
 
 ## Installation
 
@@ -26,42 +39,68 @@ Or install it yourself as:
 
 ## Usage
 
-Just as inspiration, here are a few sample usages :
+RSpecProxies is used on top of RSpec's ```and_return_original``` and ```and_wrap_original``` expectations. The syntax is meant to be very similar. Just as inspiration, here are a few sample usages.
+
+### Verify caching
+
+NB: this is an illustration of the built-in spy features that RSpec now provides
 
-### Verify caching with capture_results_from
+By definition, caching should not change the behaviour of your system. But some methods should not be called many times. This used to be a good place to use mocks. RSpec spies now helps to deal with that in an unintrusive way :
 
 ```ruby
 it 'caches users' do
-  users = User.capture_results_from(:load)
+  allow(User).to receive(:load).and_return_original
 
   controller.login('joe', 'secret')
   controller.login('joe', 'secret')
 
-  expect(users).to have_exactly(1).items
+  expect(users).to have_received(:load).once
 end
 ```
 
-### Verify loaded data with capture_result_from
+### Verify loaded data
+
+Sometimes, the verifications you want to make in your test depends on the data that has been loaded. The best way to handle that is to know what data is going to be loaded, but that is not always easy or possible. An alternative is heavy mocking with will take you down the setup hell road, is often not a good choice at all. Using proxies, it is possible to win on both aspects.
 
 ```ruby
-it 'loads the actual user' do
-  capture_result_from(User, :load, into: :user)
+it 'can check that the correct data is used (using and_after_calling_original)' do
+  user = nil
+  allow(User).to receive(:load).and_after_calling_original { |result| user = result }
+
+  controller.login('joe', 'secret')
+
+  expect(response).to include(user.created_at.to_s)
+end
+
+it 'can check that the correct data is used (using and_capture_result_into)' do
+  allow(User).to receive(:load).and_capture_result_into(self, :user)
 
   controller.login('joe', 'secret')
 
-  expect(response).to include(@user.login_count)
+  expect(response).to include(@user.created_at.to_s)
+end
+
+it 'can check that the correct data is used (using and_collect_results_into)' do
+  users = []
+  allow(User).to receive(:load).and_collect_results_into(users)
+
+  controller.login('joe', 'secret')
+
+  expect(response).to include(users.first.created_at.to_s)
 end
 ```
 
-### Simulate unreliable network with on_call_to
+### Simulate unreliable network
+
+In this case, you might want to fail a call from time to time, and call the original otherwise. This should not require complex mock setup.
 
 ```ruby
 it 'retries on error' do
    i = 0
-   Resource.on_call_to(:get) do |*args|
+   allow(Resource).to receive(:get).and_before_calling_original { |*args|
       i++
       raise RuntimeError.new if i % 3==0
-   end
+   }
 
    resources = Resource.get_at_least(10)
 
@@ -69,21 +108,23 @@ it 'retries on error' do
 end
 ```
 
-### Setup deep stubs with proxy_chain
+### Shortcut a long deep call
+
+Sometimes, you want to mock a particular method of some particular object. RSpec provides ```receive_message_chain``` just for that, but it creates a full mock object which will fail if sent another message. You'd ratherwant this object to otherwise behave normally, that's what you get with nested proxies.
 
 ```ruby
 it 'rounds the completion ratio' do
-   RenderingTask.proxy_chain(:load, :completion_ratio) {|s| s.and_return(0.2523) }
+   Allow(RenderingTask).to proxy_message_chain("load.completion_ratio") {|s| s.and_return(0.2523) }
 
-   renderingController.show
+   controller.show
 
    expect(response).to include('25%')
 end
 ```
 
-### Get best of both worlds with in memory databases
+### CAUTION : {...} vs do...end
 
-Combine proxies with an inmemory database (like SQLite) while testing, and you'll get clear, straightforward and fast tests !
+In ruby, the convention is to use {...} blocks for one liners, and do...end otherwise. Unfortunately, the two don't have the same precedence, which means that they don't exactly work the same way. RSpecProxies in particular does not support do...end out of the box. That's why all the examples above use {...}, even for multi lines blocks.
 
 ## Contributing
 
@@ -92,3 +133,14 @@ Combine proxies with an inmemory database (like SQLite) while testing, and you'l
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+### A word on docker and docker-compose
+
+If you want to contribute to RSpecProxies, you can make use of the docker-compose configuration to quickly setup an isolated ruby environment. Make sure you have [docker](https://docs.docker.com/engine/installation/) and [docker-compose](https://docs.docker.com/compose/install/) installed, then type :
+
+```bash
+docker-compose run rubybox
+bundle install
+```
+
+and you should be in a brand new container, ready to hack.

data/docker-compose.yml

@@ -0,0 +1,11 @@
+rubybox:
+  build: .
+  command: bash
+  working_dir: /usr/src/app
+  environment:
+  #  PORT: 8080
+    BUNDLE_PATH: 'vendor/bundle'
+  # ports:
+  #   - '8080:8080'
+  volumes:
+    - '.:/usr/src/app'

data/lib/rspecproxies.rb

@@ -2,3 +2,4 @@
 
 require "rspecproxies/version"
 require "rspecproxies/proxies"
+require "rspecproxies/proxy_chains"

data/lib/rspecproxies/proxies.rb

@@ -1,73 +1,42 @@
 # -*- encoding: utf-8 -*-
 
-class Object
-
-  include RSpec::Mocks::ExampleMethods
-
-  # Will call the given block with it's result every time the method
-  # returns
-  def on_result_from(method_name)
-    stock_response = self.original_response(method_name)
-
-    allow(self).to receive(method_name) do |*args, &block|
-      result = stock_response.call(*args, &block)
-      yield result
-      result
-    end
-  end
-
-  # Will capture all the results of the method into the returned
-  # array
-  def capture_results_from(method_name)
-    all_results = []
-    on_result_from(method_name) {|result| all_results << result }
-    all_results
-  end
-
-  # Will capture (or override) result from the target's method in
-  # the details[:into] instance variable
-  def capture_result_from(target, method_name, details)
-    into = details[:into]
-    target.on_result_from(method_name) {|result| instance_variable_set("@#{into}", result)}
-  end
-
-  # Will call the given block with all the actual arguments every time
-  # the method is called
-  def on_call_to(method_name)
-    stock_response = self.original_response(method_name)
-
-    allow(self).to receive(method_name) do |*args, &block|
-      yield *args
-      stock_response.call(*args, &block)
+module RSpecProxies
+  module Proxies
+
+    # Will call the given block with all the actual arguments every time
+    # the method is called
+    def and_before_calling_original
+      self.and_wrap_original do |m, *args, &block|
+        yield *args
+        m.call(*args, &block)
+      end
     end
 
-  end
-
-  # Sets up proxies all down the selector chain, until the last where
-  # a simple method stub is created and on which the block is called.
-  # Allows to set up stub chains quickly and safely.
-  def proxy_chain(*selectors, &block)
-    if selectors.count == 1
-      final_stub = allow(self).to receive(selectors.first)
-      block.call(final_stub) unless block.nil?
-    else
-      self.on_result_from(selectors.first) do |result|
-        result.proxy_chain(*selectors[1..-1], &block)
+    # Will call the given block with it's result every time the method
+    # returns
+    def and_after_calling_original
+      self.and_wrap_original do |m, *args, &block|
+        result = m.call(*args, &block)
+        yield result
+        result
       end
     end
-  end
 
-  protected
+    # Will capture all the results of the method into the given
+    # array
+    def and_collect_results_into(collector)
+      self.and_after_calling_original { |result| collector << result }
+    end
 
-  # Lambda that calls the original implementation of a method
-  def original_response(method_name)
-    if self.methods.include?(method_name)
-      self.method(method_name)
-    else
-      lambda do |*args, &block|
-        self.send(:method_missing, method_name, *args, &block)
+    # Will capture (or override) result from the target's method in
+    # the specified instance variable of target
+    def and_capture_result_into(target, instance_variable_name)
+      self.and_after_calling_original do |result|
+        target.instance_variable_set("@#{instance_variable_name}", result)
       end
     end
-  end
 
+  end
 end
+
+RSpec::Mocks::Matchers::Receive.include(RSpecProxies::Proxies)

data/lib/rspecproxies/proxy_chains.rb

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+
+module RSpecProxies
+
+  module ProxyChains
+
+    # Sets up proxies all down the selector chain, until the last where
+    # a simple method stub is created and on which the block is called.
+    # Allows to set up stub chains quickly and safely.
+    #
+    # message_chain : a dot separated message chain, like the standard
+    # message_chain expectation
+    def proxy_message_chain(message_chain, &last_proxy_setup_block)
+      proxy_message_chain_a((message_chain.split('.').map &:intern), &last_proxy_setup_block)
+    end
+
+    # Same as #proxy_message_chain but using an array of symbols as
+    # message_chain instead of a dot separated string
+    def proxy_message_chain_a(messages, &last_proxy_setup_block)
+      first_message = messages.first
+      return last_proxy_setup_block.call(receive(first_message)) if messages.size == 1
+
+      receive(first_message).and_wrap_original do |m, *args, &original_block|
+        result = m.call(*args, &original_block)
+        allow(result).to proxy_message_chain_a(messages.drop(1), &last_proxy_setup_block)
+        result
+      end
+    end
+
+  end
+
+end
+
+RSpec::Core::ExampleGroup.include(RSpecProxies::ProxyChains)

data/lib/rspecproxies/version.rb

@@ -1,5 +1,5 @@
 # -*- encoding: utf-8 -*-
 
 module RSpecProxies
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

data/rspecproxies.gemspec

@@ -18,11 +18,10 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "rspec", "~> 3.0"
+  spec.add_dependency "rspec", "~> 3.5"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "rake"
   spec.add_development_dependency "guard-rspec"
   spec.add_development_dependency "codeclimate-test-reporter"
 end

data/spec/rspecproxies/proxies_spec.rb

@@ -52,16 +52,24 @@ module RSpecProxies
 
     it 'hooks on return from a method' do
       user = nil
-
-      User.on_result_from(:load) {|u| user = u}
+      allow(User).to receive(:load).and_after_calling_original {|u| user = u}
 
       @controller.render('Joe')
 
       expect(user).to eq(User.new('Joe'))
     end
 
+    it 'calls the original method with the given block when hooking on return' do
+      allow(Array).to receive(:new).and_after_calling_original {}
+
+      array = Array.new(2) { 4 }
+
+      expect(array).to eq([4,4])
+    end
+
     it 'has a shortcut to collect return values from a method' do
-      users = User.capture_results_from(:load)
+      users = []
+      allow(User).to receive(:load).and_collect_results_into(users)
 
       @controller.render('Joe')
       @controller.render('Jim')
@@ -70,7 +78,7 @@ module RSpecProxies
     end
 
     it 'has a shortcut to collect the latest return value from a method' do
-      capture_result_from(User, :load, into: :user)
+      allow(User).to receive(:load).and_capture_result_into(self, :user)
 
       html = @controller.render('Joe')
 
@@ -78,20 +86,38 @@ module RSpecProxies
     end
 
     it 'hooks on arguments before a method call' do
-      User.on_call_to(:load) do |name|
+      allow(User).to receive(:load).and_before_calling_original { |name|
         raise RuntimeError.new if name == 'Jim'
-      end
+      }
 
       expect(@controller.render('Joe')).not_to be_nil
       expect{@controller.render('Jim')}.to raise_error(RuntimeError)
     end
 
-    it "can setup deep stubs on yet unloaded instances" do
-      User.proxy_chain(:load, :url) {|s| s.and_return('http://pirates.net')}
+    it 'calls the original method with the given block when hooking on arguments' do
+      allow(Array).to receive(:new).and_before_calling_original {}
+
+      array = Array.new(2) { 4 }
+
+      expect(array).to eq([4,4])
+    end
+
+    it 'can setup deep stubs on yet unloaded instances' do
+      puts self.class.superclass
+
+      allow(User).to proxy_message_chain("load.url") {|s| s.and_return('http://pirates.net')}
 
       html = @controller.render('Jack')
 
       expect(html).to include('http://pirates.net')
     end
+
+    it 'calls original methods with the given block when creating deep proxies' do
+      allow(Array).to proxy_message_chain('new.map') { |s| s.and_call_original }
+
+      array = Array.new(2) { 4 }.map {|i| i+1}
+
+      expect(array).to eq([5,5])
+    end
   end
 end

metadata

@@ -1,120 +1,83 @@
 --- !ruby/object:Gem::Specification
 name: rspecproxies
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Philou
 autorequire: 
 bindir: bin
-cert_chain:
-- |
-  -----BEGIN CERTIFICATE-----
-  MIIDkjCCAnqgAwIBAgIBATANBgkqhkiG9w0BAQUFADBHMRkwFwYDVQQDDBBwaGls
-  aXBwZS5ib3VyZ2F1MRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/Is
-  ZAEZFgNjb20wHhcNMTMwOTIzMTEwOTA3WhcNMTQwOTIzMTEwOTA3WjBHMRkwFwYD
-  VQQDDBBwaGlsaXBwZS5ib3VyZ2F1MRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzAR
-  BgoJkiaJk/IsZAEZFgNjb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
-  AQC8CpoqZwEbzXr55EUxdSplgn0MYZ9xPGO/XmRa8bD63n+JYWF0AS+mj452ZY18
-  rwM+yKrKhtsA+aJJdlOafgIUnY5SrZOr7v7kgc6T2YNoUj+M00Um2jv+shQbOtV6
-  qGp0Jw1HfPNUMVa+3pXZyAGCecN6rTnsZJIuW6KNaJUq6lEMVXanoTHgAKrH5aHd
-  Y6ofwQL86d6LDkC1S4p86iMUWvF34w8h5ItVo+JKlPRR22rzsK/ZKgNH3lfjbS6i
-  JWqPva70rL2xz5kCVn6DL7XhNZtqnAO4kvCQyQeWezvcoGXEnbHacKky7B+/WKec
-  OIWEwedl6j+X0OD5OYki3QaTAgMBAAGjgYgwgYUwCQYDVR0TBAIwADALBgNVHQ8E
-  BAMCBLAwHQYDVR0OBBYEFJnLz40Onu/dfpLSipU5FgTy6WLmMCUGA1UdEQQeMByB
-  GnBoaWxpcHBlLmJvdXJnYXVAZ21haWwuY29tMCUGA1UdEgQeMByBGnBoaWxpcHBl
-  LmJvdXJnYXVAZ21haWwuY29tMA0GCSqGSIb3DQEBBQUAA4IBAQBGoH72KWYACGZl
-  cMHMJ9d/DRU7rynJ8c4xuuM4c3Ri8bGPqI/a1BAp4QPJApS4+ANXXJ220hslrekP
-  9/ExEKFiqiywh1clih9ttuN4cHqJzCP6QHqJznQrvaYToZLxGARDf3Mwz4mFSh4W
-  snSep53DZ1vrY2Gzmig/4PuBF4q3nhwPgxV6H3SH4/Py7QF5COZPQlCdBwPYczqW
-  XxIbXhRVXcgjBHT0w2HsXkOwmmYvBzbrfqtTx5NswwHcIeQZB/NID7berIf9awx3
-  yLcl1cmm5ALtJ/+Bkkmp0i4amXeTDMvq9r8PBsVsQwxYOYJBP+Umxz3PX6HjFHrQ
-  XdkXx3oZ
-  -----END CERTIFICATE-----
-date: 2014-08-24 00:00:00.000000000 Z
+cert_chain: []
+date: 2016-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.5'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: codeclimate-test-reporter
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Proxy doubles for RSpec
@@ -124,16 +87,20 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- DayBook.org
+- Dockerfile
 - Gemfile
 - Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- docker-compose.yml
 - lib/rspecproxies.rb
 - lib/rspecproxies/proxies.rb
+- lib/rspecproxies/proxy_chains.rb
 - lib/rspecproxies/version.rb
 - rspecproxies.gemspec
 - spec/rspecproxies/proxies_spec.rb
@@ -148,17 +115,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.6.4
 signing_key: 
 specification_version: 4
 summary: Special RSpec extensions to simplify mocking by providing proxies