padded_cell 0.1.0-aarch64-linux-gnu → 0.3.0-aarch64-linux-gnu

data/lib/padded_cell/pool.rb

@@ -13,18 +13,34 @@ module PaddedCell
   #
   # With isolation :test a worker forks a Cell per test; with :worker it runs
   # tests itself, faster but sharing process state. A worker that dies
-  # mid-test, or runs past the timeout, gets its test reported as an error and
-  # is replaced; its replacement continues the class.
+  # mid-test, or runs past its deadline (--timeout, --budget), gets its test
+  # reported as an error and is replaced; its replacement continues the class.
+  #
+  # Replaced, up to a point: workers that keep dying (a boot that segfaults,
+  # an after_fork hook that exits) would turn every remaining test into a
+  # crash report. Past PaddedCellNative::Restarts' limit the pool gives up.
+  # Once the run's budget is spent, it dispatches nothing more.
   class Pool
-    Slot = Struct.new(:worker, :pid, :socket, :test, :started, :batch)
+    Slot = Struct.new(:worker, :pid, :socket, :test, :started, :batch, :deadline)
+
+    # Tests left undispatched by stop! (--fail-fast, the budget, giving up).
+    attr_reader :undispatched
+
+    # Why the pool gave up on its workers, or nil.
+    attr_reader :gave_up
 
     # tests: [[klass, method_name], ...], dispatched by index.
-    def initialize(tests, jobs:, isolation:, seed:, timeout: nil)
+    # limits: the run's Limits
+    # coverage: a Chart::Accumulator when measuring coverage
+    def initialize(tests, jobs:, isolation:, seed:, limits: Limits.new, coverage: nil)
       @tests = tests
       @jobs = jobs
       @isolation = isolation
       @seed = seed
-      @timeout = timeout
+      @limits = limits
+      @coverage = coverage
+      @restarts = PaddedCellNative::Restarts.new(jobs)
+      @undispatched = 0
     end
 
     # Runs batches of test indices in order (consuming them), yielding
@@ -34,7 +50,7 @@ module PaddedCell
       @on_result = on_result
       @sockets = []
       Hooks.run_before_fork
-      @slots = Array.new([@jobs, batches.sum(&:size)].min) { spawn(Slot.new(it, nil, nil, nil, nil, [])) }
+      @slots = Array.new([@jobs, batches.sum(&:size)].min) { spawn(Slot.new(it, nil, nil, nil, nil, [], nil)) }
       @slots.each { feed(it) }
       loop do
         busy = @slots.select(&:test)
@@ -47,8 +63,11 @@ module PaddedCell
       shutdown(force: !$!.nil?)
     end
 
+    def success? = @success
+
     # Dispatch nothing more; tests already running still report.
     def stop!
+      @undispatched += @queue.sum(&:size) + @slots.sum { it.batch.size }
       @queue.clear
       @slots.each { it.batch.clear }
     end
@@ -63,7 +82,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, limits: @limits, probe: @coverage&.probe)
+              .run(slot.worker, child)
       end
       child.close
       @sockets << parent
@@ -71,57 +91,26 @@ 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)
+      return stop! if @limits.spent?
+
       slot.batch = @queue.shift || steal if slot.batch.empty?
       slot.test = slot.batch.shift
       return unless slot.test
 
       slot.started = Minitest.clock_time
+      slot.deadline = @limits.for_test
       begin
         slot.socket.puts(slot.test)
       rescue Errno::EPIPE, Errno::ECONNRESET
-        # The worker died between tests: its replacement gets this one.
+        # The worker died between tests: its replacement gets this one, unless
+        # it dies too. Restarts bounds the retries.
         reap(slot)
-        spawn(slot).socket.puts(slot.test)
+        @coverage&.lost_worker
+        return abandon(slot) unless @restarts.died(Limits.now)
+
+        spawn(slot)
+        retry
       end
     end
 
@@ -132,17 +121,24 @@ module PaddedCell
     end
 
     def receive(slot)
-      header = slot.socket.read(4)
+      header = read_frame(slot, 4)
       return died(slot) unless header&.bytesize == 4
 
       size = header.unpack1('N')
-      payload = slot.socket.read(size)
+      payload = read_frame(slot, size)
       return died(slot) unless payload&.bytesize == size
 
       report(slot, Results.load(payload, *@tests.fetch(slot.test)))
       feed(slot)
     end
 
+    # nil when the worker died: EOF, or a reset when it left data unread.
+    def read_frame(slot, size)
+      slot.socket.read(size)
+    rescue Errno::ECONNRESET
+      nil
+    end
+
     def report(slot, result)
       index = slot.test
       slot.test = nil
@@ -151,32 +147,51 @@ module PaddedCell
 
     def died(slot)
       status = reap(slot)
+      give_up unless @restarts.died(Limits.now)
       replace(slot, Results.describe(status, 'worker'), Minitest.clock_time - slot.started)
     end
 
-    # Cells time out inside their worker; with :worker isolation the runner
-    # kills the worker itself.
+    # Stops replacing workers: whatever was not dispatched is not run.
+    def give_up
+      window = PaddedCellNative::Restarts.window_ns / Limits::NS
+      @gave_up = "workers died more than #{@restarts.limit} times in #{window}s"
+      stop!
+    end
+
+    # A test taken for a worker that died before receiving it, and is not
+    # replaced.
+    def abandon(slot)
+      slot.test = nil
+      @undispatched += 1
+      give_up
+    end
+
+    # Cells meet their deadline inside their worker; with :worker isolation
+    # the runner kills the worker itself.
     def wait_time(busy)
-      return unless @timeout && @isolation == :worker
+      return unless @isolation == :worker
 
-      deadline = busy.map { it.started + @timeout }.min
-      [deadline - Minitest.clock_time, 0].max
+      now = Limits.now
+      busy.filter_map { Limits.remaining(it.deadline, now) }.min
     end
 
     def expire(busy)
+      now = Limits.now
       busy.each do |slot|
-        next if Minitest.clock_time - slot.started < @timeout
+        next unless slot.deadline.expired?(now)
 
         Process.kill(:KILL, slot.pid)
         reap(slot)
-        replace(slot, "timed out after #{@timeout}s", @timeout)
+        replace(slot, @limits.message(slot.deadline), Minitest.clock_time - slot.started)
       end
     end
 
     # 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:))
+      stop! if @limits.spent?
       return if @queue.empty? && @slots.all? { it.batch.empty? }
 
       spawn(slot)
@@ -184,8 +199,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 +219,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

@@ -4,8 +4,11 @@ require 'etc'
 require 'minitest'
 require_relative '../padded_cell'
 require_relative 'results'
+require_relative 'limits'
 require_relative 'cell'
+require_relative 'worker'
 require_relative 'pool'
+require_relative 'asylum'
 require_relative 'loader'
 require_relative 'timings'
 require_relative 'reporters'
@@ -18,8 +21,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, budget: 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 +33,54 @@ 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
+      # The budget covers the whole run, loading included.
+      @limits = Limits.new(timeout: options[:timeout], budget: options[:budget])
       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 +94,134 @@ 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
+
+    # 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 after reporting it. True when interrupted.
-    def dispatch(tests, batches, reporter)
-      pool = nil
-      on_result = lambda do |index, result|
+    # 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) or tests were left out (the budget ran
+    # out, workers kept dying), 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
+                             limits: @limits, 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
+      complete = report_left_out(pool)
+      retries_ok = retry_held(tests, held, record)
+      pool.success? && retries_ok && complete ? 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 tests never ran because the budget ran out or workers kept
+    # dying. --fail-fast leaving them out is what it asked for.
+    def report_left_out(pool)
+      left_out = pool.undispatched
+      if pool.gave_up
+        warn "padded_cell: #{pool.gave_up}; gave up, #{left_out} tests not run"
+      elsif @limits.spent? && left_out.positive?
+        warn "padded_cell: run budget of #{@limits.budget}s spent, #{left_out} tests not run"
+      else
+        return true
+      end
+      false
+    end
+
+    # False when a retry's worker failed.
+    def retry_held(tests, held, record)
+      return true if held.empty?
+
+      # No budget left to retry in: failures stay failures.
+      if @limits.spent?
+        held.each { |index, result| record.call(index, result) }
+        return true
+      end
+
+      asylum = Asylum.new(tests, attempts: options[:asylum], seed: options[:seed], limits: @limits)
+      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 +235,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.3.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
+    # limits: the run's Limits; probe: a Chart::Probe when measuring coverage
+    def initialize(tests, isolation:, seed:, limits:, probe:)
+      @tests = tests
+      @isolation = isolation
+      @seed = seed
+      @limits = limits
+      @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, limits: @limits, 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