activesupport 8.0.3 → 8.1.0.rc1

data/lib/active_support/test_case.rb

@@ -6,6 +6,7 @@ require "active_support/testing/setup_and_teardown"
 require "active_support/testing/tests_without_assertions"
 require "active_support/testing/assertions"
 require "active_support/testing/error_reporter_assertions"
+require "active_support/testing/event_reporter_assertions"
 require "active_support/testing/deprecation"
 require "active_support/testing/declarative"
 require "active_support/testing/isolation"
@@ -15,13 +16,29 @@ require "active_support/testing/constant_stubbing"
 require "active_support/testing/file_fixtures"
 require "active_support/testing/parallelization"
 require "active_support/testing/parallelize_executor"
+require "active_support/testing/notification_assertions"
 require "concurrent/utility/processor_counter"
 
 module ActiveSupport
   class TestCase < ::Minitest::Test
     Assertion = Minitest::Assertion
 
+    # Class variable to store the parallel worker ID
+    @@parallel_worker_id = nil
+
     class << self
+      # Returns the current parallel worker ID if tests are running in parallel,
+      # nil otherwise.
+      #
+      #   ActiveSupport::TestCase.parallel_worker_id # => 2
+      def parallel_worker_id
+        @@parallel_worker_id
+      end
+
+      def parallel_worker_id=(value) # :nodoc:
+        @@parallel_worker_id = value
+      end
+
       # Sets the order in which test cases are run.
       #
       #   ActiveSupport::TestCase.test_order = :random # => :random
@@ -51,8 +68,8 @@ module ActiveSupport
       # is forked. For each process a new database will be created suffixed
       # with the worker number.
       #
-      #   test-database-0
-      #   test-database-1
+      #   test-database_0
+      #   test-database_1
       #
       # If <tt>ENV["PARALLEL_WORKERS"]</tt> is set the workers argument will be ignored
       # and the environment variable will be used instead. This is useful for CI
@@ -78,14 +95,45 @@ module ActiveSupport
       # Because parallelization presents an overhead, it is only enabled when the
       # number of tests to run is above the +threshold+ param. The default value is
       # 50, and it's configurable via +config.active_support.test_parallelization_threshold+.
-      def parallelize(workers: :number_of_processors, with: :processes, threshold: ActiveSupport.test_parallelization_threshold)
-        workers = Concurrent.processor_count if workers == :number_of_processors
-        workers = ENV["PARALLEL_WORKERS"].to_i if ENV["PARALLEL_WORKERS"]
+      #
+      # If you want to skip Rails default creation of one database per process in favor of
+      # writing your own implementation, you can set +parallelize_databases+, or configure it
+      # via +config.active_support.parallelize_test_databases+.
+      #
+      #   parallelize(workers: :number_of_processors, parallelize_databases: false)
+      #
+      # Note that your test suite may deadlock if you attempt to use only one database
+      # with multiple processes.
+      def parallelize(workers: :number_of_processors, with: :processes, threshold: ActiveSupport.test_parallelization_threshold, parallelize_databases: ActiveSupport.parallelize_test_databases)
+        case
+        when ENV["PARALLEL_WORKERS"]
+          workers = ENV["PARALLEL_WORKERS"].to_i
+        when workers == :number_of_processors
+          workers = (Concurrent.available_processor_count || Concurrent.processor_count).floor
+        end
+
+        if with == :processes
+          ActiveSupport.parallelize_test_databases = parallelize_databases
+        end
 
         Minitest.parallel_executor = ActiveSupport::Testing::ParallelizeExecutor.new(size: workers, with: with, threshold: threshold)
       end
 
-      # Set up hook for parallel testing. This can be used if you have multiple
+      # Before fork hook for parallel testing. This can be used to run anything
+      # before the processes are forked.
+      #
+      # In your +test_helper.rb+ add the following:
+      #
+      #   class ActiveSupport::TestCase
+      #     parallelize_before_fork do
+      #       # run this before fork
+      #     end
+      #   end
+      def parallelize_before_fork(&block)
+        ActiveSupport::Testing::Parallelization.before_fork_hook(&block)
+      end
+
+      # Setup hook for parallel testing. This can be used if you have multiple
       # databases or any behavior that needs to be run after the process is forked
       # but before the tests run.
       #
@@ -141,11 +189,18 @@ module ActiveSupport
 
     alias_method :method_name, :name
 
+    # Returns the current parallel worker ID if tests are running in parallel
+    def parallel_worker_id
+      self.class.parallel_worker_id
+    end
+
     include ActiveSupport::Testing::TaggedLogging
     prepend ActiveSupport::Testing::SetupAndTeardown
     prepend ActiveSupport::Testing::TestsWithoutAssertions
     include ActiveSupport::Testing::Assertions
     include ActiveSupport::Testing::ErrorReporterAssertions
+    include ActiveSupport::Testing::EventReporterAssertions
+    include ActiveSupport::Testing::NotificationAssertions
     include ActiveSupport::Testing::Deprecation
     include ActiveSupport::Testing::ConstantStubbing
     include ActiveSupport::Testing::TimeHelpers

data/lib/active_support/testing/assertions.rb

@@ -71,19 +71,19 @@ module ActiveSupport
       #     post :delete, params: { id: ... }
       #   end
       #
-      # An array of expressions can also be passed in and evaluated.
+      # An array of expressions can be passed in and evaluated.
       #
       #   assert_difference [ 'Article.count', 'Post.count' ], 2 do
       #     post :create, params: { article: {...} }
       #   end
       #
-      # A hash of expressions/numeric differences can also be passed in and evaluated.
+      # A hash of expressions/numeric differences can be passed in and evaluated.
       #
-      #   assert_difference ->{ Article.count } => 1, ->{ Notification.count } => 2 do
+      #   assert_difference({ 'Article.count' => 1, 'Notification.count' => 2 }) do
       #     post :create, params: { article: {...} }
       #   end
       #
-      # A lambda or a list of lambdas can be passed in and evaluated:
+      # A lambda, a list of lambdas or a hash of lambdas/numeric differences can be passed in and evaluated:
       #
       #   assert_difference ->{ Article.count }, 2 do
       #     post :create, params: { article: {...} }
@@ -93,6 +93,10 @@ module ActiveSupport
       #     post :create, params: { article: {...} }
       #   end
       #
+      #   assert_difference ->{ Article.count } => 1, ->{ Notification.count } => 2 do
+      #     post :create, params: { article: {...} }
+      #   end
+      #
       # An error message can be specified.
       #
       #   assert_difference 'Article.count', -1, 'An Article should be destroyed' do
@@ -181,12 +185,24 @@ module ActiveSupport
       #
       # The keyword arguments +:from+ and +:to+ can be given to specify the
       # expected initial value and the expected value after the block was
-      # executed.
+      # executed. The comparison is done using case equality (===), which means
+      # you can specify patterns or classes:
       #
+      #   # Exact value match
       #   assert_changes :@object, from: nil, to: :foo do
       #     @object = :foo
       #   end
       #
+      #   # Case equality
+      #   assert_changes -> { user.token }, to: /\w{32}/ do
+      #     user.generate_token
+      #   end
+      #
+      #   # Type check
+      #   assert_changes -> { current_error }, from: nil, to: RuntimeError do
+      #     raise "Oops"
+      #   end
+      #
       # An error message can be specified.
       #
       #   assert_changes -> { Status.all_good? }, 'Expected the status to be bad' do
@@ -238,12 +254,24 @@ module ActiveSupport
       #   end
       #
       # Provide the optional keyword argument +:from+ to specify the expected
-      # initial value.
+      # initial value. The comparison is done using case equality (===), which means
+      # you can specify patterns or classes:
       #
+      #   # Exact value match
       #   assert_no_changes -> { Status.all_good? }, from: true do
       #     post :create, params: { status: { ok: true } }
       #   end
       #
+      #   # Case equality
+      #   assert_no_changes -> { user.token }, from: /\w{32}/ do
+      #     user.touch
+      #   end
+      #
+      #   # Type check
+      #   assert_no_changes -> { current_error }, from: RuntimeError do
+      #     retry_operation
+      #   end
+      #
       # An error message can be specified.
       #
       #   assert_no_changes -> { Status.all_good? }, 'Expected the status to be good' do

data/lib/active_support/testing/error_reporter_assertions.rb

@@ -44,7 +44,7 @@ module ActiveSupport
                   ActiveSupport.error_reporter.subscribe(self)
                   @subscribed = true
                 else
-                  raise Minitest::Assertion, "No error reporter is configured"
+                  flunk("No error reporter is configured")
                 end
               end
             end
@@ -102,6 +102,23 @@ module ActiveSupport
           assert(false, message)
         end
       end
+
+      # Captures reported errors from within the block that match the given
+      # error class.
+      #
+      #   reports = capture_error_reports(IOError) do
+      #     Rails.error.report(IOError.new("Oops"))
+      #     Rails.error.report(IOError.new("Oh no"))
+      #     Rails.error.report(StandardError.new)
+      #   end
+      #
+      #   assert_equal 2, reports.size
+      #   assert_equal "Oops", reports.first.error.message
+      #   assert_equal "Oh no", reports.last.error.message
+      def capture_error_reports(error_class = StandardError, &block)
+        reports = ErrorCollector.record(&block)
+        reports.select { |r| error_class === r.error }
+      end
     end
   end
 end

data/lib/active_support/testing/event_reporter_assertions.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  module Testing
+    # Provides test helpers for asserting on ActiveSupport::EventReporter events.
+    module EventReporterAssertions
+      module EventCollector # :nodoc:
+        @subscribed = false
+        @mutex = Mutex.new
+
+        class Event # :nodoc:
+          attr_reader :event_data
+
+          def initialize(event_data)
+            @event_data = event_data
+          end
+
+          def inspect
+            "#{event_data[:name]} (payload: #{event_data[:payload].inspect}, tags: #{event_data[:tags].inspect})"
+          end
+
+          def matches?(name, payload, tags)
+            return false unless name.to_s == event_data[:name]
+
+            if payload && payload.is_a?(Hash)
+              return false unless matches_hash?(payload, :payload)
+            end
+
+            return false unless matches_hash?(tags, :tags)
+            true
+          end
+
+          private
+            def matches_hash?(expected_hash, event_key)
+              expected_hash.all? do |k, v|
+                if v.is_a?(Regexp)
+                  event_data.dig(event_key, k).to_s.match?(v)
+                else
+                  event_data.dig(event_key, k) == v
+                end
+              end
+            end
+        end
+
+        class << self
+          def emit(event)
+            event_recorders&.each do |events|
+              events << Event.new(event)
+            end
+            true
+          end
+
+          def record
+            subscribe
+            events = []
+            event_recorders << events
+            begin
+              yield
+              events
+            ensure
+              event_recorders.delete_if { |r| events.equal?(r) }
+            end
+          end
+
+          private
+            def subscribe
+              return if @subscribed
+
+              @mutex.synchronize do
+                unless @subscribed
+                  if ActiveSupport.event_reporter
+                    ActiveSupport.event_reporter.subscribe(self)
+                    @subscribed = true
+                  else
+                    raise Minitest::Assertion, "No event reporter is configured"
+                  end
+                end
+              end
+            end
+
+            def event_recorders
+              ActiveSupport::IsolatedExecutionState[:active_support_event_reporter_assertions] ||= []
+            end
+        end
+      end
+
+      # Asserts that the block does not cause an event to be reported to +Rails.event+.
+      #
+      # If no name is provided, passes if evaluated code in the yielded block reports no events.
+      #
+      #   assert_no_event_reported do
+      #     service_that_does_not_report_events.perform
+      #   end
+      #
+      # If a name is provided, passes if evaluated code in the yielded block reports no events
+      # with that name.
+      #
+      #   assert_no_event_reported("user.created") do
+      #     service_that_does_not_report_events.perform
+      #   end
+      def assert_no_event_reported(name = nil, payload: {}, tags: {}, &block)
+        events = EventCollector.record(&block)
+
+        if name.nil?
+          assert_predicate(events, :empty?)
+        else
+          matching_event = events.find { |event| event.matches?(name, payload, tags) }
+          if matching_event
+            message = "Expected no '#{name}' event to be reported, but found:\n  " \
+              "#{matching_event.inspect}"
+            flunk(message)
+          end
+          assert(true)
+        end
+      end
+
+      # Asserts that the block causes an event with the given name to be reported
+      # to +Rails.event+.
+      #
+      # Passes if the evaluated code in the yielded block reports a matching event.
+      #
+      #   assert_event_reported("user.created") do
+      #     Rails.event.notify("user.created", { id: 123 })
+      #   end
+      #
+      # To test further details about the reported event, you can specify payload and tag matchers.
+      #
+      #   assert_event_reported("user.created",
+      #     payload: { id: 123, name: "John Doe" },
+      #     tags: { request_id: /[0-9]+/ }
+      #   ) do
+      #     Rails.event.tagged(request_id: "123") do
+      #       Rails.event.notify("user.created", { id: 123, name: "John Doe" })
+      #     end
+      #   end
+      #
+      # The matchers support partial matching - only the specified keys need to match.
+      #
+      #   assert_event_reported("user.created", payload: { id: 123 }) do
+      #     Rails.event.notify("user.created", { id: 123, name: "John Doe" })
+      #   end
+      def assert_event_reported(name, payload: nil, tags: {}, &block)
+        events = EventCollector.record(&block)
+
+        if events.empty?
+          flunk("Expected an event to be reported, but there were no events reported.")
+        elsif (event = events.find { |event| event.matches?(name, payload, tags) })
+          assert(true)
+          event.event_data
+        else
+          message = "Expected an event to be reported matching:\n  " \
+            "name: #{name.inspect}\n  " \
+            "payload: #{payload.inspect}\n  " \
+            "tags: #{tags.inspect}\n" \
+            "but none of the #{events.size} reported events matched:\n  " \
+            "#{events.map(&:inspect).join("\n  ")}"
+          flunk(message)
+        end
+      end
+
+      # Asserts that the provided events were reported, regardless of order.
+      #
+      #   assert_events_reported([
+      #     { name: "user.created", payload: { id: 123 } },
+      #     { name: "email.sent", payload: { to: "user@example.com" } }
+      #   ]) do
+      #     create_user_and_send_welcome_email
+      #   end
+      #
+      # Supports the same payload and tag matching as +assert_event_reported+.
+      #
+      #   assert_events_reported([
+      #     {
+      #       name: "process.started",
+      #       payload: { id: 123 },
+      #       tags: { request_id: /[0-9]+/ }
+      #     },
+      #     { name: "process.completed" }
+      #   ]) do
+      #     Rails.event.tagged(request_id: "456") do
+      #       start_and_complete_process(123)
+      #     end
+      #   end
+      def assert_events_reported(expected_events, &block)
+        events = EventCollector.record(&block)
+
+        if events.empty? && expected_events.size > 0
+          flunk("Expected #{expected_events.size} events to be reported, but there were no events reported.")
+        end
+
+        events_copy = events.dup
+
+        expected_events.each do |expected_event|
+          name = expected_event[:name]
+          payload = expected_event[:payload] || {}
+          tags = expected_event[:tags] || {}
+
+          matching_event_index = events_copy.find_index { |event| event.matches?(name, payload, tags) }
+
+          if matching_event_index
+            events_copy.delete_at(matching_event_index)
+          else
+            message = "Expected an event to be reported matching:\n  " \
+              "name: #{name.inspect}\n  " \
+              "payload: #{payload.inspect}\n  " \
+              "tags: #{tags.inspect}\n" \
+              "but none of the #{events.size} reported events matched:\n  " \
+              "#{events.map(&:inspect).join("\n  ")}"
+            flunk(message)
+          end
+        end
+
+        assert(true)
+      end
+
+      # Allows debug events to be reported to +Rails.event+ for the duration of a given block.
+      #
+      #   with_debug_event_reporting do
+      #     service_that_reports_debug_events.perform
+      #   end
+      #
+      def with_debug_event_reporting(&block)
+        ActiveSupport.event_reporter.with_debug(&block)
+      end
+    end
+  end
+end

data/lib/active_support/testing/notification_assertions.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  module Testing
+    module NotificationAssertions
+      # Assert a notification was emitted with a given +pattern+ and optional +payload+.
+      #
+      # You can assert that a notification was emitted by passing a pattern, which accepts
+      # either a string or regexp, an optional payload, and a block. While the block
+      # is executed, if a matching notification is emitted, the assertion will pass
+      # and the notification will be returned.
+      #
+      # Note that the payload is matched as a subset, meaning that the notification must
+      # contain at least the specified keys and values, but may contain additional ones.
+      #
+      #     assert_notification("post.submitted", title: "Cool Post") do
+      #       post.submit(title: "Cool Post", body: "Cool Body") # => emits matching notification
+      #     end
+      #
+      # Using the returned notification, you can make more customized assertions.
+      #
+      #     notification = assert_notification("post.submitted", title: "Cool Post") do
+      #       ActiveSupport::Notifications.instrument("post.submitted", title: "Cool Post", body: Body.new("Cool Body"))
+      #     end
+      #
+      #     assert_instance_of(Body, notification.payload[:body])
+      #
+      def assert_notification(pattern, payload = nil, &block)
+        notifications = capture_notifications(pattern, &block)
+        assert_not_empty(notifications, "No #{pattern} notifications were found")
+
+        return notifications.first if payload.nil?
+
+        notification = notifications.find { |notification| notification.payload.slice(*payload.keys) == payload }
+        assert_not_nil(notification, "No #{pattern} notification with payload #{payload} was found")
+
+        notification
+      end
+
+      # Assert the number of notifications emitted with a given +pattern+.
+      #
+      # You can assert the number of notifications emitted by passing a pattern, which accepts
+      # either a string or regexp, a count, and a block. While the block is executed,
+      # the number of matching notifications emitted will be counted. After the block's
+      # execution completes, the assertion will pass if the count matches.
+      #
+      #     assert_notifications_count("post.submitted", 1) do
+      #       post.submit(title: "Cool Post") # => emits matching notification
+      #     end
+      #
+      def assert_notifications_count(pattern, count, &block)
+        actual_count = capture_notifications(pattern, &block).count
+        assert_equal(count, actual_count, "Expected #{count} instead of #{actual_count} notifications for #{pattern}")
+      end
+
+      # Assert no notifications were emitted for a given +pattern+.
+      #
+      # You can assert no notifications were emitted by passing a pattern, which accepts
+      # either a string or regexp, and a block. While the block is executed, if no
+      # matching notifications are emitted, the assertion will pass.
+      #
+      #     assert_no_notifications("post.submitted") do
+      #       post.destroy # => emits non-matching notification
+      #     end
+      #
+      def assert_no_notifications(pattern = nil, &block)
+        notifications = capture_notifications(pattern, &block)
+        error_message = if pattern
+          "Expected no notifications for #{pattern} but found #{notifications.size}"
+        else
+          "Expected no notifications but found #{notifications.size}"
+        end
+        assert_empty(notifications, error_message)
+      end
+
+      # Capture emitted notifications, optionally filtered by a +pattern+.
+      #
+      # You can capture emitted notifications, optionally filtered by a pattern,
+      # which accepts either a string or regexp, and a block.
+      #
+      #     notifications = capture_notifications("post.submitted") do
+      #       post.submit(title: "Cool Post") # => emits matching notification
+      #     end
+      #
+      def capture_notifications(pattern = nil, &block)
+        notifications = []
+        ActiveSupport::Notifications.subscribed(->(n) { notifications << n }, pattern, &block)
+        notifications
+      end
+    end
+  end
+end

data/lib/active_support/testing/parallelization/server.rb

@@ -14,6 +14,7 @@ module ActiveSupport
         def initialize
           @queue = Queue.new
           @active_workers = Concurrent::Map.new
+          @worker_pids = Concurrent::Map.new
           @in_flight = Concurrent::Map.new
         end
 
@@ -40,12 +41,24 @@ module ActiveSupport
           end
         end
 
-        def start_worker(worker_id)
+        def start_worker(worker_id, worker_pid)
           @active_workers[worker_id] = true
+          @worker_pids[worker_id] = worker_pid
         end
 
-        def stop_worker(worker_id)
+        def stop_worker(worker_id, worker_pid)
           @active_workers.delete(worker_id)
+          @worker_pids.delete(worker_id)
+        end
+
+        def remove_dead_workers(dead_pids)
+          dead_pids.each do |dead_pid|
+            worker_id = @worker_pids.key(dead_pid)
+            if worker_id
+              @active_workers.delete(worker_id)
+              @worker_pids.delete(worker_id)
+            end
+          end
         end
 
         def active_workers?

data/lib/active_support/testing/parallelization/worker.rb

@@ -18,7 +18,7 @@ module ActiveSupport
             DRb.stop_service
 
             @queue = DRbObject.new_with_uri(@url)
-            @queue.start_worker(@id)
+            @queue.start_worker(@id, Process.pid)
 
             begin
               after_fork
@@ -29,7 +29,7 @@ module ActiveSupport
             set_process_title("(stopping)")
 
             run_cleanup
-            @queue.stop_worker(@id)
+            @queue.stop_worker(@id, Process.pid)
           end
         end
 
@@ -78,6 +78,8 @@ module ActiveSupport
         end
 
         def after_fork
+          ActiveSupport::TestCase.parallel_worker_id = @number
+
           Parallelization.after_fork_hooks.each do |cb|
             cb.call(@number)
           end

data/lib/active_support/testing/parallelization.rb

@@ -9,6 +9,14 @@ require "active_support/testing/parallelization/worker"
 module ActiveSupport
   module Testing
     class Parallelization # :nodoc:
+      @@before_fork_hooks = []
+
+      def self.before_fork_hook(&blk)
+        @@before_fork_hooks << blk
+      end
+
+      cattr_reader :before_fork_hooks
+
       @@after_fork_hooks = []
 
       def self.after_fork_hook(&blk)
@@ -32,7 +40,12 @@ module ActiveSupport
         @url = DRb.start_service("drbunix:", @queue_server).uri
       end
 
+      def before_fork
+        Parallelization.before_fork_hooks.each(&:call)
+      end
+
       def start
+        before_fork
         @worker_pool = @worker_count.times.map do |worker|
           Worker.new(worker, @url).start
         end
@@ -47,8 +60,19 @@ module ActiveSupport
       end
 
       def shutdown
+        dead_worker_pids = @worker_pool.filter_map do |pid|
+          Process.waitpid(pid, Process::WNOHANG)
+        rescue Errno::ECHILD
+          pid
+        end
+        @queue_server.remove_dead_workers(dead_worker_pids)
+
         @queue_server.shutdown
-        @worker_pool.each { |pid| Process.waitpid pid }
+        @worker_pool.each do |pid|
+          Process.waitpid(pid)
+        rescue Errno::ECHILD
+          nil
+        end
       end
     end
   end

data/lib/active_support/testing/tests_without_assertions.rb

@@ -11,7 +11,7 @@ module ActiveSupport
 
         if assertions.zero? && !skipped? && !error?
           file, line = method(name).source_location
-          warn "Test is missing assertions: `#{name}` #{file}:#{line}"
+          warn "Test is missing assertions: `#{name}` #{File.expand_path(file)}:#{line}"
         end
       end
     end