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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eacdeae4029e071ca2835526dead187b93a4807f90affc3fa608b8c357abb7d7
-  data.tar.gz: 23fb4f79f2a5780a3f00fe2880498127a87e639cd030336d0098b022d19fb970
+  metadata.gz: d938c3e531357727a22bf6a2759c2f381960729f309ce98c54474087cc5e7599
+  data.tar.gz: 6f91994847f2b887ddd3523c71e1c197028d529a55a9b2726f8146afcd847cb3
 SHA512:
-  metadata.gz: 157b8fc9134ee65732f2e8121536416a296ae8a4f1ad069938622ed3585b20738c2cdbfab8973ec5295ef71720aadd406edf47c842a44bf9479aca5426c8032f
-  data.tar.gz: 4fb70f06c36989630f370ffe58ec7b65ba510227646041573a080d05b1493add583bb3596978104036e4a88a7b302f247c09a2914d3b08cad0d150a44f3c3958
+  metadata.gz: 703c85c4e53f4c03c6b068e688b459d0b279e3ad80117075e3ded0e342b73383975f4632bbb4694d48d6c8e5e2fe8233b7839efc7df53ee2f2e5ffb904157ab0
+  data.tar.gz: f9d6f0dbd6e472529eabe4c82bccb669295957fcaad2c7319b2a2d8136267a52986b8e4c1dabf2ed9c71e70d1da1d79839ba9c3abbfdf5bd5c0e561a0b3e02ec

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.2.0 (2026-10-11)
+
+- Built-in coverage: `--coverage[=lines,branches,methods,eval]` (or
+  `PADDED_CELL_COVERAGE`) measures the runner, every worker and every cell,
+  and sums them exactly. Configured with `PaddedCell.coverage` in the test
+  helper: tracked files, filters, groups, the `:rails` profile. Honors
+  `# :nocov:` blocks and `# simplecov:disable` comments. Writes
+  `coverage.md` (the code that never ran, for agents, reviews and CI
+  summaries), `lcov.info`, and `coverage.json` / `.resultset.json`.
+  `minimum`, `minimum_by_file`, `minimum_by_group` and `maximum_drop` fail a
+  whole passing run with exit 3. `--coverage-merge` merges shards' reports.
+- `--seed` must be 0 to 2**64 - 1; others crashed the planner.
+- `--asylum[=N]`: retry failed tests (N times, default 2) after the run,
+  alone and in fresh cells. Tests that pass on retry count as passed and are
+  reported as flaky, with the likely cause (timing and shared state, or
+  randomness and order) and their first failure; JUnit gets
+  `<flakyFailure>`, JSON a `flaky` field.
+- A `cleanup` hook that raises fails the run (exit 1), `--asylum` retries
+  included. It exited 0 when the tests passed.
+- A passing run filtered with `--name` exits 0: it exited 1, reporting that
+  nothing ran.
+- `--list` applies `--name` and `--exclude`, before `--shard`, as a run does.
+- An invalid `--name` or `--exclude` regexp is a usage error (exit 2), not a
+  crash.
+
 ## 0.1.0 (2026-10-11)
 
 First release, for CRuby 4.0+ and Minitest 6 on Linux, macOS and FreeBSD: a

data/README.md

@@ -70,13 +70,15 @@ $ padded_cell -n /refund/ -e test_slow     # Minitest's --include / --exclude
 $ padded_cell -j 8 --seed 1234             # 8 workers, reproducible order
 $ padded_cell --timeout 30                 # kill and fail anything running 30s
 $ padded_cell --fail-fast
+$ padded_cell --asylum                     # retry failures; report the flaky ones (see below)
 $ padded_cell --list                       # what would run, without loading anything
 $ padded_cell --shard 2/4                  # CI: the second quarter of the classes
 $ padded_cell --junit tmp/junit.xml --json tmp/results.jsonl
+$ padded_cell --coverage                   # line and branch coverage (see Coverage)
 ```
 
 Exit status: 0 when everything passed, 1 otherwise, 2 for usage or load
-errors, 130 when interrupted.
+errors, 3 when only coverage is below a threshold, 130 when interrupted.
 
 ### How a run works
 
@@ -113,6 +115,38 @@ discards Active Record's connection pool, and every test would reload its
 fixtures, so those suites default to `worker`. The `Run options:` line shows
 which one a run uses; `--isolation` overrides it.
 
+### Flaky tests
+
+`--asylum[=N]` gives failed tests up to N more attempts (default 2) once the
+run is over: one test at a time, each in a fresh cell. A test that passes on
+retry counts as passed, but padded_cell shows every attempt, its seed, and
+what made the difference:
+
+```console
+4 runs, 4 assertions, 1 failures, 0 errors, 0 skips
+
+You're not crazy, the world is. 2 tests failed, then passed:
+
+  FlakyTest#test_passes_when_retried
+    seed 1      lost the race
+    seed 1      passed, alone → timing, contention or state left by other tests
+
+  FlakyTest#test_depends_on_the_seed
+    seed 1      unlucky seed.
+    seed 1      unlucky seed. (alone)
+    seed 15472  passed, alone → randomness or test order
+
+It's not the world, it's the test:
+  FlakyTest#test_always_fails failed all 3 attempts
+```
+
+The first retry keeps the run's seed and runs alone, so passing there points
+at timing, contention or leftover state; later retries change the seed, so
+passing only there points at randomness or order. A test that fails every
+attempt keeps its first failure, and the run fails. JUnit reports carry a
+`<flakyFailure>` per flaky test; JSON lines carry the attempts in a `flaky`
+field, or an `asylum` field for a test that never passed.
+
 ### Hooks
 
 For anything that must not be shared across forks:
@@ -125,7 +159,115 @@ PaddedCell.cleanup { |worker| Database.drop("app_test_#{worker}") }
 ```
 
 `before_fork` runs in the runner, `after_fork` and `cleanup` once per worker
-(`0...jobs`). Cells run no hooks: they inherit their worker's state.
+(`0...jobs`). Cells run no hooks: they inherit their worker's state. A
+failing `after_fork` fails every test of its worker; a failing `cleanup`
+fails the run, even when every test passed.
+
+## Coverage
+
+Ruby's `Coverage`, measured in the runner, in every worker and in every
+cell, and summed exactly: a parallel run reports the counts of a serial one.
+
+```console
+$ padded_cell --coverage test/                         # lines and branches
+$ padded_cell --coverage=lines,branches,methods test/
+$ PADDED_CELL_COVERAGE=1 bin/rails padded_cell
+```
+
+Measuring starts before the suite loads, so what is measured (`lines`,
+`branches`, `methods`, and `eval` for templates, experimental) comes from the
+command line. The report is configured in the test helper:
+
+```ruby
+# test/test_helper.rb
+PaddedCell.coverage(:rails) do
+  track "{app,lib}/**/*.rb"           # report files never loaded, at 0%
+  skip "app/legacy/"                  # also `filter`
+  group "Operations", "app/concepts"  # string, regexp, array or block
+  group("Contracts") { |file| file.filename.include?("contract") }
+  minimum line: 90, branch: 80
+  minimum_by_file line: 50
+  minimum_by_group "Operations", line: 95
+  maximum_drop line: 1                # since the previous whole run
+  formats :markdown, :lcov, :json
+  dir "coverage"                      # --coverage-dir wins
+end
+```
+
+- Paths are matched relative to the project root. A string matches whole
+  path segments (`"app/models"` takes `app/models/user.rb`, not
+  `app/models_old/`), `"lib/"` a directory anywhere, `"contract.rb"` a file
+  name ending; a regexp matches the path; a block gets the file
+  (`filename`, `project_filename`, `src`).
+- Left out by default: `vendor/bundle`, hidden files, `test/`, `spec/`,
+  `features/`. `clear_filters` drops these.
+- `:rails` skips `config/` and `db/`, groups `app/channels`,
+  `app/controllers`, `app/helpers`, `app/jobs` and `app/workers`, `lib/`,
+  `app/mailers`, `app/models` and `app/views`, and tracks
+  `{app,lib}/**/*.rb`. A file in no group is Ungrouped.
+- Thresholds compare percents floored to 2 decimals.
+
+`PaddedCell.coverage` configures only; without `--coverage` nothing is
+measured. Outside padded_cell, guard it with `if defined?(PaddedCell.coverage)`.
+
+Into `coverage/` go, by format:
+
+- `markdown`: `coverage.md`, for agents, reviews and CI summaries
+  (`cat coverage/coverage.md >> $GITHUB_STEP_SUMMARY`): the totals and
+  groups, then every file with code that never ran, the most missed first,
+  with its missed lines, branches and methods, and that code. It stops
+  listing files at 1 MB, the size of a GitHub job summary.
+- `lcov`: `lcov.info` (`SF:./path`), for CI and editors.
+- `json`: `coverage.json` and `.resultset.json`, in SimpleCov's formats, for
+  the tools reading them.
+
+Also, every run: `.padded_cell.json` (what the report is made of, and what
+`--coverage-merge` reads), and after a whole passing run `.last_run.json`.
+
+Lines and branches inside `# :nocov:` blocks, and under
+`# simplecov:disable [line|branch|method]` / `# simplecov:enable` comments,
+are skipped. A directive after code skips its own line.
+
+A run below a threshold exits 3. Thresholds hold for a whole, passing,
+complete run only: they are not checked when tests failed, when tests were
+picked by name or line, under `--shard`, or when a worker or cell died
+before handing over what it measured (the report then says it is partial).
+Reports are written either way, failing runs included.
+
+A suite that starts SimpleCov as well is refused (exit 2): two tools cannot
+share Ruby's `Coverage`.
+
+### Shards
+
+Each shard reports on its own; merge them, at the same commit, without
+running anything:
+
+```console
+$ padded_cell --coverage --coverage-dir coverage/1 --shard 1/2 test/   # machine 1
+$ padded_cell --coverage --coverage-dir coverage/2 --shard 2/2 test/   # machine 2
+$ padded_cell --coverage-merge coverage/1,coverage/2 --coverage-dir coverage
+```
+
+The merge refuses files that differ between shards or from the checkout,
+and checks thresholds when every shard of the run is there. Lines that run
+while the suite loads count once per shard.
+
+### Cost
+
+Measuring is opt-in: Ruby's instrumentation slows tests down. On a Rails
+suite of 6,300 tests, lines and branches took the run from 465 s to 638 s of
+CPU.
+
+A worker hands over what it measured every 10 seconds or more: each time,
+Ruby copies the coverage of every file it loaded, gems included (a few
+milliseconds in a small app, a few hundred in a big Rails one), so the
+interval stretches to keep this under 1% of the worker's time. A worker that
+dies loses what it measured since. With `--isolation test` every cell pays
+one such copy, at its end.
+
+Files never loaded report their branches in the order Ruby compiles them.
+With `eval`, code that `class_eval` runs from a heredoc counts as lines of
+its file; directives in templates are not read.
 
 ## Rails
 
@@ -144,8 +286,7 @@ $ bin/rails padded_cell ARGS="-j 8 test/models"
 Rails suites with fixtures run with `--isolation worker` unless told
 otherwise (see [Isolation](#isolation)).
 
-Coverage tools that write their results from an `at_exit` hook (SimpleCov)
-see only the runner, as with Rails' process parallelization.
+For coverage, see [Coverage](#coverage).
 
 ## Library
 
@@ -173,9 +314,9 @@ Needs Rust 1.99+ (`mise install` reads `mise.toml`).
 
 ```console
 bundle install
-rake test:all        # cargo test, then the Ruby suite (compiles the extension first)
-rake test            # the Ruby suite only
-rake dogfood         # this suite, run by padded_cell
+rake test:all        # cargo test, then this suite run by padded_cell itself
+rake dogfood         # this suite, run by padded_cell (compiles the extension first)
+rake test            # this suite on plain Minitest, for when padded_cell itself is broken
 rake lint            # dictator, cargo fmt --check, clippy
 ```
 

data/lib/padded_cell/asylum.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  # --asylum: tests that failed get more attempts once the run is over, one
+  # at a time, each in a fresh cell. A test that passes on retry counts as
+  # passed but is reported as flaky, with every attempt and what changed:
+  #
+  #   attempt 1, same seed, run alone:  timing, contention, or state left by
+  #                                     the tests that ran around it
+  #   attempt 2+, another seed:         randomness or test order
+  #
+  # A test that fails every attempt keeps its first failure.
+  class Asylum
+    ALONE = 'timing, contention or state left by other tests'
+    RESEEDED = 'randomness or test order'
+
+    # The seed of retry attempt, derived from the run's seed so a report can
+    # be replayed. Attempt 1 keeps the run's seed.
+    def self.retry_seed(seed, attempt)
+      attempt == 1 ? seed : (seed + (attempt * 0x9e37)) % 0xffff
+    end
+
+    def initialize(tests, attempts:, seed:, timeout: nil)
+      @tests = tests
+      @attempts = attempts
+      @seed = seed
+      @timeout = timeout
+      @success = true
+    end
+
+    # False when a retry's worker failed (its cleanup hook).
+    def success? = @success
+
+    # failures: {test index => first failing result}. Yields (index, result)
+    # once per test, with its final result. Its metadata holds the attempts:
+    # :flaky when it passed on retry, :asylum when it never did. Both are
+    # plain data, for Marshal and the JUnit and JSON reports.
+    def call(failures)
+      history = failures.to_h { |index, result| [index, [attempt_entry(@seed, false, result)]] }
+      pending = failures.keys
+      1.upto(@attempts) do |attempt|
+        break if pending.empty?
+
+        pending -= retry_round(pending, history, attempt) do |index, result|
+          result.metadata[:flaky] = flaky(failures[index], history[index], attempt)
+          yield index, result
+        end
+      end
+      pending.each do |index|
+        failures[index].metadata[:asylum] = { attempts: history[index].size, history: history[index] }
+        yield index, failures[index]
+      end
+    end
+
+    private
+
+    # Runs the pending tests once more, alone; returns the ones that passed.
+    def retry_round(pending, history, attempt)
+      seed = self.class.retry_seed(@seed, attempt)
+      passed = []
+      pool = Pool.new(@tests, jobs: 1, isolation: :test, seed:, timeout: @timeout)
+      pool.run([pending.dup]) do |index, result|
+        recovered = result.passed? && !result.skipped?
+        history[index] << attempt_entry(seed, true, recovered ? nil : result)
+        next unless recovered
+
+        passed << index
+        yield index, result
+      end
+      @success &&= pool.success?
+      passed
+    end
+
+    # One attempt: its seed, whether it ran alone, and how it ended.
+    def attempt_entry(seed, alone, failed)
+      { seed:, alone:, outcome: failed ? summary(failed.failure)[:message] : 'passed' }
+    end
+
+    def flaky(first, history, attempt)
+      {
+        attempts: history.size, seed: history.last[:seed], cause: attempt == 1 ? ALONE : RESEEDED,
+        first_failure: summary(first.failure), history:
+      }
+    end
+
+    def summary(failure)
+      type = failure.is_a?(Minitest::UnexpectedError) ? failure.error.class.name : failure.class.name
+      { type:, message: failure.message.lines.first.to_s.strip }
+    end
+  end
+end

data/lib/padded_cell/cell.rb

@@ -12,15 +12,18 @@ module PaddedCell
     # result when the cell died or ran past timeout seconds.
     #
     #   close: descriptors the cell must not keep open (the worker's socket)
-    def run(klass, name, seed:, timeout: nil, close: [])
+    #   probe: the worker's Chart::Probe, which gets the cell's coverage
+    def run(klass, name, seed:, timeout: nil, close: [], probe: nil)
       # Binary: the result is Marshal data, and with Encoding.default_internal
       # set (Rails sets it) a text-mode pipe transcodes what is written to it.
       reader, writer = IO.pipe
       [reader, writer].each(&:binmode)
       started = Minitest.clock_time
-      pid = fork_cell(klass, name, seed, reader, writer, close)
+      pid = fork_cell(klass, name, seed, reader, writer, close, probe)
       writer.close
-      collect(pid, reader, klass, name, started, timeout)
+      delta, result = collect(pid, reader, klass, name, started, timeout)
+      delta ? probe.absorb(delta) : probe&.lost
+      result
     ensure
       reader&.close
       writer&.close unless writer&.closed?
@@ -34,7 +37,7 @@ module PaddedCell
       Results.crashed(klass, name, "exit(#{e.status}) called during the test")
     end
 
-    def fork_cell(klass, name, seed, reader, writer, close)
+    def fork_cell(klass, name, seed, reader, writer, close, probe)
       $stdout.flush
       $stderr.flush
       Process.fork do
@@ -43,7 +46,9 @@ module PaddedCell
           reader.close
           close.each(&:close)
           srand(seed)
-          writer.write(Results.dump(execute(klass, name)))
+          probe&.start
+          result = execute(klass, name)
+          writer.write(Results.envelope(probe&.capture, result))
           status = 0
         rescue Exception => e # anything: report it, then exit!
           warn "padded_cell: cell #{klass}##{name} failed to report: #{e.class}: #{e.message}"
@@ -54,19 +59,20 @@ module PaddedCell
       end
     end
 
+    # [coverage delta or nil, result]
     def collect(pid, reader, klass, name, started, timeout)
       data = read(reader, timeout && (started + timeout))
       elapsed = Minitest.clock_time - started
       if data.nil?
         Process.kill(:KILL, pid)
         Process.wait(pid)
-        return Results.crashed(klass, name, "timed out after #{timeout}s", time: elapsed)
+        return [nil, Results.crashed(klass, name, "timed out after #{timeout}s", time: elapsed)]
       end
 
       _, status = Process.wait2(pid)
-      return Results.load(data, klass, name) unless data.empty?
+      return Results.unwrap(data, klass, name) unless data.empty?
 
-      Results.crashed(klass, name, Results.describe(status, 'cell'), time: elapsed)
+      [nil, Results.crashed(klass, name, Results.describe(status, 'cell'), time: elapsed)]
     end
 
     # Everything until EOF, or nil when the deadline passes first.

data/lib/padded_cell/chart/accumulator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'coverage'
+require 'fileutils'
+require 'tmpdir'
+
+module PaddedCell
+  module Chart
+    # The runner's side. Starts Ruby's Coverage before the suite loads, hands
+    # each worker a Probe, then sums its own measure (loading the suite) with
+    # every frame the workers wrote.
+    class Accumulator
+      attr_reader :criteria
+
+      # criteria: what Ruby's Coverage measures, :lines always among them
+      def initialize(criteria)
+        @criteria = criteria
+        @root = File.realpath(Dir.pwd)
+        @roots = [Dir.pwd, @root].uniq.map { "#{it}/" }
+        @kept = {}
+        @lost = 0
+        @known = Set.new
+      end
+
+      # Nothing loaded before is measured.
+      def start
+        ::Coverage.setup(**@criteria.to_h { [it, true] })
+        ::Coverage.resume
+        @frames = Dir.mktmpdir('padded_cell-coverage')
+        self
+      end
+
+      # After the suite loaded, before the first fork: the files whose
+      # structure the runner will report itself. Forks inherit the set.
+      def snapshot
+        ::Coverage.peek_result.each_key { @known << it if keep?(it) }
+      end
+
+      # For a worker, right after its fork.
+      def probe
+        Probe.new(file: File.join(@frames, "#{Process.pid}.cov"), known: @known, keep: method(:keep?),
+                  methods: @criteria.include?(:methods), interval: Chart.config.interval)
+      end
+
+      # A worker died: what it measured since its last flush is gone.
+      def lost_worker = @lost += 1
+
+      # Sums everything (see Raw); nil for an interrupted run.
+      def finish(interrupted: false)
+        return if interrupted
+
+        total = Delta.capture(::Coverage.peek_result, Set.new, method(:keep?))
+        cells = 0
+        frames.each do |frame|
+          Delta.merge!(total, frame[:delta])
+          cells += frame[:lost]
+        end
+        Raw.build(normalize(total), root: @root, criteria: @criteria, lost: { workers: @lost, cells: })
+      ensure
+        FileUtils.rm_rf(@frames) if @frames
+      end
+
+      private
+
+      # Files under the project root, which exist (not eval'd code).
+      def keep?(path)
+        @kept.fetch(path) { @kept[path] = @roots.any? { path.start_with?(it) } && File.file?(path) }
+      end
+
+      # Every complete frame of every worker. A worker killed while writing
+      # leaves a truncated last frame, skipped.
+      def frames
+        Dir[File.join(@frames, '*.cov')].flat_map do |file|
+          data = File.binread(file)
+          offset = 0
+          frames = []
+          while offset + 4 <= data.bytesize
+            size = data.unpack1('N', offset:)
+            break if offset + 4 + size > data.bytesize
+
+            frames << Marshal.load(data.byteslice(offset + 4, size)) # written by our own workers
+            offset += 4 + size
+          end
+          frames
+        end
+      end
+
+      # Keys by real path relative to the root: a file required through a
+      # symlink and through its real path is one file. A file deleted during
+      # the run is not reported.
+      def normalize(total)
+        total.each_with_object({}) do |(path, entry), files|
+          relative = File.realpath(path).delete_prefix("#{@root}/")
+          next if relative.start_with?('/')
+
+          files[relative] ? Delta.merge!(files, { relative => entry }) : files[relative] = entry
+        rescue SystemCallError
+          next
+        end
+      end
+    end
+  end
+end

data/lib/padded_cell/chart/config.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  module Chart
+    # A PaddedCell.coverage block, in the test helper:
+    #
+    #   PaddedCell.coverage(:rails) do
+    #     track "{app,lib}/**/*.rb"
+    #     skip "app/legacy/"
+    #     group "Operations", "app/concepts"
+    #     minimum line: 90, branch: 80
+    #     minimum_by_file line: 50
+    #     minimum_by_group "Models", line: 95
+    #     maximum_drop line: 1
+    #     formats :markdown, :lcov, :json
+    #   end
+    #
+    # Filters and groups match paths (see Filter). What is
+    # measured is decided before the suite loads, on the command line:
+    # --coverage=lines,branches,methods.
+    class Config
+      FORMATS = %i[markdown lcov json].freeze
+      # Left out unless cleared: bundled gems, hidden files, test files.
+      DEFAULT_FILTERS = ['/vendor/bundle/', /\A\..*/, %r{\A(test|features|spec|autotest)/}].freeze
+      RAILS_GROUPS = {
+        'Channels' => 'app/channels', 'Controllers' => 'app/controllers', 'Helpers' => 'app/helpers',
+        'Jobs' => %w[app/jobs app/workers], 'Libraries' => 'lib/', 'Mailers' => 'app/mailers',
+        'Models' => 'app/models', 'Views' => 'app/views'
+      }.freeze
+
+      attr_reader :filters, :groups, :tracked, :output_formats, :directory, :token, :interval, :minimums,
+                  :file_minimums, :group_minimums, :maximum_drops
+
+      def initialize
+        @filters = DEFAULT_FILTERS.map { Filter.build(it) }
+        @groups = {}
+        @tracked = []
+        @minimums = {}
+        @file_minimums = {}
+        @group_minimums = {}
+        @maximum_drops = {}
+        @output_formats = %i[markdown lcov json]
+        @directory = 'coverage'
+        @token = 'nocov'
+        @interval = Probe::INTERVAL
+      end
+
+      # :rails skips config/ and db/, groups the
+      # app's directories, tracks {app,lib}/**/*.rb.
+      def profile(name)
+        raise ArgumentError, "unknown coverage profile #{name.inspect} (known: :rails)" unless name.to_s == 'rails'
+
+        skip(%r{\Aconfig/}, %r{\Adb/})
+        RAILS_GROUPS.each { |group_name, filter| group(group_name, filter) }
+        track('{app,lib}/**/*.rb')
+      end
+
+      # Files to report even when the suite never loads them, at 0%.
+      def track(*globs) = @tracked.concat(globs)
+
+      # Files to leave out of the report.
+      def skip(*filters, &block)
+        filters.each { @filters << Filter.build(it) }
+        @filters << Filter.build(&block) if block
+      end
+      alias filter skip
+
+      # Removes every filter, the defaults included.
+      def clear_filters = @filters.clear
+
+      # A file can be in several groups; files in none are Ungrouped.
+      # Defining a group again replaces it.
+      def group(name, filter = nil, &) = @groups[name.to_s] = Filter.build(filter, &)
+
+      # Thresholds compare percents floored to 2 decimals; a whole, passing
+      # run that misses one exits 3.
+      def minimum(line: nil, branch: nil, method: nil) = @minimums.merge!({ line:, branch:, method: }.compact)
+
+      # For every file.
+      def minimum_by_file(line: nil, branch: nil, method: nil)
+        @file_minimums.merge!({ line:, branch:, method: }.compact)
+      end
+
+      def minimum_by_group(name, line: nil, branch: nil, method: nil)
+        (@group_minimums[name.to_s] ||= {}).merge!({ line:, branch:, method: }.compact)
+      end
+
+      # How many points coverage may lose since the previous whole run.
+      def maximum_drop(line: nil, branch: nil, method: nil)
+        @maximum_drops.merge!({ line:, branch:, method: }.compact)
+      end
+
+      def formats(*names)
+        unknown = names.map(&:to_sym) - FORMATS
+        unless unknown.empty?
+          raise ArgumentError, "unknown coverage formats: #{unknown.join(', ')} (known: #{FORMATS.join(', ')})"
+        end
+
+        @output_formats = names.map(&:to_sym)
+      end
+
+      # Where reports go (default: coverage). --coverage-dir wins.
+      def dir(path) = @directory = path
+
+      # `# :nocov:` opens and closes blocks of lines coverage ignores.
+      def nocov_token(token) = @token = token
+
+      # How often, at least, a worker hands over what it measured (seconds,
+      # default 10, stretched to keep it under 1% of the worker's time; 0:
+      # after every test). A worker that dies loses what it measured since.
+      def flush_interval(seconds) = @interval = seconds
+
+      # What a report needs once files are filtered and grouped, as stored
+      # in its Document.
+      def settings
+        {
+          formats: @output_formats.map(&:to_s), nocov_token: @token, minimum: @minimums,
+          minimum_by_file: @file_minimums, minimum_by_group: @group_minimums, maximum_drop: @maximum_drops
+        }
+      end
+
+      # Criteria come from the command line, before the suite (and this
+      # block) loads.
+      def enable_coverage(*)
+        raise ArgumentError, 'coverage criteria come from --coverage=lines,branches,methods, not the test helper'
+      end
+    end
+  end
+end