# Ruby test coverage

> Set up Supercov with your agent, or run it yourself with RSpec, Minitest or Rails tests.

Web page: https://supercov.com/docs/ruby
All Supercov pages for agents: https://supercov.com/llms.txt · Full text: https://supercov.com/llms-full.txt

Ask your coding agent to set up Supercov in your project:

```text supercov-prompt
Install the supercov gem in this project's Ruby environment. Read supercov
docs and run our existing tests with the project's bundle. Show the coverage
report and any measurement limits. Don't change application code or tests.
```

## Run it yourself

Use Ruby 3.4 or newer for full measurement. Ruby 3.3 provides line, method and
simple-branch coverage, but not the full MC/DC measurement shown below.

Install Supercov in the Ruby environment you use for your project:

```sh
gem install supercov
supercov --version
```

The gem includes the CLI; you don't need Node.js. Your test runner and project
dependencies still need to be installed.

### Run your tests

For an RSpec project:

```sh
supercov -- bundle exec rspec
```

For Rails or Minitest, wrap the command you already use instead:

```sh
supercov -- bin/rails test
supercov -- ruby -Itest test/test_session.rb
```

Replace the Minitest filename with your test file, or use `supercov -- rake test`
for the full suite. Supercov runs Ruby in your project directory with your
bundle. It uses `RUBYOPT` to load its hooks without rewriting application files.
It tracks individual tests in RSpec, Minitest and test-unit, and scenarios in Cucumber.

Inspect the result:

```sh
supercov runs latest
supercov runs latest gaps --limit 5
```

## Try a small example

[Download the examples](https://supercov.com/downloads/supercov-language-examples.zip), extract them,
and open `supercov-examples/ruby`. The tests use Minitest. If it isn't available
in this Ruby environment, install it with `gem install minitest`.

The `lib/session.rb` file contains:

```ruby
def checkout(signed_in, expired, price, quantity)
  if signed_in && !expired
    total = price * quantity
    return { status: 'confirmed', total: total }
  end
  { status: 'denied', total: 0 }
end
```

Its two tests check a valid order and a signed-out visitor. Run them from the
example folder:

```sh
supercov -- ruby -Itest test/test_session.rb
supercov runs latest
```

The coverage section recorded with Supercov 2.0.0 is:

```text
Coverage
  Lines      100.00% (5/5)
  Branches   100.00% (6/6)
  MC/DC      50.00% (1/2)
```

Both branches ran, but the expiry check hasn't been tested independently:

```sh
supercov runs latest decision lib/session.rb:2
```

The report includes:

```text
signed_in && !expired
C1 covered: signed_in
C2 MISSING: !expired
```

A test for a signed-in customer with an expired session closes that gap.
The [recorded run](https://supercov.com/downloads/coverage-guide-recordings.json) reaches 100% MC/DC
after adding it; [MC/DC](https://supercov.com/docs/mcdc?language=ruby) explains the measurement.

## Check what the tests assert

These tests check the status, not `order[:total]`. Adding
`assert_equal 50, order[:total]` would check the calculation for this input.

Supercov can ask [Jev](https://typesafe.ai) whether each test would fail if a
statement it ran changed. `runs latest assertions assess` saves the answers
(it needs `TYPESAFE_API_KEY`), and `runs latest assertions` then lists the
statements no test checks, file by file. A statement that is not asserted
runs in some test, but nothing that test checks depends on it. See
[Assertion coverage](https://supercov.com/docs/assertions?language=ruby).

## Ruby-specific limits

A Spring preloader started before Supercov won't have its measurement hook;
restart it inside the measured command. JRuby and TruffleRuby aren't supported.
Forked Rails workers are supported. When tests run in overlapping threads,
some execution can only be assigned to the whole suite. See
[runner support](https://supercov.com/docs/supported-suites?language=ruby#ruby) for details.

Already using SimpleCov? See [how the reports differ](https://supercov.com/compare/simplecov.md).
`supercov docs coverage-model` prints the guide for your installed version.