rspec-conductor 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17242ccb102c17f1a469bf4e105d62f2469372059d9416bcf4ab87df4f698143
-  data.tar.gz: ab29ad25bded7e52af8b762c532f2d30d9c5451a954abfcd3330430840dda107
+  metadata.gz: 50d787ec617be586c7f66328850d62f2253bd5f1a50d1effb6417ccfdb4ee3a2
+  data.tar.gz: d71b0b92aa35eb18991ae91a2d3c95d532da79beb80e304e227da87dd214656a
 SHA512:
-  metadata.gz: 7d7aa04766f0b086c747c2c7046e6dc3050c6376389c05b68db1a83a99570c65e5d0e993df8bcd4b2379acb68d6047f4ec15dfba01423714eda39f8a1cb4da89
-  data.tar.gz: c801bac92877545bef4083eb0875efb291e58ad1af80961f7ece72fee86e2abbf3f3916c43d823eaeaefb81f605254d22e96a1ae8eddda046e6fd846fe1237de
+  metadata.gz: fe26f4f57787171577683b762e57ac8360b52d9949fbe1c6f4b6b8161da7747815e1b1296b1098ae05f9d32a605089847a0bb1c2f6f12f1273c50e7398118099
+  data.tar.gz: 6377b5235c007f274ad83778809319f7eee8e4cc484187202fb8919b8ef8e9ca7122e96e10b1948b6c9b7ca7db2e639bccc8d0e58c5781f17017cb40b119f1bd

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [1.0.2] - 2026-01-09
+- Fix --postfork-require options
+- Fix worker crashes counter
+
+## [1.0.1] - 2025-12-21
+
+- Fix spec_helper/rails_helper path finding [Thanks @diego-aslz]
+- Add --prefork-require and --no-prefork-require CLI options for non-rails apps or rails setups where loading config/application.rb is not entirely safe
+- Add --postfork-require and --no-postfork-require CLI options for flexibility
+
 ## [1.0.0] - 2025-12-21
 
 - Initial release

data/README.md

@@ -12,27 +12,36 @@ User experience was designed to serve as a simple, almost drop-in, replacement f
 
 ![rspec-conductor demo](https://github.com/user-attachments/assets/2b598635-3192-4aa0-bb39-2af01b93bb4a)
 
-## Usage
-
-Set up the databases:
+## Installation
 
-```
-rails 'parallel:drop[10]' 'parallel:setup[10]'
+Add to your Gemfile:
 
-# 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]'
+```ruby
+gem 'rspec-conductor'
 ```
 
-Then launch the CLI app (see also `bin/rspec-conductor --help`):
+## Usage
 
-```
+```bash
 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
+rspec-conductor --workers 10 -- --tag '~@flaky' spec
+# shorthand for setting the paths when there are no rspec options is also supported
+rspec-conductor --workers 10 spec
 ```
 
 `--verbose` flag is especially useful for troubleshooting.
 
+To set up the databases (if you are using this with rails) you can use a rake task from the parallel_tests gem
+
+```bash
+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[10]' 'parallel:setup[10]'
+```
+
+I might consider porting that rake task in the near future.
+
 ## 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.
@@ -41,6 +50,13 @@ Server process preloads the `rails_helper`, prepares a list of files to work, th
 
 * In order to make the CLI executable load and run fast, do not add any dependencies. That includes `active_support`.
 
+## Troubleshooting
+
+* `+[__NSCFConstantString initialize] may have been in progress in another thread when fork() was called.` on M-based Mac machines
+    * This is a common issue with ruby code, compiled libraries and forking. Set `OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` environment variable to work around this
+* Something gets loaded that shouldn't get loaded, or in a different order
+    * There are two simple ways to hook into preloads, exposed as CLI flags, `--prefork-require` (defaults to `config/application.rb`) and `--postfork-require` (defaults to either `rails_helper.rb` or `spec_helper.rb`, whichever is present on your machine). You can set any of those to whatever you need and control the load order
+
 ## FAQ
 
 * Why not preload the whole rails environment before spawning the workers instead of just `rails_helper`?

data/lib/rspec/conductor/ansi.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Conductor
+    module ANSI
+      module_function
+
+      COLOR_CODES = {
+        # Reset
+        reset: "0",
+
+        # Styles
+        bold: "1",
+        dim: "2",
+        italic: "3",
+        underline: "4",
+        blink: "5",
+        inverse: "7",
+        hidden: "8",
+        strikethrough: "9",
+
+        # Foreground colors
+        black: "30",
+        red: "31",
+        green: "32",
+        yellow: "33",
+        blue: "34",
+        magenta: "35",
+        cyan: "36",
+        white: "37",
+
+        # Bright foreground colors
+        bright_black: "90",
+        bright_red: "91",
+        bright_green: "92",
+        bright_yellow: "93",
+        bright_blue: "94",
+        bright_magenta: "95",
+        bright_cyan: "96",
+        bright_white: "97",
+
+        # Background colors
+        bg_black: "40",
+        bg_red: "41",
+        bg_green: "42",
+        bg_yellow: "43",
+        bg_blue: "44",
+        bg_magenta: "45",
+        bg_cyan: "46",
+        bg_white: "47",
+
+        # Bright background colors
+        bg_bright_black: "100",
+        bg_bright_red: "101",
+        bg_bright_green: "102",
+        bg_bright_yellow: "103",
+        bg_bright_blue: "104",
+        bg_bright_magenta: "105",
+        bg_bright_cyan: "106",
+        bg_bright_white: "107",
+      }.freeze
+
+      def colorize(string, colors, reset: true)
+        [
+          "\e[",
+          Array(colors).map { |color| color_code(color) }.join(";"),
+          "m",
+          string,
+          reset ? "\e[#{color_code(:reset)}m" : nil,
+        ].join
+      end
+
+      def color_code(color)
+        COLOR_CODES.fetch(color, COLOR_CODES[:reset])
+      end
+
+      def cursor_up(n_lines)
+        n_lines.positive? ? "\e[#{n_lines}A" : ""
+      end
+
+      def cursor_down(n_lines)
+        n_lines.positive? ? "\e[#{n_lines}B" : ""
+      end
+
+      def clear_line
+        "\e[2K\r"
+      end
+
+      # sticks invisible characters to visible ones when splitting (so that an ansi color code doesn"t get split mid-way)
+      def split_visible_char_groups(string)
+        invisible = "(?:\\e\\[[0-9;]*[a-zA-Z])"
+        visible = "(?:[^\\e])"
+        scan_regex = Regexp.new("#{invisible}*#{visible}#{invisible}*|#{invisible}+")
+        string.scan(scan_regex)
+      end
+
+      def visible_chars(string)
+        string.gsub(/\e\[[0-9;]*[a-zA-Z]/, '')
+      end
+
+      def tty_width
+        $stdout.tty? ? $stdout.winsize[1] : 80
+      end
+    end
+  end
+end

data/lib/rspec/conductor/cli.rb

@@ -13,6 +13,8 @@ module RSpec
         fail_fast_after: nil,
         verbose: false,
         display_retry_backtraces: false,
+        prefork_require: 'config/application.rb',
+        postfork_require: :spec_helper,
       }.freeze
 
       def self.run(argv)
@@ -60,6 +62,22 @@ module RSpec
             @conductor_options[:offset] = n
           end
 
+          opts.on("--prefork-require FILENAME", String, "Require this file before forking (default: config/application.rb)") do |f|
+            @conductor_options[:prefork_require] = f
+          end
+
+          opts.on("--no-prefork-require", "Do not preload config/application.rb") do
+            @conductor_options[:prefork_require] = nil
+          end
+
+          opts.on("--postfork-require FILENAME", String, "Require this file after forking (default: either rails_helper.rb or spec_helper.rb, whichever is present)") do |f|
+            @conductor_options[:postfork_require] = f
+          end
+
+          opts.on("--no-postfork-require", "Do not load anything post-fork") do
+            @conductor_options[:postfork_require] = nil
+          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
@@ -97,11 +115,11 @@ module RSpec
       end
 
       def start_server
-        require_relative "server"
-
         Server.new(
           worker_count: @conductor_options[:workers],
           worker_number_offset: @conductor_options[:offset],
+          prefork_require: @conductor_options[:prefork_require],
+          postfork_require: @conductor_options[:postfork_require],
           first_is_1: @conductor_options[:first_is_1],
           seed: @conductor_options[:seed],
           fail_fast_after: @conductor_options[:fail_fast_after],

data/lib/rspec/conductor/ext/rspec.rb

@@ -0,0 +1,13 @@
+# 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

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

@@ -2,27 +2,32 @@ module RSpec
   module Conductor
     module Formatters
       class CI
-        def initialize(frequency: 10)
-          @frequency = frequency
+        include Conductor::ANSI
+
+        DEFAULT_PRINTOUT_INTERVAL = 10
+
+        # @option printout_interval how often a printout happens, in seconds
+        def initialize(printout_interval: DEFAULT_PRINTOUT_INTERVAL)
+          @printout_interval = printout_interval
           @last_printout = Time.now
         end
 
-        def handle_worker_message(_worker, message, results)
+        def handle_worker_message(_worker_process, message, results)
           public_send(message[:type], message) if respond_to?(message[:type])
-          print_status(results) if @last_printout + @frequency < Time.now
+          print_status(results) if @last_printout + @printout_interval < 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
+          pct = results.spec_file_processed_percentage
 
           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 "Processed: #{results.spec_files_processed} / #{results.spec_files_total} (#{(pct * 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|
+            results.errors.each_with_index do |error, i|
               puts "  #{i + 1}) #{error[:description]}"
               puts "     #{error[:location]}"
               puts "     #{error[:message]}" if error[:message]
@@ -35,12 +40,6 @@ module RSpec
           end
           puts "-" * tty_width
         end
-
-        private
-
-        def tty_width
-          $stdout.tty? ? $stdout.winsize[1] : 80
-        end
       end
     end
   end

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

@@ -1,54 +1,50 @@
 require "pathname"
+require "set"
 
 module RSpec
   module Conductor
     module Formatters
       class Fancy
-        RED = 31
-        GREEN = 32
-        YELLOW = 33
-        MAGENTA = 35
-        CYAN = 36
-        NORMAL = 0
+        include Conductor::ANSI
 
         def self.recommended?
           $stdout.tty? && $stdout.winsize[0] >= 30 && $stdout.winsize[1] >= 80
         end
 
         def initialize
-          @workers = Hash.new { |h, k| h[k] = {} }
+          @worker_processes = Set.new
           @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])
+        def handle_worker_message(worker_process, message, results)
+          @worker_processes <<  worker_process
+          public_send(message[:type], worker_process, message) if respond_to?(message[:type])
           redraw(results)
         end
 
-        def example_passed(_worker, _message)
-          @dots << { char: ".", color: GREEN }
+        def example_passed(_worker_process, _message)
+          @dots << { char: ".", color: :green }
         end
 
-        def example_failed(_worker, message)
-          @dots << { char: "F", color: RED }
+        def example_failed(_worker_process, 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 }
+        def example_retried(_worker_process, _message)
+          @dots << { char: "R", color: :magenta }
         end
 
-        def example_pending(_worker, _message)
-          @dots << { char: "*", color: YELLOW }
+        def example_pending(_worker_process, _message)
+          @dots << { char: "*", color: :yellow }
         end
 
         private
 
         def redraw(results)
-          cursor_up(rewrap_lines(@last_rendered_lines).length)
+          print_cursor_up(rewrap_lines(@last_rendered_lines).length)
 
           lines = []
           lines << progress_bar(results)
@@ -62,37 +58,47 @@ module RSpec
 
           lines.each_with_index do |line, i|
             if @last_rendered_lines[i] == line
-              cursor_down(1)
+              print_cursor_down(1)
             else
-              clear_line
+              print_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
+              print_clear_line
               puts
             end
-            cursor_up(@last_rendered_lines.length - lines.length)
+            print_cursor_up(@last_rendered_lines.length - lines.length)
           end
 
           @last_rendered_lines = lines
         end
 
-        def worker_lines
-          return [] unless max_worker_num.positive?
+        def progress_bar(results)
+          pct = results.spec_file_processed_percentage
+          bar_width = [tty_width - 20, 20].max
+
+          filled = (pct * bar_width).floor
+          empty = bar_width - filled
+
+          bar = colorize("[", :reset) + colorize("▓" * filled, :green) + colorize(" " * empty, :reset) + colorize("]", :reset)
+          percentage = " #{(pct * 100).floor.to_s.rjust(3)}% (#{results.spec_files_processed}/#{results.spec_files_total})"
+
+          bar + percentage
+        end
 
-          (1..max_worker_num).map do |num|
-            worker = @workers[num]
-            prefix = colorize("Worker #{num}: ", CYAN)
+        def worker_lines
+          @worker_processes.sort_by(&:number).map do |worker_process|
+            prefix = colorize("Worker #{worker_process.number}: ", :cyan)
 
-            if worker[:status] == :shut_down
+            if worker_process.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)
+            elsif worker_process.status == :terminated
+              prefix + colorize("(terminated)", :red)
+            elsif worker_process.current_spec
+              prefix + truncate(relative_path(worker_process.current_spec), tty_width - 15)
             else
               prefix + "(idle)"
             end
@@ -103,7 +109,7 @@ module RSpec
           return [] unless @last_error
 
           lines = []
-          lines << colorize("Most recent failure:", RED)
+          lines << colorize("Most recent failure:", :red)
           lines << "  #{@last_error[:description]}"
           lines << "  #{@last_error[:location]}"
 
@@ -124,37 +130,10 @@ module RSpec
           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}" }
+            split_visible_char_groups(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
@@ -165,24 +144,16 @@ module RSpec
           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?
+        def print_cursor_up(n_lines)
+          print cursor_up(n_lines) if $stdout.tty?
         end
 
-        def clear_line
-          print("\e[2K\r") if $stdout.tty?
+        def print_cursor_down(n_lines)
+          print cursor_down(n_lines) if $stdout.tty?
         end
 
-        def tty_width
-          $stdout.tty? ? $stdout.winsize[1] : 80
+        def print_clear_line
+          print clear_line if $stdout.tty?
         end
       end
     end

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

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

data/lib/rspec/conductor/results.rb

@@ -0,0 +1,80 @@
+module RSpec
+  module Conductor
+    class Results
+      attr_accessor :passed, :failed, :pending, :worker_crashes, :errors, :started_at, :spec_files_total, :spec_files_processed
+
+      def initialize
+        @passed = 0
+        @failed = 0
+        @pending = 0
+        @worker_crashes = 0
+        @errors = []
+        @started_at = Time.now
+        @specs_started_at = nil
+        @specs_completed_at = nil
+        @spec_files_total = 0
+        @spec_files_processed = 0
+        @shutting_down = false
+      end
+
+      def success?
+        @failed.zero? && @errors.empty? && @worker_crashes.zero? && !shutting_down?
+      end
+
+      def example_passed
+        @passed += 1
+      end
+
+      def example_failed(message)
+        @failed += 1
+        @errors << message
+      end
+
+      def example_pending
+        @pending += 1
+      end
+
+      def spec_file_assigned
+        @specs_started_at ||= Time.now
+      end
+
+      def spec_file_complete
+        @spec_files_processed += 1
+      end
+
+      def spec_file_error(message)
+        @errors << message
+      end
+
+      def spec_file_processed_percentage
+        return 0.0 if @spec_files_total.zero?
+
+        @spec_files_processed.to_f / @spec_files_total
+      end
+
+      def worker_crashed
+        @worker_crashes += 1
+      end
+
+      def shut_down
+        @shutting_down = true
+      end
+
+      def shutting_down?
+        @shutting_down
+      end
+
+      def suite_complete
+        @specs_completed_at ||= Time.now
+      end
+
+      def specs_runtime
+        ((@specs_completed_at || Time.now) - (@specs_started_at || @started_at)).to_f
+      end
+
+      def total_runtime
+        ((@specs_completed_at || Time.now) - @started_at).to_f
+      end
+    end
+  end
+end

data/lib/rspec/conductor/rspec_subscriber.rb

@@ -0,0 +1,74 @@
+module RSpec
+  module Conductor
+    # Technically this is a **Formatter**, as in RSpec Formatter, but that was too confusing,
+    # and there is another thing called formatter in this library. Hence, Subscriber.
+    class RSpecSubscriber
+      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
+
+      # This one is invoked by rspec-retry, hence the slightly different api from example_* methods
+      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/server.rb

@@ -8,9 +8,14 @@ require "io/console"
 module RSpec
   module Conductor
     class Server
+      MAX_SEED = 2**16
+      WORKER_POLL_INTERVAL = 0.01
+
       # @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 prefork_require [String] File required prior to forking
+      # @option postfork_require [String, Symbol] File required after forking
       # @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
@@ -20,17 +25,17 @@ module RSpec
       def initialize(worker_count:, rspec_args:, **opts)
         @worker_count = worker_count
         @worker_number_offset = opts.fetch(:worker_number_offset, 0)
+        @prefork_require = opts.fetch(:prefork_require, nil)
+        @postfork_require = opts.fetch(:postfork_require, nil)
         @first_is_one = opts.fetch(:first_is_1, false)
-        @seed = opts[:seed] || (Random.new_seed % 65_536)
+        @seed = opts[:seed] || (Random.new_seed % MAX_SEED)
         @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 = {}
+        @worker_processes = {}
         @spec_queue = []
-        @started_at = Time.now
-        @shutting_down = false
         @formatter = case opts[:formatter]
                      when "ci"
                        Formatters::CI.new
@@ -39,9 +44,9 @@ module RSpec
                      when "plain"
                        Formatters::Plain.new
                      else
-                       Formatters::Fancy.recommended? ? Formatters::Fancy.new : Formatters::Plain.new
+                       (!@verbose && 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 }
+        @results = Results.new
       end
 
       def run
@@ -55,6 +60,7 @@ module RSpec
 
         start_workers
         run_event_loop
+        @results.suite_complete
 
         print_summary
         exit_with_status
@@ -63,11 +69,18 @@ module RSpec
       private
 
       def preload_application
-        application = File.expand_path("config/application", Conductor.root)
+        if !@prefork_require
+          debug "Prefork require not set, skipping..."
+          return
+        end
+
+        preload = File.expand_path(@prefork_require, Conductor.root)
 
-        if File.exist?(application)
-          debug "Preloading config/application.rb..."
-          require File.expand_path("config/application", Conductor.root)
+        if File.exist?(preload)
+          debug "Preloading #{@prefork_require}..."
+          require preload
+        else
+          debug "#{@prefork_require} not found, skipping..."
         end
 
         debug "Application preloaded, autoload paths configured"
@@ -76,18 +89,17 @@ module RSpec
       def setup_signal_handlers
         %w[INT TERM].each do |signal|
           Signal.trap(signal) do
-            @workers.any? ? initiate_shutdown : Kernel.exit(1)
+            @worker_processes.any? ? initiate_shutdown : Kernel.exit(1)
           end
         end
       end
 
       def initiate_shutdown
-        return if @shutting_down
-
-        @shutting_down = true
+        return if @results.shutting_down?
 
+        @results.shut_down
         puts "Shutting down..."
-        @workers.each_value { |w| w[:socket]&.send_message({ type: :shutdown }) }
+        @worker_processes.each_value { |w| w.socket&.send_message({ type: :shutdown }) }
       end
 
       def build_spec_queue
@@ -97,7 +109,7 @@ module RSpec
         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
+        @results.spec_files_total = @spec_queue.size
       end
 
       def parsed_rspec_args
@@ -133,111 +145,107 @@ module RSpec
             worker_number: worker_number,
             socket: Protocol::Socket.new(child_socket),
             rspec_args: @rspec_args,
-            verbose: @verbose
+            verbose: @verbose,
+            postfork_require: @postfork_require,
           ).run
         end
 
         child_socket.close
         debug "Worker #{worker_number} started with pid #{pid}"
 
-        @workers[pid] = {
+        @worker_processes[pid] = WorkerProcess.new(
           pid: pid,
           number: worker_number,
           status: :running,
           socket: Protocol::Socket.new(parent_socket),
           current_spec: nil,
-        }
-        assign_work(@workers[pid])
+        )
+        assign_work(@worker_processes[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
-
+        until @worker_processes.empty?
+          worker_processes_by_io = @worker_processes.values.to_h { |w| [w.socket.io, w] }
+          readable_ios, = IO.select(worker_processes_by_io.keys, nil, nil, WORKER_POLL_INTERVAL)
+          readable_ios&.each { |io| handle_worker_message(worker_processes_by_io.fetch(io)) }
           reap_workers
         end
       end
 
-      def handle_worker_message(worker)
-        message = worker[:socket].receive_message
+      def handle_worker_message(worker_process)
+        message = worker_process.socket.receive_message
         return unless message
 
-        debug "Worker #{worker[:number]}: #{message[:type]}"
+        debug "Worker #{worker_process.number}: #{message[:type]}"
 
         case message[:type].to_sym
         when :example_passed
-          @results[:passed] += 1
+          @results.example_passed
         when :example_failed
-          @results[:failed] += 1
-          @results[:errors] << message
+          @results.example_failed(message)
 
-          if @fail_fast_after && @results[:failed] >= @fail_fast_after && !@shutting_down
-            debug "Shutting after #{@results[:failed]} failures"
+          if @fail_fast_after && @results.failed >= @fail_fast_after
+            debug "Shutting after #{@results.failed} failures"
             initiate_shutdown
           end
         when :example_pending
-          @results[:pending] += 1
+          @results.example_pending
         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)
+          @results.spec_file_complete
+          worker_process.current_spec = nil
+          assign_work(worker_process)
         when :spec_error
-          @results[:errors] << message
+          @results.spec_file_error(message)
           debug "Spec error details: #{message[:error]}"
-          worker[:current_spec] = nil
-          assign_work(worker)
+          worker_process.current_spec = nil
+          assign_work(worker_process)
         when :spec_interrupted
           debug "Spec interrupted: #{message[:file]}"
-          worker[:current_spec] = nil
+          worker_process.current_spec = nil
         end
-        @formatter.handle_worker_message(worker, message, @results)
+        @formatter.handle_worker_message(worker_process, 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)
+      def assign_work(worker_process)
+        if @spec_queue.empty? || @results.shutting_down?
+          debug "No more work for worker #{worker_process.number}, sending shutdown"
+          worker_process.socket.send_message({ type: :shutdown })
+          cleanup_worker_process(worker_process)
         else
-          @specs_started_at ||= Time.now
+          @results.spec_file_assigned
           spec_file = @spec_queue.shift
-          worker[:current_spec] = spec_file
-          debug "Assigning #{spec_file} to worker #{worker[:number]}"
+          worker_process.current_spec = spec_file
+          debug "Assigning #{spec_file} to worker #{worker_process.number}"
           message = { type: :worker_assigned_spec, file: spec_file }
-          worker[:socket].send_message(message)
-          @formatter.handle_worker_message(worker, message, @results)
+          worker_process.socket.send_message(message)
+          @formatter.handle_worker_message(worker_process, 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])
+      def cleanup_worker_process(worker_process, status: :shut_down)
+        @worker_processes.delete(worker_process.pid)
+        worker_process.socket.close
+        worker_process.status = status
+        @formatter.handle_worker_message(worker_process, { type: :worker_shut_down }, @results)
+        Process.wait(worker_process.pid)
       rescue Errno::ECHILD
         nil
       end
 
       def reap_workers
-        dead_workers = @workers.each_with_object([]) do |(pid, worker), memo|
+        dead_worker_processes = @worker_processes.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}"
+        dead_worker_processes.each do |worker_process, exitstatus|
+          cleanup_worker_process(worker_process, status: :terminated)
+          @results.worker_crashed
+          debug "Worker #{worker_process.number} exited with status #{exitstatus.exitstatus}, signal #{exitstatus.termsig}"
         end
       rescue Errno::ECHILD
         nil
@@ -245,12 +253,13 @@ module RSpec
 
       def print_summary
         puts "\n\n"
-        puts "=" * ($stdout.tty? ? $stdout.winsize[1] : 80)
-        puts "Results: #{@results[:passed]} passed, #{@results[:failed]} failed, #{@results[:pending]} pending"
+        puts "Randomized with seed #{@seed}"
+        puts "#{colorize("#{@results.passed} passed", :green)}, #{colorize("#{@results.failed} failed", :red)}, #{colorize("#{@results.pending} pending", :yellow)}"
+        puts colorize("Worker crashes: #{@results.worker_crashes}", :red) if @results.worker_crashes.positive?
 
-        if @results[:errors].any?
+        if @results.errors.any?
           puts "\nFailures:\n\n"
-          @results[:errors].each_with_index do |error, i|
+          @results.errors.each_with_index do |error, i|
             puts "  #{i + 1}) #{error[:description]}"
             puts "     #{error[:location]}"
             puts "     #{error[:message]}" if error[:message]
@@ -262,14 +271,17 @@ module RSpec
           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"
+        puts "Specs took: #{@results.specs_runtime.round(2)}s"
+        puts "Total runtime: #{@results.total_runtime.round(2)}s"
+        puts "Suite: #{@results.success? ? colorize("PASSED", :green) : colorize("FAILED", :red)}"
+      end
+
+      def colorize(string, color)
+        $stdout.tty? ? ANSI.colorize(string, color) : string
       end
 
       def exit_with_status
-        success = @results[:failed].zero? && @results[:errors].empty? && @results[:worker_crashes].zero? && !@shutting_down
-        Kernel.exit(success ? 0 : 1)
+        Kernel.exit(@results.success? ? 0 : 1)
       end
 
       def debug(message)

data/lib/rspec/conductor/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Conductor
-    VERSION = "1.0.0"
+    VERSION = "1.0.2"
   end
 end

data/lib/rspec/conductor/worker.rb

@@ -1,27 +1,17 @@
 # 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
+require_relative 'ext/rspec'
 
 module RSpec
   module Conductor
     class Worker
-      def initialize(worker_number:, socket:, rspec_args: [], verbose: false)
+      def initialize(worker_number:, socket:, rspec_args: [], verbose: false, postfork_require: :spec_helper)
         @worker_number = worker_number
         @socket = socket
         @rspec_args = rspec_args
         @verbose = verbose
+        @postfork_require = postfork_require
+
         @message_queue = []
       end
 
@@ -29,7 +19,7 @@ module RSpec
         suppress_output unless @verbose
         debug "Worker #{@worker_number} starting"
         setup_load_path
-        initialize_rspec
+        require_postfork_preloads
 
         loop do
           debug "Waiting for message"
@@ -69,18 +59,14 @@ module RSpec
 
       def setup_load_path
         parsed_options.configure(RSpec.configuration)
-        default_path = RSpec.configuration.default_path || "spec"
+        @default_path = RSpec.configuration.default_path || "spec"
+        @default_full_path = File.expand_path(@default_path, Conductor.root)
 
-        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)
+        if Dir.exist?(@default_full_path) && !$LOAD_PATH.include?(@default_full_path)
+          $LOAD_PATH.unshift(@default_full_path)
         end
 
-        debug "Load path (spec dirs): #{$LOAD_PATH.grep(/spec/)}"
+        debug "Load path (spec dirs): #{$LOAD_PATH.inspect}"
       end
 
       def suppress_output
@@ -89,17 +75,29 @@ module RSpec
         $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
+      def require_postfork_preloads
+        if @postfork_require == :spec_helper
+          rails_helper = File.expand_path("rails_helper.rb", @default_full_path)
+          spec_helper = File.expand_path("spec_helper.rb", @default_full_path)
+          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 "Neither rails_helper, nor spec_helper found, skipping..."
+          end
+        elsif @postfork_require
+          required_file = File.expand_path(@postfork_require, @default_full_path)
+          if File.exist?(required_file)
+            debug "Requiring #{required_file}..."
+            require required_file
+          else
+            debug "#{required_file} not found, skipping..."
+          end
         else
-          debug "Could detect neither rails_helper nor spec_helper"
+          debug "Skipping postfork require..."
         end
 
         debug "RSpec initialized, running before(:suite) hooks"
@@ -110,7 +108,10 @@ module RSpec
         RSpec.world.reset
         RSpec.configuration.reset_reporter
         RSpec.configuration.files_or_directories_to_run = []
-        setup_formatter(ConductorFormatter.new(@socket, file, -> { check_for_shutdown }))
+        RSpec.configuration.output_stream = null_io_out
+        RSpec.configuration.error_stream = null_io_out
+        RSpec.configuration.formatter_loader.formatters.clear
+        RSpec.configuration.add_formatter(RSpecSubscriber.new(@socket, file, -> { check_for_shutdown }))
 
         begin
           debug "Loading spec file: #{file}"
@@ -162,13 +163,6 @@ module RSpec
         @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
@@ -181,73 +175,5 @@ module RSpec
         @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/worker_process.rb

@@ -0,0 +1,13 @@
+module RSpec
+  module Conductor
+    WorkerProcess = Struct.new(:pid, :number, :status, :socket, :current_spec, keyword_init: true) do
+      def hash
+        [number].hash
+      end
+
+      def eql?(other)
+        other.is_a?(self.class) && other.number == number
+      end
+    end
+  end
+end

data/lib/rspec/conductor.rb

@@ -6,7 +6,11 @@ require_relative "conductor/version"
 require_relative "conductor/protocol"
 require_relative "conductor/server"
 require_relative "conductor/worker"
+require_relative "conductor/results"
+require_relative "conductor/worker_process"
 require_relative "conductor/cli"
+require_relative "conductor/ansi"
+require_relative "conductor/rspec_subscriber"
 require_relative "conductor/formatters/plain"
 require_relative "conductor/formatters/ci"
 require_relative "conductor/formatters/fancy"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-conductor
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Mark Abramov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-21 00:00:00.000000000 Z
+date: 2026-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-core
@@ -40,14 +40,19 @@ files:
 - Rakefile
 - exe/rspec-conductor
 - lib/rspec/conductor.rb
+- lib/rspec/conductor/ansi.rb
 - lib/rspec/conductor/cli.rb
+- lib/rspec/conductor/ext/rspec.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/results.rb
+- lib/rspec/conductor/rspec_subscriber.rb
 - lib/rspec/conductor/server.rb
 - lib/rspec/conductor/version.rb
 - lib/rspec/conductor/worker.rb
+- lib/rspec/conductor/worker_process.rb
 - rspec-conductor.gemspec
 homepage: https://github.com/markiz/rspec-conductor
 licenses: