rspec-rails 3.9.0 → 5.0.1

data/lib/rspec/rails/matchers.rb

@@ -20,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

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

@@ -0,0 +1,65 @@
+require "rspec/rails/matchers/action_cable/have_broadcasted_to"
+
+module RSpec
+  module Rails
+    module Matchers
+      # Namespace for various implementations of ActionCable features
+      #
+      # @api private
+      module ActionCable
+      end
+
+      # @api public
+      # Passes if a message has been sent to a stream/object inside a block.
+      # May chain `at_least`, `at_most` or `exactly` to specify a number of times.
+      # To specify channel from which message has been broadcasted to object use `from_channel`.
+      #
+      #
+      # @example
+      #     expect {
+      #       ActionCable.server.broadcast "messages", text: 'Hi!'
+      #     }.to have_broadcasted_to("messages")
+      #
+      #     expect {
+      #       SomeChannel.broadcast_to(user)
+      #     }.to have_broadcasted_to(user).from_channel(SomeChannel)
+      #
+      #     # Using alias
+      #     expect {
+      #       ActionCable.server.broadcast "messages", text: 'Hi!'
+      #     }.to broadcast_to("messages")
+      #
+      #     expect {
+      #       ActionCable.server.broadcast "messages", text: 'Hi!'
+      #       ActionCable.server.broadcast "all", text: 'Hi!'
+      #     }.to have_broadcasted_to("messages").exactly(:once)
+      #
+      #     expect {
+      #       3.times { ActionCable.server.broadcast "messages", text: 'Hi!' }
+      #     }.to have_broadcasted_to("messages").at_least(2).times
+      #
+      #     expect {
+      #       ActionCable.server.broadcast "messages", text: 'Hi!'
+      #     }.to have_broadcasted_to("messages").at_most(:twice)
+      #
+      #     expect {
+      #       ActionCable.server.broadcast "messages", text: 'Hi!'
+      #     }.to have_broadcasted_to("messages").with(text: 'Hi!')
+      def have_broadcasted_to(target = nil)
+        check_action_cable_adapter
+
+        ActionCable::HaveBroadcastedTo.new(target, channel: described_class)
+      end
+      alias_method :broadcast_to, :have_broadcasted_to
+
+    private
+
+      # @private
+      def check_action_cable_adapter
+        return if ::ActionCable::SubscriptionAdapter::Test === ::ActionCable.server.pubsub
+
+        raise StandardError, "To use ActionCable matchers set `adapter: test` in your cable.yml"
+      end
+    end
+  end
+end

data/lib/rspec/rails/matchers/action_cable/have_broadcasted_to.rb

@@ -0,0 +1,170 @@
+module RSpec
+  module Rails
+    module Matchers
+      module ActionCable
+        # rubocop: disable Metrics/ClassLength
+        # @private
+        class HaveBroadcastedTo < RSpec::Matchers::BuiltIn::BaseMatcher
+          def initialize(target, channel:)
+            @target = target
+            @channel = channel
+            @block = proc { }
+            @data = nil
+            set_expected_number(:exactly, 1)
+          end
+
+          def with(data = nil, &block)
+            @data = data
+            @data = @data.with_indifferent_access if @data.is_a?(Hash)
+            @block = block if block
+            self
+          end
+
+          def exactly(count)
+            set_expected_number(:exactly, count)
+            self
+          end
+
+          def at_least(count)
+            set_expected_number(:at_least, count)
+            self
+          end
+
+          def at_most(count)
+            set_expected_number(:at_most, count)
+            self
+          end
+
+          def times
+            self
+          end
+
+          def once
+            exactly(:once)
+          end
+
+          def twice
+            exactly(:twice)
+          end
+
+          def thrice
+            exactly(:thrice)
+          end
+
+          def failure_message
+            "expected to broadcast #{base_message}".tap do |msg|
+              if @unmatching_msgs.any?
+                msg << "\nBroadcasted messages to #{stream}:"
+                @unmatching_msgs.each do |data|
+                  msg << "\n   #{data}"
+                end
+              end
+            end
+          end
+
+          def failure_message_when_negated
+            "expected not to broadcast #{base_message}"
+          end
+
+          def message_expectation_modifier
+            case @expectation_type
+            when :exactly then "exactly"
+            when :at_most then "at most"
+            when :at_least then "at least"
+            end
+          end
+
+          def supports_block_expectations?
+            true
+          end
+
+          def matches?(proc)
+            raise ArgumentError, "have_broadcasted_to and broadcast_to only support block expectations" unless Proc === proc
+
+            original_sent_messages_count = pubsub_adapter.broadcasts(stream).size
+            proc.call
+            in_block_messages = pubsub_adapter.broadcasts(stream).drop(original_sent_messages_count)
+
+            check(in_block_messages)
+          end
+
+          def from_channel(channel)
+            @channel = channel
+            self
+          end
+
+        private
+
+          def stream
+            @stream ||= if @target.is_a?(String)
+                          @target
+                        else
+                          check_channel_presence
+                          @channel.broadcasting_for(@target)
+                        end
+          end
+
+          def check(messages)
+            @matching_msgs, @unmatching_msgs = messages.partition do |msg|
+              decoded = ActiveSupport::JSON.decode(msg)
+              decoded = decoded.with_indifferent_access if decoded.is_a?(Hash)
+
+              if @data.nil? || @data === decoded
+                @block.call(decoded)
+                true
+              else
+                false
+              end
+            end
+
+            @matching_msgs_count = @matching_msgs.size
+
+            case @expectation_type
+            when :exactly then @expected_number == @matching_msgs_count
+            when :at_most then @expected_number >= @matching_msgs_count
+            when :at_least then @expected_number <= @matching_msgs_count
+            end
+          end
+
+          def set_expected_number(relativity, count)
+            @expectation_type = relativity
+            @expected_number =
+              case count
+              when :once then 1
+              when :twice then 2
+              when :thrice then 3
+              else Integer(count)
+              end
+          end
+
+          def base_message
+            "#{message_expectation_modifier} #{@expected_number} messages to #{stream}".tap do |msg|
+              msg << " with #{data_description(@data)}" unless @data.nil?
+              msg << ", but broadcast #{@matching_msgs_count}"
+            end
+          end
+
+          def data_description(data)
+            if data.is_a?(RSpec::Matchers::Composable)
+              data.description
+            else
+              data
+            end
+          end
+
+          def pubsub_adapter
+            ::ActionCable.server.pubsub
+          end
+
+          def check_channel_presence
+            return if @channel.present? && @channel.respond_to?(:channel_name)
+
+            error_msg = "Broadcasting channel can't be infered. Please, specify it with `from_channel`"
+            raise ArgumentError, error_msg
+          end
+        end
+        # rubocop: enable Metrics/ClassLength
+      end
+    end
+  end
+end

data/lib/rspec/rails/matchers/action_cable/have_streams.rb

@@ -0,0 +1,58 @@
+module RSpec
+  module Rails
+    module Matchers
+      module ActionCable
+        # @api private
+        # Provides the implementation for `have_stream`, `have_stream_for`, and `have_stream_from`.
+        # Not intended to be instantiated directly.
+        class HaveStream < RSpec::Matchers::BuiltIn::BaseMatcher
+          # @api private
+          # @return [String]
+          def failure_message
+            "expected to have #{base_message}"
+          end
+
+          # @api private
+          # @return [String]
+          def failure_message_when_negated
+            "expected not to have #{base_message}"
+          end
+
+          # @api private
+          # @return [Boolean]
+          def matches?(subscription)
+            raise(ArgumentError, "have_streams is used for negated expectations only") if no_expected?
+
+            match(subscription)
+          end
+
+          # @api private
+          # @return [Boolean]
+          def does_not_match?(subscription)
+            !match(subscription)
+          end
+
+        private
+
+          def match(subscription)
+            case subscription
+            when ::ActionCable::Channel::Base
+              @actual = subscription.streams
+              no_expected? ? actual.any? : actual.any? { |i| expected === i }
+            else
+              raise ArgumentError, "have_stream, have_stream_from and have_stream_from support expectations on subscription only"
+            end
+          end
+
+          def base_message
+            no_expected? ? "any stream started" : "stream #{expected_formatted} started, but have #{actual_formatted}"
+          end
+
+          def no_expected?
+            !defined?(@expected)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+module RSpec
+  module Rails
+    module Matchers
+      # Namespace for various implementations of ActionMailbox features
+      #
+      # @api private
+      module ActionMailbox
+        # @private
+        class Base < RSpec::Rails::Matchers::BaseMatcher
+          private
+
+          def create_inbound_email(message)
+            RSpec::Rails::MailboxExampleGroup.create_inbound_email(message)
+          end
+        end
+
+        # @private
+        class ReceiveInboundEmail < Base
+          def initialize(message)
+            super()
+
+            @inbound_email = create_inbound_email(message)
+          end
+
+          if defined?(::ApplicationMailbox) && ::ApplicationMailbox.router.respond_to?(:mailbox_for)
+            def matches?(mailbox)
+              @mailbox  = mailbox
+              @receiver = ApplicationMailbox.router.mailbox_for(inbound_email)
+
+              @receiver == @mailbox
+            end
+          else
+            def matches?(mailbox)
+              @mailbox  = mailbox
+              @receiver = ApplicationMailbox.router.send(:match_to_mailbox, inbound_email)
+
+              @receiver == @mailbox
+            end
+          end
+
+          def failure_message
+            "expected #{describe_inbound_email} to route to #{mailbox}".tap do |msg|
+              if receiver
+                msg << ", but routed to #{receiver} instead"
+              end
+            end
+          end
+
+          def failure_message_when_negated
+            "expected #{describe_inbound_email} not to route to #{mailbox}"
+          end
+
+          private
+
+          attr_reader :inbound_email, :mailbox, :receiver
+
+          def describe_inbound_email
+            "mail to #{inbound_email.mail.to.to_sentence}"
+          end
+        end
+      end
+
+      # @api public
+      # Passes if the given inbound email would be routed to the subject inbox.
+      #
+      # @param message [Hash, Mail::Message] a mail message or hash of
+      #   attributes used to build one
+      def receive_inbound_email(message)
+        ActionMailbox::ReceiveInboundEmail.new(message)
+      end
+    end
+  end
+end

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

@@ -8,14 +8,14 @@ module RSpec
       #
       # @api private
       module ActiveJob
-        # rubocop: disable Style/ClassLength
+        # rubocop: disable Metrics/ClassLength
         # @private
         class Base < RSpec::Rails::Matchers::BaseMatcher
           def initialize
             @args = []
             @queue = nil
             @at = nil
-            @block = Proc.new {}
+            @block = proc { }
             set_expected_number(:exactly, 1)
           end
 
@@ -26,12 +26,16 @@ module RSpec
           end
 
           def on_queue(queue)
-            @queue = queue
+            @queue = queue.to_s
             self
           end
 
-          def at(date)
-            @at = date
+          def at(time_or_date)
+            case time_or_date
+            when Time then @at = Time.at(time_or_date.to_f)
+            else
+              @at = time_or_date
+            end
             self
           end
 
@@ -67,7 +71,7 @@ module RSpec
           end
 
           def failure_message
-            "expected to enqueue #{base_message}".tap do |msg|
+            "expected to #{self.class::FAILURE_MESSAGE_EXPECTATION_ACTION} #{base_message}".tap do |msg|
               if @unmatching_jobs.any?
                 msg << "\nQueued jobs:"
                 @unmatching_jobs.each do |job|
@@ -78,7 +82,7 @@ module RSpec
           end
 
           def failure_message_when_negated
-            "expected not to enqueue #{base_message}"
+            "expected not to #{self.class::FAILURE_MESSAGE_EXPECTATION_ACTION} #{base_message}"
           end
 
           def message_expectation_modifier
@@ -97,7 +101,7 @@ module RSpec
 
           def check(jobs)
             @matching_jobs, @unmatching_jobs = jobs.partition do |job|
-              if arguments_match?(job) && other_attributes_match?(job)
+              if job_match?(job) && arguments_match?(job) && queue_match?(job) && at_match?(job)
                 args = deserialize_arguments(job)
                 @block.call(*args)
                 true
@@ -119,7 +123,7 @@ module RSpec
               msg << " with #{@args}," if @args.any?
               msg << " on queue #{@queue}," if @queue
               msg << " at #{@at.inspect}," if @at
-              msg << " but enqueued #{@matching_jobs_count}"
+              msg << " but #{self.class::MESSAGE_EXPECTATION_ACTION} #{@matching_jobs_count}"
             end
           end
 
@@ -134,29 +138,54 @@ module RSpec
             end
           end
 
+          def job_match?(job)
+            @job ? @job == job[:job] : true
+          end
+
           def arguments_match?(job)
             if @args.any?
+              args = serialize_and_deserialize_arguments(@args)
               deserialized_args = deserialize_arguments(job)
-              RSpec::Mocks::ArgumentListMatcher.new(*@args).args_match?(*deserialized_args)
+              RSpec::Mocks::ArgumentListMatcher.new(*args).args_match?(*deserialized_args)
             else
               true
             end
           end
 
-          def other_attributes_match?(job)
-            serialized_attributes.all? { |key, value| value == job[key] }
+          def queue_match?(job)
+            return true unless @queue
+
+            @queue == job[:queue]
           end
 
-          def serialized_attributes
-            {}.tap do |attributes|
-              attributes[:at]    = serialized_at if @at
-              attributes[:queue] = @queue if @queue
-              attributes[:job]   = @job if @job
-            end
+          def at_match?(job)
+            return true unless @at
+            return job[:at].nil? if @at == :no_wait
+            return false unless job[:at]
+
+            scheduled_at = Time.at(job[:at])
+            values_match?(@at, scheduled_at) || check_for_inprecise_value(scheduled_at)
           end
 
-          def serialized_at
-            @at == :no_wait ? nil : @at.to_f
+          def check_for_inprecise_value(scheduled_at)
+            return unless Time === @at && values_match?(@at.change(usec: 0), scheduled_at)
+
+            RSpec.warn_with((<<-WARNING).gsub(/^\s+\|/, '').chomp)
+            |[WARNING] Your expected `at(...)` value does not match the job scheduled_at value
+            |unless microseconds are removed. This precision error often occurs when checking
+            |values against `Time.current` / `Time.now` which have usec precision, but Rails
+            |uses `n.seconds.from_now` internally which has a usec count of `0`.
+            |
+            |Use `change(usec: 0)` to correct these values. For example:
+            |
+            |`Time.current.change(usec: 0)`
+            |
+            |Note: RSpec cannot do this for you because jobs can be scheduled with usec
+            |precision and we do not know wether it is on purpose or not.
+            |
+            |
+            WARNING
+            false
           end
 
           def set_expected_number(relativity, count)
@@ -169,6 +198,13 @@ module RSpec
                                end
           end
 
+          def serialize_and_deserialize_arguments(args)
+            serialized = ::ActiveJob::Arguments.serialize(args)
+            ::ActiveJob::Arguments.deserialize(serialized)
+          rescue ::ActiveJob::SerializationError
+            args
+          end
+
           def deserialize_arguments(job)
             ::ActiveJob::Arguments.deserialize(job[:args])
           rescue ::ActiveJob::DeserializationError
@@ -179,10 +215,13 @@ module RSpec
             ::ActiveJob::Base.queue_adapter
           end
         end
-        # rubocop: enable Style/ClassLength
+        # rubocop: enable Metrics/ClassLength
 
         # @private
         class HaveEnqueuedJob < Base
+          FAILURE_MESSAGE_EXPECTATION_ACTION = 'enqueue'.freeze
+          MESSAGE_EXPECTATION_ACTION = 'enqueued'.freeze
+
           def initialize(job)
             super()
             @job = job
@@ -207,6 +246,9 @@ module RSpec
 
         # @private
         class HaveBeenEnqueued < Base
+          FAILURE_MESSAGE_EXPECTATION_ACTION = 'enqueue'.freeze
+          MESSAGE_EXPECTATION_ACTION = 'enqueued'.freeze
+
           def matches?(job)
             @job = job
             check(queue_adapter.enqueued_jobs)
@@ -218,6 +260,38 @@ module RSpec
             !matches?(proc)
           end
         end
+
+        # @private
+        class HavePerformedJob < Base
+          FAILURE_MESSAGE_EXPECTATION_ACTION = 'perform'.freeze
+          MESSAGE_EXPECTATION_ACTION = 'performed'.freeze
+
+          def initialize(job)
+            super()
+            @job = job
+          end
+
+          def matches?(proc)
+            raise ArgumentError, "have_performed_job only supports block expectations" unless Proc === proc
+
+            original_performed_jobs_count = queue_adapter.performed_jobs.count
+            proc.call
+            in_block_jobs = queue_adapter.performed_jobs.drop(original_performed_jobs_count)
+
+            check(in_block_jobs)
+          end
+        end
+
+        # @private
+        class HaveBeenPerformed < Base
+          FAILURE_MESSAGE_EXPECTATION_ACTION = 'perform'.freeze
+          MESSAGE_EXPECTATION_ACTION = 'performed'.freeze
+
+          def matches?(job)
+            @job = job
+            check(queue_adapter.performed_jobs)
+          end
+        end
       end
 
       # @api public
@@ -305,11 +379,85 @@ module RSpec
         ActiveJob::HaveBeenEnqueued.new
       end
 
+      # @api public
+      # Passes if a job has been performed inside block. May chain at_least, at_most or exactly to specify a number of times.
+      #
+      # @example
+      #     expect {
+      #       perform_jobs { HeavyLiftingJob.perform_later }
+      #     }.to have_performed_job
+      #
+      #     expect {
+      #       perform_jobs {
+      #         HelloJob.perform_later
+      #         HeavyLiftingJob.perform_later
+      #       }
+      #     }.to have_performed_job(HelloJob).exactly(:once)
+      #
+      #     expect {
+      #       perform_jobs { 3.times { HelloJob.perform_later } }
+      #     }.to have_performed_job(HelloJob).at_least(2).times
+      #
+      #     expect {
+      #       perform_jobs { HelloJob.perform_later }
+      #     }.to have_performed_job(HelloJob).at_most(:twice)
+      #
+      #     expect {
+      #       perform_jobs {
+      #         HelloJob.perform_later
+      #         HeavyLiftingJob.perform_later
+      #       }
+      #     }.to have_performed_job(HelloJob).and have_performed_job(HeavyLiftingJob)
+      #
+      #     expect {
+      #       perform_jobs {
+      #         HelloJob.set(wait_until: Date.tomorrow.noon, queue: "low").perform_later(42)
+      #       }
+      #     }.to have_performed_job.with(42).on_queue("low").at(Date.tomorrow.noon)
+      def have_performed_job(job = nil)
+        check_active_job_adapter
+        ActiveJob::HavePerformedJob.new(job)
+      end
+      alias_method :perform_job, :have_performed_job
+
+      # @api public
+      # Passes if a job has been performed. May chain at_least, at_most or exactly to specify a number of times.
+      #
+      # @example
+      #     before do
+      #       ActiveJob::Base.queue_adapter.performed_jobs.clear
+      #       ActiveJob::Base.queue_adapter.perform_enqueued_jobs = true
+      #       ActiveJob::Base.queue_adapter.perform_enqueued_at_jobs = true
+      #     end
+      #
+      #     HeavyLiftingJob.perform_later
+      #     expect(HeavyLiftingJob).to have_been_performed
+      #
+      #     HelloJob.perform_later
+      #     HeavyLiftingJob.perform_later
+      #     expect(HeavyLiftingJob).to have_been_performed.exactly(:once)
+      #
+      #     3.times { HelloJob.perform_later }
+      #     expect(HelloJob).to have_been_performed.at_least(2).times
+      #
+      #     HelloJob.perform_later
+      #     HeavyLiftingJob.perform_later
+      #     expect(HelloJob).to have_been_performed
+      #     expect(HeavyLiftingJob).to have_been_performed
+      #
+      #     HelloJob.set(wait_until: Date.tomorrow.noon, queue: "low").perform_later(42)
+      #     expect(HelloJob).to have_been_performed.with(42).on_queue("low").at(Date.tomorrow.noon)
+      def have_been_performed
+        check_active_job_adapter
+        ActiveJob::HaveBeenPerformed.new
+      end
+
     private
 
       # @private
       def check_active_job_adapter
         return if ::ActiveJob::QueueAdapters::TestAdapter === ::ActiveJob::Base.queue_adapter
+
         raise StandardError, "To use ActiveJob matchers set `ActiveJob::Base.queue_adapter = :test`"
       end
     end