padded_cell 0.1.0-x86_64-linux-gnu → 0.2.0-x86_64-linux-gnu

data/lib/padded_cell/chart.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'chart/delta'
+require_relative 'chart/probe'
+require_relative 'chart/raw'
+require_relative 'chart/accumulator'
+require_relative 'chart/filter'
+require_relative 'chart/config'
+require_relative 'chart/source_files'
+require_relative 'chart/document'
+require_relative 'chart/merge'
+require_relative 'chart/report'
+
+module PaddedCell
+  # Built-in coverage: Ruby's Coverage measured in the
+  # runner, every worker and every cell, summed exactly in the runner. The
+  # chart, as the asylum keeps one per patient: inside, a name that is not
+  # Ruby's own Coverage; outside, it is all --coverage.
+  #
+  # Measuring starts before the suite loads, so what is measured comes from
+  # the command line (--coverage=lines,branches,methods,eval); the report is
+  # configured in the test helper, with PaddedCell.coverage (see Config).
+  module Chart
+    CRITERIA = %i[lines branches methods eval].freeze
+    DEFAULT_CRITERIA = %i[lines branches].freeze
+
+    class << self
+      # Every PaddedCell.coverage block, in one Config.
+      def config = @config ||= Config.new
+
+      def configure(profile = nil, &block)
+        config.profile(profile) if profile
+        config.instance_eval(&block) if block
+        config
+      end
+    end
+  end
+end

data/lib/padded_cell/cli.rb

@@ -2,6 +2,7 @@
 
 require 'optparse'
 require_relative 'runner'
+require_relative 'chart'
 
 module PaddedCell
   # The padded_cell command.
@@ -18,13 +19,16 @@ module PaddedCell
 
     module_function
 
-    # Exit status: 0 passed, 1 failed, 2 usage or load error, 130 interrupted.
+    # Exit status: 0 passed, 1 failed, 2 usage or load error, 3 coverage below
+    # a minimum, 130 interrupted.
     def start(argv, io: $stdout)
-      options = { io: }
+      options = { io:, coverage: coverage_criteria(ENV.fetch('PADDED_CELL_COVERAGE', nil)) }
       parser(options).parse!(argv)
+      return merge(options) if options[:coverage_merge]
+
       options[:paths] = argv
       Runner.new(**options).run
-    rescue OptionParser::ParseError, ArgumentError, LoadFailure, Unsupported, SystemCallError => e
+    rescue OptionParser::ParseError, ArgumentError, RegexpError, LoadFailure, Unsupported, SystemCallError => e
       warn "padded_cell: #{e.message}"
       2
     end
@@ -34,6 +38,7 @@ module PaddedCell
         opts.banner = BANNER
         opts.version = VERSION
         runner_options(opts, options)
+        coverage_options(opts, options)
         output_options(opts, options)
         opts.on('--version', 'Print the version') do
           options[:io].puts "padded_cell #{VERSION}"
@@ -50,7 +55,7 @@ module PaddedCell
       opts.on('-j', '--jobs N', Integer, "Workers (default: #{Etc.nprocessors})") do
         options[:jobs] = positive(it)
       end
-      opts.on('-s', '--seed SEED', Integer, 'Order seed (default: random, or $SEED)') { options[:seed] = it }
+      opts.on('-s', '--seed SEED', Integer, 'Order seed (default: random, or $SEED)') { options[:seed] = seed(it) }
       opts.on('-n', '-i', '--name', '--include PATTERN', 'Only tests matching (/regexp/ or exact name)') do
         options[:include] = it
       end
@@ -66,9 +71,36 @@ module PaddedCell
         options[:timeout] = positive(it)
       end
       opts.on('--fail-fast', 'Stop dispatching after the first failure') { options[:fail_fast] = true }
+      opts.on('--asylum[=N]', Integer, 'Retry failed tests up to N times (default 2) after the run, alone, ' \
+                                       'each in a fresh cell; report the flaky ones') do
+        options[:asylum] = it.nil? ? 2 : positive(it)
+      end
       opts.on('--list', 'List the tests that would run (static, loads nothing)') { options[:list] = true }
     end
 
+    def coverage_options(opts, options)
+      opts.on('--[no-]coverage[=CRITERIA]', 'Measure coverage: lines, branches, methods, eval ' \
+                                            "(default: #{Chart::DEFAULT_CRITERIA.join(',')}; " \
+                                            'or $PADDED_CELL_COVERAGE)') do
+        options[:coverage] = coverage_criteria(it.to_s)
+      end
+      opts.on('--coverage-dir DIR', 'Write coverage reports to DIR (default: coverage, or the test helper\'s)') do
+        options[:coverage_dir] = it
+      end
+      opts.on('--coverage-merge DIR,DIR', Array, 'Merge the coverage of shards (their --coverage-dir) ' \
+                                                 'into one report; runs no test') do
+        options[:coverage_merge] = it
+      end
+    end
+
+    # --coverage-merge: 0, or 3 when a threshold is missed.
+    def merge(options)
+      document = Chart::Merge.call(options[:coverage_merge])
+      dir = options[:coverage_dir] || 'coverage'
+      document.write(dir)
+      Chart::Report.new(document, dir:, io: options[:io]).call(check: document.complete?) ? 0 : 3
+    end
+
     def output_options(opts, options)
       opts.on('-v', '--verbose', 'One line per test, with timings') { options[:verbose] = true }
       opts.on('--show-skips', 'Show skipped tests at the end') { options[:show_skips] = true }
@@ -78,6 +110,13 @@ module PaddedCell
       opts.on('--no-timings', 'Neither read nor write timings') { options[:timings] = nil }
     end
 
+    # The planner takes an unsigned 64-bit seed.
+    def seed(value)
+      raise OptionParser::InvalidArgument, "#{value} (must be 0 to 2**64 - 1)" unless value.between?(0, (2**64) - 1)
+
+      value
+    end
+
     # OptionParser names the switch in the message.
     def positive(value)
       raise OptionParser::InvalidArgument, "#{value} (must be positive)" unless value.positive?
@@ -85,6 +124,22 @@ module PaddedCell
       value
     end
 
+    # "branches,methods" => [:lines, :branches, :methods] (lines always);
+    # "1" or "true" => the defaults; nil, "", "0" or "false" => off.
+    def coverage_criteria(value)
+      value = value.to_s.strip.downcase
+      return if ['', '0', 'false'].include?(value)
+      return Chart::DEFAULT_CRITERIA if %w[1 true].include?(value)
+
+      names = value.split(',').map { it.strip.to_sym }
+      unknown = names - Chart::CRITERIA
+      unless unknown.empty?
+        raise OptionParser::InvalidArgument, "coverage #{unknown.join(',')} (known: #{Chart::CRITERIA.join(', ')})"
+      end
+
+      [:lines] | names
+    end
+
     def shard(value)
       index, count = value.split('/', 2).map { Integer(it, 10, exception: false) }
       unless index && count&.positive? && index.between?(1, count)

data/lib/padded_cell/loader.rb

@@ -53,11 +53,15 @@ module PaddedCell
     end
 
     def call(klass, name)
+      matches_name?(klass, name) && (!@selection.line_filtered? || line_selected?(klass, name))
+    end
+
+    def matches_name?(klass, name)
       id = "#{klass}##{name}"
       return false if @include && !matches?(@include, name, id)
       return false if @exclude && matches?(@exclude, name, id)
 
-      !@selection.line_filtered? || line_selected?(klass, name)
+      true
     end
 
     private

data/lib/padded_cell/pool.rb

@@ -19,12 +19,14 @@ module PaddedCell
     Slot = Struct.new(:worker, :pid, :socket, :test, :started, :batch)
 
     # tests: [[klass, method_name], ...], dispatched by index.
-    def initialize(tests, jobs:, isolation:, seed:, timeout: nil)
+    # coverage: a Chart::Accumulator when measuring coverage
+    def initialize(tests, jobs:, isolation:, seed:, timeout: nil, coverage: nil)
       @tests = tests
       @jobs = jobs
       @isolation = isolation
       @seed = seed
       @timeout = timeout
+      @coverage = coverage
     end
 
     # Runs batches of test indices in order (consuming them), yielding
@@ -47,6 +49,8 @@ module PaddedCell
       shutdown(force: !$!.nil?)
     end
 
+    def success? = @success
+
     # Dispatch nothing more; tests already running still report.
     def stop!
       @queue.clear
@@ -63,7 +67,8 @@ module PaddedCell
         # A worker holding another worker's socket would keep it from ever
         # seeing EOF: keep only its own end.
         [parent, *@sockets].each(&:close)
-        work(slot.worker, child)
+        Worker.new(@tests, isolation: @isolation, seed: @seed, timeout: @timeout, probe: @coverage&.probe)
+              .run(slot.worker, child)
       end
       child.close
       @sockets << parent
@@ -71,45 +76,6 @@ module PaddedCell
       slot
     end
 
-    # The worker process.
-    def work(worker, socket)
-      status = 1
-      begin
-        srand(@seed)
-        setup_error = after_fork(worker)
-        while (line = socket.gets)
-          payload = Results.dump(perform(Integer(line), socket, setup_error))
-          socket.write([payload.bytesize].pack('N'), payload)
-        end
-        Hooks.run_cleanup(worker) unless setup_error
-        status = 0
-      rescue Exception => e # anything: report it, then exit!
-        warn "padded_cell: worker #{worker} failed: #{e.class}: #{e.message}"
-      ensure
-        exit!(status)
-      end
-    end
-
-    # A failing after_fork hook fails every test of the worker, the way Rails
-    # parallel testing reports a broken parallelize_setup.
-    def after_fork(worker)
-      Hooks.run_after_fork(worker)
-      nil
-    rescue StandardError => e
-      e
-    end
-
-    def perform(index, socket, setup_error)
-      klass, name = @tests.fetch(index)
-      if setup_error
-        Results.crashed(klass, name, "after_fork hook failed: #{setup_error.class}: #{setup_error.message}")
-      elsif @isolation == :test
-        Cell.run(klass, name, seed: @seed, timeout: @timeout, close: [socket])
-      else
-        Cell.execute(klass, name)
-      end
-    end
-
     def feed(slot)
       slot.batch = @queue.shift || steal if slot.batch.empty?
       slot.test = slot.batch.shift
@@ -121,6 +87,7 @@ module PaddedCell
       rescue Errno::EPIPE, Errno::ECONNRESET
         # The worker died between tests: its replacement gets this one.
         reap(slot)
+        @coverage&.lost_worker
         spawn(slot).socket.puts(slot.test)
       end
     end
@@ -175,6 +142,7 @@ module PaddedCell
 
     # Reports the running test of a dead worker and starts a new one.
     def replace(slot, message, time)
+      @coverage&.lost_worker
       klass, name = @tests.fetch(slot.test)
       report(slot, Results.crashed(klass, name, message, time:))
       return if @queue.empty? && @slots.all? { it.batch.empty? }
@@ -184,8 +152,16 @@ module PaddedCell
     end
 
     def reap(slot)
+      close_socket(slot)
+      wait_for(slot)
+    end
+
+    def close_socket(slot)
       @sockets.delete(slot.socket)
       slot.socket.close
+    end
+
+    def wait_for(slot)
       _, status = Process.wait2(slot.pid)
       slot.pid = nil
       status
@@ -196,7 +172,8 @@ module PaddedCell
     def shutdown(force:)
       live = Array(@slots).select(&:pid)
       live.each { Process.kill(:KILL, it.pid) } if force
-      live.each { reap(it) }
+      live.each { close_socket(it) }
+      @success = live.map { wait_for(it) }.all?(&:success?)
     end
   end
 end

data/lib/padded_cell/reporters.rb

@@ -36,6 +36,12 @@ module PaddedCell
       end
 
       def relative(file) = file.delete_prefix("#{Dir.pwd}/")
+
+      # --asylum's report on a test that passed on retry, if it did.
+      def flaky(result) = result.metadata? ? result.metadata[:flaky] : nil
+
+      # --asylum's attempts at a test that never passed.
+      def asylum(result) = result.metadata? ? result.metadata[:asylum] : nil
     end
 
     # JUnit XML, as read by GitHub, GitLab, Jenkins and friends.
@@ -67,10 +73,20 @@ module PaddedCell
         file, line = file_and_line(result)
         attributes = %(classname="#{escape(result.klass)}" name="#{escape(result.name)}" file="#{escape(file)}" ) +
                      %(line="#{line}" time="#{format('%.6f', result.time)}" assertions="#{result.assertions}")
-        body = outcome(result)
+        body = outcome(result) + flaky_failure(result)
         body.empty? ? %(    <testcase #{attributes}/>\n) : %(    <testcase #{attributes}>\n#{body}    </testcase>\n)
       end
 
+      # Surefire's element for a test that failed, then passed on retry.
+      def flaky_failure(result)
+        info = flaky(result)
+        return '' unless info
+
+        first = info[:first_failure]
+        %(      <flakyFailure type="#{escape(first[:type])}" message="#{escape(first[:message])}">) +
+          %(#{escape(info[:cause])}</flakyFailure>\n)
+      end
+
       def outcome(result)
         failure = result.failure
         case status(result)
@@ -98,8 +114,9 @@ module PaddedCell
         {
           id: "#{result.klass}##{result.name}", class: result.klass, name: result.name, file:, line:,
           status: status(result), time: result.time, assertions: result.assertions,
-          failures: result.failures.map { { type: it.result_label, message: it.message.scrub } }
-        }
+          failures: result.failures.map { { type: it.result_label, message: it.message.scrub } },
+          flaky: flaky(result), asylum: asylum(result)
+        }.compact
       end
     end
   end

data/lib/padded_cell/results.rb

@@ -74,6 +74,19 @@ module PaddedCell
       placeholders << [owner, last]
     end
 
+    # What a cell sends its worker: its coverage delta (nil without
+    # coverage) beside its result. The outer layer holds only core types, so
+    # it loads even when the result does not.
+    def envelope(delta, result) = Marshal.dump([delta, dump(result)])
+
+    # [delta, result] from an envelope; never raises.
+    def unwrap(data, klass, name)
+      delta, payload = Marshal.load(data) # written by our own cell
+      [delta, load(payload, klass, name)]
+    rescue StandardError => e
+      [nil, crashed(klass, name, "its result could not be loaded: #{e.class}: #{e.message}")]
+    end
+
     # Marshal.dump, after replacing failures that cannot cross a pipe (an
     # exception holding a Proc, an IO...) with plain copies.
     def dump(result)

data/lib/padded_cell/runner.rb

@@ -5,7 +5,9 @@ require 'minitest'
 require_relative '../padded_cell'
 require_relative 'results'
 require_relative 'cell'
+require_relative 'worker'
 require_relative 'pool'
+require_relative 'asylum'
 require_relative 'loader'
 require_relative 'timings'
 require_relative 'reporters'
@@ -18,8 +20,9 @@ module PaddedCell
   class Runner
     DEFAULTS = {
       paths: [], jobs: Etc.nprocessors, seed: nil, include: nil, exclude: nil, shard: [0, 1],
-      isolation: nil, timeout: nil, fail_fast: false, verbose: false, show_skips: false,
-      list: false, junit: nil, json: nil, timings: 'tmp/padded_cell/timings.tsv', io: $stdout
+      isolation: nil, timeout: nil, asylum: nil, fail_fast: false, verbose: false, show_skips: false,
+      list: false, junit: nil, json: nil, timings: 'tmp/padded_cell/timings.tsv', coverage: nil,
+      coverage_dir: nil, io: $stdout
     }.freeze
 
     attr_reader :options
@@ -29,33 +32,52 @@ module PaddedCell
       @options[:seed] ||= (ENV['SEED'] || Random.new_seed).to_i % 0xFFFF
     end
 
-    # Exit status: 0 when everything passed, 1 otherwise, 130 on Ctrl-C.
+    # Exit status: 0 when everything passed, 1 otherwise, 3 when only
+    # coverage is below a minimum, 130 on Ctrl-C.
     def run
       selection = Selection.parse(options[:paths])
       refs = Discovery.call(selection.files)
-      return list(selection, refs) if options[:list]
+      filter = Filter.new(selection, refs, include: options[:include], exclude: options[:exclude])
+      return list(selection, refs, filter) if options[:list]
       raise Unsupported, 'padded_cell needs fork, which this Ruby does not have' unless Process.respond_to?(:fork)
 
+      @coverage = start_coverage if options[:coverage]
       Loader.call(selection.files, seed: options[:seed])
+      refuse_simplecov if @coverage
       if defined?(ActiveSupport::TestCase)
         require_relative 'active_support_hooks'
         ActiveSupportHooks.install
       end
       options[:isolation] ||= default_isolation
-      filter = Filter.new(selection, refs, include: options[:include], exclude: options[:exclude])
+      # Coverage thresholds hold for the whole suite only.
+      @whole = !selection.line_filtered? && !options[:include] && !options[:exclude]
       execute(Loader.tests.select { filter.call(*it) })
     end
 
     private
 
+    # Before the suite loads: nothing loaded earlier is measured.
+    def start_coverage
+      require_relative 'chart'
+      Chart::Accumulator.new(options[:coverage]).start
+    end
+
+    # Two tools cannot share Ruby's Coverage.
+    def refuse_simplecov
+      return unless defined?(::SimpleCov) && ::SimpleCov.respond_to?(:pid) && ::SimpleCov.pid
+
+      raise Unsupported, 'SimpleCov is running, and --coverage replaces it: remove SimpleCov.start (and any ' \
+                         'SimpleCov.result in parallelize_teardown) from the test helper'
+    end
+
     # A fork per test discards Active Record's connection pool, and with it
     # the fixtures loaded through it: every test would reload them. With
     # fixtures around, tests share their worker instead.
     def default_isolation = defined?(ActiveRecord::FixtureSet) ? :worker : :test
 
     # Tests as they would run (static discovery, no loading), in file order.
-    def list(selection, refs)
-      refs = refs.select { selection.covers?(it.file, it.lines) }
+    def list(selection, refs, filter)
+      refs = refs.select { selection.covers?(it.file, it.lines) && filter.matches_name?(it.class_name, it.name) }
       kept = Scheduler.batches(refs.map(&:class_name), seed: options[:seed], shard: options[:shard]).flatten.sort
       kept.each do |index|
         ref = refs[index]
@@ -69,37 +91,112 @@ module PaddedCell
       timings = Timings.load(options[:timings])
       batches = Scheduler.batches(tests.map { |klass, _| klass.to_s }, durations: ids.map { timings[it] },
                                                                       seed: options[:seed], shard: options[:shard])
+      nothing_ran = batches.empty?
       reporter = build_reporter
       reporter.start
-      interrupted = dispatch(tests, batches, reporter) { |index, result| timings[ids[index]] = result.time }
+      retried = []
+      @coverage&.snapshot
+      status = dispatch(tests, batches, reporter, retried) { |index, result| timings[ids[index]] = result.time }
       reporter.report
+      report_asylum(retried)
+      covered = @coverage ? report_coverage(status, reporter) : true
       Timings.save(options[:timings], timings)
       after_run
-      finish(reporter, interrupted, batches.empty?)
+      result = finish(reporter, status, nothing_ran)
+      result.zero? && !covered ? 3 : result
     end
 
-    # Yields each result after reporting it. True when interrupted.
-    def dispatch(tests, batches, reporter)
-      pool = nil
-      on_result = lambda do |index, result|
+    # Writes the coverage reports, even for a failing run; false when the
+    # coverage of a whole, passing, complete run is below a minimum.
+    def report_coverage(status, reporter)
+      raw = @coverage.finish(interrupted: status == 130)
+      return true unless raw
+
+      dir = options[:coverage_dir] || Chart.config.directory
+      document = Chart::Document.build(raw, config: Chart.config, shard: options[:shard], whole: @whole)
+      document.write(dir)
+      check = status.zero? && reporter.passed? && document.complete?
+      Chart::Report.new(document, dir:, io: options[:io]).call(check:)
+    end
+
+    # Yields each result as it arrives. With --asylum a failure is held back:
+    # only its final result, after the retries, is reported. Returns 1 when a
+    # worker failed (its cleanup hook), 130 when interrupted, 0 otherwise.
+    def dispatch(tests, batches, reporter, retried)
+      held = {}
+      record = lambda do |index, result|
         reporter.prerecord(*tests[index])
         reporter.record(result)
-        yield index, result
-        pool&.stop! if options[:fail_fast] && !result.passed? && !result.skipped?
+        retried << result if result.metadata? && (result.metadata[:flaky] || result.metadata[:asylum])
       end
       pool = Pool.new(tests, jobs: options[:jobs], isolation: options[:isolation], seed: options[:seed],
-                             timeout: options[:timeout])
-      pool.run(batches, &on_result)
-      false
+                             timeout: options[:timeout], coverage: @coverage)
+      pool.run(batches) do |index, result|
+        yield index, result
+        failed = failed?(result)
+        options[:asylum] && failed ? held[index] = result : record.call(index, result)
+        pool.stop! if options[:fail_fast] && failed
+      end
+      retries_ok = retry_held(tests, held, record)
+      pool.success? && retries_ok ? 0 : 1
     rescue Interrupt
       warn 'Interrupted. Exiting...'
-      true
+      # Failures still waiting for a retry are failures.
+      held.each { |index, result| record.call(index, result) }
+      130
+    end
+
+    # False when a retry's worker failed.
+    def retry_held(tests, held, record)
+      return true if held.empty?
+
+      asylum = Asylum.new(tests, attempts: options[:asylum], seed: options[:seed], timeout: options[:timeout])
+      asylum.call(held) do |index, result|
+        held.delete(index)
+        record.call(index, result)
+      end
+      asylum.success?
+    end
+
+    def failed?(result) = !result.passed? && !result.skipped?
+
+    # After Minitest's summary: what --asylum found, attempt by attempt.
+    def report_asylum(retried)
+      flaky, failing = retried.partition { it.metadata[:flaky] }
+      report_flaky(flaky) if flaky.any?
+      report_failing(failing) if failing.any?
+    end
+
+    def report_flaky(flaky)
+      io = options[:io]
+      tests = flaky.size == 1 ? '1 test' : "#{flaky.size} tests"
+      io.puts "\nYou're not crazy, the world is. #{tests} failed, then passed:"
+      width = flaky.flat_map { it.metadata[:flaky][:history] }.map { it[:seed].to_s.size }.max
+      flaky.each do |result|
+        info = result.metadata[:flaky]
+        io.puts "\n  #{result.klass}##{result.name}"
+        info[:history].each do |attempt|
+          io.puts "    seed #{attempt[:seed].to_s.ljust(width)}  #{attempt_line(attempt, info[:cause])}"
+        end
+      end
+    end
+
+    def attempt_line(attempt, cause)
+      return "passed, alone → #{cause}" if attempt[:outcome] == 'passed'
+
+      attempt[:alone] ? "#{attempt[:outcome]} (alone)" : attempt[:outcome]
+    end
+
+    def report_failing(failing)
+      io = options[:io]
+      io.puts "\nIt's not the world, it's the test:"
+      failing.each { io.puts "  #{it.klass}##{it.name} failed all #{it.metadata[:asylum][:attempts]} attempts" }
     end
 
     def build_reporter
       reporter = Minitest::CompositeReporter.new
       minitest_options = {
-        io: options[:io], seed: options[:seed], args: "--seed #{options[:seed]} --isolation #{options[:isolation]}",
+        io: options[:io], seed: options[:seed], args: run_options,
         verbose: options[:verbose], show_skips: options[:show_skips]
       }
       reporter << Minitest::SummaryReporter.new(options[:io], minitest_options)
@@ -113,13 +210,19 @@ module PaddedCell
       reporter
     end
 
+    # What a rerun needs to reproduce this run's order and settings.
+    def run_options
+      args = "--seed #{options[:seed]} --isolation #{options[:isolation]}"
+      options[:asylum] ? "#{args} --asylum=#{options[:asylum]}" : args
+    end
+
     # Minitest.after_run blocks, which autorun would have called.
     def after_run
       Minitest.class_variable_get(:@@after_run).reverse_each(&:call)
     end
 
-    def finish(reporter, interrupted, nothing_ran)
-      return 130 if interrupted
+    def finish(reporter, status, nothing_ran)
+      return status unless status.zero?
       if nothing_ran && options[:include]
         warn "Nothing ran for filter: #{options[:include]}"
         return 1

data/lib/padded_cell/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PaddedCell
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/padded_cell/worker.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  # A Pool's worker process. Reads test indices from its socket, runs each
+  # (in a Cell, or itself with isolation :worker) and writes back its
+  # Minitest::Result as a length-prefixed Marshal frame. Exits once the
+  # socket closes.
+  class Worker
+    # probe: a Chart::Probe when measuring coverage
+    def initialize(tests, isolation:, seed:, timeout:, probe:)
+      @tests = tests
+      @isolation = isolation
+      @seed = seed
+      @timeout = timeout
+      @probe = probe
+    end
+
+    # Never returns.
+    def run(worker, socket)
+      status = 1
+      begin
+        srand(@seed)
+        @probe&.start
+        setup_error = after_fork(worker)
+        while (line = socket.gets)
+          payload = Results.dump(perform(Integer(line), socket, setup_error))
+          socket.write([payload.bytesize].pack('N'), payload)
+          @probe&.tick
+        end
+        # Before cleanup, which may stop Coverage.
+        @probe&.flush
+        Hooks.run_cleanup(worker) unless setup_error
+        status = 0
+      rescue Exception => e # anything: report it, then exit!
+        warn "padded_cell: worker #{worker} failed: #{e.class}: #{e.message}"
+      ensure
+        exit!(status)
+      end
+    end
+
+    private
+
+    # A failing after_fork hook fails every test of the worker, the way Rails
+    # parallel testing reports a broken parallelize_setup.
+    def after_fork(worker)
+      Hooks.run_after_fork(worker)
+      nil
+    rescue StandardError => e
+      e
+    end
+
+    def perform(index, socket, setup_error)
+      klass, name = @tests.fetch(index)
+      if setup_error
+        Results.crashed(klass, name, "after_fork hook failed: #{setup_error.class}: #{setup_error.message}")
+      elsif @isolation == :test
+        Cell.run(klass, name, seed: @seed, timeout: @timeout, close: [socket], probe: @probe)
+      else
+        Cell.execute(klass, name)
+      end
+    end
+  end
+end

data/lib/padded_cell.rb

@@ -23,6 +23,14 @@ module PaddedCell
     def after_fork(&) = Hooks.after_fork(&)
 
     def cleanup(&) = Hooks.cleanup(&)
+
+    # Configures the coverage report (see Chart::Config). Inert unless
+    # padded_cell runs with --coverage. A helper also run without
+    # padded_cell guards it: `if defined?(PaddedCell.coverage)`.
+    def coverage(profile = nil, &)
+      require_relative 'padded_cell/chart'
+      Chart.configure(profile, &)
+    end
   end
 end