rspec-conductor 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 17242ccb102c17f1a469bf4e105d62f2469372059d9416bcf4ab87df4f698143
+  data.tar.gz: ab29ad25bded7e52af8b762c532f2d30d9c5451a954abfcd3330430840dda107
+SHA512:
+  metadata.gz: 7d7aa04766f0b086c747c2c7046e6dc3050c6376389c05b68db1a83a99570c65e5d0e993df8bcd4b2379acb68d6047f4ec15dfba01423714eda39f8a1cb4da89
+  data.tar.gz: c801bac92877545bef4083eb0875efb291e58ad1af80961f7ece72fee86e2abbf3f3916c43d823eaeaefb81f605254d22e96a1ae8eddda046e6fd846fe1237de

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [1.0.0] - 2025-12-21
+
+- Initial release

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake"
+if ENV["RSPEC_VERSION"].to_s.empty?
+  gem "rspec", ">= 3.8.0"
+else
+  gem "rspec", "~> #{ENV["RSPEC_VERSION"]}"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Mark Abramov
+
+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,58 @@
+# rspec-conductor
+
+There is a common issue when running parallel spec runners with parallel-tests: since you have to decide on the list of spec files for each runner before the run starts, you don't have good control over how well the load is distributed. What ends up happening is one runner finishes after 3 minutes, another after 7 minutes, not utilizing the CPU effectively.
+
+rspec-conductor uses a different approach, it spawns a bunch of workers, then gives each of them one spec file to run. As soon as a worker finishes, it gives them another spec file, etc.
+
+User experience was designed to serve as a simple, almost drop-in, replacement for the parallel_tests gem.
+
+## Demo
+
+2x sped-up recording of what it looks like in a real project.
+
+![rspec-conductor demo](https://github.com/user-attachments/assets/2b598635-3192-4aa0-bb39-2af01b93bb4a)
+
+## Usage
+
+Set up the databases:
+
+```
+rails 'parallel:drop[10]' 'parallel:setup[10]'
+
+# if you like the first-is-1 mode, keeping your parallel test envs separate from your regular env:
+PARALLEL_TEST_FIRST_IS_1=true rails 'parallel:drop[16]' 'parallel:setup[16]'
+```
+
+Then launch the CLI app (see also `bin/rspec-conductor --help`):
+
+```
+rspec-conductor <OPTIONS> -- <RSPEC_OPTIONS> <SPEC_PATHS>
+rspec-conductor --workers 10 -- --tag '~@flaky' spec_ether/system/
+rspec-conductor --workers 10 spec_ether/system/ # shorthand when there are no spec options is also supported
+```
+
+`--verbose` flag is especially useful for troubleshooting.
+
+## Mechanics
+
+Server process preloads the `rails_helper`, prepares a list of files to work, then spawns the workers, each with `ENV['TEST_ENV_NUMBER'] = <worker_number>` (same as parallel-tests). The two communicate over a standard unix socket. Message format is basically a tuple of `(size, json_payload)`. It should also be possible to run this process over the network, but I haven't found a solid usecase for this.
+
+## Development notes
+
+* In order to make the CLI executable load and run fast, do not add any dependencies. That includes `active_support`.
+
+## FAQ
+
+* Why not preload the whole rails environment before spawning the workers instead of just `rails_helper`?
+
+Short answer: it's unsafe. Any file descriptors, such as db connections, redis connections and even libcurl environment (which we use for elasticsearch), are shared between all the child processes, leading to hard to debug bugs.
+
+* Why not use any of the existing libraries? (see Prior Art section)
+
+`test-queue` forks after loading the whole environment rather than just the `rails_helper` (see above). `ci-queue` is deprecated for rspec. `rspecq` I couldn't get working and also I didn't like the design.
+
+## Prior Art
+
+* [test-queue](https://github.com/tmm1/test-queue)
+* [rspecq](https://github.com/skroutz/rspecq/)
+* [ci-queue](https://github.com/Shopify/ci-queue/)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :conductor do
+  sh "exe/rspec-conductor", "-w", "4", "spec/"
+end
+
+task default: [:spec, :conductor]

data/exe/rspec-conductor

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/rspec/conductor"
+
+ENV["RAILS_ENV"] = "test"
+ENV["RACK_ENV"] = "test"
+
+RSpec::Conductor::CLI.run(ARGV)

data/lib/rspec/conductor/cli.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module RSpec
+  module Conductor
+    class CLI
+      DEFAULTS = {
+        workers: 4,
+        offset: 0,
+        first_is_1: false,
+        seed: nil,
+        fail_fast_after: nil,
+        verbose: false,
+        display_retry_backtraces: false,
+      }.freeze
+
+      def self.run(argv)
+        new(argv).run
+      end
+
+      def initialize(argv)
+        @argv = argv
+        @conductor_options = DEFAULTS.dup
+        @rspec_args = []
+      end
+
+      def run
+        parse_arguments
+        start_server
+      end
+
+      private
+
+      def parse_arguments
+        separator_index = @argv.index("--")
+
+        if separator_index
+          conductor_args = @argv[0...separator_index]
+          @rspec_args = @argv[(separator_index + 1)..]
+        else
+          conductor_args = @argv
+          @rspec_args = []
+        end
+
+        parse_conductor_options(conductor_args)
+        @rspec_args.prepend(*conductor_args) # can use spec paths as positional arguments before -- for convenience
+        apply_rspec_defaults
+      end
+
+      def parse_conductor_options(args)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: rspec-conductor [options] -- [rspec options]"
+
+          opts.on("-w", "--workers NUM", Integer, "Number of workers (default: #{DEFAULTS[:workers]})") do |n|
+            @conductor_options[:workers] = n
+          end
+
+          opts.on("-o", "--offset NUM", Integer, "Worker number offset, if you need to run multiple conductors in parallel (default: 0)") do |n|
+            @conductor_options[:offset] = n
+          end
+
+          opts.on("--first-is-1", 'ENV["TEST_ENV_NUMBER"] for the worker 1 is "1" rather than ""') do
+            @conductor_options[:first_is_1] = true
+          end
+
+          opts.on("-s", "--seed NUM", Integer, "Randomization seed") do |n|
+            @conductor_options[:seed] = n
+          end
+
+          opts.on("--fail-fast-after NUM", Integer, "Fail the run after a certain number of failed specs") do |n|
+            @conductor_options[:fail_fast_after] = n
+          end
+
+          opts.on("--formatter FORMATTER", ["plain", "ci", "fancy"], "Use a certain formatter") do |f|
+            @conductor_options[:formatter] = f
+          end
+
+          opts.on("--display-retry-backtraces", "Display retried exception backtraces") do
+            @conductor_options[:display_retry_backtraces] = true
+          end
+
+          opts.on("--verbose", "Enable debug output") do
+            @conductor_options[:verbose] = true
+          end
+
+          opts.on("-h", "--help", "Show this help") do
+            puts opts
+            Kernel.exit
+          end
+        end.parse!(args)
+      end
+
+      def apply_rspec_defaults
+        has_paths = @rspec_args.any? { |arg| !arg.start_with?("-") }
+        @rspec_args << File.join(Conductor.root, "spec/") unless has_paths
+      end
+
+      def start_server
+        require_relative "server"
+
+        Server.new(
+          worker_count: @conductor_options[:workers],
+          worker_number_offset: @conductor_options[:offset],
+          first_is_1: @conductor_options[:first_is_1],
+          seed: @conductor_options[:seed],
+          fail_fast_after: @conductor_options[:fail_fast_after],
+          rspec_args: @rspec_args,
+          formatter: @conductor_options[:formatter],
+          display_retry_backtraces: @conductor_options[:display_retry_backtraces],
+          verbose: @conductor_options[:verbose],
+        ).run
+      end
+    end
+  end
+end

data/lib/rspec/conductor/formatters/ci.rb

@@ -0,0 +1,47 @@
+module RSpec
+  module Conductor
+    module Formatters
+      class CI
+        def initialize(frequency: 10)
+          @frequency = frequency
+          @last_printout = Time.now
+        end
+
+        def handle_worker_message(_worker, message, results)
+          public_send(message[:type], message) if respond_to?(message[:type])
+          print_status(results) if @last_printout + @frequency < Time.now
+        end
+
+        def print_status(results)
+          @last_printout = Time.now
+          pct_done = results[:spec_files_total].positive? ? results[:spec_files_processed].to_f / results[:spec_files_total] : 0
+
+          puts "-" * tty_width
+          puts "Current status [#{Time.now.strftime("%H:%M:%S")}]:"
+          puts "Processed: #{results[:spec_files_processed]} / #{results[:spec_files_total]} (#{(pct_done * 100).floor}%)"
+          puts "#{results[:passed]} passed, #{results[:failed]} failed, #{results[:pending]} pending"
+          if results[:errors].any?
+            puts "Failures:\n"
+            results[:errors].each_with_index do |error, i|
+              puts "  #{i + 1}) #{error[:description]}"
+              puts "     #{error[:location]}"
+              puts "     #{error[:message]}" if error[:message]
+              if error[:backtrace]&.any?
+                puts "     Backtrace:"
+                error[:backtrace].each { |line| puts "       #{line}" }
+              end
+              puts
+            end
+          end
+          puts "-" * tty_width
+        end
+
+        private
+
+        def tty_width
+          $stdout.tty? ? $stdout.winsize[1] : 80
+        end
+      end
+    end
+  end
+end

data/lib/rspec/conductor/formatters/fancy.rb

@@ -0,0 +1,190 @@
+require "pathname"
+
+module RSpec
+  module Conductor
+    module Formatters
+      class Fancy
+        RED = 31
+        GREEN = 32
+        YELLOW = 33
+        MAGENTA = 35
+        CYAN = 36
+        NORMAL = 0
+
+        def self.recommended?
+          $stdout.tty? && $stdout.winsize[0] >= 30 && $stdout.winsize[1] >= 80
+        end
+
+        def initialize
+          @workers = Hash.new { |h, k| h[k] = {} }
+          @last_rendered_lines = []
+          @dots = []
+          @last_error = nil
+        end
+
+        def handle_worker_message(worker, message, results)
+          @workers[worker[:number]] = worker
+          public_send(message[:type], worker, message) if respond_to?(message[:type])
+          redraw(results)
+        end
+
+        def example_passed(_worker, _message)
+          @dots << { char: ".", color: GREEN }
+        end
+
+        def example_failed(_worker, message)
+          @dots << { char: "F", color: RED }
+          @last_error = message.slice(:description, :location, :exception_class, :message, :backtrace)
+        end
+
+        def example_retried(_worker, _message)
+          @dots << { char: "R", color: MAGENTA }
+        end
+
+        def example_pending(_worker, _message)
+          @dots << { char: "*", color: YELLOW }
+        end
+
+        private
+
+        def redraw(results)
+          cursor_up(rewrap_lines(@last_rendered_lines).length)
+
+          lines = []
+          lines << progress_bar(results)
+          lines << ""
+          lines.concat(worker_lines)
+          lines << ""
+          lines << @dots.map { |dot| colorize(dot[:char], dot[:color]) }.join
+          lines << ""
+          lines.concat(error_lines) if @last_error
+          lines = rewrap_lines(lines)
+
+          lines.each_with_index do |line, i|
+            if @last_rendered_lines[i] == line
+              cursor_down(1)
+            else
+              clear_line
+              puts line
+            end
+          end
+
+          if @last_rendered_lines.length && lines.length < @last_rendered_lines.length
+            (@last_rendered_lines.length - lines.length).times do
+              clear_line
+              puts
+            end
+            cursor_up(@last_rendered_lines.length - lines.length)
+          end
+
+          @last_rendered_lines = lines
+        end
+
+        def worker_lines
+          return [] unless max_worker_num.positive?
+
+          (1..max_worker_num).map do |num|
+            worker = @workers[num]
+            prefix = colorize("Worker #{num}: ", CYAN)
+
+            if worker[:status] == :shut_down
+              prefix + "(finished)"
+            elsif worker[:status] == :terminated
+              prefix + colorize("(terminated)", RED)
+            elsif worker[:current_spec]
+              prefix + truncate(relative_path(worker[:current_spec]), tty_width - 15)
+            else
+              prefix + "(idle)"
+            end
+          end
+        end
+
+        def error_lines
+          return [] unless @last_error
+
+          lines = []
+          lines << colorize("Most recent failure:", RED)
+          lines << "  #{@last_error[:description]}"
+          lines << "  #{@last_error[:location]}"
+
+          if @last_error[:exception_class] || @last_error[:message]
+            err_msg = [@last_error[:exception_class], @last_error[:message]].compact.join(": ")
+            lines << "  #{err_msg}"
+          end
+
+          if @last_error[:backtrace]&.any?
+            lines << "  Backtrace:"
+            @last_error[:backtrace].first(10).each { |l| lines << "    #{l}" }
+          end
+
+          lines
+        end
+
+        def rewrap_lines(lines)
+          lines.flat_map do |line|
+            _, indent, body = line.partition(/^\s*/)
+            max_width = tty_width - indent.size
+            split_chars_respecting_ansi(body).each_slice(max_width).map { |chars| "#{indent}#{chars.join}" }
+          end
+        end
+
+        # sticks invisible characters to visible ones when splitting (so that an ansi color code doesn"t get split mid-way)
+        def split_chars_respecting_ansi(body)
+          invisible = "(?:\\e\\[[\\d;]*m)"
+          visible = "(?:[^\\e])"
+          scan_regex = Regexp.new("#{invisible}*#{visible}#{invisible}*|#{invisible}+")
+          body.scan(scan_regex)
+        end
+
+        def progress_bar(results)
+          total = results[:spec_files_total]
+          processed = results[:spec_files_processed]
+          pct = total.positive? ? processed.to_f / total : 0
+          bar_width = [tty_width - 60, 20].max
+
+          filled = (pct * bar_width).floor
+          empty = bar_width - filled
+
+          bar = colorize("[", NORMAL) + colorize("▓" * filled, GREEN) + colorize(" " * empty, NORMAL) + colorize("]", NORMAL)
+          percentage = " #{(pct * 100).floor.to_s.rjust(3)}% (#{processed}/#{total})"
+
+          bar + percentage
+        end
+
+        def max_worker_num
+          @workers.keys.max || 0
+        end
+
+        def relative_path(filename)
+          Pathname(filename).relative_path_from(Conductor.root).to_s
+        end
+
+        def truncate(str, max_length)
+          return "" unless str
+
+          str.length > max_length ? "...#{str[-(max_length - 3)..]}" : str
+        end
+
+        def colorize(string, color)
+          $stdout.tty? ? "\e[#{color}m#{string}\e[#{NORMAL}m" : string
+        end
+
+        def cursor_up(n_lines)
+          print("\e[#{n_lines}A") if $stdout.tty? && n_lines.positive?
+        end
+
+        def cursor_down(n_lines)
+          print("\e[#{n_lines}B") if $stdout.tty? && n_lines.positive?
+        end
+
+        def clear_line
+          print("\e[2K\r") if $stdout.tty?
+        end
+
+        def tty_width
+          $stdout.tty? ? $stdout.winsize[1] : 80
+        end
+      end
+    end
+  end
+end

data/lib/rspec/conductor/formatters/plain.rb

@@ -0,0 +1,44 @@
+module RSpec
+  module Conductor
+    module Formatters
+      class Plain
+        # TTY standard colors
+        RED = 31
+        GREEN = 32
+        YELLOW = 33
+        MAGENTA = 35
+        NORMAL = 0
+
+        def handle_worker_message(_worker, message, _results)
+          public_send(message[:type], message) if respond_to?(message[:type])
+        end
+
+        def example_passed(_message)
+          print ".", GREEN
+        end
+
+        def example_failed(_message)
+          print "F", RED
+        end
+
+        def example_retried(_message)
+          print "R", MAGENTA
+        end
+
+        def example_pending(_message)
+          print "*", YELLOW
+        end
+
+        private
+
+        def print(string, color)
+          if $stdout.tty?
+            $stdout.print("\e[#{color}m#{string}\e[#{NORMAL}m")
+          else
+            $stdout.print(string)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/conductor/protocol.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RSpec
+  module Conductor
+    module Protocol
+      class Socket
+        attr_reader :io
+
+        def initialize(io)
+          @io = io
+        end
+
+        def send_message(message)
+          json = JSON.generate(message)
+          length = [json.bytesize].pack("N")
+          io.write(length)
+          io.write(json.b)
+          io.flush
+        rescue Errno::EPIPE, IOError
+          nil
+        end
+
+        def receive_message
+          length_bytes = io.read(4)
+          return nil unless length_bytes&.bytesize == 4
+
+          length = length_bytes.unpack1("N")
+          json = io.read(length)
+          return nil unless json&.bytesize == length
+
+          JSON.parse(json, symbolize_names: true)
+        rescue Errno::ECONNRESET, IOError, JSON::ParserError
+          nil
+        end
+
+        def close
+          io.close unless io.closed?
+        end
+      end
+    end
+  end
+end

data/lib/rspec/conductor/server.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "English"
+require "socket"
+require "json"
+require "io/console"
+
+module RSpec
+  module Conductor
+    class Server
+      # @option worker_count [Integer] How many workers to spin
+      # @option rspec_args [Array<String>] A list of rspec options
+      # @option worker_number_offset [Integer] Start worker numbering with an offset
+      # @option first_is_1 [Boolean] TEST_ENV_NUMBER for the first worker is "1" instead of ""
+      # @option seed [Integer] Set a predefined starting seed
+      # @option fail_fast_after [Integer, NilClass] Shut down the workers after a certain number of failures
+      # @option formatter [String] Use a certain formatter
+      # @option verbose [Boolean] Use especially verbose output
+      # @option display_retry_backtraces [Boolean] Display backtraces for specs retried via rspec-retry
+      def initialize(worker_count:, rspec_args:, **opts)
+        @worker_count = worker_count
+        @worker_number_offset = opts.fetch(:worker_number_offset, 0)
+        @first_is_one = opts.fetch(:first_is_1, false)
+        @seed = opts[:seed] || (Random.new_seed % 65_536)
+        @fail_fast_after = opts[:fail_fast_after]
+        @display_retry_backtraces = opts.fetch(:display_retry_backtraces, false)
+        @verbose = opts.fetch(:verbose, false)
+
+        @rspec_args = rspec_args
+        @workers = {}
+        @spec_queue = []
+        @started_at = Time.now
+        @shutting_down = false
+        @formatter = case opts[:formatter]
+                     when "ci"
+                       Formatters::CI.new
+                     when "fancy"
+                       Formatters::Fancy.new
+                     when "plain"
+                       Formatters::Plain.new
+                     else
+                       Formatters::Fancy.recommended? ? Formatters::Fancy.new : Formatters::Plain.new
+                     end
+        @results = { passed: 0, failed: 0, pending: 0, errors: [], worker_crashes: 0, started_at: @started_at, spec_files_total: 0, spec_files_processed: 0 }
+      end
+
+      def run
+        setup_signal_handlers
+        build_spec_queue
+        preload_application
+
+        $stdout.sync = true
+        puts "RSpec Conductor starting with #{@worker_count} workers (seed: #{@seed})"
+        puts "Running #{@spec_queue.size} spec files\n\n"
+
+        start_workers
+        run_event_loop
+
+        print_summary
+        exit_with_status
+      end
+
+      private
+
+      def preload_application
+        application = File.expand_path("config/application", Conductor.root)
+
+        if File.exist?(application)
+          debug "Preloading config/application.rb..."
+          require File.expand_path("config/application", Conductor.root)
+        end
+
+        debug "Application preloaded, autoload paths configured"
+      end
+
+      def setup_signal_handlers
+        %w[INT TERM].each do |signal|
+          Signal.trap(signal) do
+            @workers.any? ? initiate_shutdown : Kernel.exit(1)
+          end
+        end
+      end
+
+      def initiate_shutdown
+        return if @shutting_down
+
+        @shutting_down = true
+
+        puts "Shutting down..."
+        @workers.each_value { |w| w[:socket]&.send_message({ type: :shutdown }) }
+      end
+
+      def build_spec_queue
+        paths = extract_paths_from_args
+
+        config = RSpec::Core::Configuration.new
+        config.files_or_directories_to_run = paths
+
+        @spec_queue = config.files_to_run.shuffle(random: Random.new(@seed))
+        @results[:spec_files_total] = @spec_queue.size
+      end
+
+      def parsed_rspec_args
+        @parsed_rspec_args ||= RSpec::Core::ConfigurationOptions.new(@rspec_args)
+      end
+
+      def extract_paths_from_args
+        files = parsed_rspec_args.options[:files_or_directories_to_run] || []
+        files.empty? ? [File.join(Conductor.root, "spec/")] : files
+      end
+
+      def start_workers
+        @worker_count.times do |i|
+          spawn_worker(@worker_number_offset + i + 1)
+        end
+      end
+
+      def spawn_worker(worker_number)
+        parent_socket, child_socket = Socket.pair(:UNIX, :STREAM, 0)
+
+        debug "Spawning worker #{worker_number}"
+
+        pid = fork do
+          parent_socket.close
+
+          ENV["TEST_ENV_NUMBER"] = if @first_is_one || worker_number != 1
+                                     worker_number.to_s
+                                   else
+                                     ""
+                                   end
+
+          Worker.new(
+            worker_number: worker_number,
+            socket: Protocol::Socket.new(child_socket),
+            rspec_args: @rspec_args,
+            verbose: @verbose
+          ).run
+        end
+
+        child_socket.close
+        debug "Worker #{worker_number} started with pid #{pid}"
+
+        @workers[pid] = {
+          pid: pid,
+          number: worker_number,
+          status: :running,
+          socket: Protocol::Socket.new(parent_socket),
+          current_spec: nil,
+        }
+        assign_work(@workers[pid])
+      end
+
+      def run_event_loop
+        until @workers.empty?
+          workers_by_io = @workers.values.to_h { |w| [w[:socket].io, w] }
+          readable_ios, = IO.select(workers_by_io.keys, nil, nil, 0.01)
+
+          readable_ios&.each do |io|
+            worker = workers_by_io.fetch(io)
+            handle_worker_message(worker)
+          end
+
+          reap_workers
+        end
+      end
+
+      def handle_worker_message(worker)
+        message = worker[:socket].receive_message
+        return unless message
+
+        debug "Worker #{worker[:number]}: #{message[:type]}"
+
+        case message[:type].to_sym
+        when :example_passed
+          @results[:passed] += 1
+        when :example_failed
+          @results[:failed] += 1
+          @results[:errors] << message
+
+          if @fail_fast_after && @results[:failed] >= @fail_fast_after && !@shutting_down
+            debug "Shutting after #{@results[:failed]} failures"
+            initiate_shutdown
+          end
+        when :example_pending
+          @results[:pending] += 1
+        when :example_retried
+          if @display_retry_backtraces
+            puts "\nExample #{message[:description]} retried:\n  #{message[:location]}\n  #{message[:exception_class]}: #{message[:message]}\n#{message[:backtrace].map { "    #{_1}" }.join("\n")}\n"
+          end
+        when :spec_complete
+          @results[:spec_files_processed] += 1
+          worker[:current_spec] = nil
+          assign_work(worker)
+        when :spec_error
+          @results[:errors] << message
+          debug "Spec error details: #{message[:error]}"
+          worker[:current_spec] = nil
+          assign_work(worker)
+        when :spec_interrupted
+          debug "Spec interrupted: #{message[:file]}"
+          worker[:current_spec] = nil
+        end
+        @formatter.handle_worker_message(worker, message, @results)
+      end
+
+      def assign_work(worker)
+        if @spec_queue.empty? || @shutting_down
+          debug "No more work for worker #{worker[:number]}, sending shutdown"
+          worker[:socket].send_message({ type: :shutdown })
+          cleanup_worker(worker)
+        else
+          @specs_started_at ||= Time.now
+          spec_file = @spec_queue.shift
+          worker[:current_spec] = spec_file
+          debug "Assigning #{spec_file} to worker #{worker[:number]}"
+          message = { type: :worker_assigned_spec, file: spec_file }
+          worker[:socket].send_message(message)
+          @formatter.handle_worker_message(worker, message, @results)
+        end
+      end
+
+      def cleanup_worker(worker, status: :shut_down)
+        @workers.delete(worker[:pid])
+        worker[:socket].close
+        worker[:status] = status
+        @formatter.handle_worker_message(worker, { type: :worker_shut_down }, @results)
+        Process.wait(worker[:pid])
+      rescue Errno::ECHILD
+        nil
+      end
+
+      def reap_workers
+        dead_workers = @workers.each_with_object([]) do |(pid, worker), memo|
+          result = Process.waitpid(pid, Process::WNOHANG)
+          memo << [worker, $CHILD_STATUS] if result
+        end
+
+        dead_workers.each do |worker, exitstatus|
+          cleanup_worker(worker, status: :terminated)
+          debug "Worker #{worker[:number]} exited with status #{exitstatus.exitstatus}, signal #{exitstatus.termsig}"
+        end
+      rescue Errno::ECHILD
+        nil
+      end
+
+      def print_summary
+        puts "\n\n"
+        puts "=" * ($stdout.tty? ? $stdout.winsize[1] : 80)
+        puts "Results: #{@results[:passed]} passed, #{@results[:failed]} failed, #{@results[:pending]} pending"
+
+        if @results[:errors].any?
+          puts "\nFailures:\n\n"
+          @results[:errors].each_with_index do |error, i|
+            puts "  #{i + 1}) #{error[:description]}"
+            puts "     #{error[:location]}"
+            puts "     #{error[:message]}" if error[:message]
+            if error[:backtrace]&.any?
+              puts "     Backtrace:"
+              error[:backtrace].each { |line| puts "       #{line}" }
+            end
+            puts
+          end
+        end
+
+        puts "Randomized with seed #{@seed}"
+        puts "Specs took: #{(Time.now - (@specs_started_at || @started_at)).to_f.round(2)}s"
+        puts "Total runtime: #{(Time.now - @started_at).to_f.round(2)}s"
+      end
+
+      def exit_with_status
+        success = @results[:failed].zero? && @results[:errors].empty? && @results[:worker_crashes].zero? && !@shutting_down
+        Kernel.exit(success ? 0 : 1)
+      end
+
+      def debug(message)
+        return unless @verbose
+
+        $stderr.puts "[conductor] #{message}"
+      end
+    end
+  end
+end

data/lib/rspec/conductor/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Conductor
+    VERSION = "1.0.0"
+  end
+end

data/lib/rspec/conductor/worker.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+# RSpec doesn't provide us with a good way to handle before/after suite hooks,
+# doing what we can here
+class RSpec::Core::Configuration
+  def __run_before_suite_hooks
+    RSpec.current_scope = :before_suite_hook if RSpec.respond_to?(:current_scope=)
+    run_suite_hooks("a `before(:suite)` hook", @before_suite_hooks) if respond_to?(:run_suite_hooks)
+  end
+
+  def __run_after_suite_hooks
+    RSpec.current_scope = :after_suite_hook if RSpec.respond_to?(:current_scope=)
+    run_suite_hooks("an `after(:suite)` hook", @after_suite_hooks) if respond_to?(:run_suite_hooks)
+  end
+end
+
+module RSpec
+  module Conductor
+    class Worker
+      def initialize(worker_number:, socket:, rspec_args: [], verbose: false)
+        @worker_number = worker_number
+        @socket = socket
+        @rspec_args = rspec_args
+        @verbose = verbose
+        @message_queue = []
+      end
+
+      def run
+        suppress_output unless @verbose
+        debug "Worker #{@worker_number} starting"
+        setup_load_path
+        initialize_rspec
+
+        loop do
+          debug "Waiting for message"
+          message = @message_queue.shift || @socket.receive_message
+
+          unless message
+            debug "Received nil message, exiting"
+            break
+          end
+
+          debug "Received: #{message.inspect}"
+
+          case message[:type].to_sym
+          when :worker_assigned_spec
+            debug "Running spec: #{message[:file]}"
+            run_spec(message[:file])
+            debug "Finished spec: #{message[:file]}"
+            break if @shutdown_requested
+          when :shutdown
+            debug "Shutdown received"
+            @shutdown_requested = true
+            break
+          end
+        end
+
+        debug "Worker #{@worker_number} shutting down, running after(:suite) hooks and exiting"
+        RSpec.configuration.__run_after_suite_hooks
+      rescue StandardError => e
+        debug "Worker crashed: #{e.class}: #{e.message}"
+        debug e.backtrace.join("\n")
+        raise
+      ensure
+        @socket.close
+      end
+
+      private
+
+      def setup_load_path
+        parsed_options.configure(RSpec.configuration)
+        default_path = RSpec.configuration.default_path || "spec"
+
+        spec_path = File.expand_path("spec", Conductor.root)
+        default_full_path = File.expand_path(default_path, Conductor.root)
+
+        $LOAD_PATH.unshift(spec_path) if Dir.exist?(spec_path) && !$LOAD_PATH.include?(spec_path)
+
+        if default_full_path != spec_path && Dir.exist?(default_full_path)
+          $LOAD_PATH.unshift(default_full_path)
+        end
+
+        debug "Load path (spec dirs): #{$LOAD_PATH.grep(/spec/)}"
+      end
+
+      def suppress_output
+        $stdout.reopen(null_io_out)
+        $stderr.reopen(null_io_out)
+        $stdin.reopen(null_io_in)
+      end
+
+      def initialize_rspec
+        rails_helper = File.expand_path("rails_helper.rb", Conductor.root)
+        spec_helper = File.expand_path("spec_helper.rb", Conductor.root)
+        if File.exist?(rails_helper)
+          debug "Requiring rails_helper to boot Rails..."
+          require rails_helper
+        elsif File.exist?(spec_helper)
+          debug "Requiring spec_helper..."
+          require spec_helper
+        else
+          debug "Could detect neither rails_helper nor spec_helper"
+        end
+
+        debug "RSpec initialized, running before(:suite) hooks"
+        RSpec.configuration.__run_before_suite_hooks
+      end
+
+      def run_spec(file)
+        RSpec.world.reset
+        RSpec.configuration.reset_reporter
+        RSpec.configuration.files_or_directories_to_run = []
+        setup_formatter(ConductorFormatter.new(@socket, file, -> { check_for_shutdown }))
+
+        begin
+          debug "Loading spec file: #{file}"
+          debug "Exclusion filters: #{RSpec.configuration.exclusion_filter.description}"
+          debug "Inclusion filters: #{RSpec.configuration.inclusion_filter.description}"
+          load file
+          debug "Example groups after load: #{RSpec.world.example_groups.count}"
+
+          example_groups = RSpec.world.ordered_example_groups
+          debug "Example count: #{RSpec.world.example_count}"
+
+          RSpec.configuration.reporter.report(RSpec.world.example_count) do |reporter|
+            example_groups.each { |g| g.run(reporter) }
+          end
+
+          @socket.send_message(
+            type: :spec_complete,
+            file: file
+          )
+        rescue StandardError => e
+          debug "Spec error: #{e.class}: #{e.message}"
+          debug "Backtrace: #{e.backtrace.join("\n")}"
+          @socket.send_message(
+            type: :spec_error,
+            file: file,
+            error: e.message,
+            backtrace: e.backtrace
+          )
+        end
+      end
+
+      def check_for_shutdown
+        return unless @socket.io.wait_readable(0)
+
+        message = @socket.receive_message
+        return unless message
+
+        if message[:type].to_sym == :shutdown
+          debug "Shutdown received mid-spec"
+          @shutdown_requested = true
+          RSpec.world.wants_to_quit = true
+        else
+          debug "Non shutdown message: #{message}"
+          @message_queue << message
+        end
+      end
+
+      def parsed_options
+        @parsed_options ||= RSpec::Core::ConfigurationOptions.new(@rspec_args)
+      end
+
+      def setup_formatter(conductor_formatter)
+        RSpec.configuration.output_stream = null_io_out
+        RSpec.configuration.error_stream = null_io_out
+        RSpec.configuration.formatter_loader.formatters.clear
+        RSpec.configuration.add_formatter(conductor_formatter)
+      end
+
+      def debug(message)
+        $stderr.puts "[worker #{@worker_number}] #{message}"
+      end
+
+      def null_io_out
+        @null_io_out ||= File.open(File::NULL, "w")
+      end
+
+      def null_io_in
+        @null_io_in ||= File.open(File::NULL, "r")
+      end
+    end
+
+    class ConductorFormatter
+      RSpec::Core::Formatters.register self,
+        :example_passed,
+        :example_failed,
+        :example_pending
+
+      def initialize(socket, file, shutdown_check)
+        @socket = socket
+        @file = file
+        @shutdown_check = shutdown_check
+      end
+
+      def example_passed(notification)
+        @socket.send_message(
+          type: :example_passed,
+          file: @file,
+          description: notification.example.full_description,
+          location: notification.example.location,
+          run_time: notification.example.execution_result.run_time
+        )
+        @shutdown_check.call
+      end
+
+      def example_failed(notification)
+        ex = notification.example
+        @socket.send_message(
+          type: :example_failed,
+          file: @file,
+          description: ex.full_description,
+          location: ex.location,
+          run_time: ex.execution_result.run_time,
+          exception_class: ex.execution_result.exception&.class&.name,
+          message: ex.execution_result.exception&.message,
+          backtrace: format_backtrace(ex.execution_result.exception&.backtrace, ex.metadata)
+        )
+        @shutdown_check.call
+      end
+
+      def example_pending(notification)
+        ex = notification.example
+        @socket.send_message(
+          type: :example_pending,
+          file: @file,
+          description: ex.full_description,
+          location: ex.location,
+          pending_message: ex.execution_result.pending_message
+        )
+        @shutdown_check.call
+      end
+
+      def retry(ex)
+        @socket.send_message(
+          type: :example_retried,
+          description: ex.full_description,
+          location: ex.location,
+          exception_class: ex.exception&.class&.name,
+          message: ex.exception&.message,
+          backtrace: format_backtrace(ex.exception&.backtrace, ex.metadata)
+        )
+      end
+
+      private
+
+      def format_backtrace(backtrace, example_metadata = nil)
+        RSpec::Core::BacktraceFormatter.new.format_backtrace(backtrace || [], example_metadata || {})
+      end
+    end
+  end
+end

data/lib/rspec/conductor.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+
+require_relative "conductor/version"
+require_relative "conductor/protocol"
+require_relative "conductor/server"
+require_relative "conductor/worker"
+require_relative "conductor/cli"
+require_relative "conductor/formatters/plain"
+require_relative "conductor/formatters/ci"
+require_relative "conductor/formatters/fancy"
+
+module RSpec
+  module Conductor
+    def self.root
+      @root ||= Dir.pwd
+    end
+
+    def self.root=(root)
+      @root = root
+    end
+  end
+end

data/rspec-conductor.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/rspec/conductor/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rspec-conductor"
+  spec.version = RSpec::Conductor::VERSION
+  spec.authors = ["Mark Abramov"]
+  spec.email = ["me@markabramov.me"]
+
+  spec.summary = "Queue-based parallel test runner for rspec"
+  spec.description = "Queue-based parallel test runner for rspec"
+  spec.homepage = "https://github.com/markiz/rspec-conductor"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "https://github.com/markiz/rspec-conductor/blob/master/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|spec)/|\.(?:git|github))})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.add_dependency "rspec-core", ">= 3.8.0"
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: rspec-conductor
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mark Abramov
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-21 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.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.0
+description: Queue-based parallel test runner for rspec
+email:
+- me@markabramov.me
+executables:
+- rspec-conductor
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/rspec-conductor
+- lib/rspec/conductor.rb
+- lib/rspec/conductor/cli.rb
+- lib/rspec/conductor/formatters/ci.rb
+- lib/rspec/conductor/formatters/fancy.rb
+- lib/rspec/conductor/formatters/plain.rb
+- lib/rspec/conductor/protocol.rb
+- lib/rspec/conductor/server.rb
+- lib/rspec/conductor/version.rb
+- lib/rspec/conductor/worker.rb
+- rspec-conductor.gemspec
+homepage: https://github.com/markiz/rspec-conductor
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/markiz/rspec-conductor
+  source_code_uri: https://github.com/markiz/rspec-conductor
+  changelog_uri: https://github.com/markiz/rspec-conductor/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Queue-based parallel test runner for rspec
+test_files: []