Deprecate `use_route` in controller tests

Reference #17453

2 files changed, 24 insertions, 3 deletions

diff --git a/actionpack/lib/action_controller/test_case.rb b/actionpack/lib/action_controller/test_case.rb
index 30eae41f60..cd92962dc3 100644
--- a/actionpack/lib/action_controller/test_case.rb
+++ b/actionpack/lib/action_controller/test_case.rb
@@ -2,6 +2,7 @@ require 'rack/session/abstract/id'
 require 'active_support/core_ext/object/to_query'
 require 'active_support/core_ext/module/anonymous'
 require 'active_support/core_ext/hash/keys'
+require 'active_support/deprecation'
 
 require 'rails-dom-testing'
 
@@ -710,7 +711,27 @@ module ActionController
             :relative_url_root => nil,
             :_recall => @request.path_parameters)
 
-          route_name = options.delete :use_route
+          if route_name = options.delete(:use_route)
+            ActiveSupport::Deprecation.warn <<-MSG.squish
+              Passing the `use_route` option in functional tests are deprecated.
+              Support for this option in the `process` method (and the related
+              `get`, `head`, `post`, `patch`, `put` and `delete` helpers) will
+              be removed in the next version without replacement.
+
+              Functional tests are essentially unit tests for controllers and
+              they should not require knowledge to how the application's routes
+              are configured. Instead, you should explicitly pass the appropiate
+              params to the `process` method.
+
+              Previously the engines guide also contained an incorrect example
+              that recommended using this option to test an engine's controllers
+              within the dummy application. That recommendation was incorrect
+              and has since been corrected. Instead, you should override the
+              `@routes` variable in the test case with `Foo::Engine.routes`. See
+              the updated engines guide for details.
+            MSG
+          end
+
           url, query_string = @routes.path_for(options, route_name).split("?", 2)
 
           @request.env["SCRIPT_NAME"] = @controller.config.relative_url_root
diff --git a/actionpack/test/controller/test_case_test.rb b/actionpack/test/controller/test_case_test.rb
index fdabad3abd..ba2ff7d12c 100644
--- a/actionpack/test/controller/test_case_test.rb
+++ b/actionpack/test/controller/test_case_test.rb
@@ -528,7 +528,7 @@ XML
         get 'via_named_route', as: :a_named_route, to: 'test_case_test/test#test_uri'
       end
 
-      get :test_uri, use_route: :a_named_route
+      assert_deprecated { get :test_uri, use_route: :a_named_route }
       assert_equal '/via_named_route', @response.body
     end
   end
@@ -798,7 +798,7 @@ module EngineControllerTests
       with_routing do |set|
         set.draw { mount Engine => '/foo' }
 
-        get :index, use_route: :foo
+        assert_deprecated { get :index, use_route: :foo }
         assert_equal @response.body, 'bar'
       end
     end