Merge pull request #48194 from jonathanhefner/assert_enqueued_email_with-deprecate-params-via-args

Deprecate params via `:args` for `assert_enqueued_email_with`

actionmailer/CHANGELOG.md

@@ -1,3 +1,25 @@
+*   Deprecate passing params to `assert_enqueued_email_with` via the `:args`
+    kwarg. `assert_enqueued_email_with` now supports a `:params` kwarg, so use
+    that to pass params:
+
+    ```ruby
+    # BEFORE
+    assert_enqueued_email_with MyMailer, :my_method, args: { my_param: "value" }
+
+    # AFTER
+    assert_enqueued_email_with MyMailer, :my_method, params: { my_param: "value" }
+    ```
+
+    To specify named mailer args as a Hash, wrap the Hash in an array:
+
+    ```ruby
+    assert_enqueued_email_with MyMailer, :my_method, args: [{ my_arg: "value" }]
+    # OR
+    assert_enqueued_email_with MyMailer, :my_method, args: [my_arg: "value"]
+    ```
+
+    *Jonathan Hefner*
+
 *   Accept procs for args and params in `assert_enqueued_email_with`
 
     ```ruby

actionmailer/lib/action_mailer/test_helper.rb

@@ -184,7 +184,26 @@ def assert_enqueued_email_with(mailer, method, params: nil, args: nil, queue: ni
         mailer = mailer.instance_variable_get(:@mailer)
       end
 
-      params, args = args, nil if args.is_a?(Hash)
+      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
 

actionmailer/test/test_helper_test.rb

@@ -431,9 +431,11 @@ def test_assert_enqueued_email_with_with_no_block_with_args
 
   def test_assert_enqueued_email_with_with_parameterized_args
     assert_nothing_raised do
-      assert_enqueued_email_with TestHelperMailer, :test_parameter_args, args: { all: "good" } do
-        silence_stream($stdout) do
-          TestHelperMailer.with(all: "good").test_parameter_args.deliver_later
+      assert_deprecated(ActionMailer.deprecator) do
+        assert_enqueued_email_with TestHelperMailer, :test_parameter_args, args: { all: "good" } do
+          silence_stream($stdout) do
+            TestHelperMailer.with(all: "good").test_parameter_args.deliver_later
+          end
         end
       end
     end
@@ -483,6 +485,8 @@ def test_assert_enqueued_email_with_with_no_block_with_parameterized_args
     assert_nothing_raised do
       silence_stream($stdout) do
         TestHelperMailer.with(all: "good").test_parameter_args.deliver_later
+      end
+      assert_deprecated(ActionMailer.deprecator) do
         assert_enqueued_email_with TestHelperMailer, :test_parameter_args, args: { all: "good" }
       end
     end