Add have_enqueued mail matcher (#2047)

* Write first test case for calling simple mailer method with deliver_later

* Move deliver_later gem logic into HaveEnqueuedMail matcher

Moving the internals of
https://github.com/jdlubrano/deliver_later_matchers into rspec-rails as
a new RSpec::Rails::Matchers::HaveEnqueuedMail class.

* Add tests for arguments matcher and error messages.  Largely based on existing ActiveJob matcher tests.

* Add exactly, at_least, at_most functionality for have_enqueued_mail matcher.

* Support mailer methods with default/optional arguments; Support matching email methods that accept parameters when no specific arguments are expected.

* Correct private YARD doc on RSpec::Rails::Matchers::HaveEnqueuedJob

* Provide unmatching enqueued email info in failure messages

The ActiveJob matcher provides output for each unmatching, enqueued job
in its failure messages.  Those unmatching jobs have certainly helped me
catch typos in the past, so it makes sense to provide similar feedback
in enqueued email failure messages.

* Add tests for have_enqueued_mail matcher at_least and at_most modifiers

* Add support for `at` and `on_queue`

deliver_later can be called with `wait`, `wait_until`, and `queue`
keyword arguments, so the have_enqueued_mail matcher should support
matching those types of things.  At this point, I am beginning to
suspect that this code would be better off using inheritance over
composition.  I am going to try and refactor to inherit from the
ActiveJob base matcher now that I have all of the tests in a good state.

* Explicitly require rspec/mocks for access to `anything` method

* Ignore Rubocop class length for HaveEnqueuedMail class

* Replace .negative? with < 0 for older ruby versions

* Remove .inspect call from test to see if that works...

* Remove %i array syntax for older ruby versions

* Remove the send_time part of the error message to see if that is causing the failed test

* Replace new Hash key syntax with old => format for Ruby 1.8.7

* Call strftime in test to get some semblance of timestamp verification

* Fix Ruby 1.8.7 syntax errors

* Fix ActiveJob::Base.queue_adapter error

When using the HaveEnqueuedMail matcher, the error message should not complain
about using "ActiveJob" matchers.

* Refactor HaveEnqueuedMail matcher to be a subclass of the HaveEnqueuedJob matcher

Implementing as a subclass resulted in DRYer code IMO.  There was no
longer a need to reimplement once, twice, thrice and other duplicated
methods that were basically just delegating to the job_matcher instance
variable anyways.

* Support with blocks

* Test that non-mailer jobs do not appear in the have_enqueued_mail matcher list of mail jobs

* Make 'deliver_now' a frozen constant

* Only pass a mailer-specific block to super if a block is provided

* Fix hash rocket syntax for Ruby 1.8.7

Author: jdlubrano

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