actionmailer 3.0.4 → 7.1.6

data/lib/action_mailer/test_helper.rb

@@ -1,45 +1,51 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/array/extract_options"
+require "active_job"
+
 module ActionMailer
+  # Provides helper methods for testing Action Mailer, including #assert_emails
+  # and #assert_no_emails.
   module TestHelper
-    extend ActiveSupport::Concern
+    include ActiveJob::TestHelper
 
     # Asserts that the number of emails sent matches the given number.
     #
     #   def test_emails
     #     assert_emails 0
-    #     ContactMailer.deliver_contact
+    #     ContactMailer.welcome.deliver_now
     #     assert_emails 1
-    #     ContactMailer.deliver_contact
+    #     ContactMailer.welcome.deliver_now
     #     assert_emails 2
     #   end
     #
-    # If a block is passed, that block should cause the specified number of emails to be sent.
+    # If a block is passed, that block should cause the specified number of
+    # emails to be sent.
     #
     #   def test_emails_again
     #     assert_emails 1 do
-    #       ContactMailer.deliver_contact
+    #       ContactMailer.welcome.deliver_now
     #     end
     #
     #     assert_emails 2 do
-    #       ContactMailer.deliver_contact
-    #       ContactMailer.deliver_contact
+    #       ContactMailer.welcome.deliver_now
+    #       ContactMailer.welcome.deliver_later
     #     end
     #   end
-    def assert_emails(number)
+    def assert_emails(number, &block)
       if block_given?
-        original_count = ActionMailer::Base.deliveries.size
-        yield
-        new_count = ActionMailer::Base.deliveries.size
-        assert_equal original_count + number, new_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
     end
 
-    # Assert that no emails have been sent.
+    # Asserts that no emails have been sent.
     #
     #   def test_emails
     #     assert_no_emails
-    #     ContactMailer.deliver_contact
+    #     ContactMailer.welcome.deliver_now
     #     assert_emails 1
     #   end
     #
@@ -53,9 +59,226 @@ module ActionMailer
     #
     # Note: This assertion is simply a shortcut for:
     #
-    #   assert_emails 0
+    #   assert_emails 0, &block
     def assert_no_emails(&block)
       assert_emails 0, &block
     end
+
+    # Asserts that the number of emails enqueued for later delivery matches
+    # the given number.
+    #
+    #   def test_emails
+    #     assert_enqueued_emails 0
+    #     ContactMailer.welcome.deliver_later
+    #     assert_enqueued_emails 1
+    #     ContactMailer.welcome.deliver_later
+    #     assert_enqueued_emails 2
+    #   end
+    #
+    # If a block is passed, that block should cause the specified number of
+    # emails to be enqueued.
+    #
+    #   def test_emails_again
+    #     assert_enqueued_emails 1 do
+    #       ContactMailer.welcome.deliver_later
+    #     end
+    #
+    #     assert_enqueued_emails 2 do
+    #       ContactMailer.welcome.deliver_later
+    #       ContactMailer.welcome.deliver_later
+    #     end
+    #   end
+    def assert_enqueued_emails(number, &block)
+      assert_enqueued_jobs(number, only: ->(job) { delivery_job_filter(job) }, &block)
+    end
+
+    # Asserts that a specific email has been enqueued, optionally
+    # 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.
+    #
+    #   def test_email_in_block
+    #     assert_enqueued_email_with ContactMailer, :welcome do
+    #       ContactMailer.welcome.deliver_later
+    #     end
+    #   end
+    #
+    # If +args+ is provided as a Hash, a parameterized email is matched.
+    #
+    #   def test_parameterized_email
+    #     assert_enqueued_email_with ContactMailer, :welcome,
+    #       args: {email: 'user@example.com'} do
+    #       ContactMailer.with(email: 'user@example.com').welcome.deliver_later
+    #     end
+    #   end
+    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
+
+      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.
+    #
+    #   def test_no_emails
+    #     assert_no_enqueued_emails
+    #     ContactMailer.welcome.deliver_later
+    #     assert_enqueued_emails 1
+    #   end
+    #
+    # If a block is provided, it should not cause any emails to be enqueued.
+    #
+    #   def test_no_emails
+    #     assert_no_enqueued_emails do
+    #       # No emails should be enqueued from this block
+    #     end
+    #   end
+    def assert_no_enqueued_emails(&block)
+      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
+
+        Base.descendants.map(&:delivery_job).include?(job_class)
+      end
   end
 end

data/lib/action_mailer/version.rb

@@ -1,10 +1,11 @@
-module ActionMailer
-  module VERSION #:nodoc:
-    MAJOR = 3
-    MINOR = 0
-    TINY  = 4
-    PRE   = nil
+# frozen_string_literal: true
+
+require_relative "gem_version"
 
-    STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')
+module ActionMailer
+  # Returns the currently loaded version of Action Mailer as a
+  # +Gem::Version+.
+  def self.version
+    gem_version
   end
 end

data/lib/action_mailer.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 #--
-# Copyright (c) 2004-2010 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
@@ -21,32 +23,57 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
-actionpack_path = File.expand_path('../../../actionpack/lib', __FILE__)
-$:.unshift(actionpack_path) if File.directory?(actionpack_path) && !$:.include?(actionpack_path)
-
-require 'abstract_controller'
-require 'action_view'
-require 'action_mailer/version'
+require "abstract_controller"
+require "action_mailer/version"
+require "action_mailer/deprecator"
 
 # Common Active Support usage in Action Mailer
-require 'active_support/core_ext/class'
-require 'active_support/core_ext/object/blank'
-require 'active_support/core_ext/array/uniq_by'
-require 'active_support/core_ext/module/attr_internal'
-require 'active_support/core_ext/module/delegation'
-require 'active_support/core_ext/string/inflections'
-require 'active_support/lazy_load_hooks'
+require "active_support"
+require "active_support/rails"
+require "active_support/core_ext/class"
+require "active_support/core_ext/module/attr_internal"
+require "active_support/core_ext/string/inflections"
+require "active_support/lazy_load_hooks"
 
+# :include: ../README.rdoc
 module ActionMailer
   extend ::ActiveSupport::Autoload
 
-  autoload :AdvAttrAccessor
-  autoload :Collector
+  eager_autoload do
+    autoload :Collector
+  end
+
   autoload :Base
+  autoload :Callbacks
   autoload :DeliveryMethods
-  autoload :DeprecatedApi
+  autoload :InlinePreviewInterceptor
   autoload :MailHelper
-  autoload :OldApi
+  autoload :Parameterized
+  autoload :Preview
+  autoload :Previews, "action_mailer/preview"
   autoload :TestCase
   autoload :TestHelper
+  autoload :MessageDelivery
+  autoload :MailDeliveryJob
+  autoload :QueuedDelivery
+  autoload :FormBuilder
+
+  def self.eager_load!
+    super
+
+    require "mail"
+    Mail.eager_autoload!
+
+    Base.descendants.each do |mailer|
+      mailer.eager_load! unless mailer.abstract?
+    end
+  end
+end
+
+autoload :Mime, "action_dispatch/http/mime_type"
+
+ActiveSupport.on_load(:action_view) do
+  ActionView::Base.default_formats ||= Mime::SET.symbols
+  ActionView::Template.mime_types_implementation = Mime
+  ActionView::LookupContext::DetailsKey.clear
 end

data/lib/rails/generators/mailer/USAGE

@@ -1,15 +1,20 @@
 Description:
-    Stubs out a new mailer and its views. Pass the mailer name, either
+    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:
-    `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, test, and fixtures:
-        Mailer:     app/mailers/notifications.rb
-        Views:      app/views/notifications/signup.erb [...]
-        Test:       test/functional/notifications_test.rb
-        Fixtures:   test/fixtures/notifications/signup [...]

data/lib/rails/generators/mailer/mailer_generator.rb

@@ -1,16 +1,38 @@
+# frozen_string_literal: true
+
 module Rails
   module Generators
     class MailerGenerator < NamedBase
-      source_root File.expand_path("../templates", __FILE__)
+      source_root File.expand_path("templates", __dir__)
+
+      argument :actions, type: :array, default: [], banner: "method method"
 
-      argument :actions, :type => :array, :default => [], :banner => "method method"
-      check_class_collision
+      check_class_collision suffix: "Mailer"
 
       def create_mailer_file
-        template "mailer.rb", File.join('app/mailers', class_path, "#{file_name}.rb")
+        template "mailer.rb", File.join("app/mailers", class_path, "#{file_name}_mailer.rb")
+
+        in_root do
+          if behavior == :invoke && !File.exist?(application_mailer_file_name)
+            template "application_mailer.rb", application_mailer_file_name
+          end
+        end
       end
 
       hook_for :template_engine, :test_framework
+
+      private
+        def file_name # :doc:
+          @_file_name ||= super.sub(/_mailer\z/i, "")
+        end
+
+        def application_mailer_file_name
+          @_application_mailer_file_name ||= if mountable_engine?
+            "app/mailers/#{namespaced_path}/application_mailer.rb"
+          else
+            "app/mailers/application_mailer.rb"
+          end
+        end
     end
   end
 end

data/lib/rails/generators/mailer/templates/application_mailer.rb.tt

@@ -0,0 +1,6 @@
+<% module_namespacing do -%>
+class ApplicationMailer < ActionMailer::Base
+  default from: 'from@example.com'
+  layout 'mailer'
+end
+<% end %>

data/lib/rails/generators/mailer/templates/mailer.rb.tt

@@ -0,0 +1,17 @@
+<% module_namespacing do -%>
+class <%= class_name %>Mailer < ApplicationMailer
+<% actions.each do |action| -%>
+
+  # Subject can be set in your I18n file at config/locales/en.yml
+  # with the following lookup:
+  #
+  #   en.<%= file_path.tr("/",".") %>_mailer.<%= action %>.subject
+  #
+  def <%= action %>
+    @greeting = "Hi"
+
+    mail to: "to@example.org"
+  end
+<% end -%>
+end
+<% end -%>