🥘 Kettle::Soup::Cover

if ci_badges.map(&:color).detect { it != "green"} ☝️ let me know, as I may have missed the discord notification.

---

if ci_badges.map(&:color).all? { it == "green"} 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.

👣 How will this project approach the September 2025 hostile takeover of RubyGems? 🚑️

I've summarized my thoughts in this blog post.

🌻 Synopsis

kettle-soup-cover is a 12-factor SimpleCov harness for Ruby projects. It keeps coverage policy in environment variables, configures branch coverage, loads a curated formatter stack, isolates turbo_tests2 worker reports, and can collate parallel worker output into one final report.

The normal setup is intentionally small:

1. Add the gem to your :development, :test bundle with require: false.
2. Require kettle-soup-cover before loading the app or library under test.
3. Require simplecov and call SimpleCov.start only when Kettle::Soup::Cover::DO_COV is true.
4. Require kettle/soup/cover/config after simplecov and before SimpleCov.start.

That configuration works for RSpec, Minitest, and other Ruby test runners. In CI, coverage is enabled by default from CI=true; locally it stays off unless K_SOUP_COV_DO=true is set. When turbo_tests2 sets TEST_ENV_NUMBER, worker coverage is written under coverage/turbo_tests/<worker> and hard minimum enforcement is deferred until the parent collation step.

A quick shot of 12-factor coverage power:

export K_SOUP_COV_COMMAND_NAME="RSpec (COVERAGE)" # Display name for the coverage run
export K_SOUP_COV_CLEAN_RESULTSET=true # Delete stale .resultset.json before SimpleCov.start
export K_SOUP_COV_DEBUG=false # Enable debug output for configuration (true/false)
export K_SOUP_COV_DIR=coverage # Root directory where coverage reports are written
export K_SOUP_COV_DO=true # Enable coverage collection (true/false)
export K_SOUP_COV_FILTER_DIRS="bin,docs,vendor" # Comma-separated dirs to filter out of coverage
export K_SOUP_COV_FORMATTERS="html,tty" # Comma-separated list: html,xml,rcov,lcov,json,tty
export K_SOUP_COV_MERGE_TIMEOUT=3600 # Timeout in seconds when merging multiple coverage results
export K_SOUP_COV_MIN_BRANCH=53 # Minimum required branch coverage percentage (integer)
export K_SOUP_COV_MIN_HARD=true # If true, fail the run when coverage thresholds are not met
export K_SOUP_COV_MIN_LINE=69 # Minimum required line coverage percentage (integer)
export K_SOUP_COV_MULTI_FORMATTERS=true # Enable multiple SimpleCov formatters (true/false)
export K_SOUP_COV_PREFIX="K_SOUP_COV_" # Prefix used for the envvars (useful for namespacing)
export K_SOUP_COV_OPEN_BIN=xdg-open # Command to open HTML report in `coverage` rake task (or empty to disable)
export K_SOUP_COV_TURBO_TESTS=true # Isolate turbo_tests2 worker coverage when TEST_ENV_NUMBER is set
export K_SOUP_COV_TURBO_TESTS_DIR=turbo_tests # Worker coverage subdirectory below K_SOUP_COV_DIR
export K_SOUP_COV_USE_MERGING=true # Enable merging of results for parallel/test matrix runs (true/false)
export K_SOUP_COV_VERBOSE=false # Enable verbose logging (true/false)
export MAX_ROWS=5 # simplecov-console setting: limits tty output to the worst N rows of uncovered files

I hope I've piqued your interest enough to give it a ⭐️ if the forge you are on supports it.

What does the name mean?

A Covered Kettle of SOUP (Software of Unknown Provenance)

The name is derived in part from the medical devices field, where this library is considered a package of SOUP.

💡 Info you can shake a stick at

Tokens to Remember
Works with JRuby
Works with Truffle Ruby
Works with MRI Ruby 4
Works with MRI Ruby 3
Support & Community
Source
Documentation
Compliance
Style
Maintainer 🎖️
... 💖	🧊 🐙 🛖 🧪

Compatibility

Compatible with MRI Ruby 3.2.0+, and concordant releases of JRuby, and TruffleRuby. CI workflows and Appraisals are generated for MRI Ruby 3.2.0+. This test floor is configured by ruby.test_minimum in .kettle-jem.yml and may be higher than the gem's runtime compatibility floor when legacy Rubies are not practical for the current toolchain.

The amazing test matrix is powered by the kettle-dev stack.

How kettle-dev manages complexity in tests

Gem	Source	Role	Daily download rank
appraisal2	GitHub	multi-dependency Appraisal matrix generation
appraisal2-rubocop	GitHub	RuboCop Appraisal generator integration
kettle-dev	GitHub	development, release, and CI workflow tooling
kettle-jem	GitHub	Appraisals & CI workflow templates
kettle-test	GitHub	standard test runner and coverage harness
rubocop-lts	GitHub	Ruby-version-aware linting
turbo_tests2	GitHub	parallel test execution

Federated DVCS

Find this repo on federated forges (Coming soon!)

Federated DVCS Repository	Status	Issues	PRs	Wiki	CI	Discussions
🧪 kettle-dev/kettle-soup-cover on GitLab	The Truth	💚	💚	💚	🐭 Tiny Matrix	➖
🧊 kettle-dev/kettle-soup-cover on CodeBerg	An Ethical Mirror (Donate)	💚	💚	➖	⭕️ No Matrix	➖
🐙 kettle-dev/kettle-soup-cover on GitHub	Another Mirror	💚	💚	💚	💯 Full Matrix	💚
🎮️ Discord Server		Let's	talk	about	this	library!

Enterprise Support

Available as part of the Tidelift Subscription.

Need enterprise-level guarantees?

The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.

• 💡Subscribe for support guarantees covering all your FLOSS dependencies
• 💡Tidelift is part of Sonar
• 💡Tidelift pays maintainers to maintain the software you depend on!
  📊@Pointy Haired Boss: An enterprise support subscription is "never gonna let you down", and supports open source maintainers

Alternatively:

• 
• 
• 

✨ Installation

Install the gem and add to the application's Gemfile by executing:

bundle add kettle-soup-cover

If bundler is not being used to manage dependencies, install the gem by executing:

gem install kettle-soup-cover

⚙️ Configuration

Configure this gem with environment variables. Variable names use K_SOUP_COV_PREFIX, which defaults to K_SOUP_COV_; for example the DIR setting is read from K_SOUP_COV_DIR.

Variable	Default	Purpose
CI	false	Standard CI flag. Used as the default for DO and MIN_HARD.
K_SOUP_COV_CLEAN_RESULTSET	true locally, false on CI and in turbo workers	Deletes stale .resultset.json before SimpleCov.start. Set false for spawned subprocess coverage so one process does not wipe another process' resultset.
K_SOUP_COV_COMMAND_NAME	RSpec (COVERAGE)	SimpleCov command name. Workers become COMMAND_NAME (turbo_tests2 worker N).
K_SOUP_COV_DEBUG	false	Enables debug-oriented constants.
K_SOUP_COV_DIR	coverage	Root coverage directory. Workers use DIR/TURBO_TESTS_DIR/TEST_ENV_NUMBER.
K_SOUP_COV_DO	CI	Enables the caller's require "simplecov" / SimpleCov.start block.
K_SOUP_COV_FILTER_DIRS	bin,certs,checksums,config,coverage,docs,features,gemfiles,pkg,results,sig,spec,src,test,test-results,vendor	Comma-separated root directories skipped by SimpleCov.
K_SOUP_COV_FORMATTERS	html,xml,rcov,lcov,json,tty on CI; html,tty locally	Formatter list. Supported values are html, xml, rcov, lcov, json, and tty.
K_SOUP_COV_MERGE_TIMEOUT	3600	SimpleCov merge timeout in seconds when merging is enabled.
K_SOUP_COV_MIN_BRANCH	80	Branch coverage minimum.
K_SOUP_COV_MIN_HARD	CI	Fails the run when minimums are missed. Worker processes always defer hard enforcement to collation.
K_SOUP_COV_MIN_LINE	80	Line coverage minimum.
K_SOUP_COV_MULTI_FORMATTERS	true on CI; otherwise true when any formatter is configured	Uses SimpleCov's multi-formatter support.
K_SOUP_COV_OPEN_BIN	open on macOS, xdg-open elsewhere	Browser-opening command for rake coverage. Set empty to only print the report path.
K_SOUP_COV_PREFIX	K_SOUP_COV_	Alternate namespace for all K_SOUP_COV_* variables.
K_SOUP_COV_TURBO_TESTS	true	Enables turbo_tests2 worker coverage isolation when TEST_ENV_NUMBER is present.
K_SOUP_COV_TURBO_TESTS_DIR	turbo_tests	Subdirectory for worker coverage under K_SOUP_COV_DIR.
K_SOUP_COV_USE_MERGING	true	Enables SimpleCov result merging.
K_SOUP_COV_VERBOSE	false	Enables verbose-oriented constants.
MAX_ROWS	formatter-defined	Passed through to simplecov-console; MAX_ROWS=0 removes the tty formatter.
TEST_ENV_NUMBER	empty	Set by parallel test tools. Non-empty values mark a turbo_tests2 worker.

🔧 Basic Usage

Gemfile

Use require: false so coverage starts exactly where your test helper starts it. Keep the gem in both :development and :test if you want the bundled coverage rake task locally.

group :development, :test do
  gem "kettle-soup-cover", "~> 3.0", require: false
end

RSpec, Minitest, or another Ruby test runner

In your test helper, require kettle-soup-cover before loading the library or application under test. Start SimpleCov only when DO_COV is true. Requiring simplecov loads the project-local .simplecov, so limit that file to project-local SimpleCov.configure rules and load kettle/soup/cover/config in the helper:

require "kettle-soup-cover"

if Kettle::Soup::Cover::DO_COV
  require "simplecov"
  require "kettle/soup/cover/config"
  # Minitest users that rely on SimpleCov's external at_exit handling should set:
  # SimpleCov.external_at_exit = true
  SimpleCov.start
end

# Now load your app or library under test.
require "my_gem"

Use .simplecov only for project-local SimpleCov rules, such as the files this project should cover:

SimpleCov.configure do
  cover "lib/**/*.rb", "lib/**/*.rake", "exe/*.rb"
end

Rails and RSpec

In Rails, start coverage after spec_helper is loaded and before Rails boots:

require "kettle-soup-cover"
require "spec_helper"

ENV["RAILS_ENV"] ||= "test"

if Kettle::Soup::Cover::DO_COV
  require "simplecov"
  require "kettle/soup/cover/config"
  SimpleCov.start
end

require File.expand_path("../config/environment", __dir__)

Rake tasks

Define a test task, then install this gem's local coverage task:

require "kettle-soup-cover"
Kettle::Soup::Cover.install_tasks

desc "Run specs through the test task expected by kettle-soup-cover"
task test: :spec

rake coverage forces coverage on, resets coverage constants through kettle-wash, invokes test, and opens K_SOUP_COV_DIR/index.html unless K_SOUP_COV_OPEN_BIN is empty.

turbo_tests2 coverage

When K_SOUP_COV_TURBO_TESTS=true and TEST_ENV_NUMBER is non-empty, kettle-soup-cover treats the process as a worker:

• K_SOUP_COV_DIR remains the root coverage directory.
• worker output goes to K_SOUP_COV_DIR/K_SOUP_COV_TURBO_TESTS_DIR/TEST_ENV_NUMBER;
• worker command names include the worker number;
• SimpleCov.finalize_merge(false) is applied in workers;
• hard coverage minimums are disabled in workers and enforced during parent collation.

The installed tasks provide both turbo_tests:* and turbo_tests2:* names:

Kettle::Soup::Cover.install_tasks

Use turbo_tests:setup before workers and turbo_tests:cleanup after workers when your runner does not invoke those hooks automatically.

Coverage JSON analyzer

To inspect the current local coverage report, use the bundled analyzer:

bin/kettle-soup-cover -d

By default it clears the configured coverage directory, runs bin/rake coverage with fresh JSON-only output, and then prints the detailed report. If you want to inspect an already-generated artifact without rerunning tests, pass it explicitly:

bin/kettle-soup-cover -p coverage/coverage.json

Usage examples:

kettle-soup-cover              # Uses $K_SOUP_COV_DIR/coverage.json (default coverage/coverage.json)
kettle-soup-cover -p path/to/coverage.json  # Read JSON from a custom path
kettle-soup-cover ./coverage/coverage.json  # Positional path is accepted as an alternative to -p/--path
kettle-soup-cover -f kettle/soup           # Show only files matching kettle/soup (partial substring match)
kettle-soup-cover -f "kettle/soup/**/*.rb" # Globbing is supported; -f will treat patterns containing *?[] as globs

Notes:

• The script requires the json formatter to be active in K_SOUP_COV_FORMATTERS if you don't supply an explicit JSON path via -p or a positional arg; otherwise it will abort with an actionable message.
• -f/--file is a file filter (partial path match) and cannot be used to specify the coverage JSON path.
• K_SOUP_COV_DIR controls the default path used by the script (defaults to coverage).

Filters

There are two built-in SimpleCov filters which can be loaded via Kettle::Soup::Cover.load_filters.

You could use them like this:

SimpleCov.add_group("Too Long", Kettle::Soup::Cover::Filters::GtLineFilter.new(1000))

Advanced Usage

There are a number of ENV variables that control things within this gem. All of them can be found, along with their default values, in lib/kettle/soup/cover/constants.rb.

Handy List of ENV Variables

Most are self explanatory. I tried to follow POLS, the principle of least surprise, so they mostly DWTFYT. Want to help improve this documentation? PRs are easy!

Below is a reference for the environment variables used by this gem. Each section documents the variable name, its default value, what it controls, and an example of usage. Variable names are prefixed with the value of K_SOUP_COV_PREFIX (by default K_SOUP_COV_).

K_SOUP_COV_COMMAND_NAME

• Default: RSpec (COVERAGE)
• What it controls: Display name for the coverage run, used in UIs or log output.
• Example: export K_SOUP_COV_COMMAND_NAME="Unit Tests (Coverage)"

K_SOUP_COV_DEBUG

• Default: false (string value read truthily)
• What it controls: Enable debug output for the configuration, prints the prefixes and selected values.
• Example: export K_SOUP_COV_DEBUG=true

K_SOUP_COV_DIR

• Default: coverage
• What it controls: Root directory where SimpleCov writes coverage reports. Turbo worker processes write under K_SOUP_COV_DIR/K_SOUP_COV_TURBO_TESTS_DIR/TEST_ENV_NUMBER. The exe/kettle-soup-cover script and rake tasks look here for artifacts like coverage.json or index.html.
• Example: export K_SOUP_COV_DIR=my-coverage

K_SOUP_COV_DO

• Default: Uses CI if unset (CI=false default). Setting to true or false enables/disables coverage collection.
• What it controls: Controls whether the gem enables SimpleCov at runtime (DO_COV behavior).
• Example: export K_SOUP_COV_DO=true

K_SOUP_COV_FILTER_DIRS

• Default: bin,certs,checksums,config,coverage,docs,features,gemfiles,pkg,results,sig,spec,src,test,test-results,vendor
• What it controls: A comma-separated list of directory names to filter out from coverage reports.
• Example: export K_SOUP_COV_FILTER_DIRS=vendor,bin,docs

K_SOUP_COV_FORMATTERS

• Default: html,xml,rcov,lcov,json,tty on CI; html,tty locally.
• What it controls: Comma-separated list of formatters that determine the kind of coverage reports generated. Supported values include html, xml, rcov, lcov, json, tty.
• Example: export K_SOUP_COV_FORMATTERS="html,json"

Note: the exe/kettle-soup-cover script requires that the json formatter be enabled so it can read a canonical coverage/coverage.json file. If you plan to use that script, ensure json is included in your K_SOUP_COV_FORMATTERS value as shown in the example above.

K_SOUP_COV_CLEAN_RESULTSET

• Default: false on CI and in turbo worker processes; true locally.
• What it controls: When true, deletes coverage/.resultset.json before SimpleCov starts. This prevents stale entries from prior runs (e.g., after a refactor that shifts line/branch numbers) from polluting the current run's coverage report. In CI each job starts from a clean workspace so this is unnecessary; locally developers re-run tests frequently and stale entries accumulate.
• Example: export K_SOUP_COV_CLEAN_RESULTSET=false

Important for spawned-process coverage: if you use .simplecov_spawn.rb (or similar) to collect coverage from child processes, set K_SOUP_COV_CLEAN_RESULTSET=false inside that file so spawned processes do not wipe the resultset that other workers are accumulating. Only the main process should clean.

K_SOUP_COV_MERGE_TIMEOUT

• Default: 3600
• What it controls: When using merging (K_SOUP_COV_USE_MERGING=true), this sets a numeric timeout in seconds for the merge operation.
• Example: export K_SOUP_COV_MERGE_TIMEOUT=3600

K_SOUP_COV_MIN_BRANCH

• Default: 80
• What it controls: Minimum allowed branch coverage percentage. Used to assert that coverage thresholds are met.
• Example: export K_SOUP_COV_MIN_BRANCH=85

K_SOUP_COV_MIN_HARD

• Default: Uses CI if unset (CI=false default). Worker processes always use false.
• What it controls: Whether failing coverage thresholds should fail the run (hard failure) or only warn. In turbo_tests2 worker processes, hard enforcement is deferred to the parent collation process.
• Example: export K_SOUP_COV_MIN_HARD=true

K_SOUP_COV_MIN_LINE

• Default: 80
• What it controls: Minimum allowed line coverage percentage.
• Example: export K_SOUP_COV_MIN_LINE=92

K_SOUP_COV_MULTI_FORMATTERS

• Default: If running on CI (true) the default is true, otherwise the default is true if any formatters are present.
• What it controls: Whether to configure SimpleCov to run multiple formatters concurrently or not.
• Example: export K_SOUP_COV_MULTI_FORMATTERS=false

K_SOUP_COV_PREFIX

• Default: K_SOUP_COV_
• What it controls: Prefix used for the environment variables described in this section; useful if you want a custom-namespaced set for tests.
• Example: export K_SOUP_COV_PREFIX="MY_COV_"

K_SOUP_COV_OPEN_BIN

• Default: Uses open on macOS and xdg-open on Linux.
• What it controls: Command used by the Rake coverage task to open the HTML report. Set to an empty value to disable auto-opening and just print report locations.
• Example: export K_SOUP_COV_OPEN_BIN=xdg-open or export K_SOUP_COV_OPEN_BIN= (to only print the path)

K_SOUP_COV_TURBO_TESTS

• Default: true
• What it controls: Enables turbo_tests2 worker isolation when TEST_ENV_NUMBER is non-empty.
• Example: export K_SOUP_COV_TURBO_TESTS=true

K_SOUP_COV_TURBO_TESTS_DIR

• Default: turbo_tests
• What it controls: Subdirectory under K_SOUP_COV_DIR for worker coverage output.
• Example: export K_SOUP_COV_TURBO_TESTS_DIR=parallel

K_SOUP_COV_USE_MERGING

• Default: true
• What it controls: When true, enables result merging semantics for multiple test runs (works with merge timeout and other behaviors).
• Example: export K_SOUP_COV_USE_MERGING=true

K_SOUP_COV_VERBOSE

• Default: false
• What it controls: Enables additional verbose logging where supported within tasks and scripts.
• Example: export K_SOUP_COV_VERBOSE=true

Note: Some third-party formatters may also read their own environment variables. For example, the simplecov-console formatter supports MAX_ROWS to limit the tty output. This is not prefixed with K_SOUP_COV_ by design and is passed through to the formatter directly.

Additionally, some of the included gems, like simplecov-console, have their own complete suite of ENV variables you can configure.

Compatible with GitHub Actions for Code Coverage feedback in pull requests

If you don't want to configure a SaaS service to update your pull requests with code coverage there are alternatives.

After the step that runs your test suite use one or more of the following.

irongut/CodeCoverageSummary

Repo: irongut/CodeCoverageSummary

      - name: Code Coverage Summary Report
        uses: irongut/CodeCoverageSummary@v1.3.0
        if: ${{ github.event_name == 'pull_request' }}
        with:
          filename: ./coverage/coverage.xml
          badge: true
          fail_below_min: true
          format: markdown
          hide_branch_rate: false
          hide_complexity: true
          indicators: true
          output: both
          thresholds: '100 100' # '<MIN LINE COVERAGE> <MIN BRANCH COVERAGE>'
        continue-on-error: ${{ matrix.experimental != 'false' }}

marocchino/sticky-pull-request-comment

Repo: marocchino/sticky-pull-request-comment

      - name: Add Coverage PR Comment
        uses: marocchino/sticky-pull-request-comment@v2
        if: ${{ github.event_name == 'pull_request' }}
        with:
          recreate: true
          path: code-coverage-results.md
        continue-on-error: ${{ matrix.experimental != 'false' }}

🔐 Security

See SECURITY.md.

🤝 Contributing

If you need some ideas of where to help, you could work on adding more code coverage, or if it is already 💯 (see below) check issues or PRs, or use the gem and think about how it could be better.

We so if you make changes, remember to update it.

See CONTRIBUTING.md for more detailed instructions.

🚀 Release Instructions

See CONTRIBUTING.md.

Code Coverage

Coverage service badges

🪇 Code of Conduct

Everyone interacting with this project's codebases, issue trackers, chat rooms and mailing lists agrees to follow the .

🌈 Contributors

Made with contributors-img.

Also see GitLab Contributors: https://gitlab.com/kettle-dev/kettle-soup-cover/-/graphs/main

⭐️ Star History

📌 Versioning

This library follows for its public API where practical. For most applications, prefer the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency("kettle-soup-cover", "~> 3.0")

📌 Is "Platform Support" part of the public API? More details inside.

Dropping support for a platform can be a breaking change for affected users. If a release changes supported platforms, it should be called out clearly in the changelog and versioned with that impact in mind.

To get a better understanding of how SemVer is intended to work over a project's lifetime, read this article from the creator of SemVer:

• "Major Version Numbers are Not Sacred"

See CHANGELOG.md for a list of releases.

📄 License

The gem is available under the following license: AGPL-3.0-only. See LICENSE.md for details.

If none of the available licenses suit your use case, please contact us to discuss a custom commercial license.

© Copyright

See LICENSE.md for the official copyright notice.

Copyright holders

• Copyright (c) 2023-2026 Peter H. Boling

🤑 A request for help

Maintainers have teeth and need to pay their dentists. After getting laid off in an RIF in March, and encountering difficulty finding a new one, I began spending most of my time building open source tools. I'm hoping to be able to pay for my kids' health insurance this month, so if you value the work I am doing, I need your support. Please consider sponsoring me or the project.

To join the community or get help 👇️ Join the Discord.

To say "thanks!" ☝️ Join the Discord or 👇️ send money.

💌 💌 💌

Please give the project a star ⭐ ♥.

Many parts of this project are actively managed by a kettle-jem smart template utilizing StructuredMerge.org merge contracts.

Thanks for RTFM. ☺️

Field	Value
Package	kettle-soup-cover
Description	🥘 A Covered Kettle of Test Coverage SOUP (Software of Unknown Provenance) Four-line SimpleCov config, w/ curated, opinionated, pre-configured, dependencies for every CI platform, batteries included. Fund overlooked open source projects - bottom of stack, dev/test dependencies: floss-funding.dev
Homepage	https://github.com/kettle-dev/kettle-soup-cover
Source	https://github.com/kettle-dev/kettle-soup-cover
License	AGPL-3.0-only
Funding	https://github.com/sponsors/pboling, https://ko-fi.com/pboling, https://liberapay.com/pboling/donate, https://opencollective.com/kettle-dev, https://thanks.dev/u/gh/pboling, https://tidelift.com/funding/github/rubygems/kettle-soup-cover, https://www.buymeacoffee.com/pboling