simplecov 0.21.2 → 1.0.0.rc1

data/README.md

@@ -1,61 +1,50 @@
-SimpleCov [![Gem Version](https://badge.fury.io/rb/simplecov.svg)](https://badge.fury.io/rb/simplecov) [![Build Status](https://github.com/simplecov-ruby/simplecov/workflows/stable/badge.svg?branch=main)][Continuous Integration] [![Maintainability](https://api.codeclimate.com/v1/badges/c071d197d61953a7e482/maintainability)](https://codeclimate.com/github/simplecov-ruby/simplecov/maintainability) [![Inline docs](http://inch-ci.org/github/simplecov-ruby/simplecov.svg?branch=main)](http://inch-ci.org/github/simplecov-ruby/simplecov)
+SimpleCov [![Gem Version](https://badge.fury.io/rb/simplecov.svg)](https://badge.fury.io/rb/simplecov) [![Build Status](https://github.com/simplecov-ruby/simplecov/actions/workflows/stable.yml/badge.svg?branch=main)][Continuous Integration] [![Lint](https://github.com/simplecov-ruby/simplecov/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/simplecov-ruby/simplecov/actions/workflows/lint.yml) [![Typecheck](https://github.com/simplecov-ruby/simplecov/actions/workflows/typecheck.yml/badge.svg?branch=main)](https://github.com/simplecov-ruby/simplecov/actions/workflows/typecheck.yml) [![Maintainability](https://api.codeclimate.com/v1/badges/c071d197d61953a7e482/maintainability)](https://codeclimate.com/github/simplecov-ruby/simplecov/maintainability)
 =========
 
 **Code coverage for Ruby**
 
   * [Source Code]
   * [API documentation]
+  * [Configuration]
   * [Changelog]
   * [Rubygem]
   * [Continuous Integration]
 
-[Coverage]: https://ruby-doc.org/stdlib/libdoc/coverage/rdoc/Coverage.html "API doc for Ruby's Coverage library"
+[Coverage]: https://docs.ruby-lang.org/en/master/Coverage.html "API doc for Ruby's Coverage library"
 [Source Code]: https://github.com/simplecov-ruby/simplecov "Source Code @ GitHub"
 [API documentation]: http://rubydoc.info/gems/simplecov/frames "RDoc API Documentation at Rubydoc.info"
 [Configuration]: http://rubydoc.info/gems/simplecov/SimpleCov/Configuration "Configuration options API documentation"
 [Changelog]: https://github.com/simplecov-ruby/simplecov/blob/main/CHANGELOG.md "Project Changelog"
 [Rubygem]: http://rubygems.org/gems/simplecov "SimpleCov @ rubygems.org"
 [Continuous Integration]: https://github.com/simplecov-ruby/simplecov/actions?query=workflow%3Astable "SimpleCov is built around the clock by github.com"
-[Dependencies]: https://gemnasium.com/simplecov-ruby/simplecov "SimpleCov dependencies on Gemnasium"
-[simplecov-html]: https://github.com/simplecov-ruby/simplecov-html "SimpleCov HTML Formatter Source Code @ GitHub"
 
-SimpleCov is a code coverage analysis tool for Ruby. It uses [Ruby's built-in Coverage][Coverage] library to gather code
-coverage data, but makes processing its results much easier by providing a clean API to filter, group, merge, format,
-and display those results, giving you a complete code coverage suite that can be set up with just a couple lines of
-code.
-SimpleCov/Coverage track covered ruby code, gathering coverage for common templating solutions like erb, slim and haml is not supported.
+SimpleCov is a code coverage analysis tool for Ruby. It uses [Ruby's built-in Coverage][Coverage] library to gather
+coverage data, but makes processing the results much easier by providing a clean API to filter, group, merge, format,
+and display them — a complete coverage suite you can set up in just a couple of lines.
 
-In most cases, you'll want overall coverage results for your projects, including all types of tests, Cucumber features,
-etc. SimpleCov automatically takes care of this by caching and merging results when generating reports, so your
-report actually includes coverage across your test suites and thereby gives you a better picture of blank spots.
+SimpleCov tracks covered Ruby code; gathering coverage for templating solutions like ERB, Slim, and Haml is not
+supported (though see [Eval coverage](#eval-coverage) for ERB).
 
-The official formatter of SimpleCov is packaged as a separate gem called [simplecov-html], but will be installed and
-configured automatically when you launch SimpleCov. If you're curious, you can find it [on GitHub, too][simplecov-html].
+In most cases you'll want overall coverage results spanning all of your tests — unit tests, Cucumber features, and so
+on. SimpleCov handles this automatically by caching and merging results as it generates reports, so a report reflects
+coverage across your whole test suite and gives you a truer picture of your blank spots.
 
+SimpleCov bundles two formatters that need no extra gems: the default HTML formatter (which renders the browsable
+report) and a JSON formatter. Both were once separate gems (`simplecov-html` and `simplecov_json_formatter`) but are
+now built into SimpleCov and configured automatically when you launch it.
 
-## Contact
+## Getting started
 
-*Code and Bug Reports*
-
-* [Issue Tracker](https://github.com/simplecov-ruby/simplecov/issues)
-* See [CONTRIBUTING](https://github.com/simplecov-ruby/simplecov/blob/main/CONTRIBUTING.md) for how to contribute along
-with some common problems to check out before creating an issue.
-
-*Questions, Problems, Suggestions, etc.*
-
-* [Mailing List](https://groups.google.com/forum/#!forum/simplecov) "Open mailing list for discussion and announcements
-on Google Groups"
-
-Getting started
----------------
 1. Add SimpleCov to your `Gemfile` and `bundle install`:
 
     ```ruby
     gem 'simplecov', require: false, group: :test
     ```
-2. Load and launch SimpleCov **at the very top** of your `test/test_helper.rb`
-   (*or `spec_helper.rb`, `rails_helper`, cucumber `env.rb`, or whatever your preferred test
-   framework uses*):
+
+2. Load and launch SimpleCov **at the very top** of your test helper — `test/test_helper.rb`, `spec/spec_helper.rb`,
+   `rails_helper.rb`, Cucumber's `features/support/env.rb`, or whatever setup file your framework uses. SimpleCov
+   doesn't care which framework you run in; it just watches what code executes and reports on it, so the same two lines
+   work everywhere:
 
     ```ruby
     require 'simplecov'
@@ -64,198 +53,77 @@ Getting started
     # Previous content of test helper now starts here
     ```
 
-    **Note:** If SimpleCov starts after your application code is already loaded
-    (via `require`), it won't be able to track your files and their coverage!
-    The `SimpleCov.start` **must** be issued **before any of your application
-    code is required!**
+   > **Important:** `SimpleCov.start` **must** run **before any of your application code is required** — otherwise
+   > SimpleCov (and the underlying Coverage library) can't track those files. This bites hardest with tools that keep
+   > your app loaded between runs, like Spring; see the [Spring section](#using-spring-with-simplecov).
 
-    SimpleCov must be running in the process that you want the code coverage
-    analysis to happen on. When testing a server process (e.g. a JSON API
-    endpoint) via a separate test process (e.g. when using Selenium) where you
-    want to see all code executed by the `rails server`, and not just code
-    executed in your actual test files, you need to require SimpleCov in the
-    server process. For rails for instance, you'll want to add something like this
-    to the top of `bin/rails`, but below the "shebang" line (`#! /usr/bin/env
-    ruby`) and after config/boot is required:
+   SimpleCov must run in the process you want to analyze. When you test a server process (e.g. a JSON API) from a
+   separate test process (e.g. via Selenium) and want to see all code the `rails server` executes — not just code in
+   your test files — require SimpleCov in the server process. For Rails, add this near the top of `bin/rails`, below
+   the shebang and after `config/boot` is required:
 
     ```ruby
     if ENV['RAILS_ENV'] == 'test'
       require 'simplecov'
       SimpleCov.start 'rails'
-      puts "required simplecov"
     end
     ```
 
-3. Run your full test suite to see the percent coverage that your application has.
-4. After running your tests, open `coverage/index.html` in the browser of your choice. For example, in a Mac Terminal,
-   run the following command from your application's root directory:
-
-   ```
-   open coverage/index.html
-   ```
-   in a debian/ubuntu Terminal,
-
-   ```
-   xdg-open coverage/index.html
-   ```
-
-   **Note:** [This guide](https://dwheeler.com/essays/open-files-urls.html) can help if you're unsure which command your particular
-   operating system requires.
-
-5. Add the following to your `.gitignore` file to ensure that coverage results
-   are not tracked by Git (optional):
-
-   ```
-   echo "coverage" >> .gitignore
-   ```
-   Or if you use Windows:
-   ```
-   echo coverage >> .gitignore
-   ```
-
-   If you're making a Rails application, SimpleCov comes with built-in configurations (see below for information on
-   profiles) that will get you started with groups for your Controllers, Models and Helpers. To use it, the
-   first two lines of your test_helper should be like this:
-
-   ```ruby
-   require 'simplecov'
-   SimpleCov.start 'rails'
-   ```
-
-## Example output
-
-**Coverage results report, fully browsable locally with sorting and much more:**
-
-![SimpleCov coverage report](https://cloud.githubusercontent.com/assets/137793/17071162/db6f253e-502d-11e6-9d84-e40c3d75f333.png)
+3. Run your full test suite to see your application's coverage.
 
+4. Open the HTML report in your default browser:
 
-**Source file coverage details view:**
+    ```sh
+    simplecov open
+    ```
 
-![SimpleCov source file detail view](https://cloud.githubusercontent.com/assets/137793/17071163/db6f9f0a-502d-11e6-816c-edb2c66fad8d.png)
+   (The bundled `simplecov` CLI picks the right opener for your platform — `open` on macOS, `xdg-open` on Linux/BSD,
+   `start` on Windows. Pass `--report PATH` to open a non-default location. See [Command-line interface](#command-line-interface)
+   for the full set of subcommands.)
 
-## Use it with any framework!
+5. Optionally, keep coverage results out of Git:
 
-Similarly to the usage with Test::Unit described above, the only thing you have to do is to add the SimpleCov
-config to the very top of your Cucumber/RSpec/whatever setup file.
+    ```sh
+    echo coverage >> .gitignore
+    ```
 
-Add the setup code to the **top** of `features/support/env.rb` (for Cucumber) or `spec/spec_helper.rb` (for RSpec).
-Other test frameworks should work accordingly, whatever their setup file may be:
+For Rails applications, SimpleCov ships a built-in `rails` [profile](#profiles) that sets up groups for your
+Controllers, Models, Helpers, and Libraries:
 
 ```ruby
 require 'simplecov'
 SimpleCov.start 'rails'
 ```
 
-You could even track what kind of code your UI testers are touching if you want to go overboard with things. SimpleCov
-does not care what kind of framework it is running in; it just looks at what code is being executed and generates a
-report about it.
+## Example output
 
-### Notes on specific frameworks and test utilities
+**Coverage results report, fully browsable locally with sorting and much more:**
 
-For some frameworks and testing tools there are quirks and problems you might want to know about if you want
-to use SimpleCov with them. Here's an overview of the known ones:
+![SimpleCov coverage report](https://github.com/user-attachments/assets/33275385-e0f3-482d-b63e-2a6cd4965fe0)
 
-<table>
-  <tr><th>Framework</th><th>Notes</th><th>Issue</th></tr>
-  <tr>
-    <th>
-      parallel_tests
-    </th>
-    <td>
-      As of 0.8.0, SimpleCov should correctly recognize parallel_tests and
-      supplement your test suite names with their corresponding test env
-      numbers. SimpleCov locks the resultset cache while merging, ensuring no
-      race conditions occur when results are merged.
-    </td>
-    <td>
-      <a href="https://github.com/simplecov-ruby/simplecov/issues/64">#64</a> &amp;
-      <a href="https://github.com/simplecov-ruby/simplecov/pull/185">#185</a>
-    </td>
-  </tr>
-  <tr>
-    <th>
-      knapsack_pro
-    </th>
-    <td>
-      To make SimpleCov work with Knapsack Pro Queue Mode to split tests in parallel on CI jobs you need to provide CI node index number to the <code>SimpleCov.command_name</code> in <code>KnapsackPro::Hooks::Queue.before_queue</code> hook.
-    </td>
-    <td>
-      <a href="https://knapsackpro.com/faq/question/how-to-use-simplecov-in-queue-mode">Tip</a>
-    </td>
-  </tr>
-  <tr>
-    <th>
-      RubyMine
-    </th>
-    <td>
-      The <a href="https://www.jetbrains.com/ruby/">RubyMine IDE</a> has
-      built-in support for SimpleCov's coverage reports, though you might need
-      to explicitly set the output root using `SimpleCov.root('foo/bar/baz')`
-    </td>
-    <td>
-      <a href="https://github.com/simplecov-ruby/simplecov/issues/95">#95</a>
-    </td>
-  </tr>
-  <tr>
-    <th>
-      Spork
-    </th>
-    <td>
-      Because of how Spork works internally (using preforking), there used to
-      be trouble when using SimpleCov with it, but that has apparently been
-      resolved with a specific configuration strategy. See <a
-      href="https://github.com/simplecov-ruby/simplecov/issues/42#issuecomment-4440284">this</a>
-      comment.
-    </td>
-    <td>
-      <a href="https://github.com/simplecov-ruby/simplecov/issues/42#issuecomment-4440284">#42</a>
-    </td>
-  </tr>
-  <tr>
-    <th>
-      Spring
-    </th>
-    <td>
-      <a href="#want-to-use-spring-with-simplecov">See section below.</a>
-    </td>
-    <td>
-      <a href="https://github.com/simplecov-ruby/simplecov/issues/381">#381</a>
-    </td>
-  </tr>
-  <tr>
-    <th>
-      Test/Unit
-    </th>
-    <td>
-      Test Unit 2 used to mess with ARGV, leading to a failure to detect the
-      test process name in SimpleCov. <code>test-unit</code> releases 2.4.3+
-      (Dec 11th, 2011) should have this problem resolved.
-    </td>
-    <td>
-      <a href="https://github.com/simplecov-ruby/simplecov/issues/45">#45</a> &amp;
-      <a href="https://github.com/test-unit/test-unit/pull/12">test-unit/test-unit#12</a>
-    </td>
-  </tr>
-</table>
+**Source file coverage details view:**
 
-## Configuring SimpleCov
+![SimpleCov source file detail view](https://github.com/user-attachments/assets/abcd93b4-a45d-48bb-a0e4-6129c4429193)
 
-[Configuration] settings can be applied in three formats, which are completely equivalent:
+## Configuration
 
-* The most common way is to configure it directly in your start block:
+[Configuration] settings can be applied in three equivalent formats:
+
+* Directly in your start block (the most common way):
 
     ```ruby
     SimpleCov.start do
       some_config_option 'foo'
     end
     ```
-* You can also set all configuration options directly:
+
+* As direct setters:
 
     ```ruby
     SimpleCov.some_config_option 'foo'
     ```
-* If you do not want to start coverage immediately after launch or want to add additional configuration later on in a
-  concise way, use:
+
+* In a `configure` block — useful when you don't want to start coverage immediately, or want to add configuration later:
 
     ```ruby
     SimpleCov.configure do
@@ -263,55 +131,159 @@ to use SimpleCov with them. Here's an overview of the known ones:
     end
     ```
 
-Please check out the [Configuration] API documentation to find out what you can customize.
-
-## Using .simplecov for centralized config
+See the [Configuration] API documentation for the full list of options.
 
-If you use SimpleCov to merge multiple test suite results (e.g. Test/Unit and Cucumber) into a single report, you'd
-normally have to set up all your config options twice, once in `test_helper.rb` and once in `env.rb`.
+### Using `.simplecov` for centralized config
 
-To avoid this, you can place a file called `.simplecov` in your project root. You can then just leave the
-`require 'simplecov'` in each test setup helper (**at the top**) and move the `SimpleCov.start` code with all your
-custom config options into `.simplecov`:
+If you merge multiple test-suite results (e.g. RSpec and Cucumber) into a single report, you'd otherwise have to repeat
+your filters / groups / profile in every test helper. To avoid that, place a `.simplecov` file at your project root
+with the shared configuration; each test helper then requires SimpleCov and explicitly starts it:
 
 ```ruby
-# test/test_helper.rb
+# .simplecov — configuration only
+SimpleCov.load_profile 'rails'
+SimpleCov.skip 'lib/generators'
+SimpleCov.group 'Models', 'app/models'
+
+# spec/spec_helper.rb
 require 'simplecov'
+SimpleCov.start
 
 # features/support/env.rb
 require 'simplecov'
+SimpleCov.start
+```
 
-# .simplecov
-SimpleCov.start 'rails' do
-  # any custom configs like groups and filters can be here at a central place
+This is recommended whenever you merge frameworks that rely on each other, like Cucumber and RSpec.
+
+> [!NOTE]
+> Calling `SimpleCov.start` directly from `.simplecov` is deprecated. Tracking still begins for backward
+> compatibility, but a one-time deprecation warning fires; a future release will require the explicit `SimpleCov.start`
+> from a test helper. Migrating prevents a long-standing bug where `.simplecov` auto-loaded in a Rakefile or Rails'
+> `Bundler.require` would leave an empty parent-process report that overwrites the test subprocess's good one. See #581.
+
+### Changing the report location
+
+By default the report ends up in `SimpleCov.root / SimpleCov.coverage_dir`. For out-of-tree build setups
+(CMake/CTest, Bazel, etc.) — where the build directory is elsewhere on the filesystem and you don't want the report
+under the source root — set `SimpleCov.coverage_path` directly:
+
+```ruby
+SimpleCov.start do
+  root '/source/checkout'
+  coverage_path '/tmp/build/coverage'
 end
 ```
 
-Using `.simplecov` rather than separately requiring SimpleCov multiple times is recommended if you are merging multiple
-test frameworks like Cucumber and RSpec that rely on each other, as invoking SimpleCov multiple times can cause coverage
-information to be lost.
+Setting `coverage_path` explicitly pins the destination — subsequent changes to `root` or `coverage_dir` don't move
+it. The directory is created if it doesn't already exist.
+
+### Running coverage only on demand
 
-## Branch coverage (ruby "~> 2.5")
-Add branch coverage measurement statistics to your results. Supported in CRuby versions 2.5+.
+The Ruby STDLIB Coverage library is *very* fast (on a ~10-minute Rails suite the slowdown is only a couple of seconds),
+so SimpleCov's policy is to generate coverage on every run — it costs you almost nothing and you always have the latest
+results. There's therefore no built-in on-demand switch, but you can add one with an `ENV` conditional:
+
+```ruby
+SimpleCov.start if ENV["COVERAGE"]
+```
+
+Then coverage runs only when you ask for it:
+
+```sh
+COVERAGE=true rake test
+```
+
+### Migrating from the legacy configuration API
+
+The configuration API was redesigned to use a smaller set of consistent verbs. The legacy methods continue to work but
+emit deprecation warnings that name their replacement; the table below is the canonical migration map.
+
+| Legacy                              | New                              | Notes                                                                                                                  |
+|-------------------------------------|----------------------------------|------------------------------------------------------------------------------------------------------------------------|
+| `add_filter "lib/legacy"`           | `skip "lib/legacy"`              | Identical matcher grammar (string = path-segment substring; Regexp; block; Array). No behavior change.                 |
+| `add_group "Models", "app/models"`  | `group "Models", "app/models"`   | Identical matcher grammar. No behavior change.                                                                         |
+| `track_files "lib/**/*.rb"`         | `cover "lib/**/*.rb"`            | `cover` includes unloaded files (the legacy `track_files` behavior) **and** restricts the report to the matching set. To keep the old additive-only behavior, pass every directory you want reported: `cover "lib/**/*.rb", "app/**/*.rb"`. |
+| `use_merging false`                 | `merging false`                  | Same value, same behavior.                                                                                             |
+| `enable_for_subprocesses true`      | `merge_subprocesses true`        | Same value, same behavior.                                                                                             |
+| `enable_coverage_for_eval`          | `enable_coverage :eval`          | Eval coverage now folds into the same call you use to enable `:line`/`:branch`/`:method`: `enable_coverage :branch, :eval`. |
+| `print_error_status` (reader)       | `print_errors`                   | Reader only. The `print_error_status=` writer still works without a warning, but `print_errors true`/`print_errors false` is the new spelling. |
+| `minimum_coverage_by_file line: 70, 'app/x.rb' => 100` | `coverage(:line) { minimum_per_file 70; minimum_per_file 100, only: 'app/x.rb' }` | The `coverage` block fixes the criterion, so per-path overrides are plain percentages with an `only:` target instead of a hash mixing Symbol / String / Regexp keys. See [Per-criterion thresholds](#per-criterion-thresholds-with-coverage). |
+| `minimum_coverage_by_group 'Models' => { line: 90 }` | `coverage(:line) { minimum_per_group 90, only: 'Models' }` | Same uniform shape as `minimum_per_file`. |
+
+Brand-new in the redesigned API (no legacy method to migrate from):
+
+| Method                              | Purpose                                                                                                                  |
+|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| `cover "lib/**/*.rb"`               | Positive scope (allowlist). Multiple calls union; strings are globs. See above for the relationship with `track_files`.  |
+| `no_default_skips`                  | Clear every previously-installed filter — defaults and anything earlier in the block — so subsequent `skip`s start clean.|
+| `formatter false` / `formatters []` | Opt out of formatting entirely. Workers in big parallel CI runs only need their `.resultset.json` for a final `SimpleCov.collate` step; skipping the formatter saves the per-job HTML / multi-formatter overhead. See #964. |
+| `parallel_tests true` / `false`     | Force on / off the auto-require of the `parallel_tests` gem. Default (unset) auto-detects from `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` and silently skips if the gem isn't installed. Set explicitly when you use those env vars for unrelated subprocess coordination. See #1018. |
+
+Example before/after:
+
+```ruby
+# Before
+SimpleCov.start do
+  add_filter "/test/"
+  add_filter %r{\Aconfig/}
+  add_group "Models", "app/models"
+  track_files "lib/**/*.rb"
+  enable_coverage_for_eval
+  use_merging true
+  enable_for_subprocesses true
+end
+
+# After
+SimpleCov.start do
+  skip "/test/"
+  skip %r{\Aconfig/}
+  group "Models", "app/models"
+  cover "lib/**/*.rb"
+  enable_coverage :eval
+  merging true
+  merge_subprocesses true
+end
+```
+
+## Coverage criteria
+
+Line coverage is on by default. You can additionally enable branch, method, oneshot-line, and eval coverage, and choose
+which criterion leads the report.
+
+### Disabling line coverage
+
+If you want a branch-only or method-only run (e.g. you find the line numbers noisy in CI and only care about whether
+each conditional was exercised), enable the criterion you want and then disable line coverage:
 
 ```ruby
 SimpleCov.start do
   enable_coverage :branch
+  disable_coverage :line
 end
 ```
 
-Branch coverage is a feature introduced in Ruby 2.5 concerning itself with whether a
-particular branch of a condition had been executed. Line coverage on the other hand
-is only interested in whether a line of code has been executed.
+If you disable every criterion, `SimpleCov.start` raises `SimpleCov::ConfigurationError` — at least one of `:line`,
+`:branch`, or `:method` must remain enabled.
+
+### Branch coverage
 
-This comes in handy for instance for one line conditionals:
+Branch coverage records whether each branch of a condition executed, not just whether a line ran.
+
+```ruby
+SimpleCov.start do
+  enable_coverage :branch
+end
+```
+
+It's handy for one-line conditionals:
 
 ```ruby
 number.odd? ? "odd" : "even"
 ```
 
-In line coverage this line would always be marked as executed but you'd never know if both
-conditions were met. Guard clauses have a similar story:
+Line coverage always marks this line as executed, but never tells you whether both arms were taken. Guard clauses have
+the same story:
 
 ```ruby
 return if number.odd?
@@ -319,91 +291,178 @@ return if number.odd?
 # more code
 ```
 
-If all the code in that method was covered you'd never know if the guard clause was ever
-triggered! With line coverage as just evaluating the condition marks it as covered.
+If the whole method is covered you still won't know whether the guard ever triggered — line coverage just sees the
+condition evaluated.
+
+In the HTML report, lines are annotated as `branch_type: hit_count`:
+
+* `then: 2` — the `then` branch (of an `if`) was executed twice
+* `else: 0` — the `else` branch (of an `if` or `case`) was never executed
+
+Even if you don't write an `else` branch, it still shows up: a missed implicit `else` means the `if` condition was
+never false, or no `when` of a `case` matched.
 
-In the HTML report the lines of code will be annotated like `branch_type: hit_count`:
+**Is branch coverage strictly better?** No. Branch coverage only concerns itself with conditionals — coverage of
+sequential code is of no interest to it. A file with no conditional logic has no branch data, and SimpleCov reports its
+0-of-0 branches as 100% (everything coverable was covered). So look at both metrics together: missing 10% of your lines
+might account for 50% of your branches.
 
-* `then: 2` - the then branch (of an `if`) was executed twice
-* `else: 0` - the else branch (of an `if` or `case`) was never executed
+#### Ignoring implicit `else` branches
 
-Not that even if you don't declare an `else` branch it will still show up in the coverage
-reports meaning that the condition of the `if` was not hit or that no `when` of `case`
-was hit during the test runs.
+Ruby's `Coverage` library reports an `:else` branch for several constructs even when the source has no literal `else`
+keyword — exhaustive `case/in` pattern matches, `case/when` without an `else` arm, `||=` / `&&=`, and `if` / `unless`
+without an `else`. Those synthetic branches show up as missed and depress the branch-coverage percentage despite there
+being no code to test. If your style relies on exhaustive pattern matching (or you just want `||=` to stop tanking
+coverage), opt out:
 
-**Is branch coverage strictly better?** No. Branch coverage really only concerns itself with
-conditionals - meaning coverage of sequential code is of no interest to it. A file without
-conditional logic will have no branch coverage data and SimpleCov will report 0 of 0
-branches covered as 100% (as everything that can be covered was covered).
+```ruby
+SimpleCov.start do
+  enable_coverage :branch
+  ignore_branches :implicit_else
+end
+```
 
-Hence, we recommend looking at both metrics together. Branch coverage might also be a good
-overall metric to look at - while you might be missing only 10% of your lines that might
-account for 50% of your branches for instance.
+`ignore_branches` is variadic; `:implicit_else` and `:eval_generated` (below) are the supported tokens. Calling it
+before (or without) `enable_coverage :branch` is harmless: the setting is stored and applies once branch coverage is
+enabled. Explicit `else` arms still count.
 
-## Primary Coverage
+#### Ignoring eval-generated branches and methods
 
-By default, the primary coverage type is `line`. To set the primary coverage to something else, use the following:
+Rails' `delegate` (and other macros that call `module_eval(body, __FILE__, __LINE__)`) make Ruby's `Coverage` library
+attribute the eval'd code to the macro's source line. The result is a `delegate :foo, to: :bar` line that surfaces in
+the report as if it had its own `def foo` and an `if` branch — both reported as missed when the delegated method isn't
+called from the suite. Drop those synthetic entries:
 
 ```ruby
-# or in configure SimpleCov.primary_coverage :branch
 SimpleCov.start do
   enable_coverage :branch
-  primary_coverage :branch
+  enable_coverage :method
+  ignore_branches :eval_generated
+  ignore_methods :eval_generated
 end
 ```
 
-Primary coverage determines what will come in first all output, and the type of coverage to check if you don't specify the type of coverage when customizing exit behavior (`SimpleCov.minimum_coverage 90`).
+`ignore_methods` is variadic; `:eval_generated` is the only supported token. Both filters detect eval-generated entries
+by walking the static source with [Prism](https://github.com/ruby/prism) and dropping any Coverage entry whose start
+line lacks a real `def` keyword (for methods) or branch construct (for branches). Prism is bundled with Ruby 3.3+; on
+older Rubies `gem install prism` enables the filter, otherwise it's a silent no-op. Real `def`s and branches that share
+a line with an eval-generated entry are kept (line-presence is the matcher).
+
+### Oneshot lines coverage
+
+Oneshot lines coverage is a faster alternative to line coverage.
 
-Note that coverage must first be enabled for non-default coverage types.
+Traditional coverage records *how many times* each line ran. Often it's enough to know *whether* each line ran at
+least once — and the counting just adds overhead. Oneshot coverage records only the first execution of each line; the
+hook for each line fires once, after which the program runs with zero overhead.
+
+```ruby
+SimpleCov.start do
+  enable_coverage :oneshot_line
+  primary_coverage :oneshot_line
+end
+```
+
+### Eval coverage
+
+You can measure coverage for code evaluated by `Kernel#eval`. Supported in CRuby 3.2+.
+
+```ruby
+SimpleCov.start do
+  enable_coverage :eval
+end
+```
+
+This is typically useful for ERB. Set `ERB#filename=` so SimpleCov can trace the original `.erb` source file.
+
+### Primary coverage
+
+By default the primary coverage type is `line`. The primary type determines what comes first in all output, and which
+type is checked when you customize exit behavior without naming a type (e.g. `SimpleCov.minimum_coverage 90`). To change
+it:
+
+```ruby
+SimpleCov.start do
+  enable_coverage :branch
+  primary_coverage :branch
+end
+
+# or, outside a block:
+SimpleCov.primary_coverage :branch
+```
+
+Coverage must first be enabled for non-default types.
 
 ## Filters
 
-Filters can be used to remove selected files from your coverage data. By default, a filter is applied that removes all
-files OUTSIDE of your project's root directory - otherwise you'd end up with billions of coverage reports for source
-files in the gems you are using.
+Filters remove selected files from your coverage data.
 
-You can define your own to remove things like configuration files, tests or whatever you don't need in your coverage
-report.
+### Default filters
+
+`SimpleCov.start` loads four filters out of the box:
+
+* **`root_filter`** — drops every file outside of `SimpleCov.root`, so you don't end up with coverage reports for the
+  source files of every gem in your bundle. (See [Covering files outside the root](#covering-files-outside-the-root).)
+* **`bundler_filter`** — drops `/vendor/bundle/` (in case a project keeps its gems checked into the repo).
+* **`hidden_filter`** — drops any path that starts with a dot, matching the regex `/\A\..*/`. This is what hides
+  `.bundle/`, `.semaphore-cache/`, and similar dotfile directories — but it also hides legitimate top-level directories
+  like `.scripts/`. If you keep code in such a directory, remove this filter (see below).
+* **`test_frameworks`** — drops common test directories (`test/`, `spec/`, `features/`, `autotest/`), matching the
+  regex `%r{\A(test|features|spec|autotest)/}`. Running the test suite always executes 100% of the test files
+  themselves, which inflates the overall percentage and obscures application coverage. Remove this filter if you
+  prefer to see test files in the report (e.g. to surface dead helpers).
+
+For a clean slate (no defaults at all), `require 'simplecov/no_defaults'` *before* `require 'simplecov'`, or call
+`SimpleCov.clear_filters` from your config block. To drop a specific default while keeping the others, use
+`remove_filter`:
+
+```ruby
+SimpleCov.start do
+  remove_filter(/\A\..*/) # restore coverage for .scripts/, .tooling/, etc.
+end
+```
+
+`remove_filter` matches by value, so pass back the same `String` or `Regexp` the default profile used. For filters
+added with a block, pass the same `Proc` object you originally handed to `skip`.
 
 ### Defining custom filters
 
-You can currently define a filter using either a String or Regexp (that will then be Regexp-matched against each source
-file's path), a block or by passing in your own Filter class.
+Define your own filters to remove configuration files, tests, or anything else you don't need in the report. A filter
+can be a String or Regexp (Regexp-matched against each source file's path), a block, your own Filter class, or an array
+of any of these.
 
 #### String filter
 
 ```ruby
 SimpleCov.start do
-  add_filter "/test/"
+  skip "/test/"
 end
 ```
 
-This simple string filter will remove all files that match "/test/" in their path.
+Removes all files whose path matches "/test/".
 
 #### Regex filter
 
 ```ruby
 SimpleCov.start do
-  add_filter %r{^/test/}
+  skip %r{^/test/}
 end
 ```
 
-This simple regex filter will remove all files that start with /test/ in their path.
+Removes all files whose path starts with /test/.
 
 #### Block filter
 
 ```ruby
 SimpleCov.start do
-  add_filter do |source_file|
+  skip do |source_file|
     source_file.lines.count < 5
   end
 end
 ```
 
-Block filters receive a SimpleCov::SourceFile instance and expect your block to return either true (if the file is to be
-removed from the result) or false (if the result should be kept). Please check out the RDoc for SimpleCov::SourceFile to
-learn about the methods available to you. In the above example, the filter will remove all files that have less than 5
-lines of code.
+Block filters receive a `SimpleCov::SourceFile` and return `true` to remove the file or `false` to keep it. (See the
+RDoc for `SimpleCov::SourceFile` for the available methods.) The example above removes files with fewer than 5 lines.
 
 #### Custom filter class
 
@@ -414,104 +473,234 @@ class LineFilter < SimpleCov::Filter
   end
 end
 
-SimpleCov.add_filter LineFilter.new(5)
+SimpleCov.skip LineFilter.new(5)
 ```
 
-Defining your own filters is pretty easy: Just inherit from SimpleCov::Filter and define a method
-'matches?(source_file)'. When running the filter, a true return value from this method will result in the removal of the
-given source_file. The filter_argument method is being set in the SimpleCov::Filter initialize method and thus is set to
-5 in this example.
+Inherit from `SimpleCov::Filter` and define `matches?(source_file)`; a `true` return removes the file. The
+`filter_argument` is set in the `SimpleCov::Filter` initializer — `5` in this example.
 
 #### Array filter
 
 ```ruby
 SimpleCov.start do
   proc = Proc.new { |source_file| false }
-  add_filter ["string", /regex/, proc, LineFilter.new(5)]
+  skip ["string", /regex/, proc, LineFilter.new(5)]
 end
 ```
 
-You can pass in an array containing any of the other filter types.
+Pass an array containing any of the other filter types.
 
-#### Ignoring/skipping code
+### Ignoring/skipping code
 
-You can exclude code from the coverage report by wrapping it in `# :nocov:`.
+Disable coverage for a span of code with `# simplecov:disable` and `# simplecov:enable` comments. The available
+categories are `line`, `branch`, and `method`; combine them with commas, and omit them to target all three. Anything
+trailing the directive is treated as a free-form reason and ignored — no separator is required, though `--` or any
+other marker is fine if you prefer one.
 
 ```ruby
-# :nocov:
-def skip_this_method
+# simplecov:disable line
+def skipped_lines
   never_reached
 end
-# :nocov:
+# simplecov:enable line
+
+# simplecov:disable branch, method legacy adapter, scheduled for removal
+class LegacyAdapter
+  def call(value)
+    value ? :yes : :no
+  end
+end
+# simplecov:enable
+
+raise "absurd" # simplecov:disable
 ```
 
-The name of the token can be changed to your liking. [Learn more about the nocov feature.]( https://github.com/simplecov-ruby/simplecov/blob/main/features/config_nocov_token.feature)
+Inline directives (trailing real code) only affect the line they sit on. Block directives sit on their own line and
+remain in effect until the matching `# simplecov:enable` for the same category — or end of file if never closed.
+Directive markers inside string literals or heredocs are ignored.
 
-**Note:** You shouldn't have to use the nocov token to skip private methods that are being included in your coverage. If
-you appropriately test the public interface of your classes and objects you should automatically get full coverage of
-your private methods.
+> [!WARNING]
+> The older `# :nocov:` toggle still works but is **deprecated** and will be removed in a future release. Each file
+> that uses it emits a one-time deprecation warning pointing at the recommended `# simplecov:disable` /
+> `# simplecov:enable` replacement. The configurable token name (`SimpleCov.nocov_token`) is similarly deprecated.
 
-## Default root filter and coverage for things outside of it
+> [!NOTE]
+> You shouldn't have to skip private methods that are included in your coverage. If you appropriately test the public
+> interface of your classes and objects, you should automatically get full coverage of your private methods.
 
-By default, SimpleCov filters everything outside of the `SimpleCov.root` directory. However, sometimes you may want
-to include coverage reports for things you include as a gem, for example a Rails Engine.
+### How `cover` and `skip` interact
 
-Here's an example by [@lsaffie](https://github.com/lsaffie) from [#221](https://github.com/simplecov-ruby/simplecov/issues/221)
-that shows how you can achieve just that:
+`cover` and `skip` operate on different sides of the same chain. `skip` (and its deprecated `add_filter` alias) drops
+matching files from the report. `cover` declares a positive scope that restricts the final report to files matching at
+least one `cover` matcher.
+
+Order: `skip` runs first, then `cover`. A file matched by any `skip` filter is dropped before `cover` is consulted, so
+a file matched by both is dropped, not kept. The two are not commutative.
 
 ```ruby
+SimpleCov.start do
+  cover "{app,lib}/**/*.rb"
+  skip  "app/legacy"
+end
+```
+
+That config covers `app/` and `lib/`, then drops `app/legacy/`. With only `cover` and no overlapping `skip`, every
+configured default filter (hidden files, vendored gems, test directories) still applies — `cover` doesn't bypass them.
+Use `no_default_skips` to opt out of the defaults wholesale before adding your own.
+
+`cover` also expands string-glob matchers on disk so files that exist but were never `require`'d during the run still
+appear in the report (at 0% coverage). Regexp and Proc cover matchers don't trigger disk discovery — they only filter
+the universe of files that Ruby's `Coverage` library reported.
+
+### Covering files outside the root
+
+The `root_filter` drops every file outside of `SimpleCov.root` from the raw coverage data before any other filters or
+groups run, so paths you might want to track (a Rails Engine installed as a gem, sibling directories in a Docker
+layout, etc.) never reach your filter chain. To include them, widen `SimpleCov.root` to a directory that contains both
+the project and the extra paths — `'/'` works when there's no useful common ancestor — and then express the
+inclusion/exclusion as filters or groups:
+
+```ruby
+SimpleCov.root '/'
 SimpleCov.start :rails do
-  filters.clear # This will remove the :root_filter and :bundler_filter that come via simplecov's defaults
-  add_filter do |src|
-    !(src.filename =~ /^#{SimpleCov.root}/) unless src.filename =~ /my_engine/
-  end
+  skip { |src| !src.filename.start_with?(Rails.root.to_s, '/path/to/my_engine') }
 end
 ```
 
 ## Groups
 
-You can separate your source files into groups. For example, in a Rails app, you'll want to have separate listings for
-Models, Controllers, Helpers, and Libs. Group definition works similarly to Filters (and also accepts custom
-filter classes), but source files end up in a group when the filter passes (returns true), as opposed to filtering
-results, which exclude files from results when the filter results in a true value.
-
-Add your groups with:
+Separate your source files into groups — for example, a Rails app might list Models, Controllers, Helpers, and Libs
+separately. Group definition works like filters (and also accepts custom filter classes), but a source file ends up in
+a group when the filter *passes* (returns `true`), as opposed to being excluded from results when a filter returns
+`true`.
 
 ```ruby
 SimpleCov.start do
-  add_group "Models", "app/models"
-  add_group "Controllers", "app/controllers"
-  add_group "Long files" do |src_file|
+  group "Models", "app/models"
+  group "Controllers", "app/controllers"
+  group "Long files" do |src_file|
     src_file.lines.count > 100
   end
-  add_group "Multiple Files", ["app/models", "app/controllers"] # You can also pass in an array
-  add_group "Short files", LineFilter.new(5) # Using the LineFilter class defined in Filters section above
+  group "Multiple Files", ["app/models", "app/controllers"] # You can also pass in an array
+  group "Short files", LineFilter.new(5) # Using the LineFilter class defined in the Filters section above
 end
 ```
 
-## Merging results
+## Profiles
 
-You normally want to have your coverage analyzed across ALL of your test suites, right?
+By default, SimpleCov's only assumption is that you want coverage for files inside your project root. To avoid
+repetitive configuration, you can use predefined blocks of configuration called 'profiles', or define your own. Pass a
+profile's name as the first argument to `SimpleCov.start`.
 
-Simplecov automatically caches coverage results in your
-(coverage_path)/.resultset.json, and will merge or override those with
-subsequent runs, depending on whether simplecov considers those subsequent runs
-as different test suites or as the same test suite as the cached results. To
-make this distinction, simplecov has the concept of "test suite names".
+SimpleCov bundles a `rails` profile that looks roughly like this:
 
-### Test suite names
+```ruby
+SimpleCov.profiles.define 'rails' do
+  skip '/test/'
+  skip '/config/'
+
+  group 'Controllers', 'app/controllers'
+  group 'Models', 'app/models'
+  group 'Helpers', 'app/helpers'
+  group 'Libraries', 'lib'
+end
+```
+
+It's just a `SimpleCov.configure` block. Launch it from your test helper, optionally adding more config:
 
-SimpleCov tries to guess the name of the currently running test suite based upon the shell command the tests
-are running on. This should work fine for Unit Tests, RSpec, and Cucumber. If it fails, it will use the shell
-command that invoked the test suite as a command name.
+```ruby
+SimpleCov.start 'rails'
 
-If you have some non-standard setup and still want nicely labeled test suites, you have to give Simplecov a
-cue as to what the name of the currently running test suite is. You can do so by specifying
-`SimpleCov.command_name` in one test file that is part of your specific suite.
+# or
 
-To customize the suite names on a Rails app (yeah, sorry for being Rails-biased, but everyone knows what
-the structure of those projects is. You can apply this accordingly to the RSpecs in your
-Outlook-WebDAV-Calendar-Sync gem), you could do something like this:
+SimpleCov.start 'rails' do
+  # additional config here
+end
+```
+
+### The `strict` profile
+
+For projects that have already reached full coverage (or want to ratchet up to it), the bundled `strict` profile
+enables line, branch, and method coverage and pins each minimum threshold at 100%:
+
+```ruby
+SimpleCov.start 'strict'
+```
+
+That's equivalent to:
+
+```ruby
+SimpleCov.start do
+  enable_coverage :branch
+  enable_coverage :method
+  enable_coverage :eval if Coverage.respond_to?(:supported?) && Coverage.supported?(:eval)
+  minimum_coverage line: 100, branch: 100, method: 100
+end
+```
+
+The profile drops the branch / method clauses on engines that don't support those criteria (JRuby), so it still loads
+cleanly there, enforcing line coverage at 100%. `:eval` is included on Ruby 3.2+ (where the runtime supports it), so
+any code reached through `Kernel#eval` — typically ERB templates with `ERB#filename=` set — is held to the same 100%
+bar. On older Rubies, the `:eval` clause is silently skipped.
+
+### Custom profiles
+
+Load additional profiles with `SimpleCov.load_profile('xyz')`. This lets you build on an existing profile and reuse
+it across unit tests and Cucumber features:
+
+```ruby
+# lib/simplecov_custom_profile.rb
+require 'simplecov'
+SimpleCov.profiles.define 'myprofile' do
+  load_profile 'rails'
+  skip 'vendor' # Don't include vendored stuff
+end
+
+# features/support/env.rb
+require 'simplecov_custom_profile'
+SimpleCov.start 'myprofile'
+
+# test/test_helper.rb
+require 'simplecov_custom_profile'
+SimpleCov.start 'myprofile'
+```
+
+### Profile plugin gems
+
+If `SimpleCov.start "<name>"` doesn't find a profile registered under `<name>`, the bundled profile loader tries to
+autoload one in two steps: first `require "simplecov/profiles/<name>"` (where bundled profiles like `rails` and
+`strict` live), then `require "simplecov-profile-<name>"` (the conventional name for a third-party plugin gem). Either
+require is expected to call `SimpleCov.profiles.define "<name>" do ... end` so the registered block can be applied. If
+both requires fail or neither registers the profile, `SimpleCov.start` raises `SimpleCov::ConfigurationError`.
+
+To publish your own profile as a gem, name it `simplecov-profile-<name>` and have its main file call
+`SimpleCov.profiles.define`:
+
+```ruby
+# In a gem named simplecov-profile-myteam
+SimpleCov.profiles.define "myteam" do
+  enable_coverage :branch
+  cover "{app,lib}/**/*.rb"
+  skip  "app/legacy"
+end
+```
+
+A user who adds the gem to their Gemfile can then `SimpleCov.start "myteam"` without explicitly requiring it.
+
+## Merging results and parallel tests
+
+You normally want coverage analyzed across ALL of your test suites at once. SimpleCov automatically caches results in
+`(coverage_path)/.resultset.json` and merges them with subsequent runs — or overrides them, depending on whether it
+considers a subsequent run a different test suite or the same one. To make that distinction, SimpleCov uses the concept
+of **test suite names**.
+
+### Test suite names
+
+SimpleCov guesses the running suite's name from the shell command that started the tests. This works fine for Test::Unit,
+RSpec, and Cucumber; if it fails, it falls back to the invoking shell command as the command name.
+
+For a non-standard setup, give SimpleCov a cue with `SimpleCov.command_name` in one test file per suite (you only need
+it once per suite — even with 200 unit test files, setting it in one is enough):
 
 ```ruby
 # test/unit/some_test.rb
@@ -527,52 +716,36 @@ SimpleCov.command_name "test:integration"
 SimpleCov.command_name "features"
 ```
 
-Note that this only has to be invoked ONCE PER TEST SUITE, so even if you have 200 unit test files,
-specifying it in `some_test.rb` is enough.
+**If multiple suites resolve to the same `command_name`, their results clobber each other instead of merging.**
+SimpleCov detects unique names for the most common setups, but if you have more than one suite that doesn't follow a
+common pattern, ensure each gets a unique `command_name`.
 
-Last but not least **if multiple suites resolve to the same `command_name`** be aware that the coverage results **will
-clobber each other instead of being merged**.  SimpleCov is smart enough to detect unique names for the most common
-setups, but if you have more than one test suite that doesn't follow a common pattern then you will want to manually
-ensure that each suite gets a unique `command_name`.
-
-If you are running tests in parallel each process has the potential to clobber results from the other test processes.
-If you are relying on the default `command_name` then SimpleCov will attempt to detect and avoid parallel test suite
-`command_name` collisions based on the presence of `ENV['PARALLEL_TEST_GROUPS']` and `ENV['TEST_ENV_NUMBER']`.  If your
-parallel test runner does not set one or both of these then *you must* set a `command_name` and ensure that it is unique
-per process (eg. `command_name "Unit Tests PID #{$$}"`).
-
-If you are using parallel_tests, you must incorporate `TEST_ENV_NUMBER` into the command name yourself, in
-order for SimpleCov to merge the results correctly. For example:
+When running tests in parallel, each process can clobber the others' results. With the default `command_name`,
+SimpleCov detects and avoids collisions based on `ENV['PARALLEL_TEST_GROUPS']` and `ENV['TEST_ENV_NUMBER']`. If your
+runner sets neither, *you must* set a `command_name` that's unique per process (e.g. `command_name "Unit Tests PID #{$$}"`).
+With parallel_tests specifically, incorporate `TEST_ENV_NUMBER` into the name yourself so results merge correctly:
 
 ```ruby
 # spec/spec_helper.rb
 SimpleCov.command_name "features" + (ENV['TEST_ENV_NUMBER'] || '')
 ```
 
-[simplecov-html] prints the used test suites in the footer of the generated coverage report.
-
-
-### Merging test runs under the same execution environment
+The HTML report prints the test suites it used in its footer.
 
-Test results are automatically merged with previous runs in the same execution
-environment when generating the result, so when coverage is set up properly for
-Cucumber and your unit / functional / integration tests, all of those test
-suites will be taken into account when building the coverage report.
+### Merging within one execution environment
 
-#### Timeout for merge
-
-Of course, your cached coverage data is likely to become invalid at some point. Thus, when automatically merging
-subsequent test runs, result sets that are older than `SimpleCov.merge_timeout` will not be used any more. By default,
-the timeout is 600 seconds (10 minutes), and you can raise (or lower) it by specifying `SimpleCov.merge_timeout 3600`
-(1 hour), or, inside a configure/start block, with just `merge_timeout 3600`.
+Results are automatically merged with previous runs in the same execution environment when the report is generated, so
+once coverage is set up for Cucumber and your unit / functional / integration tests, all of those suites feed into one
+report.
 
-You can deactivate this automatic merging altogether with `SimpleCov.use_merging false`.
+Cached coverage data eventually goes stale, so result sets older than `SimpleCov.merge_timeout` are dropped from the
+merge. The default is 600 seconds (10 minutes); raise or lower it with `SimpleCov.merge_timeout 3600` (1 hour), or
+`merge_timeout 3600` inside a configure/start block. Deactivate automatic merging entirely with `SimpleCov.merging false`.
 
-### Merging test runs under different execution environments
+### Merging across execution environments
 
-If your tests are done in parallel across multiple build machines, you can fetch them all and merge them into a single
-result set using the `SimpleCov.collate` method. This can be added to a Rakefile or script file, having downloaded a set of
-`.resultset.json` files from each parallel test run.
+If your tests run in parallel across multiple build machines, download each run's `.resultset.json` and merge them into
+a single result set with `SimpleCov.collate`:
 
 ```ruby
 # lib/tasks/coverage_report.rake
@@ -586,12 +759,10 @@ namespace :coverage do
 end
 ```
 
-`SimpleCov.collate` also takes an optional simplecov profile and an optional
-block for configuration, just the same as `SimpleCov.start` or
-`SimpleCov.configure`.  This means you can configure a separate formatter for
-the collated output. For instance, you can make the formatter in
-`SimpleCov.start` the `SimpleCov::Formatter::SimpleFormatter`, and only use more
-complex formatters in the final `SimpleCov.collate` run.
+`SimpleCov.collate` also takes an optional profile and an optional configuration block, just like `SimpleCov.start` or
+`SimpleCov.configure`. This means you can configure a separate formatter for the collated output — for instance, use the
+plain `SimpleCov::Formatter::SimpleFormatter` in each worker's `SimpleCov.start` and reserve heavier formatters for the
+final `SimpleCov.collate` run:
 
 ```ruby
 # spec/spec_helper.rb
@@ -610,7 +781,7 @@ SimpleCov.start 'rails' do
     ])
   end
 
-  track_files "**/*.rb"
+  cover "{app,lib}/**/*.rb"
 end
 ```
 
@@ -630,21 +801,19 @@ namespace :coverage do
 end
 ```
 
-## Running simplecov against subprocesses
+### Forked subprocesses
 
-`SimpleCov.enable_for_subprocesses` will allow SimpleCov to observe subprocesses starting using `Process.fork`.
-This modifies ruby's core Process.fork method so that SimpleCov can see into it, appending `" (subprocess #{pid})"`
-to the `SimpleCov.command_name`, with results that can be merged together using SimpleCov's merging feature.
-
-To configure this, use `.at_fork`.
+`SimpleCov.merge_subprocesses true` lets SimpleCov observe subprocesses started with `Process.fork`. It wraps Ruby's
+`Process.fork` so SimpleCov can see into the child, appending `" (subprocess #{pid})"` to the `command_name`, with
+results that merge back together. Configure the child with `.at_fork`:
 
 ```ruby
-SimpleCov.enable_for_subprocesses true
+SimpleCov.merge_subprocesses true
 SimpleCov.at_fork do |pid|
-  # This needs a unique name so it won't be ovewritten
+  # This needs a unique name so it won't be overwritten
   SimpleCov.command_name "#{SimpleCov.command_name} (subprocess: #{pid})"
   # be quiet, the parent process will be in charge of output and checking coverage totals
-  SimpleCov.print_error_status = false
+  SimpleCov.print_errors false
   SimpleCov.formatter SimpleCov::Formatter::SimpleFormatter
   SimpleCov.minimum_coverage 0
   # start
@@ -652,248 +821,555 @@ SimpleCov.at_fork do |pid|
 end
 ```
 
-NOTE: SimpleCov must have already been started before `Process.fork` was called.
+SimpleCov must already be started before `Process.fork` is called.
+
+> [!NOTE]
+> The bundled `rails` profile turns this on automatically, so `ActiveSupport::TestCase.parallelize(workers: ...)`
+> worker forks contribute to the merged report instead of being silently dropped.
 
-### Running simplecov against spawned subprocesses
+#### Spawned subprocesses
 
-Perhaps you're testing a ruby script with `PTY.spawn` or `Open3.popen`, or `Process.spawn` or etc.
-SimpleCov can cover this too.
+You can also cover a Ruby script you launch with `PTY.spawn`, `Open3.popen`, `Process.spawn`, and the like. Add a
+`.simplecov_spawn.rb` file to your project root:
 
-Add a .simplecov_spawn.rb file to your project root
 ```ruby
 # .simplecov_spawn.rb
-require 'simplecov' # this will also pick up whatever config is in .simplecov
-                    # so ensure it just contains configuration, and doesn't call SimpleCov.start.
-SimpleCov.command_name 'spawn' # As this is not for a test runner directly, script doesn't have a pre-defined base command_name
-SimpleCov.at_fork.call(Process.pid) # Use the per-process setup described previously
-SimpleCov.start # only now can we start.
+require 'simplecov' # this will also pick up whatever config is in .simplecov,
+                    # so ensure it just contains configuration and doesn't call SimpleCov.start.
+SimpleCov.command_name 'spawn' # As this isn't for a test runner directly, the script has no pre-defined base command_name
+SimpleCov.at_fork.call(Process.pid) # Use the per-process setup described above
+SimpleCov.start # only now can we start
 ```
-Then, instead of calling your script directly, like:
+
+Then, instead of spawning your script directly:
+
 ```ruby
 PTY.spawn('my_script.rb') do # ...
 ```
-Use bin/ruby to require the new .simplecov_spawn file, then your script
+
+use `ruby -r` to require the spawn file first:
+
 ```ruby
 PTY.spawn('ruby -r./.simplecov_spawn my_script.rb') do # ...
 ```
 
-## Running coverage only on demand
+### Parallel-test-runner adapters
 
-The Ruby STDLIB Coverage library that SimpleCov builds upon is *very* fast (on a ~10 min Rails test suite, the speed
-drop was only a couple seconds for me), and therefore it's SimpleCov's policy to just generate coverage every time you
-run your tests because it doesn't do your test speed any harm and you're always equipped with the latest and greatest
-coverage results.
+SimpleCov coordinates with parallel test runners through a small pluggable adapter interface
+(`SimpleCov::ParallelAdapters`). Two adapters ship out of the box:
 
-Because of this, SimpleCov has no explicit built-in mechanism to run coverage only on demand.
+- **`ParallelTestsAdapter`** — wraps the [grosser/parallel_tests](https://github.com/grosser/parallel_tests) gem and
+  uses its `ParallelTests.first_process?` / `ParallelTests.wait_for_other_processes_to_finish` APIs for precise worker
+  coordination.
+- **`GenericAdapter`** — catch-all for any runner that follows the `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` env-var
+  convention but doesn't ship a Ruby API (parallel_rspec, knapsack-style splitters, custom CI sharding scripts).
+  Activates when `TEST_ENV_NUMBER` is set and no more-specific adapter is.
 
-However, you can still accomplish this very easily by introducing an ENV variable conditional into your SimpleCov setup
-block, like this:
+Adapters are tried in registration order; the first whose `active?` returns `true` is chosen. With both built-ins, this
+means parallel_tests users get the precise gem-based path and parallel_rspec (or any env-var-only runner) gets the
+polling-based fallback without any configuration change. See #1065.
 
-```ruby
-SimpleCov.start if ENV["COVERAGE"]
-```
+#### Registering a custom adapter
 
-Then, SimpleCov will only run if you execute your tests like this:
+If you use a parallel runner with different env vars or its own synchronization API, define a class that inherits from
+`SimpleCov::ParallelAdapters::Base` and register it:
 
-```shell
-COVERAGE=true rake test
-```
+```ruby
+# In your spec_helper.rb / test_helper.rb (before SimpleCov.start)
+class MyRunnerAdapter < SimpleCov::ParallelAdapters::Base
+  def self.active?
+    !ENV["MY_RUNNER_PID"].nil?
+  end
 
-## Errors and exit statuses
+  def self.first_worker?
+    ENV["MY_RUNNER_PID"].to_i == 1
+  end
 
-To aid in debugging issues, if an error is raised, SimpleCov will print a message to `STDERR`
-with the exit status of the error, like:
+  def self.wait_for_siblings
+    MyRunner.barrier!   # if your runner provides a sync primitive
+  end
 
-```
-SimpleCov failed with exit 1
+  def self.expected_worker_count
+    ENV["MY_RUNNER_WORKERS"].to_i
+  end
+end
+
+SimpleCov::ParallelAdapters.register MyRunnerAdapter
 ```
 
-This `STDERR` message can be disabled with:
+Custom adapters are inserted at the front of the selection chain, so they take precedence over the built-ins. `Base`
+provides safe no-op defaults for any method you don't override (single-process semantics: `active?` returns `false`,
+`first_worker?` returns `true`, etc.).
 
-```
-SimpleCov.print_error_status = false
+## Coverage thresholds and exit behavior
+
+Define what SimpleCov does when your test suite finishes by customizing the `at_exit` hook. The default is shown below;
+do whatever you like instead:
+
+```ruby
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+end
 ```
 
-## Profiles
+The threshold settings below make SimpleCov exit non-zero when coverage doesn't meet your expectations, so they double
+as CI gates.
 
-By default, SimpleCov's only config assumption is that you only want coverage reports for files inside your project
-root. To save yourself from repetitive configuration, you can use predefined blocks of configuration, called 'profiles',
-or define your own.
+### Per-criterion thresholds with `coverage`
 
-You can then pass the name of the profile to be used as the first argument to SimpleCov.start. For example, simplecov
-comes bundled with a 'rails' profile. It looks somewhat like this:
+The `coverage` block configures each criterion (line, branch, method) the same way: because the criterion is fixed by
+the enclosing block, every threshold value is a plain percentage, so line, branch, and method coverage read identically.
+Naming a criterion also enables it (line is enabled by default).
 
 ```ruby
-SimpleCov.profiles.define 'rails' do
-  add_filter '/test/'
-  add_filter '/config/'
+SimpleCov.start do
+  coverage :line do
+    minimum           90    # suite-wide minimum; SimpleCov exits non-zero if unmet
+    minimum_per_file  80    # per-file minimum
+    minimum_per_file  100, only: "app/mailers/request_mailer.rb"  # per-path override (String path or Regexp)
+    minimum_per_group 95, only: "Models"                          # minimum for a named group
+    maximum_drop      5     # exit non-zero if coverage drops more than 5% between runs
+  end
 
-  add_group 'Controllers', 'app/controllers'
-  add_group 'Models', 'app/models'
-  add_group 'Helpers', 'app/helpers'
-  add_group 'Libraries', 'lib'
+  coverage :branch, minimum: 80    # one-liner form for a single setting
+  coverage :method, minimum: 100
 end
 ```
 
-As you can see, it's just a SimpleCov.configure block. In your test_helper.rb, launch SimpleCov with:
+| Verb | Effect |
+|------|--------|
+| `minimum N` | Suite-wide minimum for this criterion. |
+| `maximum N` | Suite-wide maximum: fails if coverage rises above N. Pairs with `minimum` to pin coverage so an unexpected jump fails instead of being silently absorbed. |
+| `exact N` | Pins coverage by setting both `minimum` and `maximum` to N. |
+| `maximum_drop N` | Maximum allowed drop between runs (`maximum_drop 0` refuses any drop). |
+| `minimum_per_file N` | Per-file minimum. Add `only: "path"` / `only: %r{regexp}` to override it for matching files (later, more specific overrides win). |
+| `minimum_per_group N, only: "Name"` | Minimum for a named [group](#groups). |
+
+Every verb is also a keyword on the one-liner form (`coverage :branch, minimum: 80, maximum_drop: 5`). Two more options:
+`coverage :line, oneshot: true` selects the faster [oneshot-lines mode](#oneshot-lines-coverage), and
+`coverage :branch, primary: true` makes branch the report's leading criterion (the one a bare `minimum_coverage 90`
+targets). `coverage :eval` enables [eval coverage](#eval-coverage).
+
+### Suite-wide shortcuts
+
+For the common case of a single suite-wide threshold, the flat helpers are convenient sugar over the block above. A bare
+number targets the primary criterion (line by default); a Hash sets per-criterion values:
 
 ```ruby
-SimpleCov.start 'rails'
+SimpleCov.minimum_coverage 90                      # primary criterion (line)
+SimpleCov.minimum_coverage line: 90, branch: 80
+SimpleCov.maximum_coverage line: 90
+SimpleCov.maximum_coverage_drop line: 5, branch: 10
+SimpleCov.expected_coverage 95.42                  # pins minimum == maximum
+SimpleCov.refuse_coverage_drop :line, :branch      # maximum drop of 0
 ```
 
-or
+`expected_coverage` floors the actual percentage to two decimal places, so an actual of 95.4287 still passes at
+`expected_coverage 95.42`.
+
+> [!NOTE]
+> `minimum_coverage_by_file` and `minimum_coverage_by_group` are **deprecated** in favor of the `coverage` block's
+> `minimum_per_file` / `minimum_per_group`. They still work but emit a deprecation warning. For example, replace
+> `minimum_coverage_by_file line: 70, 'app/x.rb' => 100` with:
+>
+> ```ruby
+> coverage :line do
+>   minimum_per_file 70
+>   minimum_per_file 100, only: "app/x.rb"
+> end
+> ```
+
+## Formatters
+
+### Using your own formatter
 
 ```ruby
-SimpleCov.start 'rails' do
-  # additional config here
-end
+SimpleCov.formatter = SimpleCov::Formatter::HTMLFormatter
 ```
 
-### Custom profiles
+`SimpleCov.result.format!` then invokes `SimpleCov::Formatter::YourFormatter.new.format(result)`, where `result` is a
+`SimpleCov::Result`. Do whatever you wish with it.
 
-You can load additional profiles with the SimpleCov.load_profile('xyz') method. This allows you to build upon an
-existing profile and customize it so you can reuse it in unit tests and Cucumber features. For example:
+### Using multiple formatters
 
-```ruby
-# lib/simplecov_custom_profile.rb
-require 'simplecov'
-SimpleCov.profiles.define 'myprofile' do
-  load_profile 'rails'
-  add_filter 'vendor' # Don't include vendored stuff
-end
+As of SimpleCov 0.9 you can specify multiple result formats. The HTML and JSON formatters are built in; other
+formatters ship as separate gems you'll need to add and require — for example,
+[simplecov-cobertura](https://github.com/dashingrocket/simplecov-cobertura) for the Cobertura XML that many CI services
+consume.
 
-# features/support/env.rb
-require 'simplecov_custom_profile'
-SimpleCov.start 'myprofile'
+```ruby
+require "simplecov-cobertura"
 
-# test/test_helper.rb
-require 'simplecov_custom_profile'
-SimpleCov.start 'myprofile'
+SimpleCov.formatters = [
+  SimpleCov::Formatter::HTMLFormatter,
+  SimpleCov::Formatter::CoberturaFormatter,
+]
 ```
 
-## Customizing exit behaviour
+### JSON formatter
 
-You can define what SimpleCov should do when your test suite finishes by customizing the at_exit hook:
+`SimpleCov::Formatter::JSONFormatter` emits JSON — useful for CI consumption or reporting to external services.
 
 ```ruby
-SimpleCov.at_exit do
-  SimpleCov.result.format!
+SimpleCov.formatter = SimpleCov::Formatter::JSONFormatter
+```
+
+By default `coverage.json` carries the full source-text array for every file, which makes the payload self-contained
+but dominates the file size on larger projects. Tools that read the project's source files directly from disk can opt
+out of that field with:
+
+```ruby
+SimpleCov.start do
+  source_in_json false
 end
 ```
 
-Above is the default behaviour. Do whatever you like instead!
+The HTML report's `coverage_data.js` always retains the source array — the client-side viewer renders source from
+there. The setting only affects the side-file `coverage.json`. When the source is omitted, `meta.commit` (the git
+commit SHA the report was generated against) lets tools recover the exact source lines from repository history.
+
+> The JSON formatter was originally a separate gem,
+> [simplecov_json_formatter](https://github.com/codeclimate-community/simplecov_json_formatter). It is now built in and
+> loaded by default; existing code that does `require "simplecov_json_formatter"` will continue to work.
+
+### JSON Schema for `coverage.json`
+
+`coverage.json` is a public contract, described by a JSON Schema (2020-12) so downstream tools can validate it,
+generate types, or pin to a known shape. Every emitted document carries a top-level `$schema` URL pointing at the
+versioned canonical, plus a human-readable `meta.schema_version` (`"major.minor"`).
+
+The **versioned canonical** lives at [`schemas/coverage-v1.0.schema.json`](schemas/coverage-v1.0.schema.json) and
+long-lived integrations should pin to it. Once a SimpleCov release ships with a given versioned schema file, that file
+is immutable: bug fixes, additions, or shape changes ship as a new versioned file (a minor or major bump), never as a
+silent rewrite of an already-released one. Schemas may still be corrected in-place between gem releases — i.e., the
+schema file as it currently exists on `main` may change before the next gem release, but the schema for any published
+gem version stays frozen. A convenience alias at [`schemas/coverage.schema.json`](schemas/coverage.schema.json) always
+tracks the latest and may shift when a new SimpleCov release bumps the schema.
+
+The schema version is independent of the gem version:
+
+- Additive changes (new fields) bump the **minor** segment. Existing consumers keep working.
+- Removals or shape changes bump the **major** segment, and ship as a new `schemas/coverage-vX.0.schema.json` file so
+  v1.x consumers stay valid.
+
+The current version is **1.0**. Top-level structure:
+
+```jsonc
+{
+  "$schema":  "https://raw.githubusercontent.com/simplecov-ruby/simplecov/main/schemas/coverage-v1.0.schema.json",
+  "meta":     { /* schema_version, simplecov_version, command_name, project_name, timestamp, root, commit, line_coverage, branch_coverage, method_coverage */ },
+  "total":    { /* aggregate stats for lines (and branches / methods when enabled) */ },
+  "coverage": { "<project-relative path>": { /* per-file lines, source, branches, methods, etc. */ } },
+  "groups":   { "<group name>": { /* per-group stats + files */ } },
+  "errors":   { /* minimum_coverage, minimum_coverage_by_file, minimum_coverage_by_group, maximum_coverage, maximum_coverage_drop violations */ }
+}
+```
+
+The `.resultset.json` file is **not** schema'd — it's SimpleCov-internal and may change shape across releases. Build
+integrations on top of `coverage.json`.
 
-### Minimum coverage
+### More formatters, editor integrations, and hosted services
 
-You can define the minimum coverage percentage expected. SimpleCov will return non-zero if unmet.
+  * [Open Source formatter and integration plugins for SimpleCov](doc/alternate-formatters.md)
+  * [Editor Integration](doc/editor-integration.md)
+  * [Hosted (commercial) services](doc/commercial-services.md)
+
+## Output and diagnostics
+
+### Errors and exit statuses
+
+If an error is raised, SimpleCov prints a message to `STDERR` with the exit status, to aid debugging:
+
+```
+SimpleCov failed with exit 1
+```
+
+Disable this message with:
 
 ```ruby
-SimpleCov.minimum_coverage 90
-# same as above (the default is to check line coverage)
-SimpleCov.minimum_coverage line: 90
-# check for a minimum line coverage of 90% and minimum 80% branch coverage
-SimpleCov.minimum_coverage line: 90, branch: 80
+SimpleCov.print_errors false
 ```
 
-### Minimum coverage by file
+### Color output
+
+When color is enabled, SimpleCov highlights coverage percentages in its `STDERR` diagnostics by band (green for
+`>= 90%`, yellow for `>= 75%`, red below) and prints the "SimpleCov failed with exit ..." summary in red. By default,
+color is on only when `STDERR` is a TTY. Two environment variables override that:
+
+- `NO_COLOR=1` (any non-empty value) disables color even when stderr is a TTY. Honors the
+  [no-color.org](https://no-color.org) convention.
+- `FORCE_COLOR=1` (any non-empty value) enables color even when stderr is not a TTY. Useful when stderr is piped through
+  a wrapper that itself renders ANSI in a terminal (`parallel_tests --combine-stderr`, log multiplexers, some CI runners).
+
+`NO_COLOR` wins if both are set.
 
-You can define the minimum coverage by file percentage expected. SimpleCov will return non-zero if unmet. This is useful
-to help ensure coverage is relatively consistent, rather than being skewed by particularly good or bad areas of the code.
+For programmatic control, use `SimpleCov.color`. An explicit `true` or `false` wins over the env vars and TTY detection:
 
 ```ruby
-SimpleCov.minimum_coverage_by_file 80
-# same as above (the default is to check line coverage by file)
-SimpleCov.minimum_coverage_by_file line: 80
-# check for a minimum line coverage by file of 90% and minimum 80% branch coverage
-SimpleCov.minimum_coverage_by_file line: 90, branch: 80
+SimpleCov.color true   # always on
+SimpleCov.color false  # always off
+SimpleCov.color :auto  # default behavior: NO_COLOR/FORCE_COLOR/TTY
 ```
 
-### Maximum coverage drop
+## Command-line interface
 
-You can define the maximum coverage drop percentage at once. SimpleCov will return non-zero if exceeded.
+The bundled `simplecov` CLI provides a set of subcommands. The read-only reporting commands consume the JSONFormatter's
+`coverage.json` output, so you don't need to re-run your suite — any prior run that emitted JSON suffices. Paths default
+to `SimpleCov.coverage_dir` from your project's `.simplecov` when one is present.
 
-```ruby
-SimpleCov.maximum_coverage_drop 5
-# same as above (the default is to check line drop)
-SimpleCov.maximum_coverage_drop line: 5
-# check for a maximum line drop of 5% and maximum 10% branch drop
-SimpleCov.maximum_coverage_drop line: 5, branch: 10
+| Command            | Description                                                         |
+|--------------------|---------------------------------------------------------------------|
+| `run <command…>`   | Execute `<command>` with simplecov pre-loaded (no `test_helper` hook needed) |
+| `coverage <path>`  | Print coverage stats for a single file                              |
+| `report`           | Print the overall summary and per-group totals                      |
+| `uncovered`        | List the lowest-coverage files                                      |
+| `merge <files…>`   | Merge multiple `.resultset.json` files                              |
+| `diff <baseline>`  | Show per-file coverage delta vs a baseline                          |
+| `open`             | Open the HTML report in the default browser                         |
+| `serve`            | Serve the coverage report over HTTP                                 |
+| `clean`            | Remove the coverage report directory                                |
+
+Run `simplecov help` for the full option listing.
+
+### `run` — run a suite with coverage
+
+If your project has no `test_helper.rb` hook that calls `SimpleCov.start` (or you don't want to add one), `simplecov run`
+execs your test command with simplecov pre-loaded so a report drops into `coverage/` at the end:
+
+```sh
+$ simplecov run bundle exec rspec
+$ simplecov run -- bundle exec rake test
+$ simplecov run ruby my_test.rb
 ```
 
-### Refuse dropping coverage
+Internally this just sets `RUBYOPT=-rsimplecov/autostart` for the child process, so any spawned subprocess (parallel
+test workers, integration test forks, etc.) also picks up the autostart shim. If your project already has a `.simplecov`
+config that calls `SimpleCov.start`, the autostart shim defers to it and won't double-start Coverage.
+
+### `coverage` — per-file lookup
+
+For editor / TDD inner-loop integrations and tools that want one file's coverage without re-parsing the full report:
+
+```sh
+$ simplecov coverage app/models/user.rb
+/abs/path/app/models/user.rb
+  Line:   100.00% (12 / 12)
+  Branch: 100.00% (4 / 4)
+  Method: 100.00% (3 / 3)
+
+$ simplecov coverage --json app/models/user.rb        # raw JSON entry
+$ simplecov coverage --input path/to/coverage.json …  # non-default location
+```
 
-You can also entirely refuse dropping coverage between test runs:
+The same lookup is available in Ruby, with paths resolved relative to `SimpleCov.root` (absolute or project-relative):
 
 ```ruby
-SimpleCov.refuse_coverage_drop
-# same as above (the default is to only refuse line drop)
-SimpleCov.refuse_coverage_drop :line
-# refuse drop for line and branch
-SimpleCov.refuse_coverage_drop :line, :branch
+result = SimpleCov.result   # or SimpleCov::Result.from_hash(...).first
+result.coverage_for("app/models/user.rb")
+# => {line: <CoverageStatistics>, branch: <CoverageStatistics>, method: <CoverageStatistics>}
+
+result.source_file_for("app/models/user.rb")
+# => <SimpleCov::SourceFile>
 ```
 
-## Using your own formatter
+### `report` — quick terminal report
 
-You can use your own formatter with:
+For CI logs, ssh sessions, or any terminal-only workflow, `simplecov report` prints the same totals row the HTML report
+renders at the top, plus per-group totals:
 
-```ruby
-SimpleCov.formatter = SimpleCov::Formatter::HTMLFormatter
+```sh
+$ simplecov report
+All Files
+  Line:    99.75% (1638 / 1642)
+  Branch:  98.50% (396 / 402)
+  Method:  99.73% (372 / 373)
 ```
 
-When calling SimpleCov.result.format!, it will be invoked with SimpleCov::Formatter::YourFormatter.new.format(result),
-"result" being an instance of SimpleCov::Result. Do whatever your wish with that!
+Pass `--input PATH` to read a non-default `coverage.json`. `--json` emits the totals as a JSON object keyed by section
+name (`"All Files"` plus each group), useful when a CI step needs to act on the numbers rather than display them.
 
+### `uncovered` — list lowest-coverage files
 
-## Using multiple formatters
+`simplecov uncovered` prints the lowest-coverage files (by line coverage, worst-first) so you can find where to add
+tests next without opening the HTML report:
 
-As of SimpleCov 0.9, you can specify multiple result formats:
+```sh
+$ simplecov uncovered
+ 50.00%  5/10    lib/foo.rb
+ 80.00%  8/10    lib/bar.rb
 
-```ruby
-SimpleCov.formatters = SimpleCov::Formatter::MultiFormatter.new([
-  SimpleCov::Formatter::HTMLFormatter,
-  SimpleCov::Formatter::CSVFormatter,
-])
+$ simplecov uncovered --threshold 90 --top 5
+$ simplecov uncovered --criterion branch
 ```
 
-## JSON formatter
+`--threshold N` filters to files below N% coverage (default `100`); `--top N` caps the list at N entries (default
+`10`); `--criterion line|branch|method` chooses which coverage to rank by (default `line`). `--json` emits the rows as
+a JSON array (empty when nothing is below the threshold), useful for piping into a CI gate.
 
-SimpleCov is packaged with a separate gem called [simplecov_json_formatter](https://github.com/codeclimate-community/simplecov_json_formatter) that provides you with a JSON formatter, this formatter could be useful for different use cases, such as for CI consumption or for reporting to external services.
+### `merge` — combine resultsets from parallel CI workers
 
-In order to use it you will need to manually load the installed gem like so:
+CI matrices that produce one `.resultset.json` per worker can stitch them together with `simplecov merge` instead of
+hand-rolling a Rake task in every project:
 
-```ruby
-require "simplecov_json_formatter"
-SimpleCov.formatter = SimpleCov::Formatter::JSONFormatter
+```sh
+$ simplecov merge worker-*/coverage/.resultset.json --output coverage/.resultset.json
 ```
 
-> _Note:_ In case you plan to report your coverage results to CodeClimate services, know that SimpleCov will automatically use the
->  JSON formatter along with the HTML formatter when the `CC_TEST_REPORTER_ID` variable is present in the environment.
+By default `simplecov merge` ignores `merge_timeout`; pass `--honor-timeout` to drop entries older than the configured
+timeout. Pass `--dry-run` to preview the output path without writing, or `-q` / `--quiet` to suppress the success status
+line for cleaner CI logs. After merging, run `simplecov report` against the combined data.
 
-## Available formatters, editor integrations and hosted services
+### `diff` — coverage delta vs a baseline
 
-  * [Open Source formatter and integration plugins for SimpleCov](doc/alternate-formatters.md)
-  * [Editor Integration](doc/editor-integration.md)
-  * [Hosted (commercial) services](doc/commercial-services.md)
+`simplecov diff <baseline>` reads two `coverage.json` files (current plus a baseline checked into the repo, or produced
+by a previous CI run) and prints the files whose coverage moved on any enabled criterion. When branch or method coverage
+is enabled, those deltas appear alongside the line delta on the same row:
+
+```sh
+$ simplecov diff coverage/baseline.json
+  -20.00% lines  -10.00% branches  lib/foo.rb
+  + 5.00% lines  lib/bar.rb
+  +60.00% lines  lib/new.rb  (new file)
+  -95.00% lines  lib/gone.rb  (removed)
+```
+
+Regressions are listed first. Pass `--fail-on-drop` to exit non-zero when any file's line coverage slipped, so this
+composes with CI as a "coverage of this PR didn't drop" gate even when overall thresholds are still satisfied.
+`--threshold N` filters out deltas below N% in absolute value, useful when a baseline is noisy. `--json` emits the rows
+as a JSON array for programmatic consumption:
+
+```sh
+$ simplecov diff --json coverage/baseline.json
+[
+  {"file":"lib/foo.rb","status":"changed","line_delta":-20.0,"branch_delta":-10.0,"method_delta":0.0},
+  {"file":"lib/bar.rb","status":"changed","line_delta":5.0,"branch_delta":0.0,"method_delta":0.0}
+]
+```
+
+Coverage keys with a leading `/` (from `coverage.json` files emitted before the `SourceFile#project_filename` change)
+are normalized, so a baseline from an older SimpleCov still diffs cleanly against newer reports.
+
+### `serve` and `clean`
 
-## Ruby version compatibility
+`simplecov serve` serves the coverage report over HTTP — handy on a remote box where you can't open files directly.
+`--port N` binds to a specific port (default: a random open port) and `--host HOST` to a specific host (default
+`127.0.0.1`).
 
-SimpleCov is built in [Continuous Integration] on Ruby 2.5+ as well as JRuby 9.2+.
+`simplecov clean` removes the coverage report directory. `--dry-run` prints what would be removed without deleting
+anything; `-q` / `--quiet` suppresses status lines.
 
-Note for JRuby => You need to pass JRUBY_OPTS="--debug" or create .jrubyrc and add debug.fullTrace=true
+## Compatibility and troubleshooting
 
-## Want to find dead code in production?
+### Ruby version compatibility
 
-Try [Coverband](https://github.com/danmayer/coverband).
+SimpleCov is built in [Continuous Integration] on Ruby 3.1+ and JRuby 9.4+. On CRuby, every coverage criterion
+described above is available on the supported versions, with one exception: [eval coverage](#eval-coverage) requires
+CRuby 3.2+.
 
-## Want to use Spring with SimpleCov?
+### JRuby
 
-If you're using [Spring](https://github.com/rails/spring) to speed up test suite runs and want to run SimpleCov along
-with them, you'll find that it often misreports coverage with the default config due to some sort of eager loading
-issue. Don't despair!
+On JRuby, only **line coverage** is available — branch, method, oneshot-line, and eval coverage rely on features of
+CRuby's `Coverage` library that JRuby doesn't implement. SimpleCov detects this automatically: the bundled `strict`
+profile, for instance, enforces only line coverage at 100% on JRuby instead of failing to load.
+
+To get accurate line numbers in coverage results, JRuby needs its full backtrace enabled. Pass `JRUBY_OPTS="--debug"`,
+or create a `.jrubyrc` with `debug.fullTrace=true`.
+
+### Notes on specific frameworks and test utilities
+
+Some frameworks and tools have quirks worth knowing about when using SimpleCov:
+
+<table>
+  <tr><th>Framework</th><th>Notes</th><th>Issue</th></tr>
+  <tr>
+    <th>
+      parallel_tests
+    </th>
+    <td>
+      As of 0.8.0, SimpleCov should correctly recognize parallel_tests and
+      supplement your test suite names with their corresponding test env
+      numbers. SimpleCov locks the resultset cache while merging, ensuring no
+      race conditions occur when results are merged.
+    </td>
+    <td>
+      <a href="https://github.com/simplecov-ruby/simplecov/issues/64">#64</a> &amp;
+      <a href="https://github.com/simplecov-ruby/simplecov/pull/185">#185</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      knapsack_pro
+    </th>
+    <td>
+      To make SimpleCov work with Knapsack Pro Queue Mode to split tests in parallel on CI jobs you need to provide CI node index number to the <code>SimpleCov.command_name</code> in <code>KnapsackPro::Hooks::Queue.before_queue</code> hook.
+    </td>
+    <td>
+      <a href="https://knapsackpro.com/faq/question/how-to-use-simplecov-in-queue-mode">Tip</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      RubyMine
+    </th>
+    <td>
+      The <a href="https://www.jetbrains.com/ruby/">RubyMine IDE</a> has
+      built-in support for SimpleCov's coverage reports, though you might need
+      to explicitly set the output root using `SimpleCov.root('foo/bar/baz')`
+    </td>
+    <td>
+      <a href="https://github.com/simplecov-ruby/simplecov/issues/95">#95</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      Spork
+    </th>
+    <td>
+      Because of how Spork works internally (using preforking), there used to
+      be trouble when using SimpleCov with it, but that has apparently been
+      resolved with a specific configuration strategy. See <a
+      href="https://github.com/simplecov-ruby/simplecov/issues/42#issuecomment-4440284">this</a>
+      comment.
+    </td>
+    <td>
+      <a href="https://github.com/simplecov-ruby/simplecov/issues/42#issuecomment-4440284">#42</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      Spring
+    </th>
+    <td>
+      <a href="#using-spring-with-simplecov">See section below.</a>
+    </td>
+    <td>
+      <a href="https://github.com/simplecov-ruby/simplecov/issues/381">#381</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      Test/Unit
+    </th>
+    <td>
+      Test Unit 2 used to mess with ARGV, leading to a failure to detect the
+      test process name in SimpleCov. <code>test-unit</code> releases 2.4.3+
+      (Dec 11th, 2011) should have this problem resolved.
+    </td>
+    <td>
+      <a href="https://github.com/simplecov-ruby/simplecov/issues/45">#45</a> &amp;
+      <a href="https://github.com/test-unit/test-unit/pull/12">test-unit/test-unit#12</a>
+    </td>
+  </tr>
+</table>
+
+### Using Spring with SimpleCov
+
+If you use [Spring](https://github.com/rails/spring) to speed up test runs, SimpleCov often misreports coverage with the
+default config due to an eager-loading issue. There are a few fixes.
 
 One solution is to [explicitly call eager
-load](https://github.com/simplecov-ruby/simplecov/issues/381#issuecomment-347651728)
-in your `test_helper.rb` / `spec_helper.rb` after calling `SimpleCov.start`.
+load](https://github.com/simplecov-ruby/simplecov/issues/381#issuecomment-347651728) in your `test_helper.rb` /
+`spec_helper.rb` after calling `SimpleCov.start`:
 
 ```ruby
 require 'simplecov'
@@ -901,22 +1377,36 @@ SimpleCov.start 'rails'
 Rails.application.eager_load!
 ```
 
-Alternatively, you could disable Spring while running SimpleCov:
+Alternatively, disable Spring while running SimpleCov:
 
-```
+```sh
 DISABLE_SPRING=1 rake test
 ```
 
-Or you could remove `gem 'spring'` from your `Gemfile`.
+Or remove `gem 'spring'` from your `Gemfile`.
+
+### Different coverage between local and CI
 
-## Troubleshooting
+Rails generates `config/environments/test.rb` with `config.eager_load = ENV["CI"].present?` (Rails 7+), so **CI eagerly
+loads every file in `app/` while your local run does not**. The two environments then report different file sets and
+different totals from the same suite. Two ways to make the report deterministic:
 
-The **most common problem is that simplecov isn't required and started before everything else**. In order to track
-coverage for your whole application **simplecov needs to be the first one** so that it (and the underlying coverage
-library) can subsequently track loaded files and their usage.
+- Set `config.eager_load = true` everywhere in `test.rb` (slower locally, but matches CI — and matches what users
+  actually see in production).
+- Stick with the `rails` profile, which folds `{app,lib}/**/*.rb` into the report at 0% on every run regardless of
+  `eager_load`. (The profile resolves the glob relative to `SimpleCov.root`, not the test runner's cwd.) Outside the
+  profile, the equivalent is `cover "{app,lib}/**/*.rb"` — see the
+  [legacy-API migration table](#migrating-from-the-legacy-configuration-api) for the relationship with the older
+  `track_files`.
 
-If you are missing coverage for some code a simple trick is to put a puts statement in there and right after
-`SimpleCov.start` so you can see if the file really was loaded after simplecov was started.
+### Missing coverage
+
+The **most common problem is that SimpleCov isn't required and started before everything else**. To track coverage for
+your whole application, **SimpleCov must come first** so that it (and the underlying Coverage library) can track files
+as they're loaded and used.
+
+If coverage is missing for some code, a simple trick is to add a `puts` inside that file and another right after
+`SimpleCov.start`, then check the order they print in:
 
 ```ruby
 # my_code.rb
@@ -929,29 +1419,49 @@ class MyCode
   end
 end
 
-# spec_helper.rb/rails_helper.rb/test_helper.rb/.simplecov whatever
-
+# spec_helper.rb / rails_helper.rb / test_helper.rb / .simplecov — whatever
 SimpleCov.start
 puts "SimpleCov started successfully!"
 ```
 
-Now when you run your test suite and you see:
+If you see this order, you're good:
 
 ```
 SimpleCov started successfully!
 MyCode is being loaded!
 ```
 
-then it's good otherwise you likely have a problem :)
+If `MyCode is being loaded!` prints first, the file was loaded before SimpleCov started — that's your problem.
 
-## Code of Conduct
+### Upgrading from 0.x
 
-Everyone participating in this project's development, issue trackers and other channels is expected to follow our
-[Code of Conduct](./CODE_OF_CONDUCT.md)
+Four methods that had been deprecated for a decade or more were removed in 1.0. Each had a one-to-one rename:
+
+| Removed                                  | Use instead                                |
+| ---------------------------------------- | ------------------------------------------ |
+| `SimpleCov::Filter#passes?`              | `SimpleCov::Filter#matches?`               |
+| `SimpleCov.adapters`                     | `SimpleCov.profiles`                       |
+| `SimpleCov.load_adapter('rails')`        | `SimpleCov.load_profile('rails')`          |
+| `SimpleCov::Formatter::MultiFormatter[]` | `SimpleCov::Formatter::MultiFormatter.new` |
+
+If a custom filter still defines `passes?`, rename the method to `matches?` — the signature and semantics are identical.
+
+## Related projects
+
+Want to find dead code in production? Try [Coverband](https://github.com/danmayer/coverband).
 
 ## Contributing
 
-See the [contributing guide](https://github.com/simplecov-ruby/simplecov/blob/main/CONTRIBUTING.md).
+* [Issue Tracker](https://github.com/simplecov-ruby/simplecov/issues) — for code and bug reports. See
+  [CONTRIBUTING](https://github.com/simplecov-ruby/simplecov/blob/main/CONTRIBUTING.md) for how to contribute, along
+  with common problems to check before creating an issue.
+* [Mailing List](https://groups.google.com/forum/#!forum/simplecov) — open list for discussion and announcements on
+  Google Groups.
+
+## Code of Conduct
+
+Everyone participating in this project's development, issue trackers, and other channels is expected to follow our
+[Code of Conduct](./CODE_OF_CONDUCT.md).
 
 ## Kudos
 
@@ -959,4 +1469,4 @@ Thanks to Aaron Patterson for the original idea for this!
 
 ## Copyright
 
-Copyright (c) 2010-2017 Christoph Olszowka. See MIT-LICENSE for details.
+Copyright (c) 2010-2026 Erik Berlin, Benjamin Fleischer, Akira Matsuda, Christoph Olszowka, Tobias Pfeiffer, David Rodríguez, and Xavier Shay. See MIT-LICENSE for details.