Add doc for assert_queries and assert_no_queries

Follow-up to rails#50281

I think `assert_queries` and `assert_no_queries` are so useful that I
want to read the documentation for the assertions. This patch adds the
doc for them and updated the test case named `test_assert_queries` to
verify `:matcher` works as expected.

I also changed `assert_queries` to make sure the subscriber of
`"sql.active_record"` is unsubscribed without affecting other test
cases. Without this change, some test cases fail because of execution of
`String#match`, which may cause `ArgumentError: invalid byte sequence in UTF-8`.

Author: yykamei

activerecord/lib/active_record/testing/query_assertions.rb

@@ -3,19 +3,29 @@
 module ActiveRecord
   module Assertions
     module QueryAssertions
+      # Asserts that the number of SQL queries executed in the given block matches the expected count.
+      #
+      #   assert_queries(1) { Post.first }
+      #
+      # If the +:matcher+ option is provided, only queries that match the matcher are counted.
+      #
+      #   assert_queries(1, matcher: /LIMIT \?/) { Post.first }
+      #
       def assert_queries(expected_count, matcher: nil, &block)
         ActiveRecord::Base.connection.materialize_transactions
 
         queries = []
-        ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
+        callback = lambda do |*, payload|
           queries << payload[:sql] if %w[ SCHEMA TRANSACTION ].exclude?(payload[:name]) && (matcher.nil? || payload[:sql].match(matcher))
         end
-
-        result = _assert_nothing_raised_or_warn("assert_queries", &block)
-        assert_equal expected_count, queries.size, "#{queries.size} instead of #{expected_count} queries were executed. Queries: #{queries.join("\n\n")}"
-        result
+        ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
+          result = _assert_nothing_raised_or_warn("assert_queries", &block)
+          assert_equal expected_count, queries.size, "#{queries.size} instead of #{expected_count} queries were executed. Queries: #{queries.join("\n\n")}"
+          result
+        end
       end
 
+      # Asserts that no SQL queries are executed in the given block.
       def assert_no_queries(&block)
         assert_queries(0, &block)
       end

activerecord/test/cases/assertions/query_assertions_test.rb

@@ -22,15 +22,24 @@ def test_assert_queries
         }
         assert_match(/1 instead of 0 queries/, error.message)
       end
-    end
 
-    def test_assert_no_queries
-      assert_no_queries { Post.none }
+      def test_assert_queries_with_matcher
+        error = assert_raises(Minitest::Assertion) {
+          assert_queries(1, matcher: /WHERE "posts"."id" = \? LIMIT \?/) do
+            Post.where(id: 1).first
+          end
+        }
+        assert_match(/0 instead of 1 queries/, error.message)
+      end
+
+      def test_assert_no_queries
+        assert_no_queries { Post.none }
 
-      error = assert_raises(Minitest::Assertion) {
-        assert_no_queries { Post.first }
-      }
-      assert_match(/1 .* instead of 2/, error.message)
+        error = assert_raises(Minitest::Assertion) {
+          assert_no_queries { Post.first }
+        }
+        assert_match(/1 instead of 0/, error.message)
+      end
     end
   end
 end