rspec-subject_call 1.0.0

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format d

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+#gem 'pry-debugger'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,14 @@
+PATH
+  remote: .
+  specs:
+    rspec-subject_call (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rspec-subject_call!

data/README.md

@@ -0,0 +1,115 @@
+# RSpec Subject Call
+
+This gem permits succinct one liner syntax in situations that currently require
+more than one line of code. It's for impatient people who use RSpec and like
+saving keystrokes.
+
+## The Situation
+
+There are different types of methods I sometimes need to test. [[1]]
+
+A **query** performs a calculation and returns a value, like `sum`.
+
+A **command** does one thing. Often it changes one piece of state.
+e.g. `x=` or `print_document`.
+
+A method may also have a number of **side effects** which you *may* wish to
+make assertions about, such as caching, keeping counts or raising exceptions.
+
+To illustrate, here is a class that has all these types of methods.
+
+```ruby
+class A
+  attr :x
+
+  def initialize(args = {})
+    @b = args[:b]
+    @x = 0
+  end
+
+  def query
+    1
+  end
+
+  def command
+    @x = 1
+  end
+
+  def query_command
+    @x = 1
+    1
+  end
+
+  def query_command_side_effect
+    @b.command
+    @x = 1
+    1
+  end
+end
+
+class B
+  def command
+  end
+end
+```
+
+Note that `query_command_side_effect` does ALL the things. So that is a good
+method to try testing elegantly. If we can test that elegantly, we can test
+anything elegantly. Right?
+
+With vanilla RSpec, I might test this method like this:
+
+```ruby
+describe A do
+  let(:a) { A.new(b: b) }
+  let(:b) { double('b').as_null_object }
+
+  describe '#query_command_side_effect' do
+    it 'should return 1' do
+      a.query_command_side_effect.should == 1
+    end
+
+    it 'should update x' do
+      expect { a.query_command_side_effect }.to change(a, :x)
+    end
+
+    it 'should call command on b' do
+      b.should_receive(:command).once
+      a.query_command_side_effect
+    end
+  end
+end
+```
+
+But I feel as though this is more typing that I would like and could be DRYed
+up. For example, `a.query_command_side_effect` is repeated three times.
+
+## The Subject Call Solution
+
+This is how I would like to test this tricky method:
+
+```ruby
+require 'rspec/subject_call'
+
+describe A do
+  let(:a) { A.new(b: b) }
+  let(:b) { double('b').as_null_object }
+
+  describe '#query_command_side_effect' do
+    subject { a.query_command_side_effect }
+    it { should == 1 }
+    call { should change(a, :x) }
+    call { should meet_expectations { b.should_receive(:command) } }
+  end
+end
+```
+
+In the above example, `it` is short for the return value of the method under
+test, and `call` is a lambda containing the subject, suitable for use with
+`change` and `raise_error` and any other matcher that works with lambdas,
+already packaged up for you and ready to use.
+
+With this gem, the above example passes.
+
+
+[1]: http://en.wikipedia.org/wiki/Command%E2%80%93query_separation "Command-Query Separation"

data/lib/rspec/subject_call/matchers/meet_expectations_matcher.rb

@@ -0,0 +1,28 @@
+module RSpec
+  module SubjectCall
+    module Matchers
+      # A general purpose matcher that inverts order of operations
+      # allowing for one liners involving mock expectations.
+      class MeetExpectationsMatcher
+        def initialize(&block)
+          @should_receives = block
+        end
+
+        def matches?(subject)
+          @should_receives.call # e.g. x.should_receive(:y)
+          subject.call # execute the subject (assumed to be a Proc)
+        end
+
+        def description
+          'met expectations'
+        end
+      end
+    end
+  end
+
+  module Matchers
+    def meet_expectations(&block)
+      ::RSpec::SubjectCall::Matchers::MeetExpectationsMatcher.new(&block)
+    end
+  end
+end

data/lib/rspec/subject_call/matchers/return_value_matcher.rb

@@ -0,0 +1,24 @@
+require 'rspec/matchers/pretty'
+require 'rspec/matchers/built_in'
+
+module RSpec
+  module SubjectCall
+    module Matchers
+      class ReturnValueMatcher < RSpec::Matchers::BuiltIn::Eq
+        def matches?(subject)
+          @actual = subject.call
+        end
+
+        def description
+          "return #{expected.inspect}"
+        end
+      end
+    end
+  end
+
+  module Matchers
+    def return_value(expected)
+      ::RSpec::SubjectCall::Matchers::ReturnValueMatcher.new(expected)
+    end
+  end
+end

data/lib/rspec/subject_call/version.rb

@@ -0,0 +1,5 @@
+module RSpec
+  module SubjectCall
+    VERSION = '1.0.0'
+  end
+end

data/lib/rspec/subject_call.rb

@@ -0,0 +1,99 @@
+require 'rspec/subject_call/matchers/meet_expectations_matcher'
+require 'rspec/subject_call/matchers/return_value_matcher'
+
+module RSpec
+  module SubjectCall
+    module ExampleGroupClassMethods
+      # Define a method +subject+ for use inside examples, and also a method
+      # +call+ which returns a lambda containing the subject, suitable for use
+      # with matchers that take lambdas.
+      #
+      # e.g.
+      #
+      #    subject { obj.my_method }
+      #
+      #    it { should == some_result }
+      #
+      #    it 'should change something, should syntax' do
+      #       call.should change{something}
+      #    end
+      #
+      #    it 'should change something, expect syntax' do
+      #       expect(call).to change{something}
+      #    end
+      #
+      def subject(name=nil, &block)
+        if block
+          define_method(:call_subject) do
+            instance_eval(&block)
+          end
+          define_method(:call) do
+            lambda { call_subject }
+          end
+        end
+
+        # Do the things subject normally does.
+        super(name, &block)
+      end
+
+      # Allow for syntax similar to +its+:
+      #
+      #   its(:my_method) { should == 1 }
+      #   calling(:my_method) { should change{something} }
+      #
+      def calling(method_name, &block)
+        describe(method_name) do
+          let(:__its_subject) do
+            method_chain = method_name.to_s.split('.')
+            lambda do
+              method_chain.inject(subject) do |inner_subject, attr|
+                inner_subject.send(attr)
+              end
+            end
+          end
+
+          def should(matcher=nil, message=nil)
+            RSpec::Expectations::PositiveExpectationHandler.handle_matcher(__its_subject, matcher, message)
+          end
+
+          def should_not(matcher=nil, message=nil)
+            RSpec::Expectations::NegativeExpectationHandler.handle_matcher(__its_subject, matcher, message)
+          end
+
+          example(&block)
+        end
+      end
+
+      # Like +it+ but sets the implicit subject to the lambda you supplied when
+      # defining the subject, so that you can use it with matchers that take
+      # blocks like +change+:
+      #
+      #   call { should change{something} }
+      #
+      def call(desc=nil, *args, &block)
+        # Create a new example, where the subject is set to the subject block,
+        # as opposed to its return value.
+        example do
+          self.class.class_eval do
+            define_method(:subject) do
+              if defined?(@_subject_call)
+                @_subject_call
+              else
+                @_subject_call = call
+              end
+            end
+          end
+          instance_eval(&block)
+        end
+      end
+    end
+  end
+end
+
+module RSpec
+  module Core
+    class ExampleGroup
+      extend ::RSpec::SubjectCall::ExampleGroupClassMethods
+    end
+  end
+end

data/rspec-subject_call.gemspec

@@ -0,0 +1,17 @@
+require File.expand_path('lib/rspec/subject_call/version', File.dirname(__FILE__))
+
+Gem::Specification.new do |s|
+  s.name                      = 'rspec-subject_call'
+  s.version                   = RSpec::SubjectCall::VERSION
+  s.platform                  = Gem::Platform::RUBY
+  s.authors                   = [ 'Gregory McIntyre' ]
+  s.email                     = [ 'greg@gregorymcintyre.com' ]
+  s.homepage                  = 'http://github.com/rails-oceania/rspec-subject_call'
+  s.description               = 'Enable reuse of the subject for use with expect..to..change and my_double.should_receive'
+  s.summary                   = "rspec-subject_call-#{s.version}"
+  s.required_rubygems_version = '> 1.3.6'
+
+  s.files = `git ls-files`.split($\)
+  s.executables = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+  s.require_path = 'lib'
+end

data/spec/readme_example_spec.rb

@@ -0,0 +1,66 @@
+class A
+  attr :x
+
+  def initialize(args = {})
+    @b = args[:b]
+    @x = 0
+  end
+
+  def query
+    1
+  end
+
+  def command
+    @x = 1
+  end
+
+  def query_command
+    @x = 1
+    1
+  end
+
+  def query_command_side_effect
+    @b.command
+    @x = 1
+    1
+  end
+end
+
+class B
+  def command
+  end
+end
+
+describe A do
+  let(:a) { A.new(b: b) }
+  let(:b) { double('b').as_null_object }
+
+  describe '#query_command_side_effect' do
+    it 'should return 1' do
+      a.query_command_side_effect.should == 1
+    end
+
+    it 'should update x' do
+      expect { a.query_command_side_effect }.to change(a, :x)
+    end
+
+    it 'should call command on b' do
+      b.should_receive(:command).once
+      a.query_command_side_effect
+    end
+  end
+end
+
+require 'rspec/subject_call'
+
+describe A do
+  let(:a) { A.new(b: b) }
+  let(:b) { double('b').as_null_object }
+
+  describe '#query_command_side_effect' do
+    subject { a.query_command_side_effect }
+    it { should == 1 }
+    call { should change(a, :x) }
+    call { should meet_expectations { b.should_receive(:command) } }
+  end
+end

data/spec/rspec_subject_call_spec.rb

@@ -0,0 +1,127 @@
+class A
+  attr_reader :counter
+
+  def initialize(args = {})
+    @b = args[:b]
+    @counter = 0
+  end
+
+  def query
+    1
+  end
+
+  def command
+    @b.command
+  end
+
+  def query_command
+    @b.command
+    1
+  end
+
+  def query_command_side_effect
+    @b.command
+    @counter += 1
+    1
+  end
+end
+
+class B
+  def command
+  end
+end
+
+# ----------------------------------------------------------------------
+
+require 'rspec/subject_call'
+
+describe A do
+  subject(:a) { A.new(b: b) }
+  let(:b) { double('b').as_null_object }
+
+  describe '#query' do
+    it 'should return 1' do
+      a.query.should == 1
+    end
+  end
+
+  describe '#command' do
+    it 'should call command on b' do
+      b.should_receive(:command).once
+      a.command
+    end
+  end
+
+  describe '#query_command' do
+    it 'should return 1' do
+      a.query_command.should == 1
+    end
+
+    it 'should call command on b' do
+      b.should_receive(:command).once
+      a.query_command
+    end
+  end
+
+  describe '#query_command_side_effect - vanilla' do
+    it 'should return 1' do
+      a.query_command_side_effect.should == 1
+    end
+
+    it 'should call command on b' do
+      b.should_receive(:command).once
+      a.query_command_side_effect
+    end
+
+    it 'should increment counter' do
+      expect { a.query_command_side_effect }.to change(a, :counter).by(1)
+    end
+  end
+
+  describe '#query_command_side_effect - subject_call with custom doc strings' do
+    subject { a.query_command_side_effect }
+
+    it 'should return 1' do
+      subject.should == 1
+    end
+
+    it 'should call b.command' do
+      b.should_receive(:command)
+      call_subject
+    end
+
+    it 'should increment counter by 1' do
+      call { should change(a, :counter).by(1) }
+    end
+  end
+
+  describe '#query_command_side_effect - subject_call with one liners' do
+    subject { a.query_command_side_effect }
+    it { should == 1 }
+    call { should change(a, :counter).by(1) }
+    call { should meet_expectations { b.should_receive(:command) } }
+  end
+
+  describe '#query_command_side_effect - subject_call, its style' do
+    subject { a }
+    its(:query_command_side_effect) { should == 1 }
+    calling(:query_command_side_effect) { should change(a, :counter).by(1) }
+    calling(:query_command_side_effect) { should meet_expectations { b.should_receive(:command) } }
+  end
+
+  describe '#query_command_side_effect - expect syntax' do
+    subject { a.query_command_side_effect }
+
+    it 'should return 1' do
+      expect(subject).to eq(1)
+    end
+
+    it 'should call b.command' do
+      expect(call).to meet_expectations { b.should_receive(:command) }
+    end
+
+    it 'should increment counter by 1' do
+      expect(call).to change(a, :counter).by(1)
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: rspec-subject_call
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Gregory McIntyre
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-04 00:00:00.000000000 Z
+dependencies: []
+description: Enable reuse of the subject for use with expect..to..change and my_double.should_receive
+email:
+- greg@gregorymcintyre.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .rspec
+- Gemfile
+- Gemfile.lock
+- README.md
+- lib/rspec/subject_call.rb
+- lib/rspec/subject_call/matchers/meet_expectations_matcher.rb
+- lib/rspec/subject_call/matchers/return_value_matcher.rb
+- lib/rspec/subject_call/version.rb
+- rspec-subject_call.gemspec
+- spec/readme_example_spec.rb
+- spec/rspec_subject_call_spec.rb
+homepage: http://github.com/rails-oceania/rspec-subject_call
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: rspec-subject_call-1.0.0
+test_files: []
+has_rdoc: