parallel_specs 0.9.0

data/lib/parallel_specs/rspec/runtime_logger.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'parallel_specs'
+require 'parallel_specs/rspec/logger_base'
+
+class ParallelSpecs::RSpec::RuntimeLogger < ParallelSpecs::RSpec::LoggerBase
+  RSpec::Core::Formatters.register(self, :example_group_started, :example_group_finished, :start_dump)
+
+  def initialize(*args)
+    super
+    @example_times = Hash.new(0)
+    @group_nesting = 0
+  end
+
+  def example_group_started(example_group)
+    @time = ParallelSpecs.now if @group_nesting.zero?
+    @group_nesting += 1
+    super
+  end
+
+  def example_group_finished(notification)
+    @group_nesting -= 1
+    if @group_nesting.zero?
+      @example_times[notification.group.file_path] += ParallelSpecs.now - @time
+    end
+    super if defined?(super)
+  end
+
+  def seed(*); end
+  def dump_summary(*); end
+  def dump_failures(*); end
+  def dump_failure(*); end
+  def dump_pending(*); end
+
+  def start_dump(*)
+    return unless ENV['TEST_ENV_NUMBER']
+
+    lock_output do
+      @example_times.sort_by(&:last).reverse_each do |file, time|
+        relative_path = file.sub(%r{^#{Regexp.escape(Dir.pwd)}/}, '').sub(%r{^\./}, '')
+        @output.puts "#{relative_path}:#{[time, 0].max}"
+      end
+    end
+    @output.flush
+  end
+end

data/lib/parallel_specs/test/runner.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require 'parallel_specs'
+require 'shellwords'
+
+module ParallelSpecs
+  module Test
+    class Runner
+      RuntimeLogTooSmallError = Class.new(StandardError)
+      RuntimeLogParseError = Class.new(StandardError)
+
+      class << self
+        def tests_in_groups(tests, num_groups, options = {})
+          ParallelSpecs::Grouper.in_even_groups_by_size(tests_with_size(tests, options), num_groups)
+        end
+
+        def tests_with_size(tests, options)
+          tests = find_tests(tests, options)
+
+          case options[:group_by]
+          when :found
+            tests.map! { |test| [test, 1] }
+          when :runtime
+            sort_by_runtime(
+              tests,
+              runtimes(tests, options),
+              options.merge(allowed_missing: (options[:allowed_missing_percent] || 50) / 100.0)
+            )
+          when :filesize
+            sort_by_filesize(tests)
+          when nil
+            begin
+              known_runtimes = runtimes(tests, options)
+            rescue Errno::ENOENT
+              warn "parallel_specs: runtime log #{runtime_log_path(options)} was not found; falling back to filesize grouping" if options[:runtime_log]
+              known_runtimes = {}
+            rescue RuntimeLogParseError => e
+              warn "parallel_specs: unable to use runtime log #{runtime_log_path(options)}: #{e.message}; falling back to filesize grouping"
+              known_runtimes = {}
+            rescue StandardError => e
+              warn "parallel_specs: unable to load runtime log #{runtime_log_path(options)}: #{e.class}: #{e.message}"
+              raise
+            end
+
+            if known_runtimes.size * 1.5 > tests.size
+              puts 'Using recorded test runtime'
+              sort_by_runtime(tests, known_runtimes)
+            else
+              sort_by_filesize(tests)
+            end
+          else
+            raise ArgumentError, "Unsupported option #{options[:group_by]}"
+          end
+
+          tests
+        end
+
+        def execute_command(cmd, process_number, num_processes, options)
+          env = {
+            'TEST_ENV_NUMBER' => test_env_number(process_number),
+            'PARALLEL_SPECS_GROUPS' => num_processes.to_s,
+            'PARALLEL_SPECS_PID_FILE' => ParallelSpecs.pid_file_path
+          }
+
+          if (dashboard_event_files = options[:dashboard_event_files])
+            env['PARALLEL_SPECS_DASHBOARD_EVENT_LOG'] = dashboard_event_files.fetch(process_number)
+          end
+
+          execute_command_and_capture_output(env, cmd, options)
+        end
+
+        def execute_command_and_capture_output(env, cmd, options)
+          pid = nil
+          output = IO.popen(env, cmd, err: [:child, :out]) do |io|
+            pid = io.pid
+            ParallelSpecs.pids.add(pid)
+            capture_output(io, options[:dashboard])
+          ensure
+            ParallelSpecs.pids.delete(pid) if pid
+          end
+
+          status = $?
+          exit_status = if status.exitstatus
+            status.exitstatus
+          elsif status.termsig
+            status.termsig + 128
+          else
+            1
+          end
+
+          { env: env, stdout: output, exit_status: exit_status, command: cmd, seed: seed_from(output) }
+        end
+
+        def print_command(command, env = {})
+          env_string = rerun_env(env).map { |key, value| "#{key}=#{Shellwords.escape(value)}" }.join(' ')
+          command_string = Shellwords.shelljoin(command)
+          puts [env_string, command_string].reject(&:empty?).join(' ')
+        end
+
+        def rerun_command(command, seed: nil)
+          seed ? command_with_seed(command, seed) : command
+        end
+
+        def command_with_seed(command, seed)
+          [*remove_command_arguments(command, '--seed'), '--seed', seed]
+        end
+
+        def find_results(test_output)
+          test_output.lines.filter_map do |line|
+            line = line.chomp.gsub(/\e\[\d+m/, '')
+            line if line_is_result?(line)
+          end
+        end
+
+        def summarize_results(results)
+          sum_up_results(results).sort.map { |word, count| "#{count} #{word}#{'s' if count != 1}" }.join(', ')
+        end
+
+        protected
+
+        def capture_output(out, dashboard)
+          result = +''
+          begin
+            loop do
+              chunk = out.readpartial(1_000_000)
+              chunk = chunk.force_encoding(Encoding.default_internal) if Encoding.default_internal
+              result << chunk
+              next if dashboard
+
+              $stdout.print(chunk)
+              $stdout.flush
+            end
+          rescue EOFError
+            nil
+          end
+          result
+        end
+
+        def seed_from(output)
+          output.to_s[/seed (\d+)/, 1]
+        end
+
+        def sort_by_runtime(tests, runtimes, options = {})
+          allowed_missing = tests.size * (options[:allowed_missing] || 1.0)
+          tests.sort!
+          tests.map! do |test|
+            time = runtimes[test]
+            allowed_missing -= 1 unless time
+            if allowed_missing.negative?
+              log = options[:runtime_log] || runtime_log
+              raise RuntimeLogTooSmallError, "Runtime log file '#{log}' does not contain sufficient data to sort #{tests.size} test files, please update or remove it."
+            end
+            [test, time]
+          end
+
+          set_unknown_runtime(tests, options)
+        end
+
+        def runtimes(tests, options)
+          path = runtime_log_path(options)
+          File.read(path).split("\n").each_with_index.each_with_object({}) do |(line, index), times|
+            next if line.empty?
+
+            test, separator, time = line.rpartition(':')
+            raise RuntimeLogParseError, "Invalid runtime log line #{index + 1} in #{path}: #{line.inspect}" if separator.empty? || test.empty? || time.empty?
+
+            times[test] = Float(time) if tests.include?(test)
+          rescue ArgumentError
+            raise RuntimeLogParseError, "Invalid runtime value on line #{index + 1} in #{path}: #{line.inspect}"
+          end
+        end
+
+        def runtime_log_path(options)
+          options[:runtime_log] || runtime_log
+        end
+
+        def sort_by_filesize(tests)
+          tests.sort!
+          tests.map! { |test| [test, File.stat(test).size] }
+        end
+
+        def find_tests(tests, options = {})
+          tests.flat_map do |file_or_folder|
+            if File.directory?(file_or_folder)
+              filter_files(Dir[File.join(file_or_folder, '**/*_spec.rb')].uniq.sort, options)
+            else
+              filter_files([file_or_folder], options)
+            end
+          end.uniq
+        end
+
+        def filter_files(files, options)
+          files = files.grep(options[:pattern]) if options[:pattern]
+          files = files.reject { |file| file.match?(options[:exclude_pattern]) } if options[:exclude_pattern]
+          files
+        end
+
+        def remove_command_arguments(command, *args)
+          remove_next = false
+          command.reject do |arg|
+            if remove_next
+              remove_next = false
+              true
+            elsif args.include?(arg)
+              remove_next = true
+              true
+            elsif args.any? { |option| arg.start_with?("#{option}=") }
+              true
+            else
+              false
+            end
+          end
+        end
+
+        def rerun_env(env)
+          env.slice('TEST_ENV_NUMBER', 'PARALLEL_SPECS_GROUPS').reject { |_key, value| value.to_s.empty? }
+        end
+
+        def test_env_number(process_number)
+          process_number.zero? ? '' : (process_number + 1).to_s
+        end
+
+        def sum_up_results(results)
+          results.join(' ').gsub(/s\b/, '').scan(/(\d+) (\w+)/).each_with_object(Hash.new(0)) do |(number, word), sum|
+            sum[word] += number.to_i
+          end
+        end
+
+        private
+
+        def set_unknown_runtime(tests, options)
+          known, unknown = tests.partition(&:last)
+          return tests if unknown.empty?
+
+          unknown_runtime = options[:unknown_runtime] || (known.empty? ? 1 : known.map!(&:last).sum / known.size)
+          unknown.each { |entry| entry[1] = unknown_runtime }
+          tests
+        end
+      end
+    end
+  end
+end

data/lib/parallel_specs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ParallelSpecs
+  VERSION = '0.9.0'
+end

data/lib/parallel_specs.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'parallel'
+require 'rbconfig'
+require 'tempfile'
+
+module ParallelSpecs
+  WINDOWS = (RbConfig::CONFIG['host_os'] =~ /cygwin|mswin|mingw|bccwin|wince|emx/)
+  RUBY_BINARY = File.join(RbConfig::CONFIG['bindir'], RbConfig::CONFIG['ruby_install_name'])
+
+  autoload :CLI, 'parallel_specs/cli'
+  autoload :VERSION, 'parallel_specs/version'
+  autoload :Grouper, 'parallel_specs/grouper'
+  autoload :Pids, 'parallel_specs/pids'
+
+  class << self
+    def determine_number_of_processes(count)
+      Integer([
+        count,
+        ENV['PARALLEL_SPECS_PROCESSORS'],
+        Parallel.processor_count
+      ].detect { |value| !value.to_s.strip.empty? })
+    end
+
+    def with_pid_file
+      previous_pid_file = ENV['PARALLEL_SPECS_PID_FILE']
+      Tempfile.open('parallel_specs-pidfile') do |file|
+        ENV['PARALLEL_SPECS_PID_FILE'] = file.path
+        @pids = pids
+        yield
+      ensure
+        ENV['PARALLEL_SPECS_PID_FILE'] = previous_pid_file
+        @pids = nil
+      end
+    end
+
+    def pids
+      @pids ||= Pids.new(pid_file_path)
+    end
+
+    def pid_file_available?
+      !ENV['PARALLEL_SPECS_PID_FILE'].to_s.empty?
+    end
+
+    def pid_file_path
+      ENV.fetch('PARALLEL_SPECS_PID_FILE')
+    end
+
+    def stop_all_processes
+      return false unless pid_file_available?
+
+      tracked_pids = pids.all
+      return false if tracked_pids.empty?
+
+      signal_delivered = false
+      tracked_pids.each do |pid|
+        Process.kill(:INT, pid)
+        signal_delivered = true
+      rescue Errno::ESRCH, Errno::EPERM => e
+        warn "parallel_specs: unable to interrupt worker pid #{pid}: #{e.class}: #{e.message}"
+      end
+      signal_delivered
+    end
+
+    def bundler_enabled?
+      return true if Object.const_defined?(:Bundler)
+
+      previous = nil
+      current = File.expand_path(Dir.pwd)
+      until !File.directory?(current) || current == previous
+        return true if File.exist?(File.join(current, 'Gemfile'))
+
+        previous = current
+        current = File.expand_path('..', current)
+      end
+
+      false
+    end
+
+    def with_ruby_binary(command)
+      WINDOWS ? [RUBY_BINARY, '--', command] : [command]
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def delta
+      before = now.to_f
+      yield
+      now.to_f - before
+    end
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: parallel_specs
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Scott Watermasysk
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: parallel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.28'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.28'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description:
+email: scottwater@gmail.com
+executables:
+- parallel_specs
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/parallel_specs
+- lib/parallel_specs.rb
+- lib/parallel_specs/cli.rb
+- lib/parallel_specs/cli/dashboard.rb
+- lib/parallel_specs/grouper.rb
+- lib/parallel_specs/pids.rb
+- lib/parallel_specs/rspec/dashboard_logger.rb
+- lib/parallel_specs/rspec/logger_base.rb
+- lib/parallel_specs/rspec/runner.rb
+- lib/parallel_specs/rspec/runtime_logger.rb
+- lib/parallel_specs/test/runner.rb
+- lib/parallel_specs/version.rb
+homepage: https://github.com/scottwater/parallel_specs
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Parallel RSpec with a live dashboard, plain CI output, and runtime balancing
+test_files: []