Minitest helper for failing tests when tasks end with unhandled exception

[nickpoorman]

If anyone knows a better way to do the following please let me know!

In case anyone else comes across this, I've found it useful to have minitest fail any time the 'Task may have ended with unhandled exception' message appears because it usually means I need to fix something.

So I use this little test helper that I enable that will fail the test when that happens. It's also been super useful for identifying and fixing .async calls that need to be called with .async(finished: false). See: #383 (comment)

# frozen_string_literal: true

# Require this in your test_helper.rb to make async warnings fail tests
# This ensures that "Task may have ended with unhandled exception" warnings
# will cause test failures with a clear, actionable message

require 'console'

module AsyncStrictTestHelper
  @warnings = []
  @enabled = false
  @original_warn = nil

  class << self
    attr_accessor :warnings, :enabled

    def enable!
      return if @enabled

      @enabled = true
      @warnings = []

      # Store original Console.warn
      @original_warn = Console.method(:warn)

      # Replace Console.warn to capture warnings
      Console.define_singleton_method(:warn) do |*args, **kwargs|
        # Check for unhandled exception warnings
        if args.any? { |arg| arg.is_a?(String) && arg.include?('Task may have ended with unhandled exception') }
          AsyncStrictTestHelper.warnings << {
            message: args.join(' '),
            exception: kwargs[:exception],
            task: args.find { |arg| arg.respond_to?(:annotation) }
          }
        end

        # Call original to maintain normal logging
        AsyncStrictTestHelper.instance_variable_get(:@original_warn).call(*args, **kwargs)
      end

      # Hook into Minitest
      return unless defined?(Minitest::Test)

      Minitest::Test.class_eval do
        # Store original methods
        alias_method :_original_setup_async_strict, :setup unless method_defined?(:_original_setup_async_strict)
        unless method_defined?(:_original_teardown_async_strict)
          alias_method :_original_teardown_async_strict,
                       :teardown
        end

        def setup
          _original_setup_async_strict if respond_to?(:_original_setup_async_strict)
          AsyncStrictTestHelper.warnings.clear
        end

        def teardown
          _original_teardown_async_strict if respond_to?(:_original_teardown_async_strict)

          # Fail test if any async warnings were logged
          return unless AsyncStrictTestHelper.warnings.any?

          warning = AsyncStrictTestHelper.warnings.first
          AsyncStrictTestHelper.warnings.clear

          # Build a clear failure message
          exception = warning[:exception]

          message_parts = [
            'Async task ended with an unhandled exception.'
          ]

          if exception
            message_parts << ''
            message_parts << "Exception: #{exception.class.name}: #{exception.message}"

            # Find the line in the test that caused the issue
            if exception.backtrace && exception.backtrace.any?
              test_line = exception.backtrace.find { |line| line.include?('test_') && line.include?('.rb:') }
              # Extract just the file and line number
              if test_line && (match = test_line.match(/(.+\.rb):(\d+)/))
                file = match[1].split('/').last
                line_no = match[2]
                message_parts << "Test location: #{file}:#{line_no}"
              end
            end
          end

          message_parts << ''
          message_parts << 'The task raised an exception before .wait was called on it.'
          message_parts << 'This often indicates a race condition or improper error handling.'
          message_parts << ''
          message_parts << 'To fix this issue:'
          message_parts << '  1. Ensure .wait is called immediately when the task is created, or'
          message_parts << '  2. Ensure .wait is called before the task completes (raises), or'
          message_parts << '  3. Handle exceptions within the async block itself, or'
          message_parts << "  4. Use .async(finished: false) which indicates that while we aren't waiting yet, we will eventually wait. finished: nil (the default) means unspecified and will log an exception because we don't know if it is going to be handled or not. Unfortunately Async cannot read the future. If you are returning a task and waiting on it later (like a promise) then you should call `.async(finished: false) to supress the warning."

          # Use flunk to fail the test with our detailed message
          flunk(message_parts.join("\n"))
        end
      end
    end

    def disable!
      return unless @enabled

      @enabled = false

      # Restore original Console.warn
      return unless @original_warn

      Console.define_singleton_method(:warn, @original_warn)
      @original_warn = nil
    end
  end
end

# Enable strict async testing
AsyncStrictTestHelper.enable!