rspec-core-parallel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03f7e28ca852dcd4b84d72d272a6db18e6d8df1e9c090517613f548fbe374a5f
+  data.tar.gz: 7f3efdb57f46ed2164770dad99c66c08925a2258a0c3440f2e1fa0b9eee3209c
+SHA512:
+  metadata.gz: 46abf9b5942f67930ec91ac9b5c3d926ddf82f721d22c2314f0cc7663f78c7c929996b206348b8a182fd3afb0c4be91a23c947acaedbcb01cbf5c1c23161446e
+  data.tar.gz: '0886bc56896897d0e33c9467934cbfd9e622955f3ea8606b4df7635196f8ec98dafe9a1a48c420026b15962636e48783324aa089da725a5a4f70c4b0a66657c1'

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+* Loading the gem makes `rspec` run the suite in forked worker processes, one
+  per physical CPU core (`config.parallel_workers = 1` runs it sequentially).
+* `rspec-parallel` command, which also takes `--parallel [COUNT]` (`-j`) and
+  `--no-parallel`.
+* Extracted from a backport of `rspec --parallel` to rspec-core 3.13. Unlike
+  there, run times are saved in `tmp/rspec_parallel_run_times.txt` even when
+  `tmp` does not exist yet.

data/LICENSE.md

@@ -0,0 +1,27 @@
+The MIT License (MIT)
+=====================
+
+* Copyright © 2026 Alessandro Rodi, Renuo AG
+* Copyright © 2012 Chad Humphries, David Chelimsky, Myron Marston
+* Copyright © 2009 Chad Humphries, David Chelimsky
+* Copyright © 2006 David Chelimsky, The RSpec Development Team
+* Copyright © 2005 Steven Baker
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# rspec-core-parallel
+
+Runs an RSpec suite on all the cores of your machine. Add the gem, and `rspec`
+runs in parallel, with one worker process per physical CPU core.
+
+RSpec loads the suite once and forks worker processes, which share the loaded
+code. Groups are handed out to idle workers, longest first, and every result is
+sent back to the main process, which reports them like a sequential run: all
+formatters, `--only-failures`, `--profile`, `--fail-fast`, `--bisect` and exit
+codes work as usual.
+
+This gem brings `--parallel` to rspec-core 3.13 until it is part of rspec-core
+itself.
+
+## Installation
+
+```ruby
+group :test do
+  gem "rspec-core-parallel"
+end
+```
+
+Rails apps load it with the other gems of the `test` group. Elsewhere, require
+it at the top of `spec_helper.rb`:
+
+```ruby
+require "rspec/core/parallel"
+```
+
+That's it: `bundle exec rspec` now runs in parallel.
+
+## Number of workers
+
+The default is one worker per physical CPU core. Set it in `spec_helper.rb`
+(`1` runs the suite sequentially):
+
+```ruby
+RSpec.configure do |config|
+  config.parallel_workers = 4
+end
+```
+
+To choose it on the command line, run `rspec-parallel`, which is `rspec` with
+the gem loaded before the options are read, so that it also takes
+`--parallel [COUNT]` (`-j`) and `--no-parallel`:
+
+```
+$ bundle exec rspec-parallel --parallel 4
+$ bundle exec rspec-parallel --no-parallel spec/models/user_spec.rb
+```
+
+Options given on the command line win over `config.parallel_workers`.
+
+## How it compares
+
+Unlike [parallel_tests](https://github.com/grosser/parallel_tests) and similar
+runners, which start one rspec process per CPU and split the spec files between
+them:
+
+* the app boots once, then workers are forked from it;
+* groups are dispatched dynamically, longest first (using the run times of the
+  previous run), and long files are split, so all the workers finish together;
+* there is one combined report, and one exit code;
+* in Rails apps, the worker databases are created and loaded by the runner.
+
+## Isolation
+
+Because every worker is a separate process, examples running at the same time
+never share global state (constants, stubs, `RSpec.configuration`...), so
+existing suites run unchanged, provided that they don't share external
+resources such as databases or files between processes.
+
+Rails apps need no setup: as with `rails test` in parallel, every worker gets
+its own test database (`app_test_0`, `app_test_1`...), created and loaded from
+the schema when needed. Set `ActiveSupport.parallelize_test_databases = false`
+to opt out.
+
+Each worker gets a `TEST_ENV_NUMBER` environment variable (`""`, `"2"`, `"3"`...,
+as with parallel_tests) and runs `parallel_worker_setup` hooks, which you can
+use to give every worker its own resources. Workers are forked once the suite
+is loaded, so values computed while loading it, such as a constant holding a
+directory or a Redis client, are the same in all of them. This includes
+configuration reading `TEST_ENV_NUMBER` while the app boots (as parallel_tests
+setups often do for Redis URLs): the variable is only set in the workers, so
+such resources must be pointed at a per-worker instance in
+`parallel_worker_setup`. For example, to give every worker its own directory
+for uploaded files:
+
+```ruby
+RSpec.configure do |config|
+  config.parallel_worker_setup do |worker_number|
+    CarrierWave.configure { |c| c.root = Rails.root.join("tmp/uploads/#{worker_number}") }
+  end
+end
+```
+
+`before(:suite)`, `after(:suite)` and `at_exit` hooks run in every worker.
+
+## Code coverage
+
+To collect code coverage from all the workers with SimpleCov, enable its
+support for forked processes:
+
+```ruby
+SimpleCov.enable_for_subprocesses true
+SimpleCov.start
+
+RSpec.configure do |config|
+  # A stable name per worker, so that each run replaces the results of the
+  # previous one instead of adding to them (SimpleCov names subprocesses after
+  # their pid by default).
+  config.parallel_worker_setup do |worker_number|
+    SimpleCov.command_name "RSpec (worker #{worker_number})"
+  end
+end
+```
+
+Workers only save their coverage: the main process, which exits last, merges
+it, writes the report and checks the minimum coverage.
+
+## Splitting long groups
+
+To spread long groups over several workers, a group expected to take longer
+than a worker's share of the suite is split into its child groups and parts of
+its examples, unless it has `before(:context)`/`after(:context)` hooks of its
+own (which can be allowed with
+`config.parallel_split_groups_with_context_hooks = true`) or is tagged with
+`:parallel_split => false`. Examples of the same file can therefore run at the
+same time in different workers: tag groups whose examples share a file or
+directory at a fixed path (such as a browser download directory) with
+`:parallel_split => false`, or use a path per worker.
+
+## Run times
+
+The run time of every example is saved in `tmp/rspec_parallel_run_times.txt`,
+or in `config.example_status_persistence_file_path` when it is set, so that the
+next runs hand out the longest groups first (see
+`config.parallel_run_times_file_path`). On CI, cache this file between builds.
+
+## Requirements
+
+* rspec-core 3.13
+* Ruby 3.3 or later with `Process.fork`: on JRuby and Windows the suite runs
+  sequentially.
+
+## License
+
+MIT. Most of the code comes from rspec-core, by the RSpec team.

data/exe/rspec-parallel

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+# `rspec`, with this gem loaded before the options are read, so that
+# `--parallel COUNT` and `--no-parallel` can be passed on the command line.
+require 'rspec/core'
+require 'rspec/core/parallel'
+
+RSpec::Core::Runner.invoke

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

@@ -0,0 +1,58 @@
+module RSpec
+  module Core
+    module Parallel
+      # A one-directional stream of Marshal-encoded, length-prefixed messages.
+      #
+      # @private
+      class Channel
+        HEADER_SIZE = 4
+
+        def self.pipe
+          reader, writer = IO.pipe
+          reader.binmode
+          writer.binmode
+          writer.sync = true
+          [new(reader), new(writer)]
+        end
+
+        attr_reader :io
+
+        def initialize(io)
+          @io = io
+        end
+
+        def write(message)
+          data = Marshal.dump(message)
+          @io.write([data.bytesize].pack('N') << data)
+        end
+
+        # @return [Object, nil] the next message, or nil once the other end is closed.
+        def read
+          header = read_exactly(HEADER_SIZE)
+          return nil unless header
+
+          data = read_exactly(header.unpack1('N'))
+          data && Marshal.load(data) # rubocop:disable Security/MarshalLoad
+        end
+
+        def readable_now?
+          # rubocop:disable-next Lint/IncompatibleIoSelectWithFiberScheduler
+          !IO.select([@io], nil, nil, 0).nil?
+        end
+
+        def close
+          @io.close unless @io.closed?
+        end
+
+      private
+
+        def read_exactly(size)
+          buffer = @io.read(size)
+          buffer if buffer && buffer.bytesize == size
+        rescue IOError, SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,428 @@
+module RSpec
+  module Core
+    module Parallel
+      # Runs in the main process: forks the workers, hands out units of work
+      # and replays the events workers send back onto the reporter.
+      #
+      # Events of one unit are replayed live while events of units running
+      # concurrently are buffered and replayed once the live unit finishes,
+      # so formatters always see each group as a contiguous whole. The start
+      # and finish of groups split into several units are replayed around
+      # the events of their units.
+      #
+      # @private
+      class Coordinator
+        SELECT_TIMEOUT = 0.5
+
+        def initialize(configuration, world, worker_count)
+          @configuration = configuration
+          @world = world
+          @worker_count = worker_count
+        end
+
+        def run(units, reporter)
+          @reporter = reporter
+          @registry = Registry.new(@world.example_groups)
+          @units = units
+          @previous_in_family = previous_in_family(units)
+          @queue = (0...units.size).to_a
+          @results = []
+          @run_times = Hash.new(0.0)
+          @buffers = {}
+          @dispatched_units = {}
+          @finished_units = {}
+          @replayed_units = {}
+          @live_unit = nil
+          @open_groups = []
+          @orphan_events = []
+          @failure_count = 0
+          @quitting = false
+          @exit_status = nil
+          @open_groups_by_unit = Hash.new { |hash, unit| hash[unit] = [] }
+          @running_examples = {}
+
+          start_workers
+          process_events while @workers.any?(&:alive?)
+          finish
+          exit(@exit_status) if @exit_status
+
+          @results.all?
+        ensure
+          terminate_workers
+        end
+
+      private
+
+        # @return [Array<Integer, nil>] for each unit, the unit of the same
+        #   top-level group running right before it when running sequentially
+        def previous_in_family(units)
+          previous = []
+          families = units.each_index.group_by { |unit| units[unit].split_ancestors.first }
+          families.delete(nil)
+          families.each_value do |family|
+            family.sort_by { |unit| units[unit].sequence }.each_cons(2) { |before, unit| previous[unit] = before }
+          end
+          previous
+        end
+
+        def start_workers
+          flush_output_streams
+          RailsIntegration.before_fork
+          Process.warmup if Process.respond_to?(:warmup)
+
+          @workers = []
+          1.upto(@worker_count) do |number|
+            worker = Worker.new(number).start(@configuration, @registry, @workers)
+            @workers << worker
+            dispatch(worker)
+          end
+        end
+
+        # Output buffered before forking would otherwise be written again by
+        # every worker when it exits.
+        def flush_output_streams
+          ObjectSpace.each_object(IO) do |io|
+            begin
+              io.flush unless io.closed?
+            rescue IOError, SystemCallError
+              nil
+            end
+          end
+        end
+
+        def dispatch(worker)
+          unit = (@quitting || @world.wants_to_quit) ? nil : @queue.shift
+
+          if unit
+            worker.current_unit = unit
+            @dispatched_units[unit] = true
+            worker.send_command(:run, unit, *unit_location(@units[unit]))
+          else
+            worker.send_command(:shutdown)
+          end
+        end
+
+        def unit_location(unit)
+          [
+            @registry.group_index(unit.group),
+            unit.examples_only,
+            unit.split_ancestors.map { |group| @registry.group_index(group) },
+            unit.examples&.map { |example| @registry.example_index(example) }
+          ]
+        end
+
+        def process_events
+          stop_dispatching if @world.wants_to_quit && !@quitting
+
+          alive = @workers.select(&:alive?)
+          ready, = IO.select(alive.map { |worker| worker.events.io }, nil, nil, SELECT_TIMEOUT)
+          ready ||= []
+
+          alive.each do |worker|
+            if ready.include?(worker.events.io)
+              batch = worker.events.read
+              batch ? batch.each { |message| handle(worker, message) if worker.alive? } : worker_exited(worker)
+            elsif worker.exited?
+              # Processes forked by the worker can keep its end of the pipe
+              # open after it exited.
+              worker_exited(worker)
+            end
+          end
+        end
+
+        def handle(worker, message)
+          case message.first
+          when :unit_done
+            _, unit, succeeded, run_time = message
+            worker.current_unit = nil
+            @results << succeeded
+            @run_times[@units[unit].split_ancestors.first || @units[unit].group] += run_time
+            unit_finished(unit)
+            dispatch(worker)
+          when :exit
+            @exit_status ||= message[2]
+            stop_dispatching
+          when :bye
+            worker.close
+          else
+            track(message)
+            count_failure(message)
+            route(message)
+          end
+        end
+
+        # Keeps track of what each unit is running, to clean up after a crash.
+        def track(message)
+          kind, unit, event, index = message
+          return unless unit
+
+          if kind == :group
+            event == :example_group_started ? @open_groups_by_unit[unit] << index : @open_groups_by_unit[unit].pop
+          elsif kind == :example
+            event == :example_started ? @running_examples[unit] = index : @running_examples.delete(unit)
+          end
+        end
+
+        def worker_exited(worker)
+          worker.close
+          unit = worker.current_unit
+          return unless unit
+
+          worker.current_unit = nil
+          @results << false
+          report_crash(worker, unit)
+          unit_finished(unit)
+          stop_dispatching if @exit_status
+        end
+
+        # Fails the example that was running, or reports an error outside of
+        # examples, and closes the groups the unit left open.
+        def report_crash(worker, unit)
+          error = ExceptionSerializer.dump(worker_crash_error(worker, unit))
+
+          if (example = @running_examples.delete(unit))
+            route([:example, unit, :example_finished, example, [nil, :failed, error, nil, 0.0, nil, nil, nil, nil]])
+            route([:example, unit, :example_failed, example, nil])
+            @failure_count += 1
+          else
+            route([:non_example_exception, unit, error, "An error occurred in parallel worker #{worker.number}."])
+          end
+
+          (@open_groups_by_unit.delete(unit) || []).reverse_each do |group|
+            route([:group, unit, :example_group_finished, group])
+          end
+        end
+
+        def worker_crash_error(worker, unit)
+          group = @units[unit].group
+          RuntimeError.new(
+            "Parallel worker #{worker.number} (pid #{worker.pid}) exited unexpectedly while running " \
+            "`#{group.metadata[:full_description]}` (#{group.location})."
+          )
+        end
+
+        def count_failure(message)
+          return unless message[0] == :example && message[2] == :example_failed
+
+          @failure_count += 1
+          stop_dispatching if fail_fast_limit_met?
+        end
+
+        def fail_fast_limit_met?
+          fail_fast = @configuration.fail_fast
+          return false unless fail_fast
+
+          @failure_count >= (fail_fast == true ? 1 : fail_fast)
+        end
+
+        def stop_dispatching
+          @quitting = true
+          @workers.each do |worker|
+            next if worker.quit_sent || !worker.alive? || !worker.current_unit
+
+            worker.quit_sent = true
+            worker.send_command(:quit)
+          end
+        end
+
+        def route(message)
+          unit = message[1]
+
+          if unit.nil?
+            @live_unit || @open_groups.any? ? @orphan_events << message : apply(message)
+          else
+            make_live(unit) if @live_unit.nil? && replayable_now?(unit)
+            unit == @live_unit ? apply(message) : (@buffers[unit] ||= []) << message
+          end
+        end
+
+        def replayable_now?(unit)
+          (@open_groups.empty? || @units[unit].split_ancestors.include?(@open_groups.last)) && next_of_family?(unit)
+        end
+
+        # The units of a split group are replayed in their order, as they
+        # would run sequentially.
+        def next_of_family?(unit)
+          previous = @previous_in_family[unit]
+          previous.nil? || @replayed_units[previous]
+        end
+
+        def started?(unit)
+          @finished_units[unit] || @buffers.key?(unit)
+        end
+
+        def unit_finished(unit)
+          @finished_units[unit] = true
+          return unless unit == @live_unit
+
+          @replayed_units[unit] = true
+          @live_unit = nil
+          replay_next_units
+        end
+
+        # Replays buffered units until reaching one that is still running.
+        # Units of the innermost open split group come first, so that the
+        # group is replayed as a whole before it is closed.
+        def replay_next_units
+          while @live_unit.nil?
+            replay_orphan_events if @open_groups.empty?
+            unit = @open_groups.empty? ? next_top_level_unit : unreplayed_units_in(@open_groups.last).first
+
+            if unit.nil?
+              break if @open_groups.empty?
+
+              close_group
+              next
+            end
+            break unless started?(unit)
+
+            make_live(unit)
+            next unless @finished_units[unit]
+
+            @replayed_units[unit] = true
+            @live_unit = nil
+          end
+        end
+
+        def next_top_level_unit
+          candidates = unreplayed_units.select { |unit| next_of_family?(unit) }
+          candidates.find { |unit| @finished_units[unit] } || candidates.first
+        end
+
+        def replay_orphan_events
+          @orphan_events.shift(@orphan_events.size).each { |message| apply(message) }
+        end
+
+        def unreplayed_units
+          @buffers.keys.reject { |unit| @replayed_units[unit] } +
+            @finished_units.keys.reject { |unit| @replayed_units[unit] || @buffers.key?(unit) }
+        end
+
+        def unreplayed_units_in(group)
+          units = @units.each_index.select do |unit|
+            !@replayed_units[unit] && @units[unit].split_ancestors.include?(group)
+          end
+          units.sort_by { |unit| @units[unit].sequence }
+        end
+
+        def make_live(unit)
+          ancestors = @units[unit].split_ancestors
+          close_group until ancestors[0, @open_groups.size] == @open_groups
+          ancestors.drop(@open_groups.size).each do |group|
+            @open_groups << group
+            @reporter.example_group_started(group)
+          end
+
+          @live_unit = unit
+          (@buffers.delete(unit) || []).each { |message| apply(message) }
+        end
+
+        def close_group
+          @reporter.example_group_finished(@open_groups.pop)
+        end
+
+        def finish
+          # Units never dispatched (after `--fail-fast` or an interrupt) have
+          # nothing to replay; replay whatever the others sent.
+          @units.each_index do |unit|
+            next @finished_units[unit] = true if @dispatched_units[unit]
+
+            @replayed_units[unit] = true
+            @results << false
+          end
+          @live_unit = nil
+          replay_next_units
+          close_group until @open_groups.empty?
+          replay_orphan_events
+
+          @run_times.each { |group, run_time| @reporter.record_group_run_time(group, run_time) }
+          @workers.each(&:wait)
+        end
+
+        def terminate_workers
+          (@workers || []).each do |worker|
+            next unless worker.alive?
+
+            worker.close
+            begin
+              Process.kill(:TERM, worker.pid)
+            rescue SystemCallError
+              nil
+            end
+            worker.wait
+          end
+        end
+
+        def apply(message)
+          case message.first
+          when :example
+            _, _, event, index, payload = message
+            example = @registry.examples[index]
+            restore(example, payload) if payload
+            @reporter.__send__(event, example)
+          when :group
+            _, _, event, index = message
+            @reporter.__send__(event, @registry.groups[index])
+          when :message
+            @reporter.message(message[2])
+          when :notify
+            _, _, event, notification = message
+            notification = WorkerReporter.unpack(notification, nil)
+            @reporter.notify(event, notification) if notification
+          when :publish
+            _, _, event, options = message
+            @reporter.publish(event, options.transform_values { |value| WorkerReporter.unpack(value) })
+          when :non_example_exception
+            _, _, exception, description = message
+            @reporter.notify_non_example_exception(ExceptionSerializer.load(exception), description)
+          end
+        end
+
+        def time_at(nanoseconds)
+          ::Time.at(nanoseconds / 1_000_000_000, nanoseconds % 1_000_000_000, :nsec)
+        end
+
+        # Hashes and arrays are updated in place, so that the metadata of groups
+        # sharing them with their examples sees the changes, as in the worker.
+        # Hashes are merged, to collect the changes of the parts of a group
+        # which ran in different workers.
+        def restore_metadata(metadata, key, value)
+          current = metadata[key]
+          if current.frozen? || current.class != value.class || !(Hash === value || Array === value)
+            metadata[key] = value
+          elsif Hash === value
+            merge_in_place(current, value)
+          else
+            current.replace(value)
+          end
+        end
+
+        def merge_in_place(target, source)
+          source.each do |key, value|
+            nested = Hash === target[key] && Hash === value && !target[key].frozen?
+            nested ? merge_in_place(target[key], value) : target[key] = value
+          end
+        end
+
+        def restore(example, payload)
+          started_at, status, exception, finished_at, run_time,
+            pending_message, pending_exception, pending_fixed, metadata = payload
+
+          result = example.execution_result
+          result.started_at = time_at(started_at) if started_at
+          return if payload.size == 1
+
+          (metadata || {}).each { |key, value| restore_metadata(example.metadata, key, WorkerReporter.unpack(value)) }
+          result.status = status
+          result.exception = ExceptionSerializer.load(exception)
+          result.finished_at = finished_at && time_at(finished_at)
+          result.run_time = run_time
+          result.pending_message = pending_message
+          result.pending_exception = ExceptionSerializer.load(pending_exception)
+          result.pending_fixed = pending_fixed
+          example.restore_exception(result.exception)
+        end
+      end
+    end
+  end
+end