actionmailer 7.0.8 → 7.1.0.beta1

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.

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

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:
       #
@@ -25,7 +25,31 @@ module ActionMailer
       mattr_accessor :preview_interceptors, instance_writer: false, default: [ActionMailer::InlinePreviewInterceptor]
     end
 
+    def preview_path
+      ActionMailer.deprecator.warn(<<-MSG.squish)
+        Using preview_path option is deprecated and will be removed in Rails 7.2.
+        Please use preview_paths instead.
+      MSG
+      self.class.preview_paths.first
+    end
+
     module ClassMethods
+      def preview_path=(value)
+        ActionMailer.deprecator.warn(<<-MSG.squish)
+          Using preview_path= option is deprecated and will be removed in Rails 7.2.
+          Please use preview_paths= instead.
+        MSG
+        self.preview_paths << value
+      end
+
+      def preview_path
+        ActionMailer.deprecator.warn(<<-MSG.squish)
+          Using preview_path option is deprecated and will be removed in Rails 7.2.
+          Please use preview_paths instead.
+        MSG
+        self.preview_paths.first
+      end
+
       # Register one or more Interceptors which will be called before mail is previewed.
       def register_preview_interceptors(*interceptors)
         interceptors.flatten.compact.each { |interceptor| register_preview_interceptor(interceptor) }
@@ -79,7 +103,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 +143,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,19 @@ 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)
+
+      # Preview paths configuration needs a pass.
+      #
+      # config.paths is cached as soon as it is accessed. Therefore, mutating
+      # paths["test/mailers/previews"] does not guarantee config.autoload_paths
+      # is going to include them.
+      #
+      # If config.paths was accessed before, config.autoload_paths is going to
+      # have whatever paths["test/mailers/previews"] had when cached.
+      app.config.autoload_paths.concat(options.preview_paths)
     end
 
     initializer "action_mailer.compile_config_methods" do
@@ -79,18 +89,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,43 @@ 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)
+
+      if args.is_a?(Hash)
+        ActionMailer.deprecator.warn <<~MSG
+          Passing a Hash to the assert_enqueued_email_with :args kwarg causes the
+          Hash to be treated as params. This behavior is deprecated and will be
+          removed in Rails 7.2.
+
+          To specify a params Hash, use the :params kwarg:
+
+            assert_enqueued_email_with MyMailer, :my_method, params: { my_param: "value" }
+
+          Or, to specify named mailer args as a Hash, wrap the Hash in an array:
+
+            assert_enqueued_email_with MyMailer, :my_method, args: [{ my_arg: "value" }]
+            # OR
+            assert_enqueued_email_with MyMailer, :my_method, args: [my_arg: "value"]
+        MSG
+
+        params, args = args, nil
+      end
+
+      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 +212,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

data/lib/action_mailer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# Copyright (c) 2004-2022 David Heinemeier Hansson
+# Copyright (c) David Heinemeier Hansson
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -25,6 +25,7 @@
 
 require "abstract_controller"
 require "action_mailer/version"
+require "action_mailer/deprecator"
 
 # Common Active Support usage in Action Mailer
 require "active_support"
@@ -34,6 +35,7 @@ require "active_support/core_ext/module/attr_internal"
 require "active_support/core_ext/string/inflections"
 require "active_support/lazy_load_hooks"
 
+# :include: actionmailer/README.rdoc
 module ActionMailer
   extend ::ActiveSupport::Autoload
 
@@ -42,6 +44,7 @@ module ActionMailer
   end
 
   autoload :Base
+  autoload :Callbacks
   autoload :DeliveryMethods
   autoload :InlinePreviewInterceptor
   autoload :MailHelper
@@ -52,12 +55,17 @@ module ActionMailer
   autoload :TestHelper
   autoload :MessageDelivery
   autoload :MailDeliveryJob
+  autoload :QueuedDelivery
 
   def self.eager_load!
     super
 
     require "mail"
     Mail.eager_autoload!
+
+    Base.descendants.each do |mailer|
+      mailer.eager_load! unless mailer.abstract?
+    end
   end
 end
 
@@ -65,6 +73,6 @@ autoload :Mime, "action_dispatch/http/mime_type"
 
 ActiveSupport.on_load(:action_view) do
   ActionView::Base.default_formats ||= Mime::SET.symbols
-  ActionView::Template::Types.delegate_to Mime
+  ActionView::Template.mime_types_implementation = Mime
   ActionView::LookupContext::DetailsKey.clear
 end

data/lib/rails/generators/mailer/USAGE

@@ -1,16 +1,20 @@
 Description:
-============
     Generates a new mailer and its views. Passes the mailer name, either
     CamelCased or under_scored, and an optional list of emails as arguments.
 
     This generates a mailer class in app/mailers and invokes your template
     engine and test framework generators.
 
-Example:
-========
-    bin/rails generate mailer Notifications signup forgot_password invoice
+Examples:
+    `bin/rails generate mailer sign_up`
+
+    creates a sign up mailer class, views, and test:
+        Mailer:     app/mailers/sign_up_mailer.rb
+        Views:      app/views/sign_up_mailer/signup.text.erb [...]
+        Test:       test/mailers/sign_up_mailer_test.rb
+
+    `bin/rails generate mailer notifications sign_up forgot_password invoice`
+
+    creates a notifications mailer with sign_up, forgot_password, and invoice actions.
+
 
-    creates a Notifications mailer class, views, and test:
-        Mailer:     app/mailers/notifications_mailer.rb
-        Views:      app/views/notifications_mailer/signup.text.erb [...]
-        Test:       test/mailers/notifications_mailer_test.rb