{"id":13412035,"url":"https://github.com/simplecov-ruby/simplecov","last_synced_at":"2025-11-11T18:33:53.997Z","repository":{"id":38344500,"uuid":"839336","full_name":"simplecov-ruby/simplecov","owner":"simplecov-ruby","description":"Code coverage for Ruby with a powerful configuration library and automatic merging of coverage across test suites","archived":false,"fork":false,"pushed_at":"2025-04-07T16:03:50.000Z","size":2804,"stargazers_count":4825,"open_issues_count":130,"forks_count":564,"subscribers_count":60,"default_branch":"main","last_synced_at":"2025-05-03T02:02:15.863Z","etag":null,"topics":["code-quality","coverage","coverage-library","coverage-report","rails","ruby","test-coverage"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simplecov-ruby.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2010-08-15T15:28:56.000Z","updated_at":"2025-05-02T17:23:19.000Z","dependencies_parsed_at":"2023-02-17T00:45:47.507Z","dependency_job_id":"41d5b259-b35c-4d78-aba7-f69c6a7b6f23","html_url":"https://github.com/simplecov-ruby/simplecov","commit_stats":{"total_commits":1334,"total_committers":222,"mean_commits":6.009009009009009,"dds":0.7068965517241379,"last_synced_commit":"b6c2d4208a5fa395ce09d7e1d3b074f680ee29b0"},"previous_names":["colszowka/simplecov"],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecov-ruby%2Fsimplecov","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecov-ruby%2Fsimplecov/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecov-ruby%2Fsimplecov/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecov-ruby%2Fsimplecov/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simplecov-ruby","download_url":"https://codeload.github.com/simplecov-ruby/simplecov/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252154873,"owners_count":21702989,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-quality","coverage","coverage-library","coverage-report","rails","ruby","test-coverage"],"created_at":"2024-07-30T20:01:20.354Z","updated_at":"2025-11-11T18:33:53.944Z","avatar_url":"https://github.com/simplecov-ruby.png","language":"Ruby","readme":"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)\n=========\n\n**Code coverage for Ruby**\n\n  * [Source Code]\n  * [API documentation]\n  * [Changelog]\n  * [Rubygem]\n  * [Continuous Integration]\n\n[Coverage]: https://docs.ruby-lang.org/en/master/Coverage.html \"API doc for Ruby's Coverage library\"\n[Source Code]: https://github.com/simplecov-ruby/simplecov \"Source Code @ GitHub\"\n[API documentation]: http://rubydoc.info/gems/simplecov/frames \"RDoc API Documentation at Rubydoc.info\"\n[Configuration]: http://rubydoc.info/gems/simplecov/SimpleCov/Configuration \"Configuration options API documentation\"\n[Changelog]: https://github.com/simplecov-ruby/simplecov/blob/main/CHANGELOG.md \"Project Changelog\"\n[Rubygem]: http://rubygems.org/gems/simplecov \"SimpleCov @ rubygems.org\"\n[Continuous Integration]: https://github.com/simplecov-ruby/simplecov/actions?query=workflow%3Astable \"SimpleCov is built around the clock by github.com\"\n[Dependencies]: https://gemnasium.com/simplecov-ruby/simplecov \"SimpleCov dependencies on Gemnasium\"\n[simplecov-html]: https://github.com/simplecov-ruby/simplecov-html \"SimpleCov HTML Formatter Source Code @ GitHub\"\n\nSimpleCov is a code coverage analysis tool for Ruby. It uses [Ruby's built-in Coverage][Coverage] library to gather code\ncoverage data, but makes processing its results much easier by providing a clean API to filter, group, merge, format,\nand display those results, giving you a complete code coverage suite that can be set up with just a couple lines of\ncode.\nSimpleCov/Coverage track covered ruby code, gathering coverage for common templating solutions like erb, slim and haml is not supported.\n\nIn most cases, you'll want overall coverage results for your projects, including all types of tests, Cucumber features,\netc. SimpleCov automatically takes care of this by caching and merging results when generating reports, so your\nreport actually includes coverage across your test suites and thereby gives you a better picture of blank spots.\n\nThe official formatter of SimpleCov is packaged as a separate gem called [simplecov-html], but will be installed and\nconfigured automatically when you launch SimpleCov. If you're curious, you can find it [on GitHub, too][simplecov-html].\n\n\n## Contact\n\n*Code and Bug Reports*\n\n* [Issue Tracker](https://github.com/simplecov-ruby/simplecov/issues)\n* See [CONTRIBUTING](https://github.com/simplecov-ruby/simplecov/blob/main/CONTRIBUTING.md) for how to contribute along\nwith some common problems to check out before creating an issue.\n\n*Questions, Problems, Suggestions, etc.*\n\n* [Mailing List](https://groups.google.com/forum/#!forum/simplecov) \"Open mailing list for discussion and announcements\non Google Groups\"\n\nGetting started\n---------------\n1. Add SimpleCov to your `Gemfile` and `bundle install`:\n\n    ```ruby\n    gem 'simplecov', require: false, group: :test\n    ```\n2. Load and launch SimpleCov **at the very top** of your `test/test_helper.rb`\n   (*or `spec_helper.rb`, `rails_helper`, cucumber `env.rb`, or whatever your preferred test\n   framework uses*):\n\n    ```ruby\n    require 'simplecov'\n    SimpleCov.start\n\n    # Previous content of test helper now starts here\n    ```\n\n    **Note:** If SimpleCov starts after your application code is already loaded\n    (via `require`), it won't be able to track your files and their coverage!\n    The `SimpleCov.start` **must** be issued **before any of your application\n    code is required!**\n\n    This is especially true if you use anything that keeps your tests application loaded like spring, check out the **[spring section](#want-to-use-spring-with-simplecov)**.\n\n    SimpleCov must be running in the process that you want the code coverage\n    analysis to happen on. When testing a server process (e.g. a JSON API\n    endpoint) via a separate test process (e.g. when using Selenium) where you\n    want to see all code executed by the `rails server`, and not just code\n    executed in your actual test files, you need to require SimpleCov in the\n    server process. For rails for instance, you'll want to add something like this\n    to the top of `bin/rails`, but below the \"shebang\" line (`#! /usr/bin/env\n    ruby`) and after config/boot is required:\n\n    ```ruby\n    if ENV['RAILS_ENV'] == 'test'\n      require 'simplecov'\n      SimpleCov.start 'rails'\n      puts \"required simplecov\"\n    end\n    ```\n\n3. Run your full test suite to see the percent coverage that your application has.\n4. After running your tests, open `coverage/index.html` in the browser of your choice. For example, in a Mac Terminal,\n   run the following command from your application's root directory:\n\n   ```\n   open coverage/index.html\n   ```\n   in a debian/ubuntu Terminal,\n\n   ```\n   xdg-open coverage/index.html\n   ```\n\n   **Note:** [This guide](https://dwheeler.com/essays/open-files-urls.html) can help if you're unsure which command your particular\n   operating system requires.\n\n5. Add the following to your `.gitignore` file to ensure that coverage results\n   are not tracked by Git (optional):\n\n   ```\n   echo coverage \u003e\u003e .gitignore\n   ```\n\n   If you're making a Rails application, SimpleCov comes with built-in configurations (see below for information on\n   profiles) that will get you started with groups for your Controllers, Models and Helpers. To use it, the\n   first two lines of your test_helper should be like this:\n\n   ```ruby\n   require 'simplecov'\n   SimpleCov.start 'rails'\n   ```\n\n## Example output\n\n**Coverage results report, fully browsable locally with sorting and much more:**\n\n![SimpleCov coverage report](https://cloud.githubusercontent.com/assets/137793/17071162/db6f253e-502d-11e6-9d84-e40c3d75f333.png)\n\n\n**Source file coverage details view:**\n\n![SimpleCov source file detail view](https://cloud.githubusercontent.com/assets/137793/17071163/db6f9f0a-502d-11e6-816c-edb2c66fad8d.png)\n\n## Use it with any framework!\n\nSimilarly to the usage with Test::Unit described above, the only thing you have to do is to add the SimpleCov\nconfig to the very top of your Cucumber/RSpec/whatever setup file.\n\nAdd the setup code to the **top** of `features/support/env.rb` (for Cucumber) or `spec/spec_helper.rb` (for RSpec).\nOther test frameworks should work accordingly, whatever their setup file may be:\n\n```ruby\nrequire 'simplecov'\nSimpleCov.start 'rails'\n```\n\nYou could even track what kind of code your UI testers are touching if you want to go overboard with things. SimpleCov\ndoes not care what kind of framework it is running in; it just looks at what code is being executed and generates a\nreport about it.\n\n### Notes on specific frameworks and test utilities\n\nFor some frameworks and testing tools there are quirks and problems you might want to know about if you want\nto use SimpleCov with them. Here's an overview of the known ones:\n\n\u003ctable\u003e\n  \u003ctr\u003e\u003cth\u003eFramework\u003c/th\u003e\u003cth\u003eNotes\u003c/th\u003e\u003cth\u003eIssue\u003c/th\u003e\u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      parallel_tests\n    \u003c/th\u003e\n    \u003ctd\u003e\n      As of 0.8.0, SimpleCov should correctly recognize parallel_tests and\n      supplement your test suite names with their corresponding test env\n      numbers. SimpleCov locks the resultset cache while merging, ensuring no\n      race conditions occur when results are merged.\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://github.com/simplecov-ruby/simplecov/issues/64\"\u003e#64\u003c/a\u003e \u0026amp;\n      \u003ca href=\"https://github.com/simplecov-ruby/simplecov/pull/185\"\u003e#185\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      knapsack_pro\n    \u003c/th\u003e\n    \u003ctd\u003e\n      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 \u003ccode\u003eSimpleCov.command_name\u003c/code\u003e in \u003ccode\u003eKnapsackPro::Hooks::Queue.before_queue\u003c/code\u003e hook.\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://knapsackpro.com/faq/question/how-to-use-simplecov-in-queue-mode\"\u003eTip\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      RubyMine\n    \u003c/th\u003e\n    \u003ctd\u003e\n      The \u003ca href=\"https://www.jetbrains.com/ruby/\"\u003eRubyMine IDE\u003c/a\u003e has\n      built-in support for SimpleCov's coverage reports, though you might need\n      to explicitly set the output root using `SimpleCov.root('foo/bar/baz')`\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://github.com/simplecov-ruby/simplecov/issues/95\"\u003e#95\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      Spork\n    \u003c/th\u003e\n    \u003ctd\u003e\n      Because of how Spork works internally (using preforking), there used to\n      be trouble when using SimpleCov with it, but that has apparently been\n      resolved with a specific configuration strategy. See \u003ca\n      href=\"https://github.com/simplecov-ruby/simplecov/issues/42#issuecomment-4440284\"\u003ethis\u003c/a\u003e\n      comment.\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://github.com/simplecov-ruby/simplecov/issues/42#issuecomment-4440284\"\u003e#42\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      Spring\n    \u003c/th\u003e\n    \u003ctd\u003e\n      \u003ca href=\"#want-to-use-spring-with-simplecov\"\u003eSee section below.\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://github.com/simplecov-ruby/simplecov/issues/381\"\u003e#381\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      Test/Unit\n    \u003c/th\u003e\n    \u003ctd\u003e\n      Test Unit 2 used to mess with ARGV, leading to a failure to detect the\n      test process name in SimpleCov. \u003ccode\u003etest-unit\u003c/code\u003e releases 2.4.3+\n      (Dec 11th, 2011) should have this problem resolved.\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://github.com/simplecov-ruby/simplecov/issues/45\"\u003e#45\u003c/a\u003e \u0026amp;\n      \u003ca href=\"https://github.com/test-unit/test-unit/pull/12\"\u003etest-unit/test-unit#12\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Configuring SimpleCov\n\n[Configuration] settings can be applied in three formats, which are completely equivalent:\n\n* The most common way is to configure it directly in your start block:\n\n    ```ruby\n    SimpleCov.start do\n      some_config_option 'foo'\n    end\n    ```\n* You can also set all configuration options directly:\n\n    ```ruby\n    SimpleCov.some_config_option 'foo'\n    ```\n* If you do not want to start coverage immediately after launch or want to add additional configuration later on in a\n  concise way, use:\n\n    ```ruby\n    SimpleCov.configure do\n      some_config_option 'foo'\n    end\n    ```\n\nPlease check out the [Configuration] API documentation to find out what you can customize.\n\n## Using .simplecov for centralized config\n\nIf you use SimpleCov to merge multiple test suite results (e.g. Test/Unit and Cucumber) into a single report, you'd\nnormally have to set up all your config options twice, once in `test_helper.rb` and once in `env.rb`.\n\nTo avoid this, you can place a file called `.simplecov` in your project root. You can then just leave the\n`require 'simplecov'` in each test setup helper (**at the top**) and move the `SimpleCov.start` code with all your\ncustom config options into `.simplecov`:\n\n```ruby\n# test/test_helper.rb\nrequire 'simplecov'\n\n# features/support/env.rb\nrequire 'simplecov'\n\n# .simplecov\nSimpleCov.start 'rails' do\n  # any custom configs like groups and filters can be here at a central place\nend\n```\n\nUsing `.simplecov` rather than separately requiring SimpleCov multiple times is recommended if you are merging multiple\ntest frameworks like Cucumber and RSpec that rely on each other, as invoking SimpleCov multiple times can cause coverage\ninformation to be lost.\n\n## Branch coverage (ruby \"~\u003e 2.5\")\nAdd branch coverage measurement statistics to your results. Supported in CRuby versions 2.5+.\n\n```ruby\nSimpleCov.start do\n  enable_coverage :branch\nend\n```\n\nBranch coverage is a feature introduced in Ruby 2.5 concerning itself with whether a\nparticular branch of a condition had been executed. Line coverage on the other hand\nis only interested in whether a line of code has been executed.\n\nThis comes in handy for instance for one line conditionals:\n\n```ruby\nnumber.odd? ? \"odd\" : \"even\"\n```\n\nIn line coverage this line would always be marked as executed but you'd never know if both\nconditions were met. Guard clauses have a similar story:\n\n```ruby\nreturn if number.odd?\n\n# more code\n```\n\nIf all the code in that method was covered you'd never know if the guard clause was ever\ntriggered! With line coverage as just evaluating the condition marks it as covered.\n\nIn the HTML report the lines of code will be annotated like `branch_type: hit_count`:\n\n* `then: 2` - the then branch (of an `if`) was executed twice\n* `else: 0` - the else branch (of an `if` or `case`) was never executed\n\nNot that even if you don't declare an `else` branch it will still show up in the coverage\nreports meaning that the condition of the `if` was not hit or that no `when` of `case`\nwas hit during the test runs.\n\n**Is branch coverage strictly better?** No. Branch coverage really only concerns itself with\nconditionals - meaning coverage of sequential code is of no interest to it. A file without\nconditional logic will have no branch coverage data and SimpleCov will report 0 of 0\nbranches covered as 100% (as everything that can be covered was covered).\n\nHence, we recommend looking at both metrics together. Branch coverage might also be a good\noverall metric to look at - while you might be missing only 10% of your lines that might\naccount for 50% of your branches for instance.\n\n## Primary Coverage\n\nBy default, the primary coverage type is `line`. To set the primary coverage to something else, use the following:\n\n```ruby\n# or in configure SimpleCov.primary_coverage :branch\nSimpleCov.start do\n  enable_coverage :branch\n  primary_coverage :branch\nend\n```\n\nPrimary coverage determines what will come first in 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`).\n\nNote that coverage must first be enabled for non-default coverage types.\n\n## Coverage for eval\n\nYou can measure coverage for code that is evaluated by `Kernel#eval`. Supported in CRuby versions 3.2+.\n\n```ruby\nSimpleCov.start do\n  enable_coverage_for_eval\nend\n```\n\nThis is typically useful for ERB. Set `ERB#filename=` to make it possible for SimpleCov to trace the original .erb source file.\n\n## Filters\n\nFilters can be used to remove selected files from your coverage data. By default, a filter is applied that removes all\nfiles OUTSIDE of your project's root directory - otherwise you'd end up with billions of coverage reports for source\nfiles in the gems you are using.\n\nYou can define your own to remove things like configuration files, tests or whatever you don't need in your coverage\nreport.\n\n### Defining custom filters\n\nYou can currently define a filter using either a String or Regexp (that will then be Regexp-matched against each source\nfile's path), a block or by passing in your own Filter class.\n\n#### String filter\n\n```ruby\nSimpleCov.start do\n  add_filter \"/test/\"\nend\n```\n\nThis simple string filter will remove all files that match \"/test/\" in their path.\n\n#### Regex filter\n\n```ruby\nSimpleCov.start do\n  add_filter %r{^/test/}\nend\n```\n\nThis simple regex filter will remove all files that start with /test/ in their path.\n\n#### Block filter\n\n```ruby\nSimpleCov.start do\n  add_filter do |source_file|\n    source_file.lines.count \u003c 5\n  end\nend\n```\n\nBlock filters receive a SimpleCov::SourceFile instance and expect your block to return either true (if the file is to be\nremoved from the result) or false (if the result should be kept). Please check out the RDoc for SimpleCov::SourceFile to\nlearn about the methods available to you. In the above example, the filter will remove all files that have less than 5\nlines of code.\n\n#### Custom filter class\n\n```ruby\nclass LineFilter \u003c SimpleCov::Filter\n  def matches?(source_file)\n    source_file.lines.count \u003c filter_argument\n  end\nend\n\nSimpleCov.add_filter LineFilter.new(5)\n```\n\nDefining your own filters is pretty easy: Just inherit from SimpleCov::Filter and define a method\n'matches?(source_file)'. When running the filter, a true return value from this method will result in the removal of the\ngiven source_file. The filter_argument method is being set in the SimpleCov::Filter initialize method and thus is set to\n5 in this example.\n\n#### Array filter\n\n```ruby\nSimpleCov.start do\n  proc = Proc.new { |source_file| false }\n  add_filter [\"string\", /regex/, proc, LineFilter.new(5)]\nend\n```\n\nYou can pass in an array containing any of the other filter types.\n\n#### Ignoring/skipping code\n\nYou can exclude code from the coverage report by wrapping it in `# :nocov:`.\n\n```ruby\n# :nocov:\ndef skip_this_method\n  never_reached\nend\n# :nocov:\n```\n\nThe 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)\n\n**Note:** You shouldn't have to use the nocov token to skip private methods that are being included in your coverage. If\nyou appropriately test the public interface of your classes and objects you should automatically get full coverage of\nyour private methods.\n\n## Default root filter and coverage for things outside of it\n\nBy default, SimpleCov filters everything outside of the `SimpleCov.root` directory. However, sometimes you may want\nto include coverage reports for things you include as a gem, for example a Rails Engine.\n\nHere's an example by [@lsaffie](https://github.com/lsaffie) from [#221](https://github.com/simplecov-ruby/simplecov/issues/221)\nthat shows how you can achieve just that:\n\n```ruby\nSimpleCov.start :rails do\n  filters.clear # This will remove the :root_filter and :bundler_filter that come via simplecov's defaults\n  add_filter do |src|\n    !(src.filename =~ /^#{SimpleCov.root}/) unless src.filename =~ /my_engine/\n  end\nend\n```\n\n## Groups\n\nYou can separate your source files into groups. For example, in a Rails app, you'll want to have separate listings for\nModels, Controllers, Helpers, and Libs. Group definition works similarly to Filters (and also accepts custom\nfilter classes), but source files end up in a group when the filter passes (returns true), as opposed to filtering\nresults, which exclude files from results when the filter results in a true value.\n\nAdd your groups with:\n\n```ruby\nSimpleCov.start do\n  add_group \"Models\", \"app/models\"\n  add_group \"Controllers\", \"app/controllers\"\n  add_group \"Long files\" do |src_file|\n    src_file.lines.count \u003e 100\n  end\n  add_group \"Multiple Files\", [\"app/models\", \"app/controllers\"] # You can also pass in an array\n  add_group \"Short files\", LineFilter.new(5) # Using the LineFilter class defined in Filters section above\nend\n```\n\n## Merging results\n\nYou normally want to have your coverage analyzed across ALL of your test suites, right?\n\nSimplecov automatically caches coverage results in your\n(coverage_path)/.resultset.json, and will merge or override those with\nsubsequent runs, depending on whether simplecov considers those subsequent runs\nas different test suites or as the same test suite as the cached results. To\nmake this distinction, simplecov has the concept of \"test suite names\".\n\n### Test suite names\n\nSimpleCov tries to guess the name of the currently running test suite based upon the shell command the tests\nare running on. This should work fine for Unit Tests, RSpec, and Cucumber. If it fails, it will use the shell\ncommand that invoked the test suite as a command name.\n\nIf you have some non-standard setup and still want nicely labeled test suites, you have to give Simplecov a\ncue as to what the name of the currently running test suite is. You can do so by specifying\n`SimpleCov.command_name` in one test file that is part of your specific suite.\n\nTo customize the suite names on a Rails app (yeah, sorry for being Rails-biased, but everyone knows what\nthe structure of those projects is. You can apply this accordingly to the RSpecs in your\nOutlook-WebDAV-Calendar-Sync gem), you could do something like this:\n\n```ruby\n# test/unit/some_test.rb\nSimpleCov.command_name 'test:units'\n\n# test/functionals/some_controller_test.rb\nSimpleCov.command_name \"test:functionals\"\n\n# test/integration/some_integration_test.rb\nSimpleCov.command_name \"test:integration\"\n\n# features/support/env.rb\nSimpleCov.command_name \"features\"\n```\n\nNote that this only has to be invoked ONCE PER TEST SUITE, so even if you have 200 unit test files,\nspecifying it in `some_test.rb` is enough.\n\nLast but not least **if multiple suites resolve to the same `command_name`** be aware that the coverage results **will\nclobber each other instead of being merged**.  SimpleCov is smart enough to detect unique names for the most common\nsetups, but if you have more than one test suite that doesn't follow a common pattern then you will want to manually\nensure that each suite gets a unique `command_name`.\n\nIf you are running tests in parallel each process has the potential to clobber results from the other test processes.\nIf you are relying on the default `command_name` then SimpleCov will attempt to detect and avoid parallel test suite\n`command_name` collisions based on the presence of `ENV['PARALLEL_TEST_GROUPS']` and `ENV['TEST_ENV_NUMBER']`.  If your\nparallel test runner does not set one or both of these then *you must* set a `command_name` and ensure that it is unique\nper process (eg. `command_name \"Unit Tests PID #{$$}\"`).\n\nIf you are using parallel_tests, you must incorporate `TEST_ENV_NUMBER` into the command name yourself, in\norder for SimpleCov to merge the results correctly. For example:\n\n```ruby\n# spec/spec_helper.rb\nSimpleCov.command_name \"features\" + (ENV['TEST_ENV_NUMBER'] || '')\n```\n\n[simplecov-html] prints the used test suites in the footer of the generated coverage report.\n\n\n### Merging test runs under the same execution environment\n\nTest results are automatically merged with previous runs in the same execution\nenvironment when generating the result, so when coverage is set up properly for\nCucumber and your unit / functional / integration tests, all of those test\nsuites will be taken into account when building the coverage report.\n\n#### Timeout for merge\n\nOf course, your cached coverage data is likely to become invalid at some point. Thus, when automatically merging\nsubsequent test runs, result sets that are older than `SimpleCov.merge_timeout` will not be used any more. By default,\nthe timeout is 600 seconds (10 minutes), and you can raise (or lower) it by specifying `SimpleCov.merge_timeout 3600`\n(1 hour), or, inside a configure/start block, with just `merge_timeout 3600`.\n\nYou can deactivate this automatic merging altogether with `SimpleCov.use_merging false`.\n\n### Merging test runs under different execution environments\n\nIf your tests are done in parallel across multiple build machines, you can fetch them all and merge them into a single\nresult set using the `SimpleCov.collate` method. This can be added to a Rakefile or script file, having downloaded a set of\n`.resultset.json` files from each parallel test run.\n\n```ruby\n# lib/tasks/coverage_report.rake\nnamespace :coverage do\n  desc \"Collates all result sets generated by the different test runners\"\n  task :report do\n    require 'simplecov'\n\n    SimpleCov.collate Dir[\"simplecov-resultset-*/.resultset.json\"]\n  end\nend\n```\n\n`SimpleCov.collate` also takes an optional simplecov profile and an optional\nblock for configuration, just the same as `SimpleCov.start` or\n`SimpleCov.configure`.  This means you can configure a separate formatter for\nthe collated output. For instance, you can make the formatter in\n`SimpleCov.start` the `SimpleCov::Formatter::SimpleFormatter`, and only use more\ncomplex formatters in the final `SimpleCov.collate` run.\n\n```ruby\n# spec/spec_helper.rb\nrequire 'simplecov'\n\nSimpleCov.start 'rails' do\n  # Disambiguates individual test runs\n  command_name \"Job #{ENV[\"TEST_ENV_NUMBER\"]}\" if ENV[\"TEST_ENV_NUMBER\"]\n\n  if ENV['CI']\n    formatter SimpleCov::Formatter::SimpleFormatter\n  else\n    formatter SimpleCov::Formatter::MultiFormatter.new([\n      SimpleCov::Formatter::SimpleFormatter,\n      SimpleCov::Formatter::HTMLFormatter\n    ])\n  end\n\n  track_files \"**/*.rb\"\nend\n```\n\n```ruby\n# lib/tasks/coverage_report.rake\nnamespace :coverage do\n  task :report do\n    require 'simplecov'\n\n    SimpleCov.collate Dir[\"simplecov-resultset-*/.resultset.json\"], 'rails' do\n      formatter SimpleCov::Formatter::MultiFormatter.new([\n        SimpleCov::Formatter::SimpleFormatter,\n        SimpleCov::Formatter::HTMLFormatter\n      ])\n    end\n  end\nend\n```\n\n## Running simplecov against subprocesses\n\n`SimpleCov.enable_for_subprocesses` will allow SimpleCov to observe subprocesses starting using `Process.fork`.\nThis modifies ruby's core Process.fork method so that SimpleCov can see into it, appending `\" (subprocess #{pid})\"`\nto the `SimpleCov.command_name`, with results that can be merged together using SimpleCov's merging feature.\n\nTo configure this, use `.at_fork`.\n\n```ruby\nSimpleCov.enable_for_subprocesses true\nSimpleCov.at_fork do |pid|\n  # This needs a unique name so it won't be overwritten\n  SimpleCov.command_name \"#{SimpleCov.command_name} (subprocess: #{pid})\"\n  # be quiet, the parent process will be in charge of output and checking coverage totals\n  SimpleCov.print_error_status = false\n  SimpleCov.formatter SimpleCov::Formatter::SimpleFormatter\n  SimpleCov.minimum_coverage 0\n  # start\n  SimpleCov.start\nend\n```\n\nNOTE: SimpleCov must have already been started before `Process.fork` was called.\n\n### Running simplecov against spawned subprocesses\n\nPerhaps you're testing a ruby script with `PTY.spawn` or `Open3.popen`, or `Process.spawn` or etc.\nSimpleCov can cover this too.\n\nAdd a .simplecov_spawn.rb file to your project root\n```ruby\n# .simplecov_spawn.rb\nrequire 'simplecov' # this will also pick up whatever config is in .simplecov\n                    # so ensure it just contains configuration, and doesn't call SimpleCov.start.\nSimpleCov.command_name 'spawn' # As this is not for a test runner directly, script doesn't have a pre-defined base command_name\nSimpleCov.at_fork.call(Process.pid) # Use the per-process setup described previously\nSimpleCov.start # only now can we start.\n```\nThen, instead of calling your script directly, like:\n```ruby\nPTY.spawn('my_script.rb') do # ...\n```\nUse bin/ruby to require the new .simplecov_spawn file, then your script\n```ruby\nPTY.spawn('ruby -r./.simplecov_spawn my_script.rb') do # ...\n```\n\n## Running coverage only on demand\n\nThe Ruby STDLIB Coverage library that SimpleCov builds upon is *very* fast (on a ~10 min Rails test suite, the speed\ndrop was only a couple seconds for me), and therefore it's SimpleCov's policy to just generate coverage every time you\nrun your tests because it doesn't do your test speed any harm and you're always equipped with the latest and greatest\ncoverage results.\n\nBecause of this, SimpleCov has no explicit built-in mechanism to run coverage only on demand.\n\nHowever, you can still accomplish this very easily by introducing an ENV variable conditional into your SimpleCov setup\nblock, like this:\n\n```ruby\nSimpleCov.start if ENV[\"COVERAGE\"]\n```\n\nThen, SimpleCov will only run if you execute your tests like this:\n\n```shell\nCOVERAGE=true rake test\n```\n\n## Errors and exit statuses\n\nTo aid in debugging issues, if an error is raised, SimpleCov will print a message to `STDERR`\nwith the exit status of the error, like:\n\n```\nSimpleCov failed with exit 1\n```\n\nThis `STDERR` message can be disabled with:\n\n```\nSimpleCov.print_error_status = false\n```\n\n## Profiles\n\nBy default, SimpleCov's only config assumption is that you only want coverage reports for files inside your project\nroot. To save yourself from repetitive configuration, you can use predefined blocks of configuration, called 'profiles',\nor define your own.\n\nYou can then pass the name of the profile to be used as the first argument to SimpleCov.start. For example, simplecov\ncomes bundled with a 'rails' profile. It looks somewhat like this:\n\n```ruby\nSimpleCov.profiles.define 'rails' do\n  add_filter '/test/'\n  add_filter '/config/'\n\n  add_group 'Controllers', 'app/controllers'\n  add_group 'Models', 'app/models'\n  add_group 'Helpers', 'app/helpers'\n  add_group 'Libraries', 'lib'\nend\n```\n\nAs you can see, it's just a SimpleCov.configure block. In your test_helper.rb, launch SimpleCov with:\n\n```ruby\nSimpleCov.start 'rails'\n```\n\nor\n\n```ruby\nSimpleCov.start 'rails' do\n  # additional config here\nend\n```\n\n### Custom profiles\n\nYou can load additional profiles with the SimpleCov.load_profile('xyz') method. This allows you to build upon an\nexisting profile and customize it so you can reuse it in unit tests and Cucumber features. For example:\n\n```ruby\n# lib/simplecov_custom_profile.rb\nrequire 'simplecov'\nSimpleCov.profiles.define 'myprofile' do\n  load_profile 'rails'\n  add_filter 'vendor' # Don't include vendored stuff\nend\n\n# features/support/env.rb\nrequire 'simplecov_custom_profile'\nSimpleCov.start 'myprofile'\n\n# test/test_helper.rb\nrequire 'simplecov_custom_profile'\nSimpleCov.start 'myprofile'\n```\n\n## Customizing exit behaviour\n\nYou can define what SimpleCov should do when your test suite finishes by customizing the at_exit hook:\n\n```ruby\nSimpleCov.at_exit do\n  SimpleCov.result.format!\nend\n```\n\nAbove is the default behaviour. Do whatever you like instead!\n\n### Minimum coverage\n\nYou can define the minimum coverage percentage expected. SimpleCov will return non-zero if unmet.\n\n```ruby\nSimpleCov.minimum_coverage 90\n# same as above (the default is to check line coverage)\nSimpleCov.minimum_coverage line: 90\n# check for a minimum line coverage of 90% and minimum 80% branch coverage\nSimpleCov.minimum_coverage line: 90, branch: 80\n```\n\n### Minimum coverage by file\n\nYou can define the minimum coverage by file percentage expected. SimpleCov will return non-zero if unmet. This is useful\nto help ensure coverage is relatively consistent, rather than being skewed by particularly good or bad areas of the code.\n\n```ruby\nSimpleCov.minimum_coverage_by_file 80\n# same as above (the default is to check line coverage by file)\nSimpleCov.minimum_coverage_by_file line: 80\n# check for a minimum line coverage by file of 90% and minimum 80% branch coverage\nSimpleCov.minimum_coverage_by_file line: 90, branch: 80\n```\n\n### Maximum coverage drop\n\nYou can define the maximum coverage drop percentage at once. SimpleCov will return non-zero if exceeded.\n\n```ruby\nSimpleCov.maximum_coverage_drop 5\n# same as above (the default is to check line drop)\nSimpleCov.maximum_coverage_drop line: 5\n# check for a maximum line drop of 5% and maximum 10% branch drop\nSimpleCov.maximum_coverage_drop line: 5, branch: 10\n```\n\n### Refuse dropping coverage\n\nYou can also entirely refuse dropping coverage between test runs:\n\n```ruby\nSimpleCov.refuse_coverage_drop\n# same as above (the default is to only refuse line drop)\nSimpleCov.refuse_coverage_drop :line\n# refuse drop for line and branch\nSimpleCov.refuse_coverage_drop :line, :branch\n```\n\n## Using your own formatter\n\nYou can use your own formatter with:\n\n```ruby\nSimpleCov.formatter = SimpleCov::Formatter::HTMLFormatter\n```\n\nCalling `SimpleCov.result.format!` will be invoked with `SimpleCov::Formatter::YourFormatter.new.format(result)`,\nand `result` is an instance of `SimpleCov::Result`. Do whatever your wish with that!\n\n\n## Using multiple formatters\n\nAs of SimpleCov 0.9, you can specify multiple result formats. Formatters besides the default HTML formatter require separate gems, however.\n\n```ruby\nrequire \"simplecov-html\"\n\nSimpleCov.formatters = [\n  SimpleCov::Formatter::HTMLFormatter,\n  SimpleCov::Formatter::CSVFormatter,\n]\n```\n\n## JSON formatter\n\nSimpleCov 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.\n\nIn order to use it you will need to manually load the installed gem like so:\n\n```ruby\nrequire \"simplecov_json_formatter\"\nSimpleCov.formatter = SimpleCov::Formatter::JSONFormatter\n```\n\n\u003e _Note:_ In case you plan to report your coverage results to CodeClimate services, know that SimpleCov will automatically use the\n\u003e  JSON formatter along with the HTML formatter when the `CC_TEST_REPORTER_ID` variable is present in the environment.\n\n## Available formatters, editor integrations and hosted services\n\n  * [Open Source formatter and integration plugins for SimpleCov](doc/alternate-formatters.md)\n  * [Editor Integration](doc/editor-integration.md)\n  * [Hosted (commercial) services](doc/commercial-services.md)\n\n## Ruby version compatibility\n\nSimpleCov is built in [Continuous Integration] on Ruby 2.5+ as well as JRuby 9.2+.\n\nNote for JRuby =\u003e You need to pass JRUBY_OPTS=\"--debug\" or create .jrubyrc and add debug.fullTrace=true\n\n## Want to find dead code in production?\n\nTry [Coverband](https://github.com/danmayer/coverband).\n\n## Want to use Spring with SimpleCov?\n\nIf you're using [Spring](https://github.com/rails/spring) to speed up test suite runs and want to run SimpleCov along\nwith them, you'll find that it often misreports coverage with the default config due to some sort of eager loading\nissue. Don't despair!\n\nOne solution is to [explicitly call eager\nload](https://github.com/simplecov-ruby/simplecov/issues/381#issuecomment-347651728)\nin your `test_helper.rb` / `spec_helper.rb` after calling `SimpleCov.start`.\n\n```ruby\nrequire 'simplecov'\nSimpleCov.start 'rails'\nRails.application.eager_load!\n```\n\nAlternatively, you could disable Spring while running SimpleCov:\n\n```\nDISABLE_SPRING=1 rake test\n```\n\nOr you could remove `gem 'spring'` from your `Gemfile`.\n\n## Troubleshooting\n\nThe **most common problem is that simplecov isn't required and started before everything else**. In order to track\ncoverage for your whole application **simplecov needs to be the first one** so that it (and the underlying coverage\nlibrary) can subsequently track loaded files and their usage.\n\nIf you are missing coverage for some code a simple trick is to put a puts statement in there and right after\n`SimpleCov.start` so you can see if the file really was loaded after simplecov was started.\n\n```ruby\n# my_code.rb\nclass MyCode\n\n  puts \"MyCode is being loaded!\"\n\n  def my_method\n    # ...\n  end\nend\n\n# spec_helper.rb/rails_helper.rb/test_helper.rb/.simplecov whatever\n\nSimpleCov.start\nputs \"SimpleCov started successfully!\"\n```\n\nNow when you run your test suite and you see:\n\n```\nSimpleCov started successfully!\nMyCode is being loaded!\n```\n\nthen it's good otherwise you likely have a problem :)\n\n## Code of Conduct\n\nEveryone participating in this project's development, issue trackers and other channels is expected to follow our\n[Code of Conduct](./CODE_OF_CONDUCT.md)\n\n## Contributing\n\nSee the [contributing guide](https://github.com/simplecov-ruby/simplecov/blob/main/CONTRIBUTING.md).\n\n## Kudos\n\nThanks to Aaron Patterson for the original idea for this!\n\n## Copyright\n\nCopyright (c) 2010-2017 Christoph Olszowka. See MIT-LICENSE for details.\n","funding_links":[],"categories":["Ruby","code-quality","Testing"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplecov-ruby%2Fsimplecov","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimplecov-ruby%2Fsimplecov","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplecov-ruby%2Fsimplecov/lists"}