saharspec 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 69a3d4d52b75ffe4622413b927337a741b810c57
-  data.tar.gz: 7da973ac28887c0fbd3c65a7aaad6bb6a5140e63
+  metadata.gz: a363bdb21050423225b98a8dae3d2f8861947426
+  data.tar.gz: 3ace51cf8d457d79caa8fe2c3b12e144c1a5a50a
 SHA512:
-  metadata.gz: 02fb0e99a0b46ace2311deed7d21132582c11f8d5c04727d211f28d5725615eed36ce9e942ec7a31a9767b23b137918eac650598869ed6e01fce79bf503ab43a
-  data.tar.gz: b112f9ea6892c954de423ce07076c530f46c66549d2201d06fe4233b18f933a6505110f148ca4b14ad139e357c0ca3ef26fb106437749d9f23ca584f7be6c987
+  metadata.gz: a6b1f390d030eeebbaa9ece4efbc64176e24cfd32d748e044a1d47fd8f7862b5a966a83fdcb64474b28496f0d9ea97150e70d725c0b99d9ed47d74d26d4f60b2
+  data.tar.gz: fbf40cbc81e264aeb3f78d14c5c934a3c501e3586e851c32718e4cd2be9eaedd58f5f3e2fc5c4664159bb1abec90b065fb907589bde3395a4b62ae89083d8180

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Saharspec history
+
+## 0.0.3 -- 2017-11-06
+
+* Introduce new `its`-family addition: `its_call(*args)`
+```ruby
+let(:array) { %i[a b c] }
+subject { array.method(:delete_at) }
+its_call(1) { is_expected.to change(array, :length).by(-1) }
+```
+* Introduce new `ret` matcher ("block is expected to return"), useful in context when block is your
+primary subject:
+
+```ruby
+let(:array) { %i[a b c] }
+subject { array.method(:delete_at) }
+its_call(1) { is_expected.to ret(:b).and change(array, :length).by(-1) }
+```
+* Introduce experimental `dont` matcher combiner (instead of `RSpec.define_negated_matcher`), used
+  as `expect { something }.to dont.change { anything }`;
+* **Breaking**: rename `its_call`→`its_block` (because the name was needed for other means).
+
+## 0.0.2 -- 2017-09-01
+
+* Make `send_message` composable;
+* Add `Util#multiline`.
+
+## 0.0.1 -- 2017-08-14
+
+Initial!

data/README.md

@@ -50,6 +50,58 @@ its_call { is_expected.to send_message(Net::HTTP, :get).with('http://google.com'
 Note: there is [reasons](https://github.com/rspec/rspec-expectations/issues/934) why it is not in rspec-mocks, though, not very persuative for
 me.
 
+#### `expect { block }.to ret(value)` matcher
+
+Checks whether `#call`-able subject (block, method, command object), when called, return value matching
+to expected.
+
+Useful when this callable subject is your primary one:
+
+```ruby
+# before: option 1. subject is value
+subject { 2 + x }
+
+context 'when numeric' do
+  let(:x) { 3 }
+  it { is_expected.to eq 5 } # DRY
+end
+
+context 'when incompatible' do
+  let(:x) { '3' }
+  it { expect { subject }.to raise_error } # not DRY
+end
+
+# option 2. subject is block
+subject { -> {2 + x } }
+
+context 'when incompatible' do
+  let(:x) { '3' }
+  it { is_expected.to raise_error } # DRY
+end
+
+context 'when numeric' do
+  let(:x) { 3 }
+  it { expect(subject.call).to eq 5 } # not DRY
+end
+
+# after
+require 'saharspec/matchers/ret'
+
+subject { -> { 2 + x } }
+
+context 'when numeric' do
+  let(:x) { 3 }
+  it { is_expected.to ret 5 } # DRY: notice `ret`
+end
+
+context 'when incompatible' do
+  let(:x) { '3' }
+  it { is_expected.to raise_error } # DRY
+end
+```
+
+Plays really well with `its_call` shown below.
+
 #### `eq_multiline(text)` matcher
 
 Dedicated to checking some multiline text generators.
@@ -81,6 +133,23 @@ require 'saharspec/matchers/eq_multiline'
 ```
 (empty lines before/after are removed, text deindented up to `|` sign)
 
+### `dont`: matcher negation
+
+Another (exprimental) attempt to get rid of `define_negated_matcher`. `dont` is not 100% grammatically
+correct, yet short and readable enought. It just negates attached matcher.
+
+```ruby
+# before
+RSpec.define_negated_matcher :not_change, :change
+
+it { expect { code }.to do_stuff.and not_change(obj, :attr) }
+
+# after: no `define_negated_matcher` needed
+require 'saharspec/matchers/dont'
+
+it { expect { code }.to do_stuff.and dont.change(obj, :attr) }
+```
+
 ### `its`-addons
 
 **Notice**: There are different opinions on usability/reasonability of `its(:attribute)` syntax,
@@ -104,18 +173,59 @@ require 'saharspec/its/map'
 its_map(:text) { are_expected.to all not_be_empty }
 ```
 
-#### `its_call`
+#### `its_block`
+
+Allows to DRY-ly refer to "block that calculates subject".
 
 ```ruby
 subject { some_operation_that_may_fail }
 
 # before
-it { expect { subject }.to raise_error(...) }
+context 'success' do
+  it { is_expected.to eq 123 }
+end
+
+context 'fail' do
+  it { expect { subject }.to raise_error(...) }
+end
+
+# after
+require 'saharspec/its/block'
+
+its_block { is_expected.to raise_error(...) }
+```
+
+#### `its_call`
+
+Allows to DRY-ly test callable object with different arguments. Plays well with forementioned `ret`
+matcher.
+
+Before:
+
+```ruby
+# before
+describe '#delete_at' do
+  let(:array) { %i[a b c] }
+
+  it { expect(array.delete_at(1) }.to eq :b }
+  it { expect(array.delete_at(8) }.to eq nil }
+  it { expect { array.delete_at(1) }.to change(array, :length).by(-1) }
+  it { expect { array.delete_at(:b) }.to raise_error TypeError }
+end
 
 # after
 require 'saharspec/its/call'
 
-its_call { is_expected.to raise_error(...) }
+describe '#delete_at' do
+  let(:array) { %i[a b c] }
+
+  subject { array.method(:delete_at) }
+
+  its_call(1) { is_expected.to ret :b }
+  its_call(1) { is_expected.to change(array, :length).by(-1) }
+  its_call(8) { is_expected.to ret nil }
+  its_call(:b) { is_expected.to raise_error TypeError }
+end
 ```
 
 ## State & future

data/lib/saharspec/its.rb

@@ -1,10 +1,15 @@
 module Saharspec
   # Wrapper module for all `its_*` RSpec additions.
   #
-  # See {Map#its_map #its_map} and {Call#its_call #its_call}
+  # See:
+  #
+  # * {Map#its_map #its_map}
+  # * {Block#its_block #its_block}
+  # * {Call#its_call #its_call}
   module Its
   end
 end
 
 require_relative 'its/map'
+require_relative 'its/block'
 require_relative 'its/call'

data/lib/saharspec/its/block.rb

@@ -0,0 +1,56 @@
+module Saharspec
+  module Its
+    module Block
+      # Creates nested example which converts current subject to a block-subject.
+      #
+      # @example
+      #
+      #    subject { calc_something(params) }
+      #
+      #    # without its_block
+      #    context 'with this params' do
+      #      it { expect { subject }.to change(some, :value).by(1) }
+      #    end
+      #
+      #    context 'with that params' do
+      #      it { expect { subject }.to raise_error(SomeError) }
+      #    end
+      #
+      #    # with its_block
+      #    context 'with this params' do
+      #      its_block { is_expected.to change(some, :value).by(1) }
+      #    end
+      #
+      #    context 'with that params' do
+      #      its_block { is_expected.to raise_error(SomeError) }
+      #    end
+      #
+      # @param options Options (metadata) that can be passed to usual RSpec example.
+      # @param block [Proc] The test itself. Inside it, `is_expected` is a synonom
+      #   for `expect { subject }`.
+      #
+      def its_block(*options, &block)
+        # rubocop:disable Lint/NestedMethodDefinition
+        describe('as block') do
+          let(:__call_subject) do
+            -> { subject }
+          end
+
+          def is_expected
+            expect(__call_subject)
+          end
+
+          example(nil, *options, &block)
+        end
+        # rubocop:enable Lint/NestedMethodDefinition
+      end
+    end
+  end
+end
+
+RSpec.configure do |rspec|
+  rspec.extend Saharspec::Its::Block
+  rspec.backtrace_exclusion_patterns << %r{/lib/saharspec/its/block}
+end
+
+RSpec::SharedContext.send(:include, Saharspec::Its::Block)

data/lib/saharspec/its/call.rb

@@ -1,46 +1,41 @@
 module Saharspec
   module Its
     module Call
-      # Creates nested example which converts current subject to a block-subject.
+      # For `#call`-able subject, creates nested example where subject is called with arguments
+      # provided, allowing to apply block matchers like `.to change(something)` or `.to raise_error`
+      # to different calls in a DRY way.
       #
-      # @example
-      #
-      #    subject { calc_something(params) }
+      # Also, plays really well with {RSpec::Matchers#ret #ret} block matcher.
       #
-      #    # without its_call
-      #    context 'with this params'
-      #      it { expect { subject }.to change(some, :value).by(1) }
-      #    end
+      # @example
+      #    let(:array) { %i[a b c] }
       #
-      #    context 'with that params'
-      #      it { expect { subject }.to raise_error(SomeError) }
-      #    end
+      #    describe '#[]' do
+      #      subject { array.method(:[]) }
       #
-      #    # with its_call
-      #    context 'with this params'
-      #      its_call { is_expected.to change(some, :value).by(1) }
+      #      its_call(1) { is_expected.to ret :b }
+      #      its_call(1..-1) { is_expected.to ret %i[b c] }
+      #      its_call('foo') { is_expected.to raise_error TypeError }
       #    end
       #
-      #    context 'with that params'
-      #      its_call { is_expected.to raise_error(SomeError) }
+      #    describe '#push' do
+      #      subject { array.method(:push) }
+      #      its_call(5) { is_expected.to change(array, :length).by(1) }
       #    end
       #
-      # @param options Other options that can be passed to usual RSpec example.
-      # @param block [Proc] The test itself. Inside it, `is_expected` (or `are_expected`) is analog of
-      #   `expect { subject }`.
-      #
-      def its_call(*options, &block)
+      def its_call(*args, &block)
         # rubocop:disable Lint/NestedMethodDefinition
         describe('call') do
           let(:__call_subject) do
-            -> { subject }
+            warn 'No need to use its_call without arguments, just it {} will work' if args.empty?
+            -> { subject.call(*args) }
           end
 
           def is_expected
             expect(__call_subject)
           end
 
-          example(nil, *options, &block)
+          example(nil, &block)
         end
         # rubocop:enable Lint/NestedMethodDefinition
       end

data/lib/saharspec/its/map.rb

@@ -13,7 +13,7 @@ module Saharspec
       #   # with attribute chain
       #   its_map(:'reverse.upcase') { is_expected.to eq %w[TSET EM ESAELP] }
       #
-      #   # with Hash (or any other object re sponding to `#[]`)
+      #   # with Hash (or any other object responding to `#[]`)
       #   subject {
       #     [
       #       {title: 'Slaughterhouse Five', author: {first: 'Kurt', last: 'Vonnegut'}},

data/lib/saharspec/matchers.rb

@@ -1,7 +1,12 @@
 module Saharspec
   # All Saharspec matchers, when required, included into `RSpec::Matchers` namespace.
   #
-  # See {RSpec::Matchers#send_message #send_message} and {RSpec::Matchers#eq_multiline #eq_multiline}.
+  # See:
+  #
+  # * {RSpec::Matchers#dont #dont}
+  # * {RSpec::Matchers#send_message #send_message}
+  # * {RSpec::Matchers#eq_multiline #eq_multiline}
+  # * {RSpec::Matchers#ret #ret}
   #
   module Matchers
   end
@@ -9,3 +14,4 @@ end
 
 require_relative 'matchers/eq_multiline'
 require_relative 'matchers/send_message'
+require_relative 'matchers/ret'

data/lib/saharspec/matchers/dont.rb

@@ -0,0 +1,66 @@
+module Saharspec
+  module Matchers
+    # @private
+    class Not < RSpec::Matchers::BuiltIn::BaseMatcher
+      def initialize
+        @delegator = Delegator.new
+      end
+
+      def description
+        "not #{@matcher.description}"
+      end
+
+      def match(_expected, actual)
+        @matcher or
+          fail(ArgumentError, '`dont` matcher used without any matcher to negate. Usage: dont.other_matcher(args)')
+        !@matcher.matches?(actual)
+      end
+
+      def supports_block_expectations?
+        @matcher.supports_block_expectations?
+      end
+
+      def method_missing(m, *a, &b) # rubocop:disable Style/MethodMissing
+        if @matcher
+          @matcher.send(m, *a, &b)
+        else
+          @matcher = @delegator.send(m, *a, &b)
+        end
+
+        self
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        if @matcher
+          @matcher.respond_to?(method, include_private)
+        else
+          @delegator.respond_to_missing?(method, include_private)
+        end
+      end
+
+      class Delegator
+        include RSpec::Matchers
+      end
+    end
+  end
+end
+
+module RSpec
+  module Matchers
+    # Negates attached matcher, allowing creating negated matchers on the fly.
+    #
+    # While not being 100% grammatically correct, seems to be readable enough.
+    #
+    # @example
+    #   # before
+    #   RSpec.define_negated_matcher :not_change, :change
+    #   it { expect { code }.to do_stuff.and not_change(obj, :attr) }
+    #
+    #   # after: no `define_negated_matcher` needed
+    #   it { expect { code }.to do_stuff.and dont.change(obj, :attr) }
+    #
+    def dont
+      Saharspec::Matchers::Not.new
+    end
+  end
+end

data/lib/saharspec/matchers/eq_multiline.rb

@@ -32,7 +32,7 @@ module RSpec
     #       |end
     #     })
     #
-    # @param [String]
+    # @param expected [String]
     def eq_multiline(expected)
       Saharspec::Matchers::EqMultiline.new(expected)
     end

data/lib/saharspec/matchers/ret.rb

@@ -0,0 +1,82 @@
+module Saharspec
+  module Matchers
+    # @private
+    class Ret
+      include RSpec::Matchers::Composable
+
+      def initialize(expected)
+        @expected = expected
+      end
+
+      def matches?(subject)
+        @subject = subject
+        return false unless subject.respond_to?(:call)
+        @actual = subject.call
+        @expected === @actual # rubocop:disable Style/CaseEquality
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def description
+        "return #{@expected.respond_to?(:description) ? @expected.description : @expected.inspect}"
+      end
+
+      def failure_message
+        "expected to #{description}, " +
+          (@subject.respond_to?(:call) ? "but returned #{@actual.inspect}" : 'but was not callable')
+      end
+
+      def failure_message_when_negated
+        "expected not to #{description}, but returned it"
+      end
+    end
+  end
+end
+
+module RSpec
+  module Matchers
+    # `ret` (short for `return`) checks if provided block **returns** value specified.
+    #
+    # It should be considered instead of simple value matchers (like `eq`) in the situations:
+    #
+    # 1. Several block behaviors tested in the same test, joined with `.and`, or in separate tests
+    # 2. You test what some block or method returns with arguments, using {Call#its_call #its_call}
+    #
+    # Values are tested with `===`, which allows chaining other matchers and patterns to the check.
+    #
+    # @note
+    #   There is a case when `ret` fails: when it is _not the first_ in a chain of matchers joined
+    #   by `.and`. That's not exactly the matchers bug, that's how RSpec works (loses block's return
+    #   value passing the block between matchers)
+    #
+    # @example
+    #    # case 1: block is a subject
+    #    subject { -> { do_something } }
+    #
+    #    it { is_expected.not_to raise_error }
+    #    it { is_expected.to change(some, :value).by(1) }
+    #    it { is_expected.to ret 8 }
+    #
+    #    # or, joined:
+    #    specify {
+    #      expect { do_something }.to ret(8).and change(some, :value).by(1)
+    #    }
+    #
+    #    # case 2: with arguments
+    #    subject { %i[a b c].method(:[]) }
+    #
+    #    its_call(1) { is_expected.to ret :b }
+    #    its_call(1..-1) { is_expected.to ret %i[b c] }
+    #    its_call('foo') { is_expected.to raise_error TypeError }
+    #
+    #    # Note, that values are tested with ===, which means all other matchers could be chained:
+    #    its_call(1) { is_expected.to ret instance_of(Symbol) }
+    #    its_call(1..-1) { is_expected.to ret instance_of(Array).and have_attributes(length: 2) }
+    #
+    def ret(expected)
+      Saharspec::Matchers::Ret.new(expected)
+    end
+  end
+end

data/lib/saharspec/matchers/send_message.rb

@@ -32,7 +32,7 @@ module Saharspec
       end
 
       def times
-        raise NoMethodError unless @times
+        fail NoMethodError unless @times
         self
       end
 
@@ -44,6 +44,11 @@ module Saharspec
         exactly(2)
       end
 
+      def ordered
+        @ordered = true
+        self
+      end
+
       # Matching
       def matches?(subject)
         run(subject)
@@ -78,8 +83,8 @@ module Saharspec
 
       def run(subject)
         @target.respond_to?(@method, true) or
-          raise NoMethodError,
-                "undefined method `#{@method}' for#{@target.inspect}:#{@target.class}"
+          fail NoMethodError,
+               "undefined method `#{@method}' for#{@target.inspect}:#{@target.class}"
         allow(@target).to allower
         subject.call
       end
@@ -95,6 +100,7 @@ module Saharspec
         have_received(@method).tap do |e|
           e.with(*@arguments) if @arguments
           e.exactly(@times).times if @times
+          e.ordered if @ordered
         end
       end
     end
@@ -115,12 +121,14 @@ module RSpec
     #
     #   # after:
     #   require 'saharspec/matchers/send_message'
+    #
     #   it { expect { code_being_tested }.to send_message(double, :fetch).with(something) }
-    #   # after + its_call
-    #   require 'saharspec/its/call'
-    #   subject { code_being_tested }
-    #   its_call { is_expected.to send_message(double, :fetch).with(something) }
     #
+    #   # after + its_block
+    #   require 'saharspec/its/block'
+    #
+    #   subject { code_being_tested }
+    #   its_block { is_expected.to send_message(double, :fetch).with(something) }
     #
     # @param target Object which expects message, double or real object
     # @param method [Symbol] Message being expected

data/lib/saharspec/version.rb

@@ -0,0 +1,9 @@
+module Saharspec
+  # @private
+  MAJOR = 0
+  # @private
+  MINOR = 0
+  # @private
+  PATCH = 3
+  VERSION = [MAJOR, MINOR, PATCH].join('.')
+end

data/saharspec.gemspec

@@ -1,6 +1,8 @@
+require_relative 'lib/saharspec/version'
+
 Gem::Specification.new do |s|
   s.name     = 'saharspec'
-  s.version  = '0.0.2'
+  s.version  = Saharspec::VERSION
   s.authors  = ['Victor Shepelev']
   s.email    = 'zverok.offline@gmail.com'
   s.homepage = 'https://github.com/zverok/saharspec'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: saharspec
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Victor Shepelev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-01 00:00:00.000000000 Z
+date: 2017-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -116,17 +116,22 @@ extra_rdoc_files: []
 files:
 - ".rubocop_todo.yml"
 - ".yardopts"
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - lib/saharspec.rb
 - lib/saharspec/its.rb
+- lib/saharspec/its/block.rb
 - lib/saharspec/its/call.rb
 - lib/saharspec/its/map.rb
 - lib/saharspec/matchers.rb
+- lib/saharspec/matchers/dont.rb
 - lib/saharspec/matchers/eq_multiline.rb
 - lib/saharspec/matchers/request_webmock.rb
+- lib/saharspec/matchers/ret.rb
 - lib/saharspec/matchers/send_message.rb
 - lib/saharspec/util.rb
+- lib/saharspec/version.rb
 - saharspec.gemspec
 homepage: https://github.com/zverok/saharspec
 licenses: