rspec-rails 3.7.0 → 4.0.0

data/lib/rspec/rails/matchers/base_matcher.rb

@@ -0,0 +1,179 @@
+module RSpec
+  module Rails
+    module Matchers
+      # @api private
+      #
+      # Base class to build matchers. Should not be instantiated directly.
+      class BaseMatcher
+        include RSpec::Matchers::Composable
+
+        # @api private
+        # Used to detect when no arg is passed to `initialize`.
+        # `nil` cannot be used because it's a valid value to pass.
+        UNDEFINED = Object.new.freeze
+
+        # @private
+        attr_reader :actual, :expected, :rescued_exception
+
+        # @private
+        attr_writer :matcher_name
+
+        def initialize(expected = UNDEFINED)
+          @expected = expected unless UNDEFINED.equal?(expected)
+        end
+
+        # @api private
+        # Indicates if the match is successful. Delegates to `match`, which
+        # should be defined on a subclass. Takes care of consistently
+        # initializing the `actual` attribute.
+        def matches?(actual)
+          @actual = actual
+          match(expected, actual)
+        end
+
+        # @api private
+        # Used to wrap a block of code that will indicate failure by
+        # raising one of the named exceptions.
+        #
+        # This is used by rspec-rails for some of its matchers that
+        # wrap rails' assertions.
+        def match_unless_raises(*exceptions)
+          exceptions.unshift Exception if exceptions.empty?
+          begin
+            yield
+            true
+          rescue *exceptions => @rescued_exception
+            false
+          end
+        end
+
+        # @api private
+        # Generates a description using {RSpec::Matchers::EnglishPhrasing}.
+        # @return [String]
+        def description
+          desc = RSpec::Matchers::EnglishPhrasing.split_words(self.class.matcher_name)
+          desc << RSpec::Matchers::EnglishPhrasing.list(@expected) if defined?(@expected)
+          desc
+        end
+
+        # @api private
+        # Matchers are not diffable by default. Override this to make your
+        # subclass diffable.
+        def diffable?
+          false
+        end
+
+        # @api private
+        # Most matchers are value matchers (i.e. meant to work with `expect(value)`)
+        # rather than block matchers (i.e. meant to work with `expect { }`), so
+        # this defaults to false. Block matchers must override this to return true.
+        def supports_block_expectations?
+          false
+        end
+
+        # @api private
+        def expects_call_stack_jump?
+          false
+        end
+
+        # @private
+        def expected_formatted
+          RSpec::Support::ObjectFormatter.format(@expected)
+        end
+
+        # @private
+        def actual_formatted
+          RSpec::Support::ObjectFormatter.format(@actual)
+        end
+
+        # @private
+        def self.matcher_name
+          @matcher_name ||= underscore(name.split('::').last)
+        end
+
+        # @private
+        def matcher_name
+          if defined?(@matcher_name)
+            @matcher_name
+          else
+            self.class.matcher_name
+          end
+        end
+
+        # @private
+        # Borrowed from ActiveSupport.
+        def self.underscore(camel_cased_word)
+          word = camel_cased_word.to_s.dup
+          word.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+          word.tr!('-', '_')
+          word.downcase!
+          word
+        end
+        private_class_method :underscore
+
+      private
+
+        def assert_ivars(*expected_ivars)
+          return unless (expected_ivars - present_ivars).any?
+
+          ivar_list = RSpec::Matchers::EnglishPhrasing.list(expected_ivars)
+          raise "#{self.class.name} needs to supply#{ivar_list}"
+        end
+
+        alias present_ivars instance_variables
+
+        # @private
+        module HashFormatting
+          # `{ :a => 5, :b => 2 }.inspect` produces:
+          #
+          #     {:a=>5, :b=>2}
+          #
+          # ...but it looks much better as:
+          #
+          #     {:a => 5, :b => 2}
+          #
+          # This is idempotent and safe to run on a string multiple times.
+          def improve_hash_formatting(inspect_string)
+            inspect_string.gsub(/(\S)=>(\S)/, '\1 => \2')
+          end
+          module_function :improve_hash_formatting
+        end
+
+        include HashFormatting
+
+        # @api private
+        # Provides default implementations of failure messages, based on the `description`.
+        module DefaultFailureMessages
+          # @api private
+          # Provides a good generic failure message. Based on `description`.
+          # When subclassing, if you are not satisfied with this failure message
+          # you often only need to override `description`.
+          # @return [String]
+          def failure_message
+            "expected #{description_of @actual} to #{description}".dup
+          end
+
+          # @api private
+          # Provides a good generic negative failure message. Based on `description`.
+          # When subclassing, if you are not satisfied with this failure message
+          # you often only need to override `description`.
+          # @return [String]
+          def failure_message_when_negated
+            "expected #{description_of @actual} not to #{description}".dup
+          end
+
+          # @private
+          def self.has_default_failure_messages?(matcher)
+            matcher.method(:failure_message).owner == self &&
+              matcher.method(:failure_message_when_negated).owner == self
+          rescue NameError
+            false
+          end
+        end
+
+        include DefaultFailureMessages
+      end
+    end
+  end
+end

data/lib/rspec/rails/matchers/be_a_new.rb

@@ -6,7 +6,7 @@ module RSpec
       # Matcher class for `be_a_new`. Should not be instantiated directly.
       #
       # @see RSpec::Rails::Matchers#be_a_new
-      class BeANew < RSpec::Matchers::BuiltIn::BaseMatcher
+      class BeANew < RSpec::Rails::Matchers::BaseMatcher
         # @private
         def initialize(expected)
           @expected = expected

data/lib/rspec/rails/matchers/be_new_record.rb

@@ -2,7 +2,7 @@ module RSpec
   module Rails
     module Matchers
       # @private
-      class BeANewRecord < RSpec::Matchers::BuiltIn::BaseMatcher
+      class BeANewRecord < RSpec::Rails::Matchers::BaseMatcher
         def matches?(actual)
           actual.new_record?
         end

data/lib/rspec/rails/matchers/be_valid.rb

@@ -15,7 +15,7 @@ module RSpec
         def failure_message
           message = "expected #{actual.inspect} to be valid"
 
-          if actual.respond_to?(:errors)
+          if actual.respond_to?(:errors) && actual.method(:errors).arity < 1
             errors = if actual.errors.respond_to?(:full_messages)
                        actual.errors.full_messages
                      else

data/lib/rspec/rails/matchers/have_enqueued_mail.rb

@@ -0,0 +1,198 @@
+# We require the minimum amount of rspec-mocks possible to avoid
+# conflicts with other mocking frameworks.
+# See: https://github.com/rspec/rspec-rails/issues/2252
+require "rspec/mocks/argument_matchers"
+require "rspec/rails/matchers/active_job"
+
+module RSpec
+  module Rails
+    module Matchers
+      # Matcher class for `have_enqueued_mail`. Should not be instantiated directly.
+      #
+      # @private
+      # @see RSpec::Rails::Matchers#have_enqueued_mail
+      class HaveEnqueuedMail < ActiveJob::HaveEnqueuedJob
+        MAILER_JOB_METHOD = 'deliver_now'.freeze
+
+        include RSpec::Mocks::ArgumentMatchers
+
+        def initialize(mailer_class, method_name)
+          super(nil)
+          @mailer_class = mailer_class
+          @method_name = method_name
+          @mail_args = []
+        end
+
+        def description
+          "enqueues #{mailer_class_name}.#{@method_name}"
+        end
+
+        def with(*args, &block)
+          @mail_args = args
+          block.nil? ? super : super(&yield_mail_args(block))
+        end
+
+        def matches?(block)
+          raise ArgumentError, 'have_enqueued_mail and enqueue_mail only work with block arguments' unless block.respond_to?(:call)
+
+          check_active_job_adapter
+          super
+        end
+
+        def failure_message
+          "expected to enqueue #{base_message}".tap do |msg|
+            msg << "\n#{unmatching_mail_jobs_message}" if unmatching_mail_jobs.any?
+          end
+        end
+
+        def failure_message_when_negated
+          "expected not to enqueue #{base_message}"
+        end
+
+        private
+
+        def base_message
+          [mailer_class_name, @method_name].compact.join('.').tap do |msg|
+            msg << " #{expected_count_message}"
+            msg << " with #{@mail_args}," if @mail_args.any?
+            msg << " on queue #{@queue}," if @queue
+            msg << " at #{@at.inspect}," if @at
+            msg << " but enqueued #{@matching_jobs.size}"
+          end
+        end
+
+        def expected_count_message
+          "#{message_expectation_modifier} #{@expected_number} #{@expected_number == 1 ? 'time' : 'times'}"
+        end
+
+        def mailer_class_name
+          @mailer_class ? @mailer_class.name : 'ActionMailer::Base'
+        end
+
+        def job_match?(job)
+          legacy_mail?(job) || parameterized_mail?(job) || unified_mail?(job)
+        end
+
+        def arguments_match?(job)
+          @args =
+            if @mail_args.any?
+              base_mailer_args + @mail_args
+            elsif @mailer_class && @method_name
+              base_mailer_args + [any_args]
+            elsif @mailer_class
+              [mailer_class_name, any_args]
+            else
+              []
+            end
+
+          super(job)
+        end
+
+        def base_mailer_args
+          [mailer_class_name, @method_name.to_s, MAILER_JOB_METHOD]
+        end
+
+        def yield_mail_args(block)
+          proc { |*job_args| block.call(*(job_args - base_mailer_args)) }
+        end
+
+        def check_active_job_adapter
+          return if ::ActiveJob::QueueAdapters::TestAdapter === ::ActiveJob::Base.queue_adapter
+
+          raise StandardError, "To use HaveEnqueuedMail matcher set `ActiveJob::Base.queue_adapter = :test`"
+        end
+
+        def unmatching_mail_jobs
+          @unmatching_jobs.select do |job|
+            job_match?(job)
+          end
+        end
+
+        def unmatching_mail_jobs_message
+          msg = "Queued deliveries:"
+
+          unmatching_mail_jobs.each do |job|
+            msg << "\n  #{mail_job_message(job)}"
+          end
+
+          msg
+        end
+
+        def mail_job_message(job)
+          mailer_method = job[:args][0..1].join('.')
+
+          mailer_args = job[:args][3..-1]
+          msg_parts = []
+          msg_parts << "with #{mailer_args}" if mailer_args.any?
+          msg_parts << "on queue #{job[:queue]}" if job[:queue] && job[:queue] != 'mailers'
+          msg_parts << "at #{Time.at(job[:at])}" if job[:at]
+
+          "#{mailer_method} #{msg_parts.join(', ')}".strip
+        end
+
+        def legacy_mail?(job)
+          job[:job] == ActionMailer::DeliveryJob
+        end
+
+        def parameterized_mail?(job)
+          RSpec::Rails::FeatureCheck.has_action_mailer_parameterized? && job[:job] == ActionMailer::Parameterized::DeliveryJob
+        end
+
+        def unified_mail?(job)
+          RSpec::Rails::FeatureCheck.has_action_mailer_unified_delivery? && job[:job] == ActionMailer::MailDeliveryJob
+        end
+      end
+      # @api public
+      # Passes if an email has been enqueued inside block.
+      # May chain with to specify expected arguments.
+      # May chain at_least, at_most or exactly to specify a number of times.
+      # May chain at to specify a send time.
+      # May chain on_queue to specify a queue.
+      #
+      # @example
+      #     expect {
+      #       MyMailer.welcome(user).deliver_later
+      #     }.to have_enqueued_mail
+      #
+      #     expect {
+      #       MyMailer.welcome(user).deliver_later
+      #     }.to have_enqueued_mail(MyMailer)
+      #
+      #     expect {
+      #       MyMailer.welcome(user).deliver_later
+      #     }.to have_enqueued_mail(MyMailer, :welcome)
+      #
+      #     # Using alias
+      #     expect {
+      #       MyMailer.welcome(user).deliver_later
+      #     }.to enqueue_mail(MyMailer, :welcome)
+      #
+      #     expect {
+      #       MyMailer.welcome(user).deliver_later
+      #     }.to have_enqueued_mail(MyMailer, :welcome).with(user)
+      #
+      #     expect {
+      #       MyMailer.welcome(user).deliver_later
+      #       MyMailer.welcome(user).deliver_later
+      #     }.to have_enqueued_mail(MyMailer, :welcome).at_least(:once)
+      #
+      #     expect {
+      #       MyMailer.welcome(user).deliver_later
+      #     }.to have_enqueued_mail(MyMailer, :welcome).at_most(:twice)
+      #
+      #     expect {
+      #       MyMailer.welcome(user).deliver_later(wait_until: Date.tomorrow.noon)
+      #     }.to have_enqueued_mail(MyMailer, :welcome).at(Date.tomorrow.noon)
+      #
+      #     expect {
+      #       MyMailer.welcome(user).deliver_later(queue: :urgent_mail)
+      #     }.to have_enqueued_mail(MyMailer, :welcome).on_queue(:urgent_mail)
+      def have_enqueued_mail(mailer_class = nil, mail_method_name = nil)
+        HaveEnqueuedMail.new(mailer_class, mail_method_name)
+      end
+      alias_method :have_enqueued_email, :have_enqueued_mail
+      alias_method :enqueue_mail, :have_enqueued_mail
+      alias_method :enqueue_email, :have_enqueued_mail
+    end
+  end
+end

data/lib/rspec/rails/matchers/have_http_status.rb

@@ -59,6 +59,7 @@ module RSpec
         #   `@invalid_response` is present, `nil` otherwise
         def invalid_response_type_message
           return unless @invalid_response
+
           "expected a response object, but an instance of " \
           "#{@invalid_response.class} was received"
         end
@@ -72,8 +73,8 @@ module RSpec
         # @example
         #   expect(response).to have_http_status(404)
         #
-        # @see RSpec::Rails::Matchers.have_http_status
-        class NumericCode < RSpec::Matchers::BuiltIn::BaseMatcher
+        # @see RSpec::Rails::Matchers#have_http_status
+        class NumericCode < RSpec::Rails::Matchers::BaseMatcher
           include HaveHttpStatus
 
           def initialize(code)
@@ -122,9 +123,9 @@ module RSpec
         # @example
         #   expect(response).to have_http_status(:created)
         #
-        # @see RSpec::Rails::Matchers.have_http_status
+        # @see RSpec::Rails::Matchers#have_http_status
         # @see https://github.com/rack/rack/blob/master/lib/rack/utils.rb `Rack::Utils::SYMBOL_TO_STATUS_CODE`
-        class SymbolicStatus < RSpec::Matchers::BuiltIn::BaseMatcher
+        class SymbolicStatus < RSpec::Rails::Matchers::BaseMatcher
           include HaveHttpStatus
 
           def initialize(status)
@@ -174,6 +175,7 @@ module RSpec
           # @return [Symbol] representing the actual http numeric code
           def actual_status
             return unless actual
+
             @actual_status ||= compute_status_from(actual)
           end
 
@@ -234,33 +236,38 @@ module RSpec
         #   expect(response).to have_http_status(:missing)
         #   expect(response).to have_http_status(:redirect)
         #
-        # @see RSpec::Rails::Matchers.have_http_status
-        # @see ActionDispatch::TestResponse
-        class GenericStatus < RSpec::Matchers::BuiltIn::BaseMatcher
+        # @see RSpec::Rails::Matchers#have_http_status
+        # @see https://github.com/rails/rails/blob/6-0-stable/actionpack/lib/action_dispatch/testing/test_response.rb `ActionDispatch::TestResponse`
+        class GenericStatus < RSpec::Rails::Matchers::BaseMatcher
           include HaveHttpStatus
 
           # @return [Array<Symbol>] of status codes which represent a HTTP status
           #   code "group"
           # @see https://github.com/rails/rails/blob/master/actionpack/lib/action_dispatch/testing/test_response.rb `ActionDispatch::TestResponse`
           def self.valid_statuses
-            [:error, :success, :missing, :redirect]
+            [
+              :error, :success, :missing,
+              :server_error, :successful, :not_found,
+              :redirect
+            ]
           end
 
           def initialize(type)
             unless self.class.valid_statuses.include?(type)
               raise ArgumentError, "Invalid generic HTTP status: #{type.inspect}"
             end
+
             @expected = type
             @actual = nil
             @invalid_response = nil
           end
 
           # @return [Boolean] `true` if Rack's associated numeric HTTP code matched
-          #   the `response` code
+          #   the `response` code or the named response status
           def matches?(response)
             test_response = as_test_response(response)
             @actual = test_response.response_code
-            test_response.send("#{expected}?")
+            check_expected_status(test_response, expected)
           rescue TypeError => _ignored
             @invalid_response = response
             false
@@ -283,6 +290,19 @@ module RSpec
             "expected the response not to have #{type_message} but it was #{actual}"
           end
 
+        protected
+
+          RESPONSE_METHODS = {
+            success: 'successful',
+            error: 'server_error',
+            missing: 'not_found'
+          }.freeze
+
+          def check_expected_status(test_response, expected)
+            test_response.send(
+              "#{RESPONSE_METHODS.fetch(expected, expected)}?")
+          end
+
         private
 
           # @return [String] formating the expected status and associated code(s)
@@ -316,11 +336,11 @@ module RSpec
             # @see https://github.com/rails/rails/blob/ca200378/actionpack/lib/action_dispatch/http/response.rb#L74
             # @see https://github.com/rack/rack/blob/ce4a3959/lib/rack/response.rb#L119-L122
             @type_codes ||= case expected
-                            when :error
+                            when :error, :server_error
                               "5xx"
-                            when :success
+                            when :success, :successful
                               "2xx"
-                            when :missing
+                            when :missing, :not_found
                               "404"
                             when :redirect
                               "3xx"
@@ -357,6 +377,7 @@ module RSpec
       # @see https://github.com/rack/rack/blob/master/lib/rack/utils.rb `Rack::Utils::SYMBOL_TO_STATUS_CODE`
       def have_http_status(target)
         raise ArgumentError, "Invalid HTTP status: nil" unless target
+
         HaveHttpStatus.matcher_for_status(target)
       end
     end

data/lib/rspec/rails/matchers/have_rendered.rb

@@ -4,7 +4,7 @@ module RSpec
       # Matcher for template rendering.
       module RenderTemplate
         # @private
-        class RenderTemplateMatcher < RSpec::Matchers::BuiltIn::BaseMatcher
+        class RenderTemplateMatcher < RSpec::Rails::Matchers::BaseMatcher
           def initialize(scope, expected, message = nil)
             @expected = Symbol === expected ? expected.to_s : expected
             @message = message
@@ -29,6 +29,7 @@ module RSpec
           def check_redirect
             response = @scope.response
             return unless response.respond_to?(:redirect?) && response.redirect?
+
             @redirect_is = @scope.send(:normalize_argument_to_redirection, response.location)
           end
 

data/lib/rspec/rails/matchers/redirect_to.rb

@@ -4,7 +4,7 @@ module RSpec
       # Matcher for redirects.
       module RedirectTo
         # @private
-        class RedirectTo < RSpec::Matchers::BuiltIn::BaseMatcher
+        class RedirectTo < RSpec::Rails::Matchers::BaseMatcher
           def initialize(scope, expected)
             @expected = expected
             @scope = scope

data/lib/rspec/rails/matchers/routing_matchers.rb

@@ -6,7 +6,7 @@ module RSpec
         extend RSpec::Matchers::DSL
 
         # @private
-        class RouteToMatcher < RSpec::Matchers::BuiltIn::BaseMatcher
+        class RouteToMatcher < RSpec::Rails::Matchers::BaseMatcher
           def initialize(scope, *expected)
             @scope = scope
             @expected = expected[1] || {}
@@ -14,7 +14,7 @@ module RSpec
               @expected.merge!(expected[0])
             else
               controller, action = expected[0].split('#')
-              @expected.merge!(:controller => controller, :action => action)
+              @expected.merge!(controller: controller, action: action)
             end
           end
 
@@ -26,7 +26,7 @@ module RSpec
               path, query = *verb_to_path_map.values.first.split('?')
               @scope.assert_recognizes(
                 @expected,
-                { :method => verb_to_path_map.keys.first, :path => path },
+                {method: verb_to_path_map.keys.first, path: path},
                 Rack::Utils.parse_nested_query(query)
               )
             end
@@ -50,20 +50,20 @@ module RSpec
         #
         # @example
         #
-        #     expect(:get => "/things/special").to route_to(
-        #       :controller => "things",
-        #       :action     => "special"
+        #     expect(get: "/things/special").to route_to(
+        #       controller: "things",
+        #       action:     "special"
         #     )
         #
-        #     expect(:get => "/things/special").to route_to("things#special")
+        #     expect(get: "/things/special").to route_to("things#special")
         #
-        # @see http://api.rubyonrails.org/classes/ActionDispatch/Assertions/RoutingAssertions.html#method-i-assert_recognizes
+        # @see https://api.rubyonrails.org/classes/ActionDispatch/Assertions/RoutingAssertions.html#method-i-assert_recognizes
         def route_to(*expected)
           RouteToMatcher.new(self, *expected)
         end
 
         # @private
-        class BeRoutableMatcher < RSpec::Matchers::BuiltIn::BaseMatcher
+        class BeRoutableMatcher < RSpec::Rails::Matchers::BaseMatcher
           def initialize(scope)
             @scope = scope
           end
@@ -72,7 +72,7 @@ module RSpec
             @actual = path
             match_unless_raises ActionController::RoutingError do
               @routing_options = @scope.routes.recognize_path(
-                path.values.first, :method => path.keys.first
+                path.values.first, method: path.keys.first
               )
             end
           end
@@ -95,9 +95,9 @@ module RSpec
         # `RouteSet#recognize_path`.
         #
         # @example You can use route helpers provided by rspec-rails.
-        #     expect(:get  => "/a/path").to be_routable
-        #     expect(:post => "/another/path").to be_routable
-        #     expect(:put  => "/yet/another/path").to be_routable
+        #     expect(get:  "/a/path").to be_routable
+        #     expect(post: "/another/path").to be_routable
+        #     expect(put:  "/yet/another/path").to be_routable
         def be_routable
           BeRoutableMatcher.new(self)
         end
@@ -115,7 +115,7 @@ module RSpec
           # Shorthand method for matching this type of route.
           %w[get post put patch delete options head].each do |method|
             define_method method do |path|
-              { method.to_sym => path }
+              {method.to_sym => path}
             end
           end
         end

data/lib/rspec/rails/matchers.rb

@@ -11,6 +11,7 @@ module RSpec
   end
 end
 
+require 'rspec/rails/matchers/base_matcher'
 require 'rspec/rails/matchers/have_rendered'
 require 'rspec/rails/matchers/redirect_to'
 require 'rspec/rails/matchers/routing_matchers'
@@ -19,6 +20,16 @@ require 'rspec/rails/matchers/be_a_new'
 require 'rspec/rails/matchers/relation_match_array'
 require 'rspec/rails/matchers/be_valid'
 require 'rspec/rails/matchers/have_http_status'
+
 if RSpec::Rails::FeatureCheck.has_active_job?
   require 'rspec/rails/matchers/active_job'
+  require 'rspec/rails/matchers/have_enqueued_mail'
+end
+
+if RSpec::Rails::FeatureCheck.has_action_cable_testing?
+  require 'rspec/rails/matchers/action_cable'
+end
+
+if RSpec::Rails::FeatureCheck.has_action_mailbox?
+  require 'rspec/rails/matchers/action_mailbox'
 end