rspec-rails 3.8.2 → 7.0.1

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

@@ -0,0 +1,258 @@
+# 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"
+
+# rubocop: disable Metrics/ClassLength
+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
+          return @failure_message if defined?(@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 detect_args_signature_mismatch(jobs)
+          return if @method_name.nil?
+
+          mailer_class = mailer_class_name.constantize
+
+          jobs.each do |job|
+            mailer_args = extract_args_without_parameterized_params(job)
+
+            if (signature_mismatch = check_args_signature_mismatch(mailer_class, @method_name, mailer_args))
+              return signature_mismatch
+            end
+          end
+
+          nil
+        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)
+          job_args = deserialize_arguments(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
+
+        # Ruby 3.1 changed how params were serialized on Rails 6.1
+        # so we override the active job implementation and customize it here.
+        def deserialize_arguments(job)
+          args = super
+
+          return args unless Hash === args.last
+
+          hash = args.pop
+
+          if hash.key?("_aj_ruby2_keywords")
+            keywords = hash["_aj_ruby2_keywords"]
+
+            original_hash = keywords.each_with_object({}) { |keyword, new_hash| new_hash[keyword.to_sym] = hash[keyword] }
+
+            args + [original_hash]
+          elsif hash.key?(:args) && hash.key?(:params)
+            args + [hash]
+          elsif hash.key?(:args)
+            args + hash[:args]
+          else
+            args + [hash]
+          end
+        end
+
+        def extract_args_without_parameterized_params(job)
+          args = deserialize_arguments(job)
+          mailer_args = args - base_mailer_args
+
+          if parameterized_mail?(job)
+            mailer_args = mailer_args[1..-1] # ignore parameterized params
+          elsif mailer_args.last.is_a?(Hash) && mailer_args.last.key?(:args)
+            mailer_args = args.last[:args]
+          end
+
+          mailer_args
+        end
+
+        def legacy_mail?(job)
+          RSpec::Rails::FeatureCheck.has_action_mailer_legacy_delivery_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
+# rubocop: enable Metrics/ClassLength

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

@@ -1,6 +1,6 @@
 # The following code inspired and modified from Rails' `assert_response`:
 #
-#   https://github.com/rails/rails/blob/master/actionpack/lib/action_dispatch/testing/assertions/response.rb#L22-L38
+#   https://github.com/rails/rails/blob/main/actionpack/lib/action_dispatch/testing/assertions/response.rb#L22-L38
 #
 # Thank you to all the Rails devs who did the heavy lifting on this!
 
@@ -33,7 +33,7 @@ module RSpec
         # @param obj [Object] object to convert to a response
         # @return [ActionDispatch::TestResponse]
         def as_test_response(obj)
-          if ::ActionDispatch::Response === obj
+          if ::ActionDispatch::Response === obj || ::Rack::MockResponse === obj
             ::ActionDispatch::TestResponse.from_response(obj)
           elsif ::ActionDispatch::TestResponse === obj
             obj
@@ -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
 
@@ -214,11 +216,7 @@ module RSpec
           # @see Rack::Utils::SYMBOL_TO_STATUS_CODE
           # @raise [ArgumentError] if an associated code could not be found
           def set_expected_code!
-            @expected ||=
-              Rack::Utils::SYMBOL_TO_STATUS_CODE.fetch(expected_status) do
-                raise ArgumentError,
-                      "Invalid HTTP status: #{expected_status.inspect}"
-              end
+            @expected ||= Rack::Utils.status_code(expected_status)
           end
         end
 
@@ -234,14 +232,14 @@ 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/7-2-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`
+          # @see https://github.com/rails/rails/blob/main/actionpack/lib/action_dispatch/testing/test_response.rb `ActionDispatch::TestResponse`
           def self.valid_statuses
             [
               :error, :success, :missing,
@@ -254,6 +252,7 @@ module RSpec
             unless self.class.valid_statuses.include?(type)
               raise ArgumentError, "Invalid generic HTTP status: #{type.inspect}"
             end
+
             @expected = type
             @actual = nil
             @invalid_response = nil
@@ -289,20 +288,11 @@ module RSpec
 
         protected
 
-          if 5 < ::Rails::VERSION::MAJOR ||
-             (::Rails::VERSION::MAJOR == 5 && 2 <= ::Rails::VERSION::MINOR)
-            RESPONSE_METHODS = {
-              :success => 'successful',
-              :error => 'server_error',
-              :missing => 'not_found'
-            }.freeze
-          else
-            RESPONSE_METHODS = {
-              :successful => 'success',
-              :server_error => 'error',
-              :not_found => 'missing'
-            }.freeze
-          end
+          RESPONSE_METHODS = {
+            success: 'successful',
+            error: 'server_error',
+            missing: 'not_found'
+          }.freeze
 
           def check_expected_status(test_response, expected)
             test_response.send(
@@ -311,7 +301,7 @@ module RSpec
 
         private
 
-          # @return [String] formating the expected status and associated code(s)
+          # @return [String] formatting the expected status and associated code(s)
           def type_message
             @type_message ||= (expected == :error ? "an error" : "a #{expected}") +
               " status code (#{type_codes})"
@@ -319,7 +309,7 @@ module RSpec
 
           # @return [String] formatting the associated code(s) for the various
           #   status code "groups"
-          # @see https://github.com/rails/rails/blob/master/actionpack/lib/action_dispatch/testing/test_response.rb `ActionDispatch::TestResponse`
+          # @see https://github.com/rails/rails/blob/main/actionpack/lib/action_dispatch/testing/test_response.rb `ActionDispatch::TestResponse`
           # @see https://github.com/rack/rack/blob/master/lib/rack/response.rb `Rack::Response`
           def type_codes
             # At the time of this commit the most recent version of
@@ -379,10 +369,11 @@ module RSpec
       #   expect(response).to have_http_status(404)
       #   expect(page).to     have_http_status(:created)
       #
-      # @see https://github.com/rails/rails/blob/master/actionpack/lib/action_dispatch/testing/test_response.rb `ActionDispatch::TestResponse`
+      # @see https://github.com/rails/rails/blob/main/actionpack/lib/action_dispatch/testing/test_response.rb `ActionDispatch::TestResponse`
       # @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/relation_match_array.rb

@@ -1,3 +1,3 @@
-if defined?(ActiveRecord::Relation)
+if defined?(ActiveRecord::Relation) && defined?(RSpec::Matchers::BuiltIn::OperatorMatcher) # RSpec 4 removed OperatorMatcher
   RSpec::Matchers::BuiltIn::OperatorMatcher.register(ActiveRecord::Relation, '=~', RSpec::Matchers::BuiltIn::ContainExactly)
 end

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

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rails
+    module Matchers
+      # @api private
+      #
+      # Matcher class for `send_email`. Should not be instantiated directly.
+      #
+      # @see RSpec::Rails::Matchers#send_email
+      class SendEmail < RSpec::Rails::Matchers::BaseMatcher
+        # @api private
+        # Define the email attributes that should be included in the inspection output.
+        INSPECT_EMAIL_ATTRIBUTES = %i[subject from to cc bcc].freeze
+
+        def initialize(criteria)
+          @criteria = criteria
+        end
+
+        # @api private
+        def supports_value_expectations?
+          false
+        end
+
+        # @api private
+        def supports_block_expectations?
+          true
+        end
+
+        def matches?(block)
+          define_matched_emails(block)
+
+          @matched_emails.one?
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message
+          result =
+            if multiple_match?
+              "More than 1 matching emails were sent."
+            else
+              "No matching emails were sent."
+            end
+          "#{result}#{sent_emails_message}"
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          "Expected not to send an email but it was sent."
+        end
+
+        private
+
+        def diffable?
+          true
+        end
+
+        def deliveries
+          ActionMailer::Base.deliveries
+        end
+
+        def define_matched_emails(block)
+          before = deliveries.dup
+
+          block.call
+
+          after = deliveries
+
+          @diff = after - before
+          @matched_emails = @diff.select(&method(:matched_email?))
+        end
+
+        def matched_email?(email)
+          @criteria.all? do |attr, value|
+            expected =
+              case attr
+              when :to, :from, :cc, :bcc then Array(value)
+              else
+                value
+              end
+
+            values_match?(expected, email.public_send(attr))
+          end
+        end
+
+        def multiple_match?
+          @matched_emails.many?
+        end
+
+        def sent_emails_message
+          if @diff.empty?
+            "\n\nThere were no any emails sent inside the expectation block."
+          else
+            sent_emails =
+              @diff.map do |email|
+                inspected = INSPECT_EMAIL_ATTRIBUTES.map { |attr| "#{attr}: #{email.public_send(attr)}" }.join(", ")
+                "- #{inspected}"
+              end.join("\n")
+            "\n\nThe following emails were sent:\n#{sent_emails}"
+          end
+        end
+      end
+
+      # @api public
+      # Check email sending with specific parameters.
+      #
+      # @example Positive expectation
+      #   expect { action }.to send_email
+      #
+      # @example Negative expectations
+      #   expect { action }.not_to send_email
+      #
+      # @example More precise expectation with attributes to match
+      #   expect { action }.to send_email(to: 'test@example.com', subject: 'Confirm email')
+      def send_email(criteria = {})
+        SendEmail.new(criteria)
+      end
+    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,17 @@ 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'
+require 'rspec/rails/matchers/send_email'
+
 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