rspec-core-parallel 0.1.0

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

@@ -0,0 +1,187 @@
+module RSpec
+  module Core
+    module Parallel
+      # A forked process running the units of work it is sent.
+      #
+      # @private
+      class Worker
+        attr_reader :number, :pid, :events
+        attr_accessor :current_unit, :quit_sent
+
+        def initialize(number)
+          @number = number
+          @current_unit = nil
+          @quit_sent = false
+          @alive = true
+          @reaped = false
+        end
+
+        def alive?
+          @alive
+        end
+
+        def start(configuration, registry, other_workers)
+          @events, events_writer = Channel.pipe
+          commands_reader, @commands = Channel.pipe
+
+          # The process exits when the block returns, running `at_exit` hooks
+          # (so that tools such as SimpleCov can save their results) but not
+          # the `ensure` clauses of the main process's call stack.
+          @pid = Process.fork do
+            @events.close
+            @commands.close
+            other_workers.each(&:close)
+            run(configuration, registry, commands_reader, events_writer)
+          end
+
+          events_writer.close
+          commands_reader.close
+          self
+        end
+
+        def send_command(*command)
+          @commands.write(command)
+          true
+        rescue IOError, SystemCallError
+          false
+        end
+
+        def close
+          @alive = false
+          @events.close
+          @commands.close
+        end
+
+        def exited?
+          @reaped ||= !Process.waitpid(@pid, Process::WNOHANG).nil?
+        rescue SystemCallError
+          @reaped = true
+        end
+
+        def wait
+          return if @reaped
+
+          Process.waitpid(@pid)
+          @reaped = true
+        rescue SystemCallError
+          @reaped = true
+        end
+
+      private
+
+        def run(configuration, registry, commands, events)
+          # :nocov: - executed in forked processes, covered by integration specs
+          prepare_environment(configuration)
+          reporter = WorkerReporter.new(configuration, registry, events, commands)
+          configuration.reporter = reporter
+
+          begin
+            RailsIntegration.after_fork(@number)
+            SimpleCovIntegration.after_fork
+            configuration.parallel_worker_hooks(:setup).each { |hook| hook.call(@number) }
+            configuration.with_suite_hooks { process_commands(registry, reporter, commands) }
+            configuration.parallel_worker_hooks(:teardown).each { |hook| hook.call(@number) }
+            RailsIntegration.run_cleanup(@number)
+          rescue SystemExit => e
+            finish_interrupted_unit(reporter)
+            reporter.exit_requested(e.status)
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            finish_interrupted_unit(reporter)
+            reporter.notify_non_example_exception(e, "An error occurred in parallel worker #{@number}.")
+          end
+          reporter.worker_finished
+        rescue IOError, SystemCallError
+          # The main process is gone: there is no one left to report to.
+          nil
+          # :nocov:
+        end
+
+        # `PARALLEL_TEST_GROUPS` is not set: with it, SimpleCov assumes it runs
+        # under parallel_tests and makes the last worker wait for a parallel_tests
+        # pid file. The main process collects the results of all the workers.
+        def prepare_environment(configuration)
+          ENV['TEST_ENV_NUMBER'] = @number == 1 ? '' : @number.to_s
+          configuration.parallel_worker_number = @number
+          configuration.world.wants_to_quit = false
+          trap_interrupt(configuration.world)
+        end
+
+        # The main process tells the user it is shutting down: workers
+        # quietly stop after their current example.
+        def trap_interrupt(world)
+          trap('INT') { world.wants_to_quit ? exit!(1) : world.wants_to_quit = true }
+        end
+
+        def process_commands(registry, reporter, commands)
+          # Once quitting, groups return without running any example.
+          while (command = commands.read) && command.first == :run
+            _, unit, group_index, examples_only, ancestor_indices, example_indices = command
+            group = registry.groups[group_index]
+            ancestors = ancestor_indices.map { |index| registry.groups[index] }
+            restrict_examples(group, example_indices.map { |index| registry.examples[index] }) if example_indices
+            reporter.unit = unit
+            @unit_started_at = RSpec::Core::Time.now
+            succeeded = run_unit(group, examples_only, ancestors, reporter)
+            reporter.unit = nil
+            reporter.unit_finished(unit, succeeded ? true : false, (RSpec::Core::Time.now - @unit_started_at).to_f)
+          end
+        end
+
+        # Workers are forked processes: the examples of a group can be
+        # restricted without affecting the other workers.
+        def restrict_examples(group, examples)
+          RSpec.world.filtered_examples[group] = examples
+        end
+
+        def finish_interrupted_unit(reporter)
+          return unless (unit = reporter.unit)
+
+          reporter.unit_finished(unit, false, (RSpec::Core::Time.now - @unit_started_at).to_f)
+          reporter.unit = nil
+        end
+
+        def run_unit(group, examples_only, ancestors, reporter)
+          return run_part(group, examples_only, reporter) if ancestors.empty?
+
+          with_context_hooks_of(ancestors.first, group, examples_only, reporter) do
+            run_unit(group, examples_only, ancestors.drop(1), reporter)
+          end
+        end
+
+        def run_part(group, examples_only, reporter)
+          examples_only ? group.run_examples(reporter) : group.run(reporter)
+        end
+
+        # Runs the context hooks of a split group around part of it, as
+        # `ExampleGroup.run` does around the whole group.
+        def with_context_hooks_of(split_group, group, examples_only, reporter)
+          return if RSpec.world.wants_to_quit
+
+          begin
+            RSpec.current_scope = :before_context_hook
+            split_group.run_before_context_hooks(split_group.new('before(:context) hook'))
+            yield
+          rescue Pending::SkipDeclaredInExample => e
+            for_part_examples(group, examples_only, reporter) { |example| example.skip_with_exception(reporter, e) }
+            true
+          rescue Support::AllExceptionsExceptOnesWeMustNotRescue => e
+            for_part_examples(group, examples_only, reporter) { |example| example.fail_with_exception(reporter, e) }
+            RSpec.world.wants_to_quit = true if reporter.fail_fast_limit_met?
+            false
+          ensure
+            RSpec.current_scope = :after_context_hook
+            split_group.run_after_context_hooks(split_group.new('after(:context) hook'))
+          end
+        end
+
+        def for_part_examples(group, examples_only, reporter, &block)
+          return group.filtered_examples.each(&block) if examples_only
+
+          reporter.example_group_started(group)
+          group.for_filtered_examples(reporter, &block)
+          reporter.example_group_finished(group)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,212 @@
+module RSpec
+  module Core
+    module Parallel
+      # Stands in for the reporter inside a worker process: rather than
+      # notifying formatters, it forwards every event to the main process.
+      #
+      # Events are sent in batches, once per example, to keep the main
+      # process, which replays the events of every worker, from becoming a
+      # bottleneck.
+      #
+      # Values provided by user code (metadata, notifications) are marshaled
+      # on their own, so that one the main process cannot load (for instance
+      # of a class defined while running an example) only affects itself.
+      #
+      # @private
+      class WorkerReporter < Reporter
+        UNFORWARDED_METADATA_KEYS = [:execution_result, :example_group, :block, :last_run_status].freeze
+        MAX_BATCH_SIZE = 200
+
+        def initialize(configuration, registry, channel, control)
+          super(configuration)
+          @registry = registry
+          @channel = channel
+          @control = control
+          @metadata_baselines = {}.compare_by_identity
+          @unit = nil
+          @batch = []
+        end
+
+        attr_accessor :unit
+
+        def notify(event, notification)
+          case notification
+          when Notifications::ExampleNotification
+            forward_example_event(event, notification.example)
+          when Notifications::GroupNotification
+            forward_group_event(event, notification.group)
+          else
+            forward_notification(event, notification)
+          end
+        end
+
+        # Custom notifications are instances of anonymous classes, which
+        # cannot be sent to the main process: their options are sent instead.
+        def publish(event, options={})
+          return super if RSPEC_NOTIFICATIONS.include?(event)
+
+          post([:publish, @unit, event, options.to_h { |key, value| [key, pack(value)] }])
+        end
+
+        def notify_non_example_exception(exception, context_description)
+          @configuration.world.non_example_failure = true
+          post([:non_example_exception, @unit, ExceptionSerializer.dump(exception), context_description])
+        end
+
+        # Sending the start of each example lets the main process report the
+        # example that was running if the worker crashes.
+        def example_started(example)
+          super
+          flush
+        end
+
+        def example_finished(example)
+          super
+          poll_control
+        end
+
+        def unit_finished(unit, succeeded, run_time)
+          post([:unit_done, unit, succeeded, run_time])
+          flush
+        end
+
+        # Asks the main process to exit with the given status once the run is
+        # over, as when `exit` is called while running the suite sequentially.
+        def exit_requested(status)
+          post([:exit, @unit, status])
+        end
+
+        def worker_finished
+          post([:bye, nil])
+          flush
+        end
+
+        # Marshals a value on its own, along with a description of it to
+        # report in its place if the main process cannot load it.
+        def self.pack(value)
+          [Marshal.dump(value), value.inspect]
+        rescue Exception # rubocop:disable Lint/RescueException
+          [nil, (value.inspect rescue value.class.name)] # rubocop:disable Style/RescueModifier
+        end
+
+        # @return the packed value, or `fallback` (by default, the description
+        #   of the value) if it cannot be loaded.
+        def self.unpack(packed, fallback=packed[1])
+          data = packed[0]
+          data ? Marshal.load(data) : fallback # rubocop:disable Security/MarshalLoad
+        rescue Exception # rubocop:disable Lint/RescueException
+          fallback
+        end
+
+        def flush
+          return if @batch.empty?
+
+          batch = @batch
+          @batch = []
+          @channel.write(batch)
+        end
+
+      private
+
+        def post(message)
+          @batch << message
+          flush if @batch.size >= MAX_BATCH_SIZE
+        end
+
+        def pack(value)
+          self.class.pack(value)
+        end
+
+        def forward_example_event(event, example)
+          index = @registry.example_index(example)
+          return forward_unknown_example(event, example) unless index
+
+          post([:example, @unit, event, index, example_payload(event, example)])
+        end
+
+        def example_payload(event, example)
+          case event
+          when :example_started
+            @metadata_baselines[example] = metadata_snapshot(example.metadata)
+            [nanoseconds(example.execution_result.started_at)]
+          when :example_finished
+            execution_result_payload(example.execution_result) << metadata_changes(example)
+          end
+        end
+
+        def execution_result_payload(result)
+          [
+            nanoseconds(result.started_at),
+            result.status,
+            ExceptionSerializer.dump(result.exception),
+            nanoseconds(result.finished_at),
+            result.run_time,
+            result.pending_message,
+            ExceptionSerializer.dump(result.pending_exception),
+            result.pending_fixed
+          ]
+        end
+
+        def nanoseconds(time)
+          time && ((time.to_i * 1_000_000_000) + time.nsec)
+        end
+
+        # Hashes and arrays can be changed in place (as rswag does with
+        # `example.metadata[:response]`), so their contents are compared too.
+        def metadata_snapshot(metadata)
+          metadata.each_with_object({}) do |(key, value), snapshot|
+            snapshot[key] = [value, contents_of(value)] unless UNFORWARDED_METADATA_KEYS.include?(key)
+          end
+        end
+
+        def contents_of(value)
+          Marshal.dump(value) if value.is_a?(Hash) || value.is_a?(Array)
+        rescue TypeError
+          nil
+        end
+
+        def metadata_changes(example)
+          baseline = @metadata_baselines.delete(example) || {}
+          changes = nil
+          example.metadata.each do |key, value|
+            next if UNFORWARDED_METADATA_KEYS.include?(key)
+
+            before, contents = baseline[key]
+            next if baseline.key?(key) && before.equal?(value) && contents_of(value) == contents
+
+            (changes ||= {})[key] = pack(value)
+          end
+          changes
+        end
+
+        def forward_unknown_example(event, example)
+          return unless event == :example_failed
+
+          message = "Failure in an example unknown to the main process: #{example.full_description}\n" +
+                    ExceptionSerializer.safe_message(example.exception || StandardError.new)
+          forward_notification(:message, Notifications::MessageNotification.new(message))
+        end
+
+        def forward_group_event(event, group)
+          index = @registry.group_index(group)
+          post([:group, @unit, event, index]) if index
+        end
+
+        def forward_notification(event, notification)
+          if event == :message
+            post([:message, @unit, notification.message.to_s])
+          else
+            post([:notify, @unit, event, pack(notification)])
+          end
+        end
+
+        def poll_control
+          return unless @control.readable_now?
+
+          command = @control.read
+          @configuration.world.wants_to_quit = true if command.nil? || command.first == :quit
+        end
+      end
+    end
+  end
+end

data/lib/rspec/core/parallel.rb

@@ -0,0 +1,95 @@
+require 'rspec/core'
+require_relative 'parallel/version'
+
+module RSpec
+  module Core
+    # Multi-process execution of a spec suite.
+    #
+    # The suite is loaded once in the main process, then forked into a pool
+    # of workers which share the loaded code copy-on-write. Top-level example
+    # groups (or parts of long ones) are dispatched dynamically to idle
+    # workers, longest first. Workers stream every
+    # reporter event back to the main process, which replays it against its
+    # own copies of the examples, so formatters, `--only-failures`, profiling
+    # and exit codes behave exactly as in a sequential run.
+    #
+    # Because every worker is a separate process, global state (constants,
+    # stubs, `RSpec.configuration`, database connections...) is never shared
+    # between concurrently running examples.
+    #
+    # @private
+    module Parallel
+      # @return [Array<Scheduler::Unit>, nil] the units of work to run in
+      #   parallel, or nil when the groups must run sequentially.
+      def self.units_for(configuration, world, example_groups)
+        return nil unless configuration.parallel_workers.to_i > 1 && !configuration.dry_run?
+
+        unless supported?
+          RSpec.warning "Running specs in parallel requires `Process.fork`, which is not " \
+                        "supported here: running them sequentially", :call_site => nil
+          return nil
+        end
+
+        require_components
+        units = Scheduler.new(configuration, world).units(example_groups, configuration.parallel_workers.to_i)
+        units if units.size > 1
+      end
+
+      # Loaded only for parallel runs.
+      def self.require_components
+        %w[
+          channel exception_serializer rails_integration simplecov_integration registry scheduler worker_reporter
+          worker coordinator
+        ].each do |file|
+          require_relative "parallel/#{file}"
+        end
+      end
+
+      # Runs the units in forked worker processes.
+      #
+      # @return [Boolean] whether all examples passed
+      def self.run(configuration, world, units, reporter)
+        worker_count = [configuration.parallel_workers.to_i, units.size].min
+        passed = Coordinator.new(configuration, world, worker_count).run(units, reporter)
+        persist_run_times(configuration, world)
+        passed
+      end
+
+      def self.persist_run_times(configuration, world)
+        return unless (path = configuration.parallel_run_times_file_path)
+
+        ExampleStatusPersister.persist(world.all_examples, path)
+      rescue SystemCallError => e
+        RSpec.warning "Could not write example run times to #{path} (configured as " \
+                      "`config.parallel_run_times_file_path`) due to a system error: " \
+                      "#{e.inspect}.", :call_site => nil
+      end
+
+      def self.supported?
+        Process.respond_to?(:fork) && RUBY_ENGINE == 'ruby' && !RSpec::Support::OS.windows?
+      end
+
+      # One worker per physical core: workers sharing a core through
+      # simultaneous multithreading (hyper-threading) mostly slow each other
+      # down, using more CPU time and memory for the same wall time.
+      def self.default_worker_count
+        require 'etc'
+        [Etc.nprocessors, physical_core_count].compact.min
+      end
+
+      def self.physical_core_count
+        siblings = Dir['/sys/devices/system/cpu/cpu[0-9]*/topology/thread_siblings_list']
+        return siblings.map { |path| File.read(path).strip }.uniq.size unless siblings.empty?
+
+        return nil unless RbConfig::CONFIG['host_os'] =~ /darwin/
+
+        count = IO.popen(%w[sysctl -n hw.physicalcpu], :err => File::NULL, &:read).to_i
+        count if count > 0
+      rescue SystemCallError, IOError
+        nil
+      end
+    end
+  end
+end
+
+require_relative 'parallel/core_ext'

data/lib/rspec-core-parallel.rb

@@ -0,0 +1 @@
+require 'rspec/core/parallel'

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: rspec-core-parallel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alessandro Rodi
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.13.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.13.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.14'
+description: 'Adds `rspec --parallel` to rspec-core 3.13: the suite is loaded once,
+  forked into one worker per CPU core, and groups are handed out longest first using
+  the run times of the previous run. Formatters, --only-failures, --bisect and exit
+  codes work as in a sequential run. Rails apps get a test database per worker.'
+email:
+- alessandro.rodi@renuo.ch
+executables:
+- rspec-parallel
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- exe/rspec-parallel
+- lib/rspec-core-parallel.rb
+- lib/rspec/core/parallel.rb
+- lib/rspec/core/parallel/channel.rb
+- lib/rspec/core/parallel/coordinator.rb
+- lib/rspec/core/parallel/core_ext.rb
+- lib/rspec/core/parallel/exception_serializer.rb
+- lib/rspec/core/parallel/rails_integration.rb
+- lib/rspec/core/parallel/registry.rb
+- lib/rspec/core/parallel/scheduler.rb
+- lib/rspec/core/parallel/simplecov_integration.rb
+- lib/rspec/core/parallel/version.rb
+- lib/rspec/core/parallel/worker.rb
+- lib/rspec/core/parallel/worker_reporter.rb
+homepage: https://github.com/renuo/rspec-core-parallel
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/renuo/rspec-core-parallel
+  source_code_uri: https://github.com/renuo/rspec-core-parallel
+  changelog_uri: https://github.com/renuo/rspec-core-parallel/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Run an RSpec suite in forked worker processes: rspec --parallel'
+test_files: []