rspec-core-parallel 0.1.0

data/lib/rspec/core/parallel/core_ext.rb

@@ -0,0 +1,253 @@
+require 'rspec/core/bisect/shell_command'
+require 'rspec/core/bisect/fork_runner'
+
+module RSpec
+  module Core
+    module Parallel
+      # The changes rspec-core needs to run a suite in parallel, applied to
+      # rspec-core 3.13 from outside.
+      #
+      # @private
+      module CoreExt
+        # @private
+        module Configuration
+          # @private
+          DEFAULT_PARALLEL_RUN_TIMES_FILE_PATH = 'tmp/rspec_parallel_run_times.txt'
+
+          def self.included(configuration)
+            # @macro add_setting
+            # Number of worker processes used to run the suite (default: 1,
+            # which runs the suite sequentially in the current process). The
+            # suite is loaded once and then forked, so every worker is a
+            # separate process: examples running concurrently never share
+            # global state. Each worker runs `before(:suite)` and
+            # `after(:suite)` hooks, and gets a `TEST_ENV_NUMBER` environment
+            # variable (`""`, `"2"`, `"3"`...) which can be used to give every
+            # worker its own database.
+            # @return [Integer]
+            configuration.add_setting :parallel_workers
+
+            # @macro add_setting
+            # Allows parallel runs to split groups having `before(:context)` or
+            # `after(:context)` hooks across workers (default: `false`).
+            #
+            # A top-level group expected to take longer than a worker's share
+            # of the suite is split into its child groups and parts of its
+            # examples, which run in different workers. By default only groups
+            # without context hooks of their own (global ones are fine) are
+            # split, since the context hooks of a split group run once for each
+            # part of it, rather than once. This is how they run when running
+            # only part of a group with `rspec path/to/spec.rb:42`, so it is
+            # safe for most suites and lets long groups be spread over workers.
+            #
+            # Tag a group with `:parallel_split => false` to always run it in a
+            # single worker.
+            # @return [Boolean]
+            configuration.add_setting :parallel_split_groups_with_context_hooks
+
+            configuration.__send__(:attr_writer, :reporter, :parallel_run_times_file_path)
+
+            # @return [Integer, nil] the number of the current parallel worker
+            #   (starting at 1), or nil when not running in a parallel worker.
+            configuration.__send__(:attr_accessor, :parallel_worker_number)
+          end
+
+          # The file in which parallel runs persist the run time of every
+          # example, so that the next parallel runs can hand out the longest
+          # groups first and spread them over workers. Defaults to
+          # `tmp/rspec_parallel_run_times.txt`, or to
+          # `example_status_persistence_file_path` when it is set (the run
+          # times persisted there are used). Set it to `nil` to not persist
+          # run times.
+          #
+          # @return [String, nil] the file path
+          def parallel_run_times_file_path
+            return @parallel_run_times_file_path if defined?(@parallel_run_times_file_path)
+
+            DEFAULT_PARALLEL_RUN_TIMES_FILE_PATH unless example_status_persistence_file_path
+          end
+
+          # Registers a block to run in each parallel worker process after it
+          # is forked, before its `before(:suite)` hooks. The block receives
+          # the worker number. Use it to set up per-worker resources, such as
+          # connecting to a per-worker database.
+          #
+          # @example
+          #   RSpec.configure do |config|
+          #     config.parallel_worker_setup do |worker_number|
+          #       SimpleCov.command_name "rspec-#{worker_number}"
+          #     end
+          #   end
+          def parallel_worker_setup(&block)
+            parallel_worker_hooks(:setup) << block
+          end
+
+          # Registers a block to run in each parallel worker process after its
+          # `after(:suite)` hooks, right before the worker exits. The block
+          # receives the worker number.
+          def parallel_worker_teardown(&block)
+            parallel_worker_hooks(:teardown) << block
+          end
+
+          # @private
+          def parallel_worker_hooks(type)
+            (@parallel_worker_hooks ||= { :setup => [], :teardown => [] })[type]
+          end
+        end
+
+        # @private
+        module ConfigurationOverrides
+          # Loading this gem means running in parallel: one worker per physical
+          # core unless set (`1` runs the suite sequentially). Where processes
+          # can't be forked, the suite runs sequentially without a warning.
+          def parallel_workers
+            value = super
+            return value unless value.nil?
+
+            Parallel.supported? ? Parallel.default_worker_count : 1
+          end
+
+        private
+
+          # rspec-core runs the default path (`spec`) when no files are given
+          # only when its command is `rspec`.
+          def command
+            super == 'rspec-parallel' ? 'rspec' : super
+          end
+        end
+
+        # @private
+        module Parser
+          def parse(source=nil)
+            # The long form of an option with an optional argument consumes the
+            # next argument even when it is a file path, the short form does not.
+            @original_args = original_args.map { |arg| arg == '--parallel' ? '-j' : arg }
+            super
+          end
+
+        private
+
+          def parser(options)
+            super.tap do |parser|
+              parser.separator ''
+              parser.separator '  **** Parallel ****'
+              parser.separator ''
+              parser.on('-j', '--[no-]parallel [COUNT]', Integer,
+                        'Run the suite in COUNT forked worker processes (default: number of physical CPU cores).') do |count|
+                options[:parallel_workers] = count.nil? ? Parallel.default_worker_count : (count || 1)
+              end
+            end
+          end
+        end
+
+        # @private
+        module Runner
+          def run_specs(example_groups)
+            parallel_units = Parallel.units_for(@configuration, @world, example_groups)
+            return super unless parallel_units
+
+            examples_count = @world.example_count(example_groups)
+            examples_passed = @configuration.reporter.report(examples_count) do |reporter|
+              Parallel.run(@configuration, @world, parallel_units, reporter)
+            end
+
+            exit_code(examples_passed)
+          end
+        end
+
+        # @private
+        module HookCollections
+          # Whether any `before(:context)` or `after(:context)` hook, other than
+          # those registered from `globals`, is registered directly on the
+          # owner of these hooks.
+          def context_hooks?(globals)
+            [:before, :after].any? do |position|
+              (all_hooks_for(position, :context) - globals.all_hooks_for(position, :context)).any?
+            end
+          end
+        end
+
+        # @private
+        module Example
+          # Sets the outcome of running this example in another process.
+          def restore_exception(exception)
+            @exception = exception
+          end
+        end
+
+        # @private
+        module ExampleGroupClassMethods
+          # The memoized `let` values of the instance running a split group's
+          # `before(:context)` hooks must not be shared with its examples.
+          def each_instance_variable_for_example(group)
+            super { |ivar| yield ivar unless ivar.to_sym == :@__memoized }
+          end
+        end
+
+        # @private
+        module Reporter
+          # Overrides the time profiled for a top-level group, for groups run
+          # in another process.
+          def record_group_run_time(group, run_time)
+            return unless @profiler && @profiler.example_groups.key?(group)
+
+            @profiler.example_groups[group][:total_time] = run_time
+          end
+        end
+
+        # Order dependencies can only be reproduced in a single process.
+        #
+        # @private
+        module BisectShellCommand
+          PARALLEL_OPTION = /\A(-j\d*|--(no-)?parallel(=\d+)?)\z/
+
+          def initialize(original_cli_args)
+            super(without_parallel_options(original_cli_args))
+          end
+
+          # The bisect runs load this gem, so that a `--parallel` in `.rspec`
+          # is a known option there too.
+          def command_for(locations, server)
+            executable = open3_safe_escape(RSpec::Core.path_to_executable)
+            "#{super.sub(executable) { "-rrspec/core/parallel #{executable}" }} --no-parallel"
+          end
+
+        private
+
+          def without_parallel_options(args)
+            kept = []
+            count_may_follow = false
+            args.each do |arg|
+              next count_may_follow = false if count_may_follow && arg =~ /\A\d+\z/
+
+              count_may_follow = %w[-j --parallel].include?(arg)
+              kept << arg unless arg =~ PARALLEL_OPTION
+            end
+            kept
+          end
+        end
+
+        # Order dependencies can only be reproduced in a single process.
+        #
+        # @private
+        module BisectRunDispatcher
+          def initialize(runner, channel)
+            super
+            runner.configuration.force(:parallel_workers => 1)
+          end
+        end
+      end
+    end
+
+    Configuration.__send__(:include, Parallel::CoreExt::Configuration)
+    Configuration.__send__(:prepend, Parallel::CoreExt::ConfigurationOverrides)
+    Parser.__send__(:prepend, Parallel::CoreExt::Parser)
+    Runner.__send__(:prepend, Parallel::CoreExt::Runner)
+    Hooks::HookCollections.__send__(:include, Parallel::CoreExt::HookCollections)
+    Example.__send__(:include, Parallel::CoreExt::Example)
+    ExampleGroup.singleton_class.__send__(:prepend, Parallel::CoreExt::ExampleGroupClassMethods)
+    Reporter.__send__(:include, Parallel::CoreExt::Reporter)
+    Bisect::ShellCommand.__send__(:prepend, Parallel::CoreExt::BisectShellCommand)
+    Bisect::ForkRunner::RunDispatcher.__send__(:prepend, Parallel::CoreExt::BisectRunDispatcher)
+  end
+end

data/lib/rspec/core/parallel/exception_serializer.rb

@@ -0,0 +1,122 @@
+module RSpec
+  module Core
+    module Parallel
+      # Carries exceptions raised in a worker over to the main process.
+      #
+      # Exceptions are Marshal-ed whenever possible so that the main process
+      # sees the very same object (class, ivars, cause...). Exceptions holding
+      # unmarshalable state (procs, IOs, singleton methods...) or whose class
+      # does not exist in the main process are rebuilt from their class name,
+      # message, backtrace and cause.
+      #
+      # @private
+      module ExceptionSerializer
+        MAX_CAUSE_DEPTH = 10
+
+        # Stands in for exceptions that cannot be reconstructed as instances
+        # of their original class.
+        class RemoteException < StandardError
+          class << self
+            attr_accessor :remote_class_name
+
+            def name
+              remote_class_name || super
+            end
+            alias_method :to_s, :name
+            alias_method :inspect, :name
+          end
+        end
+
+        def self.dump(exception, depth=0)
+          return nil unless exception
+
+          {
+            :marshaled => marshal(exception),
+            :class_name => exception.class.name,
+            :message => safe_message(exception),
+            :backtrace => exception.backtrace,
+            :cause => depth < MAX_CAUSE_DEPTH ? dump(exception.cause, depth + 1) : nil
+          }
+        end
+
+        def self.load(payload)
+          return nil unless payload
+
+          unmarshal(payload[:marshaled]) || rebuild(payload)
+        end
+
+        def self.marshal(exception)
+          Marshal.dump(exception)
+        rescue Exception # rubocop:disable Lint/RescueException
+          nil
+        end
+
+        def self.unmarshal(data)
+          return nil unless data
+
+          exception = Marshal.load(data) # rubocop:disable Security/MarshalLoad
+          exception if Exception === exception && usable?(exception)
+        rescue Exception # rubocop:disable Lint/RescueException
+          nil
+        end
+
+        def self.safe_message(exception)
+          exception.message.to_s
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          "<#{exception.class.name}#message raised #{e.class}>"
+        end
+
+        # Rebuilds the exception as an instance of its class when possible.
+        # Classes whose methods rely on state set by their constructor (such
+        # as a wrapped exception) get a stand-in reporting their name instead.
+        def self.rebuild(payload)
+          cause = load(payload[:cause])
+          klass = exception_class(payload[:class_name])
+
+          if klass && !klass.method_defined?(:all_exceptions)
+            exception = build(klass.allocate, payload, cause)
+            return exception if usable?(exception)
+          end
+
+          proxy = Class.new(RemoteException)
+          proxy.remote_class_name = payload[:class_name]
+          build(proxy.allocate, payload, cause)
+        end
+
+        def self.build(exception, payload, cause)
+          message = payload[:message]
+          Exception.instance_method(:initialize).bind_call(exception, message)
+          exception.define_singleton_method(:message) { message }
+          exception.define_singleton_method(:to_s) { message }
+          exception = attach_cause(exception, cause) if cause
+          exception.set_backtrace(payload[:backtrace]) if payload[:backtrace]
+          exception
+        end
+
+        def self.usable?(exception)
+          exception.message
+          exception.backtrace
+          exception.inspect
+          true
+        rescue Exception # rubocop:disable Lint/RescueException
+          false
+        end
+
+        def self.exception_class(class_name)
+          return nil unless class_name
+
+          klass = Object.const_get(class_name)
+          klass if Class === klass && klass <= Exception
+        rescue NameError, ArgumentError
+          nil
+        end
+
+        def self.attach_cause(exception, cause)
+          raise exception, :cause => cause
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          e
+        end
+      end
+    end
+  end
+end

data/lib/rspec/core/parallel/rails_integration.rb

@@ -0,0 +1,49 @@
+module RSpec
+  module Core
+    module Parallel
+      # Prepares Rails apps for running in parallel workers, as `rails test`
+      # does:
+      #
+      # * runs the hooks Rails provides to parallel test runners, so that
+      #   every worker gets its own test database (named after the
+      #   configured one: `app_test_0`, `app_test_1`..., created and loaded
+      #   from the schema when needed). Set
+      #   `ActiveSupport.parallelize_test_databases` to `false` to opt out.
+      #   Workers are numbered from 0 for these hooks, as in Rails. Rails
+      #   versions before 8.1 have no hooks to run before forking.
+      # * loads the translations before forking, as Rails does when eager
+      #   loading, rather than in every worker.
+      #
+      # @private
+      module RailsIntegration
+        def self.before_fork
+          ::I18n.eager_load! if defined?(::Rails.application) && ::Rails.application && defined?(::I18n.eager_load!)
+          hooks(:before_fork_hooks).each(&:call)
+        end
+
+        def self.after_fork(worker_number)
+          hooks(:after_fork_hooks).each { |hook| hook.call(worker_number - 1) }
+        end
+
+        def self.run_cleanup(worker_number)
+          hooks(:run_cleanup_hooks).each { |hook| hook.call(worker_number - 1) }
+        end
+
+        def self.hooks(type)
+          # Loading it registers the hooks creating a database per worker, as
+          # `rails/test_help` does.
+          require 'active_record/test_databases' if defined?(::ActiveRecord::TestDatabases)
+          return [] unless defined?(::ActiveSupport::Testing::Parallelization)
+          return [] unless ::ActiveSupport::Testing::Parallelization.respond_to?(type)
+          # Rails checks this setting in its hooks only from version 8.1 on.
+          return [] if ::ActiveSupport.respond_to?(:parallelize_test_databases) &&
+                       ::ActiveSupport.parallelize_test_databases == false
+
+          ::ActiveSupport::Testing::Parallelization.public_send(type)
+        rescue LoadError
+          []
+        end
+      end
+    end
+  end
+end

data/lib/rspec/core/parallel/registry.rb

@@ -0,0 +1,45 @@
+module RSpec
+  module Core
+    module Parallel
+      # Assigns every example group and example a stable index. Workers are
+      # forked after the suite is loaded, so walking the same tree yields the
+      # same indices in every process, letting processes refer to groups and
+      # examples without relying on their ids being unique.
+      #
+      # @private
+      class Registry
+        attr_reader :groups, :examples
+
+        def initialize(top_level_groups)
+          @groups = []
+          @examples = []
+          @group_indices = {}.compare_by_identity
+          @example_indices = {}.compare_by_identity
+          top_level_groups.each { |group| register(group) }
+        end
+
+        def group_index(group)
+          @group_indices[group]
+        end
+
+        def example_index(example)
+          @example_indices[example]
+        end
+
+      private
+
+        def register(group)
+          @group_indices[group] = @groups.size
+          @groups << group
+
+          group.examples.each do |example|
+            @example_indices[example] = @examples.size
+            @examples << example
+          end
+
+          group.children.each { |child| register(child) }
+        end
+      end
+    end
+  end
+end

data/lib/rspec/core/parallel/scheduler.rb

@@ -0,0 +1,162 @@
+module RSpec
+  module Core
+    module Parallel
+      # Splits the suite into units of work and orders them longest first, so
+      # that the longest units do not end up running alone at the end of the
+      # run. Durations come from the run times stored in
+      # `example_status_persistence_file_path` and
+      # `parallel_run_times_file_path`; examples without a stored run time are
+      # assumed to take the average time of those with one.
+      #
+      # A unit is usually a whole top-level group. A group expected to take
+      # longer than a worker's share of the suite is split into its child
+      # groups and parts of its own examples, unless it is tagged with
+      # `:parallel_split => false` or has `before(:context)` or
+      # `after(:context)` hooks other than global ones (see
+      # `Configuration#parallel_split_groups_with_context_hooks`). The units
+      # of a split group are kept adjacent so that its output stays together.
+      #
+      # @private
+      class Scheduler
+        # @!attribute group
+        #   @return [Class] the group to run
+        # @!attribute examples_only
+        #   @return [Boolean] whether to run only the group's own examples,
+        #     and not its child groups
+        # @!attribute split_ancestors
+        #   @return [Array<Class>] the split groups containing `group`,
+        #     outermost first
+        # @!attribute examples
+        #   @return [Array<Example>, nil] the examples to run when running
+        #     only some of the group's own examples
+        # @!attribute sequence
+        #   @return [Integer] the position of the unit among the parts of its
+        #     top-level group when running them sequentially
+        Unit = Struct.new(:group, :examples_only, :split_ancestors, :estimate, :examples, :sequence)
+
+        def initialize(configuration, world)
+          @configuration = configuration
+          @world = world
+        end
+
+        # Without run times from a previous run, the duration of groups is
+        # unknown: they are split into smaller parts, so that a long one does
+        # not end up running alone at the end of the run.
+        UNKNOWN_DURATIONS_SPLIT_FACTOR = 16
+
+        # @return [Array<Unit>] the units to run, longest first
+        def units(example_groups, worker_count)
+          top_level_units = example_groups.filter_map do |group|
+            examples = examples_of(group)
+            Unit.new(group, false, [], estimated_duration(examples)) unless examples.empty?
+          end
+          target = top_level_units.sum(&:estimate) / worker_count
+          target /= UNKNOWN_DURATIONS_SPLIT_FACTOR if run_times.empty?
+
+          families = top_level_units.map do |unit|
+            family = split(unit, target)
+            family.each_with_index { |part, sequence| part.sequence = sequence }
+            family.each_with_index.sort_by { |part, sequence| [-part.estimate, sequence] }.map(&:first)
+          end
+          sort_longest_first(families).flatten
+        end
+
+        DURATION_UNITS = { 'second' => 1, 'minute' => 60 }.freeze
+
+        # Parses durations formatted by `Formatters::Helpers.format_duration`.
+        def self.parse_duration(text)
+          parts = text.to_s.scan(/([\d.]+) (second|minute)s?/)
+          return nil if parts.empty?
+
+          parts.inject(0.0) { |total, (amount, unit)| total + (amount.to_f * DURATION_UNITS.fetch(unit)) }
+        end
+
+      private
+
+        # @return [Array<Unit>] the parts of the unit, in the order in which
+        #   they would run sequentially (with the default ordering)
+        def split(unit, target)
+          return [unit] unless unit.estimate > target && splittable?(unit.group)
+
+          units = parts_of(unit, target).flat_map { |part| split(part, target) }
+          units.size > 1 ? units : [unit]
+        end
+
+        def splittable?(group)
+          return false if group.metadata[:parallel_split] == false
+
+          @configuration.parallel_split_groups_with_context_hooks? || !group.hooks.context_hooks?(@configuration.hooks)
+        end
+
+        def parts_of(unit, target)
+          return example_chunks(unit, target) if unit.examples_only
+
+          ancestors = unit.split_ancestors + [unit.group]
+          own_examples = @world.filtered_examples[unit.group]
+          parts = own_examples.empty? ? [] : [Unit.new(unit.group, true, ancestors, estimated_duration(own_examples))]
+
+          unit.group.children.each do |child|
+            examples = examples_of(child)
+            parts << Unit.new(child, false, ancestors, estimated_duration(examples)) unless examples.empty?
+          end
+          parts
+        end
+
+        # Cuts the examples of a unit into parts expected to take at most
+        # `target` each (unless a single example takes longer).
+        def example_chunks(unit, target)
+          chunks = []
+          (unit.examples || @world.filtered_examples[unit.group]).each do |example|
+            run_time = run_time_of(example)
+            if chunks.empty? || chunks.last.estimate + run_time > target
+              chunks << Unit.new(unit.group, true, unit.split_ancestors, 0.0, [])
+            end
+            chunks.last.examples << example
+            chunks.last.estimate += run_time
+          end
+          chunks.size > 1 ? chunks : []
+        end
+
+        # Families of units run longest first: those with the longest unit,
+        # then those taking the longest overall.
+        def sort_longest_first(families)
+          families.each_with_index.sort_by do |family, position|
+            [-family.first.estimate, -family.sum(&:estimate), position]
+          end.map(&:first)
+        end
+
+        def examples_of(group)
+          group.descendants.flat_map { |descendant| @world.filtered_examples[descendant] }
+        end
+
+        def estimated_duration(examples)
+          examples.inject(0.0) { |total, example| total + run_time_of(example) }
+        end
+
+        def run_time_of(example)
+          run_times.fetch(example.id, default_run_time)
+        end
+
+        def default_run_time
+          @default_run_time ||= run_times.empty? ? 1.0 : run_times.values.sum / run_times.size
+        end
+
+        def run_times
+          @run_times ||= load_run_times
+        end
+
+        def load_run_times
+          paths = [@configuration.example_status_persistence_file_path, @configuration.parallel_run_times_file_path]
+          paths.compact.uniq.each_with_object({}) do |path, times|
+            ExampleStatusPersister.load_from(path).each do |example|
+              run_time = self.class.parse_duration(example[:run_time])
+              times[example[:example_id]] = run_time if run_time
+            end
+          rescue SystemCallError
+            next
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/core/parallel/simplecov_integration.rb

@@ -0,0 +1,30 @@
+module RSpec
+  module Core
+    module Parallel
+      # Leaves SimpleCov's report to the main process. SimpleCov saves the
+      # coverage of every process at exit, and the process it considers the
+      # final one merges them, writes the report and checks the minimum
+      # coverage. It can't tell the workers from the main process (SimpleCov
+      # 1.x even takes the first worker for the final process, because of
+      # its `TEST_ENV_NUMBER`), so workers finishing early checked the
+      # coverage collected so far and printed false "below minimum coverage"
+      # warnings. The main process exits after all the workers.
+      #
+      # @private
+      module SimpleCovIntegration
+        # @private
+        module NotFinalResultProcess
+          def final_result_process?
+            false
+          end
+        end
+
+        def self.after_fork
+          return unless defined?(::SimpleCov) && ::SimpleCov.respond_to?(:final_result_process?)
+
+          ::SimpleCov.singleton_class.__send__(:prepend, NotFinalResultProcess)
+        end
+      end
+    end
+  end
+end

data/lib/rspec/core/parallel/version.rb

@@ -0,0 +1,7 @@
+module RSpec
+  module Core
+    module Parallel
+      VERSION = '0.1.0'
+    end
+  end
+end