actionmailer 7.0.8.1 → 7.2.2.1

data/lib/action_mailer/form_builder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ActionMailer
+  # = Action Mailer Form Builder
+  #
+  # Override the default form builder for all views rendered by this
+  # mailer and any of its descendants. Accepts a subclass of
+  # ActionView::Helpers::FormBuilder.
+  #
+  # While emails typically will not include forms, this can be used
+  # by views that are shared between controllers and mailers.
+  #
+  # For more information, see +ActionController::FormBuilder+.
+  module FormBuilder
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_default_form_builder, instance_accessor: false
+    end
+
+    module ClassMethods
+      # Set the form builder to be used as the default for all forms
+      # in the views rendered by this mailer and its subclasses.
+      #
+      # ==== Parameters
+      # * <tt>builder</tt> - Default form builder, an instance of ActionView::Helpers::FormBuilder
+      def default_form_builder(builder)
+        self._default_form_builder = builder
+      end
+    end
+
+    # Default form builder for the mailer
+    def default_form_builder
+      self.class._default_form_builder
+    end
+  end
+end

data/lib/action_mailer/gem_version.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 module ActionMailer
-  # Returns the currently loaded version of Action Mailer as a <tt>Gem::Version</tt>.
+  # Returns the currently loaded version of Action Mailer as a +Gem::Version+.
   def self.gem_version
     Gem::Version.new VERSION::STRING
   end
 
   module VERSION
     MAJOR = 7
-    MINOR = 0
-    TINY  = 8
+    MINOR = 2
+    TINY  = 2
     PRE   = "1"
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

data/lib/action_mailer/inline_preview_interceptor.rb

@@ -3,6 +3,8 @@
 require "base64"
 
 module ActionMailer
+  # = Action Mailer \InlinePreviewInterceptor
+  #
   # Implements a mailer preview interceptor that converts image tag src attributes
   # that use inline cid: style URLs to data: style URLs so that they are visible
   # when previewing an HTML email in a web browser.

data/lib/action_mailer/log_subscriber.rb

@@ -3,14 +3,17 @@
 require "active_support/log_subscriber"
 
 module ActionMailer
+  # = Action Mailer \LogSubscriber
+  #
   # Implements the ActiveSupport::LogSubscriber for logging notifications when
   # email is delivered or received.
   class LogSubscriber < ActiveSupport::LogSubscriber
     # An email was delivered.
     def deliver(event)
       info do
-        perform_deliveries = event.payload[:perform_deliveries]
-        if perform_deliveries
+        if exception = event.payload[:exception_object]
+          "Failed delivery of mail #{event.payload[:message_id]} error_class=#{exception.class} error_message=#{exception.message.inspect}"
+        elsif event.payload[:perform_deliveries]
           "Delivered mail #{event.payload[:message_id]} (#{event.duration.round(1)}ms)"
         else
           "Skipped delivery of mail #{event.payload[:message_id]} as `perform_deliveries` is false"
@@ -19,6 +22,7 @@ module ActionMailer
 
       debug { event.payload[:mail] }
     end
+    subscribe_log_level :deliver, :debug
 
     # An email was generated.
     def process(event)
@@ -28,6 +32,7 @@ module ActionMailer
         "#{mailer}##{action}: processed outbound mail in #{event.duration.round(1)}ms"
       end
     end
+    subscribe_log_level :process, :debug
 
     # Use the logger configured for ActionMailer::Base.
     def logger

data/lib/action_mailer/mail_delivery_job.rb

@@ -3,13 +3,18 @@
 require "active_job"
 
 module ActionMailer
-  # The <tt>ActionMailer::MailDeliveryJob</tt> class is used when you
+  # = Action Mailer \MailDeliveryJob
+  #
+  # The +ActionMailer::MailDeliveryJob+ class is used when you
   # want to send emails outside of the request-response cycle. It supports
   # sending either parameterized or normal mail.
   #
   # Exceptions are rescued and handled by the mailer class.
   class MailDeliveryJob < ActiveJob::Base # :nodoc:
-    queue_as { ActionMailer::Base.deliver_later_queue_name }
+    queue_as do
+      mailer_class = arguments.first.constantize
+      mailer_class.deliver_later_queue_name
+    end
 
     rescue_from StandardError, with: :handle_exception_with_mailer_class
 

data/lib/action_mailer/mail_helper.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActionMailer
+  # = Action Mailer \MailHelper
+  #
   # Provides helper methods for ActionMailer::Base that can be used for easily
   # formatting messages, accessing mailer or message instances, and the
   # attachments list.
@@ -23,10 +25,18 @@ module ActionMailer
       }.join("\n\n")
 
       # Make list points stand on their own line
-      formatted.gsub!(/[ ]*([*]+) ([^*]*)/) { "  #{$1} #{$2.strip}\n" }
-      formatted.gsub!(/[ ]*([#]+) ([^#]*)/) { "  #{$1} #{$2.strip}\n" }
+      output = +""
+      splits = formatted.split(/(\*+|\#+)/)
+      while line = splits.shift
+        if line.start_with?("*", "#") && splits.first&.start_with?(" ")
+          output.chomp!(" ") while output.end_with?(" ")
+          output << "  #{line} #{splits.shift.strip}\n"
+        else
+          output << line
+        end
+      end
 
-      formatted
+      output
     end
 
     # Access the mailer instance.

data/lib/action_mailer/message_delivery.rb

@@ -3,11 +3,13 @@
 require "delegate"
 
 module ActionMailer
-  # The <tt>ActionMailer::MessageDelivery</tt> class is used by
+  # = Action Mailer \MessageDelivery
+  #
+  # The +ActionMailer::MessageDelivery+ class is used by
   # ActionMailer::Base when creating a new mailer.
   # <tt>MessageDelivery</tt> is a wrapper (+Delegator+ subclass) around a lazy
-  # created <tt>Mail::Message</tt>. You can get direct access to the
-  # <tt>Mail::Message</tt>, deliver the email or schedule the email to be sent
+  # created +Mail::Message+. You can get direct access to the
+  # +Mail::Message+, deliver the email or schedule the email to be sent
   # through Active Job.
   #
   #   Notifier.welcome(User.first)               # an ActionMailer::MessageDelivery object
@@ -62,9 +64,10 @@ module ActionMailer
     # * <tt>:queue</tt> - Enqueue the email on the specified queue
     # * <tt>:priority</tt> - Enqueues the email with the specified priority
     #
-    # By default, the email will be enqueued using <tt>ActionMailer::MailDeliveryJob</tt>. Each
-    # ActionMailer::Base class can specify the job to use by setting the class variable
-    # +delivery_job+.
+    # By default, the email will be enqueued using ActionMailer::MailDeliveryJob on
+    # the default queue. Mailer classes can customize the queue name used for the default
+    # job by assigning a +deliver_later_queue_name+ class variable, or provide a custom job
+    # by assigning a +delivery_job+. When a custom job is used, it controls the queue name.
     #
     #   class AccountRegistrationMailer < ApplicationMailer
     #     self.delivery_job = RegistrationDeliveryJob
@@ -88,9 +91,10 @@ module ActionMailer
     # * <tt>:queue</tt> - Enqueue the email on the specified queue.
     # * <tt>:priority</tt> - Enqueues the email with the specified priority
     #
-    # By default, the email will be enqueued using <tt>ActionMailer::MailDeliveryJob</tt>. Each
-    # ActionMailer::Base class can specify the job to use by setting the class variable
-    # +delivery_job+.
+    # By default, the email will be enqueued using ActionMailer::MailDeliveryJob on
+    # the default queue. Mailer classes can customize the queue name used for the default
+    # job by assigning a +deliver_later_queue_name+ class variable, or provide a custom job
+    # by assigning a +delivery_job+. When a custom job is used, it controls the queue name.
     #
     #   class AccountRegistrationMailer < ApplicationMailer
     #     self.delivery_job = RegistrationDeliveryJob
@@ -106,7 +110,9 @@ module ActionMailer
     #
     def deliver_now!
       processed_mailer.handle_exceptions do
-        message.deliver!
+        processed_mailer.run_callbacks(:deliver) do
+          message.deliver!
+        end
       end
     end
 
@@ -116,13 +122,15 @@ module ActionMailer
     #
     def deliver_now
       processed_mailer.handle_exceptions do
-        message.deliver
+        processed_mailer.run_callbacks(:deliver) do
+          message.deliver
+        end
       end
     end
 
     private
       # Returns the processed Mailer instance. We keep this instance
-      # on hand so we can delegate exception handling to it.
+      # on hand so we can run callbacks and delegate exception handling to it.
       def processed_mailer
         @processed_mailer ||= @mailer_class.new.tap do |mailer|
           mailer.process @action, *@args

data/lib/action_mailer/parameterized.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActionMailer
+  # = Action Mailer \Parameterized
+  #
   # Provides the option to parameterize mailers in order to share instance variable
   # setup, processing, and common headers.
   #
@@ -88,7 +90,11 @@ module ActionMailer
     extend ActiveSupport::Concern
 
     included do
-      attr_accessor :params
+      attr_writer :params
+
+      def params
+        @params ||= {}
+      end
     end
 
     module ClassMethods
@@ -108,14 +114,13 @@ module ActionMailer
       end
 
       private
-        def method_missing(method_name, *args)
-          if @mailer.action_methods.include?(method_name.to_s)
-            ActionMailer::Parameterized::MessageDelivery.new(@mailer, method_name, @params, *args)
+        def method_missing(method_name, ...)
+          if @mailer.action_methods.include?(method_name.name)
+            ActionMailer::Parameterized::MessageDelivery.new(@mailer, method_name, @params, ...)
           else
             super
           end
         end
-        ruby2_keywords(:method_missing)
 
         def respond_to_missing?(method, include_all = false)
           @mailer.respond_to?(method, include_all)
@@ -123,11 +128,10 @@ module ActionMailer
     end
 
     class MessageDelivery < ActionMailer::MessageDelivery # :nodoc:
-      def initialize(mailer_class, action, params, *args)
-        super(mailer_class, action, *args)
+      def initialize(mailer_class, action, params, ...)
+        super(mailer_class, action, ...)
         @params = params
       end
-      ruby2_keywords(:initialize)
 
       private
         def processed_mailer

data/lib/action_mailer/preview.rb

@@ -7,11 +7,11 @@ module ActionMailer
     extend ActiveSupport::Concern
 
     included do
-      # Set the location of mailer previews through app configuration:
+      # Add the location of mailer previews through app configuration:
       #
-      #     config.action_mailer.preview_path = "#{Rails.root}/lib/mailer_previews"
+      #     config.action_mailer.preview_paths << "#{Rails.root}/lib/mailer_previews"
       #
-      mattr_accessor :preview_path, instance_writer: false
+      mattr_accessor :preview_paths, instance_writer: false, default: []
 
       # Enable or disable mailer previews through app configuration:
       #
@@ -79,7 +79,7 @@ module ActionMailer
       # Returns all mailer preview classes.
       def all
         load_previews if descendants.empty?
-        descendants
+        descendants.sort_by { |mailer| mailer.name.titleize }
       end
 
       # Returns the mail object for the given email name. The registered preview
@@ -119,13 +119,13 @@ module ActionMailer
 
       private
         def load_previews
-          if preview_path
-            Dir["#{preview_path}/**/*_preview.rb"].sort.each { |file| require_dependency file }
+          preview_paths.each do |preview_path|
+            Dir["#{preview_path}/**/*_preview.rb"].sort.each { |file| require file }
           end
         end
 
-        def preview_path
-          Base.preview_path
+        def preview_paths
+          Base.preview_paths
         end
 
         def show_previews

data/lib/action_mailer/queued_delivery.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActionMailer
+  module QueuedDelivery
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :delivery_job, default: ::ActionMailer::MailDeliveryJob
+      class_attribute :deliver_later_queue_name, default: :mailers
+    end
+  end
+end

data/lib/action_mailer/railtie.rb

@@ -8,8 +8,13 @@ require "abstract_controller/railties/routes_helpers"
 module ActionMailer
   class Railtie < Rails::Railtie # :nodoc:
     config.action_mailer = ActiveSupport::OrderedOptions.new
+    config.action_mailer.preview_paths = []
     config.eager_load_namespaces << ActionMailer
 
+    initializer "action_mailer.deprecator", before: :load_environment_config do |app|
+      app.deprecators[:action_mailer] = ActionMailer.deprecator
+    end
+
     initializer "action_mailer.logger" do
       ActiveSupport.on_load(:action_mailer) { self.logger ||= Rails.logger }
     end
@@ -23,10 +28,7 @@ module ActionMailer
       options.stylesheets_dir ||= paths["public/stylesheets"].first
       options.show_previews = Rails.env.development? if options.show_previews.nil?
       options.cache_store ||= Rails.cache
-
-      if options.show_previews
-        options.preview_path ||= defined?(Rails.root) ? "#{Rails.root}/test/mailers/previews" : nil
-      end
+      options.preview_paths |= ["#{Rails.root}/test/mailers/previews"]
 
       # make sure readers methods get compiled
       options.asset_host          ||= app.config.asset_host
@@ -40,6 +42,7 @@ module ActionMailer
         register_interceptors(options.delete(:interceptors))
         register_preview_interceptors(options.delete(:preview_interceptors))
         register_observers(options.delete(:observers))
+        self.preview_paths |= options[:preview_paths]
 
         if delivery_job = options.delete(:delivery_job)
           self.delivery_job = delivery_job.constantize
@@ -65,12 +68,9 @@ module ActionMailer
       end
     end
 
-    initializer "action_mailer.set_autoload_paths" do |app|
+    initializer "action_mailer.set_autoload_paths", before: :set_autoload_paths do |app|
       options = app.config.action_mailer
-
-      if options.show_previews && options.preview_path
-        ActiveSupport::Dependencies.autoload_paths << options.preview_path
-      end
+      app.config.paths["test/mailers/previews"].concat(options.preview_paths)
     end
 
     initializer "action_mailer.compile_config_methods" do
@@ -79,18 +79,13 @@ module ActionMailer
       end
     end
 
-    initializer "action_mailer.eager_load_actions" do
-      ActiveSupport.on_load(:after_initialize) do
-        ActionMailer::Base.descendants.each(&:action_methods) if config.eager_load
-      end
-    end
-
     config.after_initialize do |app|
       options = app.config.action_mailer
 
       if options.show_previews
         app.routes.prepend do
-          get "/rails/mailers"       => "rails/mailers#index", internal: true
+          get "/rails/mailers" => "rails/mailers#index", internal: true
+          get "/rails/mailers/download/*path" => "rails/mailers#download", internal: true
           get "/rails/mailers/*path" => "rails/mailers#preview", internal: true
         end
       end

data/lib/action_mailer/rescuable.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActionMailer # :nodoc:
+  # = Action Mailer \Rescuable
+  #
   # Provides
   # {rescue_from}[rdoc-ref:ActiveSupport::Rescuable::ClassMethods#rescue_from]
   # for mailers. Wraps mailer action processing, mail job processing, and mail

data/lib/action_mailer/test_case.rb

@@ -74,6 +74,15 @@ module ActionMailer
         end
       end
 
+      # Reads the fixture file for the given mailer.
+      #
+      # This is useful when testing mailers by being able to write the body of
+      # an email inside a fixture. See the testing guide for a concrete example:
+      # https://guides.rubyonrails.org/testing.html#revenge-of-the-fixtures
+      def read_fixture(action)
+        IO.readlines(File.join(Rails.root, "test", "fixtures", self.class.mailer_class.name.underscore, action))
+      end
+
       private
         def initialize_test_deliveries
           set_delivery_method :test
@@ -110,10 +119,6 @@ module ActionMailer
         def encode(subject)
           Mail::Encodings.q_value_encode(subject, charset)
         end
-
-        def read_fixture(action)
-          IO.readlines(File.join(Rails.root, "test", "fixtures", self.class.mailer_class.name.underscore, action))
-        end
     end
 
     include Behavior

data/lib/action_mailer/test_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/array/extract_options"
 require "active_job"
 
 module ActionMailer
@@ -33,10 +34,8 @@ module ActionMailer
     #   end
     def assert_emails(number, &block)
       if block_given?
-        original_count = ActionMailer::Base.deliveries.size
-        perform_enqueued_jobs(only: ->(job) { delivery_job_filter(job) }, &block)
-        new_count = ActionMailer::Base.deliveries.size
-        assert_equal number, new_count - original_count, "#{number} emails expected, but #{new_count - original_count} were sent"
+        diff = capture_emails(&block).length
+        assert_equal number, diff, "#{number} emails expected, but #{diff} were sent"
       else
         assert_equal number, ActionMailer::Base.deliveries.size
       end
@@ -94,18 +93,50 @@ module ActionMailer
     end
 
     # Asserts that a specific email has been enqueued, optionally
-    # matching arguments.
+    # matching arguments and/or params.
     #
     #   def test_email
     #     ContactMailer.welcome.deliver_later
     #     assert_enqueued_email_with ContactMailer, :welcome
     #   end
     #
+    #   def test_email_with_parameters
+    #     ContactMailer.with(greeting: "Hello").welcome.deliver_later
+    #     assert_enqueued_email_with ContactMailer, :welcome, args: { greeting: "Hello" }
+    #   end
+    #
     #   def test_email_with_arguments
     #     ContactMailer.welcome("Hello", "Goodbye").deliver_later
     #     assert_enqueued_email_with ContactMailer, :welcome, args: ["Hello", "Goodbye"]
     #   end
     #
+    #   def test_email_with_named_arguments
+    #     ContactMailer.welcome(greeting: "Hello", farewell: "Goodbye").deliver_later
+    #     assert_enqueued_email_with ContactMailer, :welcome, args: [{ greeting: "Hello", farewell: "Goodbye" }]
+    #   end
+    #
+    #   def test_email_with_parameters_and_arguments
+    #     ContactMailer.with(greeting: "Hello").welcome("Cheers", "Goodbye").deliver_later
+    #     assert_enqueued_email_with ContactMailer, :welcome, params: { greeting: "Hello" }, args: ["Cheers", "Goodbye"]
+    #   end
+    #
+    #   def test_email_with_parameters_and_named_arguments
+    #     ContactMailer.with(greeting: "Hello").welcome(farewell: "Goodbye").deliver_later
+    #     assert_enqueued_email_with ContactMailer, :welcome, params: { greeting: "Hello" }, args: [{farewell: "Goodbye"}]
+    #   end
+    #
+    #   def test_email_with_parameterized_mailer
+    #     ContactMailer.with(greeting: "Hello").welcome.deliver_later
+    #     assert_enqueued_email_with ContactMailer.with(greeting: "Hello"), :welcome
+    #   end
+    #
+    #   def test_email_with_matchers
+    #     ContactMailer.with(greeting: "Hello").welcome("Cheers", "Goodbye").deliver_later
+    #     assert_enqueued_email_with ContactMailer, :welcome,
+    #       params: ->(params) { /hello/i.match?(params[:greeting]) },
+    #       args: ->(args) { /cheers/i.match?(args[0]) }
+    #   end
+    #
     # If a block is passed, that block should cause the specified email
     # to be enqueued.
     #
@@ -123,13 +154,23 @@ module ActionMailer
     #       ContactMailer.with(email: 'user@example.com').welcome.deliver_later
     #     end
     #   end
-    def assert_enqueued_email_with(mailer, method, args: nil, queue: ActionMailer::Base.deliver_later_queue_name || "default", &block)
-      args = if args.is_a?(Hash)
-        [mailer.to_s, method.to_s, "deliver_now", params: args, args: []]
-      else
-        [mailer.to_s, method.to_s, "deliver_now", args: Array(args)]
+    def assert_enqueued_email_with(mailer, method, params: nil, args: nil, queue: nil, &block)
+      if mailer.is_a? ActionMailer::Parameterized::Mailer
+        params = mailer.instance_variable_get(:@params)
+        mailer = mailer.instance_variable_get(:@mailer)
       end
-      assert_enqueued_with(job: mailer.delivery_job, args: args, queue: queue.to_s, &block)
+
+      args = Array(args) unless args.is_a?(Proc)
+      queue ||= mailer.deliver_later_queue_name || ActiveJob::Base.default_queue_name
+
+      expected = ->(job_args) do
+        job_kwargs = job_args.extract_options!
+
+        [mailer.to_s, method.to_s, "deliver_now"] == job_args &&
+          params === job_kwargs[:params] && args === job_kwargs[:args]
+      end
+
+      assert_enqueued_with(job: mailer.delivery_job, args: expected, queue: queue.to_s, &block)
     end
 
     # Asserts that no emails are enqueued for later delivery.
@@ -151,6 +192,68 @@ module ActionMailer
       assert_enqueued_emails 0, &block
     end
 
+    # Delivers all enqueued emails. If a block is given, delivers all of the emails
+    # that were enqueued throughout the duration of the block. If a block is
+    # not given, delivers all the enqueued emails up to this point in the test.
+    #
+    #   def test_deliver_enqueued_emails
+    #     deliver_enqueued_emails do
+    #       ContactMailer.welcome.deliver_later
+    #     end
+    #
+    #     assert_emails 1
+    #   end
+    #
+    #   def test_deliver_enqueued_emails_without_block
+    #     ContactMailer.welcome.deliver_later
+    #
+    #     deliver_enqueued_emails
+    #
+    #     assert_emails 1
+    #   end
+    #
+    # If the +:queue+ option is specified,
+    # then only the emails(s) enqueued to a specific queue will be performed.
+    #
+    #   def test_deliver_enqueued_emails_with_queue
+    #     deliver_enqueued_emails queue: :external_mailers do
+    #       CustomerMailer.deliver_later_queue_name = :external_mailers
+    #       CustomerMailer.welcome.deliver_later # will be performed
+    #       EmployeeMailer.deliver_later_queue_name = :internal_mailers
+    #       EmployeeMailer.welcome.deliver_later # will not be performed
+    #     end
+    #
+    #     assert_emails 1
+    #   end
+    #
+    # If the +:at+ option is specified, then only delivers emails enqueued to deliver
+    # immediately or before the given time.
+    def deliver_enqueued_emails(queue: nil, at: nil, &block)
+      perform_enqueued_jobs(only: ->(job) { delivery_job_filter(job) }, queue: queue, at: at, &block)
+    end
+
+    # Returns any emails that are sent in the block.
+    #
+    #   def test_emails
+    #     emails = capture_emails do
+    #       ContactMailer.welcome.deliver_now
+    #     end
+    #     assert_equal "Hi there", emails.first.subject
+    #
+    #     emails = capture_emails do
+    #       ContactMailer.welcome.deliver_now
+    #       ContactMailer.welcome.deliver_later
+    #     end
+    #     assert_equal "Hi there", emails.first.subject
+    #   end
+    def capture_emails(&block)
+      original_count = ActionMailer::Base.deliveries.size
+      deliver_enqueued_emails(&block)
+      new_count = ActionMailer::Base.deliveries.size
+      diff = new_count - original_count
+      ActionMailer::Base.deliveries.last(diff)
+    end
+
     private
       def delivery_job_filter(job)
         job_class = job.is_a?(Hash) ? job.fetch(:job) : job.class

data/lib/action_mailer/version.rb

@@ -4,7 +4,7 @@ require_relative "gem_version"
 
 module ActionMailer
   # Returns the currently loaded version of Action Mailer as a
-  # <tt>Gem::Version</tt>.
+  # +Gem::Version+.
   def self.version
     gem_version
   end