moarspec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cbe02b386d8bb5096462151db51d932f06787af44b10f3710113ca27ce107d91
+  data.tar.gz: 8329a3c29236662afa9614d31094389d13e2ddcc1611b1873dc2c48fa8053b50
+SHA512:
+  metadata.gz: '000817d751bd76bd08cdb817f66f40fb57f93ac39cdf7c666c06fde4837aed7d3df21924e85a79a4932d79bece239315cdc50b3db201ab07a87876847de6132f'
+  data.tar.gz: 4424ee10f7129fe955efb375d50607eb95ac291e58afda48f2f2425c2ca3657e0a37f10c00973239e15a5b1426aebe622aef064c499dc9aad46b5003597fb147

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014-15 Victor 'Zverok' Shepelev
+
+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/config/rubocop-rspec.yml

@@ -0,0 +1,15 @@
+RSpec:
+  Language:
+    Examples:
+      Regular:
+        - its_block
+        - its_call
+        - its_map
+      Skipped:
+        - xits_block
+        - xits_call
+        - xits_map
+      Focused:
+        - fits_block
+        - fits_call
+        - fits_map

data/lib/moarspec/example_groups/instant_context.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Moarspec
+  module ExampleGroups
+    # Provides a shorter way to define a context and its `let` values in one statement.
+    #
+    # @example
+    #   subject { x + y }
+    #
+    #   instant_context 'with numeric values', lets: {x: 1, y: 2} do
+    #     it { is_expected.to eq 3 }
+    #   end
+    #   # or, without an explicit description:
+    #   instant_context lets: {x: 1, y: 2} do
+    #     it { is_expected.to eq 3 }
+    #   end
+    #
+    #   # is equivalent to
+    #
+    #   context 'with numeric values (x=1, y=2)' do
+    #     let(:x) { 1 }
+    #     let(:y) { 2 }
+    #
+    #     it { is_expected.to eq 3 }
+    #   end
+    #
+    #   # without explicit description, it is equivalent to
+    #   context 'with x=1, y=2' do
+    #     # ...
+    #   end
+    #
+    # See also {Moarspec::Its::With#it_with #it_with} for a way to define just one example with
+    # its `let`s.
+    module InstantContext
+      def instant_context(description = nil, lets:, **metadata, &block)
+        full_description = "with #{lets.map { "#{_1}=#{_2.inspect}" }.join(', ')}"
+        full_description = "#{description} (#{full_description})" if description
+        absolute_path, line_number = caller_locations.first.then { [_1.absolute_path, _1.lineno] }
+
+        context full_description, **metadata do
+          # Tricking RSpec to think this context was defined where `instant_context` was called,
+          # so `rspec that_spec.rb:123` knew it is related
+          self.metadata.merge!(absolute_file_path: absolute_path, line_number: line_number)
+
+          lets.each do |name, val|
+            let(name) { val }
+          end
+          instance_eval(&block)
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |rspec|
+  rspec.extend Moarspec::ExampleGroups::InstantContext
+  rspec.backtrace_exclusion_patterns << %r{/lib/moarspec/example_groups/instant_context}
+end

data/lib/moarspec/example_groups.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Moarspec
+  # Wrapper module for all RSpec additions that adjust example groups (`context`) creation.
+  #
+  # ## {InstantContext#instant_context #instant_context}
+  #
+  # ```ruby
+  # subject { x + y }
+  #
+  # instant_context 'with numeric values', lets: {x: 1, y: 2} do
+  #   it { is_expected.to eq 3 }
+  # end
+  # ```
+  #
+  module ExampleGroups
+  end
+end
+
+require_relative 'example_groups/instant_context'

data/lib/moarspec/its/block.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Moarspec
+  module Its
+    module Block
+      # Creates nested example that redefines implicit `is_expected` to use subject as a block.
+      #
+      # @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
+          # FIXME: Not necessary? (Previously, wrapped the subject in lambda, now just repeats it)
+          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 Moarspec::Its::Block
+  rspec.backtrace_exclusion_patterns << %r{/lib/moarspec/its/block}
+end
+
+RSpec::SharedContext.include Moarspec::Its::Block

data/lib/moarspec/its/block_with.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Moarspec
+  module Its
+    module BlockWith
+      # Creates a nested context + example with `let` values defined from the arguments, and
+      # the subject treated as a block.
+      #
+      # @example
+      #
+      #   subject { x + y }
+      #
+      #   its_block_with(x: 1, y: nil) { is_expected.to raise_error }
+      #
+      #   # is equivalent to
+      #
+      #   context "with x=1, y=2" do
+      #     let(:x) { 1 }
+      #     let(:y) { nil }
+      #
+      #     it { expect { subject }.to raise_error }
+      #   end
+      #
+      def its_block_with(**lets, &block)
+        context "with #{lets.map { "#{_1}=#{_2.inspect}" }.join(', ')} as block" do
+          lets.each do |name, val|
+            let(name) { val }
+          end
+
+          def is_expected # rubocop:disable Lint/NestedMethodDefinition
+            expect { subject }
+          end
+
+          example(nil, &block)
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |rspec|
+  rspec.extend Moarspec::Its::BlockWith
+  rspec.backtrace_exclusion_patterns << %r{/lib/moarspec/its/block_with}
+end
+
+RSpec::SharedContext.include Moarspec::Its::BlockWith

data/lib/moarspec/its/call.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Moarspec
+  module Its
+    module Call
+      # 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.
+      #
+      # Also, plays really well with {RSpec::Matchers#ret #ret} block matcher.
+      #
+      # @example
+      #    let(:array) { %i[a b c] }
+      #
+      #    describe '#[]' do
+      #      subject { array.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 }
+      #    end
+      #
+      #    describe '#push' do
+      #      subject { array.method(:push) }
+      #      its_call(5) { is_expected.to change(array, :length).by(1) }
+      #    end
+      #
+      def its_call(*args, **kwargs, &block)
+        # rubocop:disable Lint/NestedMethodDefinition
+        describe("(#{args.map(&:inspect).join(', ')})") do
+          let(:__call_subject) do
+            subject.call(*args, **kwargs)
+          end
+
+          def is_expected
+            expect { __call_subject }
+          end
+
+          example(nil, &block)
+        end
+        # rubocop:enable Lint/NestedMethodDefinition
+      end
+    end
+  end
+end
+
+RSpec.configure do |rspec|
+  rspec.extend Moarspec::Its::Call
+  rspec.backtrace_exclusion_patterns << %r{/lib/moarspec/its/call}
+end
+
+RSpec::SharedContext.include Moarspec::Its::Call

data/lib/moarspec/its/map.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Moarspec
+  module Its
+    module Map
+      # Creates nested example which has current subject mapped
+      # by specified attribute as its subject.
+      #
+      # @example
+      #
+      #   # with attribute
+      #   subject { %w[test me please] }
+      #   its_map(:length) { is_expected.to eq [4, 2, 6] }
+      #
+      #   # with attribute chain
+      #   its_map('reverse.upcase') { is_expected.to eq %w[TSET EM ESAELP] }
+      #
+      #   # with Hash (or any other object responding to `#[]`)
+      #   subject {
+      #     [
+      #       {title: 'Slaughterhouse Five', author: {first: 'Kurt', last: 'Vonnegut'}},
+      #       {title: 'Hitchhickers Guide To The Galaxy', author: {first: 'Duglas', last: 'Adams'}}
+      #     ]
+      #   }
+      #   its_map([:title]) { are_expected.to eq ['Slaughterhouse Five', 'Hitchhickers Guide To The Galaxy'] }
+      #   # multiple attributes for nested hashes
+      #   its_map([:author, :last]) { are_expected.to eq ['Vonnegut', 'Adams'] }
+      #
+      # @param attribute [String, Symbol, Array<String, Symbol>] Attribute name (String or Symbol), attribute chain
+      #   (string separated with dots) or arguments to `#[]` method (Array)
+      # @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 related to result
+      #  of `map`ping the subject.
+      #
+      def its_map(attribute, *options, &block) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:disable Lint/NestedMethodDefinition
+        # TODO: better desciption for different cases
+        describe("map(&:#{attribute})") do
+          let(:__its_map_subject) do
+            if Array === attribute
+              if subject.all? { |s| Hash === s }
+                subject.map do |s|
+                  attribute.inject(s) { |inner, attr| inner[attr] }
+                end
+              else
+                subject.map { |inner| inner[*attribute] }
+              end
+            else
+              attribute_chain = attribute.to_s.split('.').map(&:to_sym)
+              attribute_chain.inject(subject) do |inner_subject, attr|
+                inner_subject.map(&attr)
+              end
+            end
+          end
+
+          def is_expected
+            expect(__its_map_subject)
+          end
+
+          alias_method :are_expected, :is_expected
+
+          options << {} unless options.last.is_a?(Hash)
+
+          example(nil, *options, &block)
+        end
+        # rubocop:enable Lint/NestedMethodDefinition
+      end
+    end
+  end
+end
+
+RSpec.configure do |rspec|
+  rspec.extend Moarspec::Its::Map
+  rspec.backtrace_exclusion_patterns << %r{/lib/moarspec/its/map}
+end
+
+RSpec::SharedContext.include Moarspec::Its::Map

data/lib/moarspec/its/with.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Moarspec
+  module Its
+    module With
+      # Creates a nested context + example with `let` values defined from the arguments.
+      #
+      # @example
+      #
+      #   subject { x + y }
+      #
+      #   it_with(x: 1, y: 2) { is_expected.to eq 3 }
+      #
+      #   # is equivalent to
+      #
+      #   context "with x=1, y=2" do
+      #     let(:x) { 1 }
+      #     let(:y) { 2 }
+      #
+      #     it { is_expected.to eq 3 }
+      #   end
+      #
+      # See also {Its::BlockWith#its_block_with #its_block_with} for a block form, and
+      # {ExampleGroups::InstantContext#instant_context #instant_context} for inline `context`+`let` definitions.
+      def it_with(**lets, &block)
+        context "with #{lets.map { "#{_1}=#{_2.inspect}" }.join(', ')}" do
+          lets.each do |name, val|
+            let(name) { val }
+          end
+          example(nil, &block)
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |rspec|
+  rspec.extend Moarspec::Its::With
+  rspec.backtrace_exclusion_patterns << %r{/lib/moarspec/its/with}
+end
+
+RSpec::SharedContext.include Moarspec::Its::With

data/lib/moarspec/its.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Moarspec
+  # Wrapper module for all `its_*` RSpec additions.
+  #
+  # ## {Map#its_map #its_map}
+  #
+  # ```ruby
+  # subject { %w[1 2 3] }
+  # its_map(:to_s) { is_expected.to eq [1, 2, 3] }
+  # ```
+  #
+  # ## {Call#its_call #its_call}
+  #
+  # ```ruby
+  # subject { [1, 2, 3].method(:[]) }
+  # its_call(2) { is_expected.to ret 3 }
+  # its_call('foo') { is_expected.to raise_error }
+  # ```
+  #
+  # ## {Block#its_block #its_block}
+  #
+  # ```ruby
+  # subject { something_action }
+  # its_block { is_expected.not_to raise_error }
+  # its_block { is_expected.to change(some, :value).by(1) }
+  # ```
+  #
+  # ## {With#it_with #it_with}
+  #
+  # ```ruby
+  # subject { x + y }
+  # it_with(x: 1, y: 2) { is_expected.to eq 3 }
+  # ```
+  #
+  # ## {BlockWith#its_block_with #its_block_with}
+  #
+  # ```ruby
+  # subject { x + y }
+  # its_block_with(x: 1, y: nil) { is_expected.to raise_error }
+  # ```
+  #
+  module Its
+  end
+end
+
+require_relative 'its/map'
+require_relative 'its/block'
+require_relative 'its/call'

data/lib/moarspec/matchers/be_json.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Moarspec
+  module Matchers
+    # @private
+    class BeJson
+      include RSpec::Matchers::Composable
+      include RSpec::Matchers # to have #match
+
+      ANY = Object.new.freeze
+
+      attr_reader :actual, :expected
+
+      def initialize(expected, **parse_opts)
+        @expected_matcher = @expected = expected
+
+        # wrap to make be_json('foo' => matcher) work, too
+        unless expected == ANY || expected.respond_to?(:matches?)
+          @expected_matcher = match(expected)
+        end
+        @parse_opts = parse_opts
+      end
+
+      def matches?(json)
+        @actual = JSON.parse(json, **@parse_opts)
+        @expected_matcher == ANY || @expected_matcher === @actual
+      rescue JSON::ParserError => e
+        @parser_error = e
+        false
+      end
+
+      def does_not_match?(*args)
+        !matches?(*args)
+      end
+
+      def diffable?
+        true
+      end
+
+      def description
+        if @expected == ANY
+          'be a valid JSON string'
+        else
+          expected = @expected.respond_to?(:description) ? @expected.description : @expected
+          "be a valid JSON matching (#{expected})"
+        end
+      end
+
+      def failure_message
+        failed =
+          case
+          when @parser_error
+            "failed: #{@parser_error}"
+          when @expected != ANY
+            "was #{@actual}"
+          end
+        "expected value to #{description} but #{failed}"
+      end
+
+      def failure_message_when_negated
+        'expected value not to be parsed as JSON, but succeeded'
+      end
+    end
+  end
+end
+
+module RSpec
+  module Matchers
+    # `be_json` checks if provided value is JSON, and optionally checks it contents.
+    #
+    # If you need to check against some hashes, it is more convenient to use `be_json_sym`, which
+    # parses JSON with `symbolize_names: true`.
+    #
+    # @example
+    #
+    #   expect('{}').to be_json # ok
+    #   expect('garbage').to be_json
+    #   # expected value to be a valid JSON string but failed: 765: unexpected token at 'garbage'
+    #
+    #   expect('{"foo": "bar"}').to be_json('foo' => 'bar') # ok
+    #   expect('{"foo": "bar"}').to be_json_sym(foo: 'bar') # more convenient
+    #
+    #   expect('{"foo": [1, 2, 3]').to be_json_sym(foo: array_including(3)) # nested matchers work
+    #   expect(something_large).to be_json_sym(include(meta: include(next_page: Integer)))
+    #
+    # @param expected Value or matcher to check JSON against. It should implement `#===` method,
+    #   so all standard and custom RSpec matchers work.
+    def be_json(expected = Moarspec::Matchers::BeJson::ANY)
+      Moarspec::Matchers::BeJson.new(expected)
+    end
+
+    # `be_json_sym` checks if value is a valid JSON and parses it with `symbolize_names: true`. This
+    # way, it is convenient to check hashes content with Ruby's short symbolic keys syntax.
+    #
+    # See {#be_json_sym} for examples.
+    #
+    # @param expected Value or matcher to check JSON against. It should implement `#===` method,
+    #   so all standard and custom RSpec matchers work.
+    def be_json_sym(expected = Moarspec::Matchers::BeJson::ANY)
+      Moarspec::Matchers::BeJson.new(expected, symbolize_names: true)
+    end
+  end
+end

data/lib/moarspec/matchers/dont.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Moarspec
+  module Matchers
+    # @private
+    class Not < RSpec::Matchers::BuiltIn::BaseMatcher
+      def initialize(*)
+        super
+        @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)'
+
+        # https://www.rubydoc.info/github/rspec/rspec-expectations/RSpec%2FMatchers%2FMatcherProtocol:does_not_match%3F
+        # In a negative expectation such as `expect(x).not_to foo`, RSpec will call
+        # `foo.does_not_match?(x)` if this method is defined. If it's not defined it
+        # will fall back to using `!foo.matches?(x)`.
+        if @matcher.respond_to?(:does_not_match?)
+          @matcher.does_not_match?(actual)
+        else
+          !@matcher.matches?(actual)
+        end
+      end
+
+      def failure_message
+        @matcher.failure_message_when_negated
+      end
+
+      def supports_block_expectations?
+        @matcher.supports_block_expectations?
+      end
+
+      def method_missing(m, *a, &)
+        if @matcher
+          @matcher.send(m, *a, &)
+        else
+          @matcher = @delegator.send(m, *a, &)
+        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
+
+      # ActiveSupport 7.1+ defines Object#with, and thus it doesn't go to `method_missing`.
+      # So, matchers like `dont.send_message(...).with(...)` stop working correctly.
+      #
+      # This is dirty, but I don't see another way.
+      if Object.instance_methods.include?(:with)
+        def with(...)
+          @matcher.with(...)
+        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
+      Moarspec::Matchers::Not.new
+    end
+  end
+end

data/lib/moarspec/matchers/eq_multiline.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative '../util'
+
+module Moarspec
+  module Matchers
+    # @private
+    class EqMultiline < RSpec::Matchers::BuiltIn::Eq
+      include Util
+      def initialize(expected)
+        super(multiline(expected))
+      end
+    end
+  end
+end
+
+module RSpec
+  module Matchers
+    # Allows to pretty test multiline strings with complex indentation (for example, results of
+    # code generation).
+    #
+    # In provided string, removes first and last empty line, trailing spaces and leading spaces up
+    # to `|` character.
+    #
+    # If you need to preserve trailing spaces, end them with another `|`.
+    #
+    # @example
+    #     require 'moarspec/matchers/eq_multiline'
+    #
+    #     expect(some_code_gen).to eq_multiline(%{
+    #       |def something
+    #       |  a = 5
+    #       |  a**2
+    #       |end
+    #     })
+    #
+    # @param expected [String]
+    def eq_multiline(expected)
+      Moarspec::Matchers::EqMultiline.new(expected)
+    end
+  end
+end

data/lib/moarspec/matchers/request_webmock.rb

@@ -0,0 +1,60 @@
+# TODO: PR to webmock itself?..
+#
+# RSpec::Matchers.define :request_webmock do |url, method: :get|
+#   match do |block|
+#     WebMock.reset!
+#     stub_request(method, url)
+#       .tap { |req| req.with(@with_options) if @with_options && !@with_block }
+#       .tap { |req| req.with(@with_options, &@with_block) if @with_block }
+#       .tap { |req| req.to_return(@response) if @response }
+#     block.call
+#     matcher = have_requested(method, url)
+#       .tap { |matcher| matcher.with(@with_options) if @with_options && !@with_block }
+#       .tap { |matcher| matcher.with(@with_options, &@with_block) if @with_block }
+#     expect(WebMock).to matcher
+#   end
+#
+#   chain :with do |options = {}, &block|
+#     @with_options = options
+#     @with_block = block
+#   end
+#
+#   chain :once do
+#     times(1)
+#   end
+#
+#   chain :twice do
+#     times(2)
+#   end
+#
+#   chain :times do |n|
+#     @times = n
+#   end
+#
+#   chain :at_least_once do
+#     at_least_times(1)
+#   end
+#
+#   chain :at_least_twice do
+#     at_least_times(2)
+#   end
+#
+#   chain :at_least_times do |n|
+#     @at_least_times = n
+#   end
+#
+#   chain :returning do |response|
+#     @response =
+#       case response
+#       when String
+#         {body: response}
+#       when Hash
+#         response
+#       else
+#         fail "Expected string or Hash of params, got #{response.inspect}"
+#       end
+#   end
+#
+#   supports_block_expectations
+# end
+#

data/lib/moarspec/matchers/ret.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Moarspec
+  module Matchers
+    # @private
+    class Ret
+      include RSpec::Matchers::Composable
+
+      attr_reader :actual, :expected
+
+      def initialize(expected)
+        @expected = expected
+      end
+
+      def matches?(subject)
+        @subject = subject
+        return false unless subject.respond_to?(:call)
+
+        @actual = subject.call
+        @expected === @actual
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def diffable?
+        true
+      end
+
+      def description
+        "return #{@expected.respond_to?(:description) ? @expected.description : @expected.inspect}"
+      end
+
+      def failure_message
+        case
+        when !@subject.respond_to?(:call)
+          "expected to #{description}, but was not callable"
+        when @expected.respond_to?(:failure_message)
+          "return value mismatch: #{@expected.failure_message}"
+        else
+          "expected to #{description}, but returned #{@actual.inspect}"
+        end
+      end
+
+      def failure_message_when_negated
+        case
+        when @expected.respond_to?(:failure_message_when_negated)
+          "return value mismatch: #{@expected.failure_message_when_negated}"
+        else
+          "expected not to #{description}, but returned it"
+        end
+      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
+    #   {Moarspec::Its::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)
+      Moarspec::Matchers::Ret.new(expected)
+    end
+  end
+end

data/lib/moarspec/matchers/send_message.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Moarspec
+  module Matchers
+    # @private
+    class SendMessage
+      include RSpec::Mocks::ExampleMethods
+      include RSpec::Matchers::Composable
+
+      def initialize(target, method)
+        @target = target
+        @method = method
+      end
+
+      # DSL
+      def with(*arguments)
+        @arguments = arguments
+        self
+      end
+
+      def returning(*res)
+        @res = [*res]
+        self
+      end
+
+      def calling_original
+        @call_original = true
+        self
+      end
+
+      def exactly(n)
+        @times = n
+        self
+      end
+
+      def at_least(n)
+        @at_least = n
+        self
+      end
+
+      def at_most(n)
+        @at_most = n
+        self
+      end
+
+      def times
+        fail NoMethodError unless @times || @at_least
+
+        self
+      end
+
+      def once
+        exactly(1)
+      end
+
+      def twice
+        exactly(2)
+      end
+
+      def thrice
+        exactly(3)
+      end
+
+      def ordered
+        @ordered = true
+        self
+      end
+
+      def yielding(*args, &block)
+        @yield_args = args
+        @yield_block = block
+        self
+      end
+
+      # Matching
+      def matches?(subject)
+        run(subject)
+        expect(@target).to expectation
+        true
+      end
+
+      def does_not_match?(subject)
+        run(subject)
+        expect(@target).not_to expectation
+        true
+      end
+
+      # Static properties
+      def supports_block_expectations?
+        true
+      end
+
+      def description
+        format('send %p.%s', @target, @method)
+      end
+
+      def failure_message
+        "expected #{description}, but sent nothing"
+      end
+
+      def failure_message_when_negated
+        "expected not #{description}, but sent it"
+      end
+
+      private
+
+      def run(subject)
+        @target.respond_to?(@method, true) or
+          fail NoMethodError,
+               "undefined method `#{@method}' for#{@target.inspect}:#{@target.class}"
+        allow(@target).to allower
+        subject.call
+      end
+
+      def allower
+        receive(@method).tap do |a|
+          a.and_return(*@res) if @res
+          a.and_call_original if @call_original
+        end
+      end
+
+      def expectation
+        have_received(@method).tap do |e|
+          e.with(*@arguments) if @arguments
+          e.exactly(@times).times if @times
+          e.at_least(@at_least).times if @at_least
+          e.at_most(@at_most).times if @at_most
+          e.ordered if @ordered
+          e.and_yield(*@yield_args, &@yield_block) if @yield_args
+        end
+      end
+    end
+  end
+end
+
+module RSpec
+  module Matchers
+    # Checks if the (block) subject sends specified message to specified object.
+    #
+    # @example
+    #   # before:
+    #   specify {
+    #      allow(double).to receive(:fetch)
+    #      code_being_tested
+    #      expect(double).to have_received(:fetch).with(something)
+    #   }
+    #
+    #   # after:
+    #   require 'moarspec/matchers/send_message'
+    #
+    #   it { expect { code_being_tested }.to send_message(double, :fetch).with(something) }
+    #
+    #   # after + its_block
+    #   require 'moarspec/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
+    #
+    # @return Instance of a matcher, allowing the following additional methods:
+    #
+    #   * `once`, `twice`, `exactly(n).times`;
+    #   * `with(arguments)`;
+    #   * `calling_original`;
+    #   * `returning(response)`.
+    #
+    def send_message(target, method)
+      Moarspec::Matchers::SendMessage.new(target, method)
+    end
+  end
+end

data/lib/moarspec/matchers.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Moarspec
+  # All Moarspec matchers, when required, included into `RSpec::Matchers` namespace.
+  #
+  # See:
+  #
+  # * {RSpec::Matchers#dont #dont}: `expect { block }.to change(this).and dont.change(that)`
+  # * {RSpec::Matchers#send_message #send_message}: `expect { block }.to send_message(File, :write)`
+  # * {RSpec::Matchers#ret #ret}: `expect { block }.to ret value`
+  # * {RSpec::Matchers#be_json #be_json}: `expect(response.body).to be_json('foo' => 'bar')`
+  # * {RSpec::Matchers#eq_multiline #eq_multiline}: multiline equality akin to squiggly heredoc
+  #
+  module Matchers
+  end
+end
+
+require_relative 'matchers/eq_multiline'
+require_relative 'matchers/send_message'
+require_relative 'matchers/ret'
+require_relative 'matchers/dont'
+require_relative 'matchers/be_json'

data/lib/moarspec/util.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Moarspec
+  module Util
+    def multiline(string)
+      # 1. for all lines looking like "<spaces>|" -- remove this.
+      # 2. remove trailing spaces
+      # 3. preserve trailing spaces ending with "|", but remove the pipe
+      # 4. remove one empty line before & after, allows prettier %Q{}
+      # TODO: check if all lines start with "|"?
+      string
+        .gsub(/^ *\|/, '')
+        .gsub(/ +$/, '')
+        .gsub(/\|$/, '')
+        .gsub(/(\A *\n|\n *\z)/, '')
+    end
+  end
+end

data/lib/moarspec/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moarspec
+  MAJOR = 0
+  MINOR = 1
+  PATCH = 0
+  VERSION = [MAJOR, MINOR, PATCH].join('.')
+end

data/lib/moarspec.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+defined?(RSpec) or
+  fail 'RSpec is not present in the current environment, check that `rspec` ' \
+       'is present in your Gemfile and is in the same group as `moarspec`' \
+
+# Umbrella module for all Moarspec RSpec DRY-ing features.
+#
+# See {file:README.md} or {Its}, {Matchers}, and {ExampleGroups} separately.
+#
+module Moarspec
+end
+
+require_relative 'moarspec/its'
+require_relative 'moarspec/matchers'
+require_relative 'moarspec/example_groups'
+require_relative 'moarspec/util'

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: moarspec
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Victor Shepelev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-06-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.76.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.76.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  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: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !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: rubygems-tasks
+  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: yard
+  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: 
+email: zverok.offline@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- config/rubocop-rspec.yml
+- lib/moarspec.rb
+- lib/moarspec/example_groups.rb
+- lib/moarspec/example_groups/instant_context.rb
+- lib/moarspec/its.rb
+- lib/moarspec/its/block.rb
+- lib/moarspec/its/block_with.rb
+- lib/moarspec/its/call.rb
+- lib/moarspec/its/map.rb
+- lib/moarspec/its/with.rb
+- lib/moarspec/matchers.rb
+- lib/moarspec/matchers/be_json.rb
+- lib/moarspec/matchers/dont.rb
+- lib/moarspec/matchers/eq_multiline.rb
+- lib/moarspec/matchers/request_webmock.rb
+- lib/moarspec/matchers/ret.rb
+- lib/moarspec/matchers/send_message.rb
+- lib/moarspec/util.rb
+- lib/moarspec/version.rb
+homepage: https://github.com/zverok/moarspec
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key: 
+specification_version: 4
+summary: Several additions for DRYer RSpec code
+test_files: []