rspec-rails 2.14.2 → 3.9.1

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

@@ -1,40 +1,49 @@
-module RSpec::Rails::Matchers
-  class BeValid < RSpec::Matchers::BuiltIn::Be
-    def initialize(*args)
-      @args = args
-    end
+module RSpec
+  module Rails
+    module Matchers
+      # @private
+      class BeValid < RSpec::Matchers::BuiltIn::Be
+        def initialize(*args)
+          @args = args
+        end
 
-    # @api private
-    def matches?(actual)
-      @actual = actual
-      actual.valid?(*@args)
-    end
+        def matches?(actual)
+          @actual = actual
+          actual.valid?(*@args)
+        end
 
-    # @api private
-    def failure_message_for_should
-      message = "expected #{actual.inspect} to be valid"
-      if actual.respond_to?(:errors)
-        message << ", but got errors: #{actual.errors.full_messages.join(', ')}"
-      end
+        def failure_message
+          message = "expected #{actual.inspect} to be valid"
 
-      message
-    end
+          if actual.respond_to?(:errors) && actual.method(:errors).arity < 1
+            errors = if actual.errors.respond_to?(:full_messages)
+                       actual.errors.full_messages
+                     else
+                       actual.errors
+                     end
 
-    # @api private
-    def failure_message_for_should_not
-      "expected #{actual.inspect} not to be valid"
-    end
-  end
+            message << ", but got errors: #{errors.map(&:to_s).join(', ')}"
+          end
 
-  # Passes if the given model instance's `valid?` method is true, meaning all
-  # of the `ActiveModel::Validations` passed and no errors exist. If a message
-  # is not given, a default message is shown listing each error.
-  #
-  # @example
-  #
-  #     thing = Thing.new
-  #     thing.should be_valid
-  def be_valid(*args)
-    BeValid.new(*args)
+          message
+        end
+
+        def failure_message_when_negated
+          "expected #{actual.inspect} not to be valid"
+        end
+      end
+
+      # @api public
+      # Passes if the given model instance's `valid?` method is true, meaning
+      # all of the `ActiveModel::Validations` passed and no errors exist. If a
+      # message is not given, a default message is shown listing each error.
+      #
+      # @example
+      #     thing = Thing.new
+      #     expect(thing).to be_valid
+      def be_valid(*args)
+        BeValid.new(*args)
+      end
+    end
   end
 end

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

@@ -0,0 +1,174 @@
+require "rspec/mocks"
+require "rspec/rails/matchers/active_job"
+
+module RSpec
+  module Rails
+    module Matchers
+      # Matcher class for `have_enqueued_mail`. Should not be instantiated directly.
+      #
+      # rubocop: disable Style/ClassLength
+      # @private
+      # @see RSpec::Rails::Matchers#have_enqueued_mail
+      class HaveEnqueuedMail < ActiveJob::HaveEnqueuedJob
+        MAILER_JOB_METHOD = 'deliver_now'.freeze
+
+        include RSpec::Mocks::ExampleMethods
+
+        def initialize(mailer_class, method_name)
+          super(mailer_job)
+          @mailer_class = mailer_class
+          @method_name = method_name
+          @mail_args = []
+          @args = mailer_args
+        end
+
+        def description
+          "enqueues #{@mailer_class.name}.#{@method_name}"
+        end
+
+        def with(*args, &block)
+          @mail_args = args
+          block.nil? ? super(*mailer_args) : super(*mailer_args, &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}".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_args
+          if @mail_args.any?
+            base_mailer_args + @mail_args
+          else
+            mailer_method_arity = @mailer_class.instance_method(@method_name).arity
+
+            number_of_args = if mailer_method_arity < 0
+                               (mailer_method_arity + 1).abs
+                             else
+                               mailer_method_arity
+                             end
+
+            base_mailer_args + Array.new(number_of_args) { anything }
+          end
+        end
+
+        def base_mailer_args
+          [@mailer_class.name, @method_name.to_s, MAILER_JOB_METHOD]
+        end
+
+        def yield_mail_args(block)
+          Proc.new { |*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[:job] == mailer_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 mailer_job
+          ActionMailer::DeliveryJob
+        end
+      end
+      # rubocop: enable Style/ClassLength
+
+      # @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(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, mail_method_name)
+        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

@@ -0,0 +1,381 @@
+# 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
+#
+# Thank you to all the Rails devs who did the heavy lifting on this!
+
+module RSpec
+  module Rails
+    module Matchers
+      # Namespace for various implementations of `have_http_status`.
+      #
+      # @api private
+      module HaveHttpStatus
+        # Instantiates an instance of the proper matcher based on the provided
+        # `target`.
+        #
+        # @param target [Object] expected http status or code
+        # @return response matcher instance
+        def self.matcher_for_status(target)
+          if GenericStatus.valid_statuses.include?(target)
+            GenericStatus.new(target)
+          elsif Symbol === target
+            SymbolicStatus.new(target)
+          else
+            NumericCode.new(target)
+          end
+        end
+
+        # @api private
+        # Conversion function to coerce the provided object into an
+        # `ActionDispatch::TestResponse`.
+        #
+        # @param obj [Object] object to convert to a response
+        # @return [ActionDispatch::TestResponse]
+        def as_test_response(obj)
+          if ::ActionDispatch::Response === obj
+            ::ActionDispatch::TestResponse.from_response(obj)
+          elsif ::ActionDispatch::TestResponse === obj
+            obj
+          elsif obj.respond_to?(:status_code) && obj.respond_to?(:response_headers)
+            # Acts As Capybara Session
+            # Hack to support `Capybara::Session` without having to load
+            # Capybara or catch `NameError`s for the undefined constants
+            obj = ActionDispatch::Response.new.tap do |resp|
+              resp.status  = obj.status_code
+              resp.headers.clear
+              resp.headers.merge!(obj.response_headers)
+              resp.body    = obj.body
+              resp.request = ActionDispatch::Request.new({})
+            end
+            ::ActionDispatch::TestResponse.from_response(obj)
+          else
+            raise TypeError, "Invalid response type: #{obj}"
+          end
+        end
+        module_function :as_test_response
+
+        # @return [String, nil] a formatted failure message if
+        #   `@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
+
+        # @api private
+        # Provides an implementation for `have_http_status` matching against
+        # numeric http status codes.
+        #
+        # Not intended to be instantiated directly.
+        #
+        # @example
+        #   expect(response).to have_http_status(404)
+        #
+        # @see RSpec::Rails::Matchers.have_http_status
+        class NumericCode < RSpec::Rails::Matchers::BaseMatcher
+          include HaveHttpStatus
+
+          def initialize(code)
+            @expected = code.to_i
+            @actual = nil
+            @invalid_response = nil
+          end
+
+          # @param [Object] response object providing an http code to match
+          # @return [Boolean] `true` if the numeric code matched the `response` code
+          def matches?(response)
+            test_response = as_test_response(response)
+            @actual = test_response.response_code.to_i
+            expected == @actual
+          rescue TypeError => _ignored
+            @invalid_response = response
+            false
+          end
+
+          # @return [String]
+          def description
+            "respond with numeric status code #{expected}"
+          end
+
+          # @return [String] explaining why the match failed
+          def failure_message
+            invalid_response_type_message ||
+            "expected the response to have status code #{expected.inspect}" \
+              " but it was #{actual.inspect}"
+          end
+
+          # @return [String] explaining why the match failed
+          def failure_message_when_negated
+            invalid_response_type_message ||
+            "expected the response not to have status code " \
+            "#{expected.inspect} but it did"
+          end
+        end
+
+        # @api private
+        # Provides an implementation for `have_http_status` matching against
+        # Rack symbol http status codes.
+        #
+        # Not intended to be instantiated directly.
+        #
+        # @example
+        #   expect(response).to have_http_status(:created)
+        #
+        # @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::Rails::Matchers::BaseMatcher
+          include HaveHttpStatus
+
+          def initialize(status)
+            @expected_status = status
+            @actual = nil
+            @invalid_response = nil
+            set_expected_code!
+          end
+
+          # @param [Object] response object providing an http code to match
+          # @return [Boolean] `true` if Rack's associated numeric HTTP code matched
+          #   the `response` code
+          def matches?(response)
+            test_response = as_test_response(response)
+            @actual = test_response.response_code
+            expected == @actual
+          rescue TypeError => _ignored
+            @invalid_response = response
+            false
+          end
+
+          # @return [String]
+          def description
+            "respond with status code #{pp_expected}"
+          end
+
+          # @return [String] explaining why the match failed
+          def failure_message
+            invalid_response_type_message ||
+            "expected the response to have status code #{pp_expected} but it" \
+              " was #{pp_actual}"
+          end
+
+          # @return [String] explaining why the match failed
+          def failure_message_when_negated
+            invalid_response_type_message ||
+            "expected the response not to have status code #{pp_expected} " \
+              "but it did"
+          end
+
+          # The initialized expected status symbol
+          attr_reader :expected_status
+          private :expected_status
+
+        private
+
+          # @return [Symbol] representing the actual http numeric code
+          def actual_status
+            return unless actual
+            @actual_status ||= compute_status_from(actual)
+          end
+
+          # Reverse lookup of the Rack status code symbol based on the numeric
+          # http code
+          #
+          # @param code [Fixnum] http status code to look up
+          # @return [Symbol] representing the http numeric code
+          def compute_status_from(code)
+            status, _ = Rack::Utils::SYMBOL_TO_STATUS_CODE.find do |_, c|
+              c == code
+            end
+            status
+          end
+
+          # @return [String] pretty format the actual response status
+          def pp_actual
+            pp_status(actual_status, actual)
+          end
+
+          # @return [String] pretty format the expected status and associated code
+          def pp_expected
+            pp_status(expected_status, expected)
+          end
+
+          # @return [String] pretty format the actual response status
+          def pp_status(status, code)
+            if status
+              "#{status.inspect} (#{code})"
+            else
+              code.to_s
+            end
+          end
+
+          # Sets `expected` to the numeric http code based on the Rack
+          # `expected_status` status
+          #
+          # @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
+          end
+        end
+
+        # @api private
+        # Provides an implementation for `have_http_status` matching against
+        # `ActionDispatch::TestResponse` http status category queries.
+        #
+        # Not intended to be instantiated directly.
+        #
+        # @example
+        #   expect(response).to have_http_status(:success)
+        #   expect(response).to have_http_status(:error)
+        #   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::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,
+              :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 or the named response status
+          def matches?(response)
+            test_response = as_test_response(response)
+            @actual = test_response.response_code
+            check_expected_status(test_response, expected)
+          rescue TypeError => _ignored
+            @invalid_response = response
+            false
+          end
+
+          # @return [String]
+          def description
+            "respond with #{type_message}"
+          end
+
+          # @return [String] explaining why the match failed
+          def failure_message
+            invalid_response_type_message ||
+            "expected the response to have #{type_message} but it was #{actual}"
+          end
+
+          # @return [String] explaining why the match failed
+          def failure_message_when_negated
+            invalid_response_type_message ||
+            "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)
+          def type_message
+            @type_message ||= (expected == :error ? "an error" : "a #{expected}") +
+              " status code (#{type_codes})"
+          end
+
+          # @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/rack/rack/blob/master/lib/rack/response.rb `Rack::Response`
+          def type_codes
+            # At the time of this commit the most recent version of
+            # `ActionDispatch::TestResponse` defines the following aliases:
+            #
+            #     alias_method :success?,  :successful?
+            #     alias_method :missing?,  :not_found?
+            #     alias_method :redirect?, :redirection?
+            #     alias_method :error?,    :server_error?
+            #
+            # It's parent `ActionDispatch::Response` includes
+            # `Rack::Response::Helpers` which defines the aliased methods as:
+            #
+            #     def successful?;   status >= 200 && status < 300; end
+            #     def redirection?;  status >= 300 && status < 400; end
+            #     def server_error?; status >= 500 && status < 600; end
+            #     def not_found?;    status == 404;                 end
+            #
+            # @see https://github.com/rails/rails/blob/ca200378/actionpack/lib/action_dispatch/testing/test_response.rb#L17-L27
+            # @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, :server_error
+                              "5xx"
+                            when :success, :successful
+                              "2xx"
+                            when :missing, :not_found
+                              "404"
+                            when :redirect
+                              "3xx"
+                            end
+          end
+        end
+      end
+
+      # @api public
+      # Passes if `response` has a matching HTTP status code.
+      #
+      # The following symbolic status codes are allowed:
+      #
+      # - `Rack::Utils::SYMBOL_TO_STATUS_CODE`
+      # - One of the defined `ActionDispatch::TestResponse` aliases:
+      #   - `:error`
+      #   - `:missing`
+      #   - `:redirect`
+      #   - `:success`
+      #
+      # @example Accepts numeric and symbol statuses
+      #   expect(response).to have_http_status(404)
+      #   expect(response).to have_http_status(:created)
+      #   expect(response).to have_http_status(:success)
+      #   expect(response).to have_http_status(:error)
+      #   expect(response).to have_http_status(:missing)
+      #   expect(response).to have_http_status(:redirect)
+      #
+      # @example Works with standard `response` objects and Capybara's `page`
+      #   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/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
+  end
+end