simplecov 0.8.0.pre2 → 0.18.0.beta1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# SimpleCov Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at simplecov.team@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

data/CONTRIBUTING.md

@@ -1,15 +1,37 @@
-# Making Contributions
+## Reporting Issues
+
+You can report issues at https://github.com/colszowka/simplecov/issues
+
+Before you go ahead please search existing issues for your problem, chances are someone else already reported it.
+
+To make sure that we can help you quickly please include and check the following information:
+
+ * Include how you run your tests and which testing framework or frameworks you are running.
+    - please ensure you are requiring and starting SimpleCov before requiring any application code.
+    - If running via rake, please ensure you are requiring SimpleCov at the top of your Rakefile
+      For example, if running via RSpec, this would be at the top of your spec_helper.
+    - Have you tried using a [`.simplecov` file](https://github.com/colszowka/simplecov#using-simplecov-for-centralized-config)?
+ * Include the SimpleCov version you are running in your report.
+ * If you are not running the latest version (please check), and you cannot update it,
+   please specify in your report why you can't update to the latest version.
+ * Include your `ruby -e "puts RUBY_DESCRIPTION"`.
+ * Please also specify the gem versions of Rails (if applicable).
+ * Include any other coverage gems you may be using and their versions.
+
+Include as much sample code as you can to help us reproduce the issue. (Inline, repo link, or gist, are fine. A failing test would help the most.)
+
+This is extremely important for narrowing down the cause of your problem.
+
+Thanks!
+
+## Making Contributions
 
 To fetch & test the library for development, do:
 
     $ git clone https://github.com/colszowka/simplecov.git
     $ cd simplecov
     $ bundle
-    $ rake appraisal:install
-    $ rake appraisal
-
-For more information on the appraisal gem (for testing against multiple gem dependency versions), please see
-https://github.com/thoughtbot/appraisal/
+    $ bundle exec rake
 
 If you want to contribute, please:
 
@@ -17,4 +39,13 @@ If you want to contribute, please:
   * Make your feature addition or bug fix.
   * Add tests for it. This is important so I don't break it in a future version unintentionally.
   * **Bonus Points** go out to anyone who also updates `CHANGELOG.md` :)
-  * Send me a pull request on Github.
+  * Send me a pull request on GitHub.
+
+## Running Individual Tests
+
+This project uses RSpec and Cucumber. Individual tests can be run like this:
+
+```bash
+bundle exec rspec path/to/test.rb
+bundle exec cucumber path/to/test.feature
+```

data/ISSUE_TEMPLATE.md

@@ -0,0 +1,23 @@
+Howdy! Thanks for reporting an issue <3
+
+Before you go ahead please search existing issues for your problem, chances are someone else already reported it.
+
+To make sure that we can help you quickly please include and check the following information:
+
+ * Include how you run your tests and which testing framework or frameworks you are running.
+    - please ensure you are requiring and starting SimpleCov before requiring any application code.
+    - If running via rake, please ensure you are requiring SimpleCov at the top of your Rakefile
+      For example, if running via RSpec, this would be at the top of your spec_helper.
+    - Have you tried using a [`.simplecov` file](https://github.com/colszowka/simplecov#using-simplecov-for-centralized-config)?
+ * Include the SimpleCov version you are running in your report.
+ * If you are not running the latest version (please check), and you cannot update it,
+   please specify in your report why you can't update to the latest version.
+ * Include your `ruby -e "puts RUBY_DESCRIPTION"`.
+ * Please also specify the gem versions of Rails (if applicable).
+ * Include any other coverage gems you may be using and their versions.
+
+Include as much sample code as you can to help us reproduce the issue. (Inline, repo link, or gist, are fine. A failing test would help the most.)
+
+This is extremely important for narrowing down the cause of your problem.
+
+Thanks!

data/{MIT-LICENSE → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2012 Christoph Olszowka
+Copyright (c) 2010-2017 Christoph Olszowka
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,15 +1,14 @@
-SimpleCov [![Build Status](https://secure.travis-ci.org/colszowka/simplecov.png)][Continuous Integration] [![Dependency Status](https://gemnasium.com/colszowka/simplecov.png)][Dependencies] [![Code Climate](https://codeclimate.com/github/colszowka/simplecov.png)](https://codeclimate.com/github/colszowka/simplecov)
+SimpleCov [![Gem Version](https://badge.fury.io/rb/simplecov.svg)](https://badge.fury.io/rb/simplecov) [![Build Status](https://travis-ci.org/colszowka/simplecov.svg?branch=master)][Continuous Integration] [![Code Climate](https://codeclimate.com/github/colszowka/simplecov.svg)](https://codeclimate.com/github/colszowka/simplecov) [![Inline docs](http://inch-ci.org/github/colszowka/simplecov.svg)](http://inch-ci.org/github/colszowka/simplecov)
 =========
-**Code coverage for Ruby 1.9**
+**Code coverage for Ruby**
 
   * [Source Code]
   * [API documentation]
   * [Changelog]
   * [Rubygem]
-  * [Mailing List]
   * [Continuous Integration]
 
-[Coverage]: http://www.ruby-doc.org/stdlib-1.9.3/libdoc/coverage/rdoc/Coverage.html "API doc for Ruby 1.9's Coverage library"
+[Coverage]: https://ruby-doc.org/stdlib/libdoc/coverage/rdoc/Coverage.html "API doc for Ruby's Coverage library"
 [Source Code]: https://github.com/colszowka/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"
@@ -18,92 +17,123 @@ SimpleCov [![Build Status](https://secure.travis-ci.org/colszowka/simplecov.png)
 [Continuous Integration]: http://travis-ci.org/colszowka/simplecov "SimpleCov is built around the clock by travis-ci.org"
 [Dependencies]: https://gemnasium.com/colszowka/simplecov "SimpleCov dependencies on Gemnasium"
 [simplecov-html]: https://github.com/colszowka/simplecov-html "SimpleCov HTML Formatter Source Code @ GitHub"
-[Mailing List]: https://groups.google.com/forum/#!forum/simplecov "Open mailing list for discussion and announcements on Google Groups"
-[Pledgie]: http://www.pledgie.com/campaigns/18379
 
-[![You can support the development of SimpleCov via Pledgie - thanks for your help](http://www.pledgie.com/campaigns/18379.png?skin_name=chrome)][Pledgie]
-
-SimpleCov is a code coverage analysis tool for Ruby 1.9. It uses [1.9'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, thus giving you a complete code coverage suite that can be set up with just a couple lines of
+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.
 
-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 then merging results when generating reports, so your
+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.
 
-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].
-
-
-
-Getting started
----------------
-
-1. Add SimpleCov to your `Gemfile` and `bundle install`:
-
-```ruby
-gem 'simplecov', :require => false, :group => :test
-```
+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].
 
-2. Load and launch SimpleCov **at the very top** of your `test/test_helper.rb` (*or `spec_helper.rb`, cucumber `env.rb`, or whatever
-   your preferred test framework uses*):
 
-```ruby
-require 'simplecov'
-SimpleCov.start
+## Contact
 
-# Previous content of test helper now starts here
-```
+*Code and Bug Reports*
 
-**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!**
+* [Issue Tracker](https://github.com/colszowka/simplecov/issues)
+* See [CONTRIBUTING](https://github.com/colszowka/simplecov/blob/master/CONTRIBUTING.md) for how to contribute along
+with some common problems to check out before creating an issue.
 
-SimpleCov must be running in the process that you want the code coverage analysis to happen on. When testing a server
-process (i.e. a JSON API endpoint) via a separate test process (i.e. 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'll want to add something
-like this to the top of `script/rails`:
+*Questions, Problems, Suggestions, etc.*
 
-```ruby
-if ENV['RAILS_ENV'] == 'test'
-  require 'simplecov'
-  SimpleCov.start 'rails'
-  puts "required simplecov"
-end
-```
+* [Mailing List](https://groups.google.com/forum/#!forum/simplecov) "Open mailing list for discussion and announcements
+on Google Groups"
 
-3. Run your tests, open up `coverage/index.html` in your browser and check out what you've missed so far.
-
-4. Add the following to your `.gitignore` file to ensure that coverage results are not tracked by Git (optional):
-
-    coverage
+Getting started
+---------------
+1. Add SimpleCov to your `Gemfile` and `bundle install`:
 
-If you're making a Rails application, SimpleCov comes with a built-in configurations (see below for information on profiles)
-which will get you started with groups for your Controllers, Views, Models and Helpers. To use it, the first two lines of
-your test_helper should be like this:
-
-```ruby
-require 'simplecov'
-SimpleCov.start 'rails'
-```
+    ```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*):
+
+    ```ruby
+    require 'simplecov'
+    SimpleCov.start
+
+    # 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!**
+
+    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'll want to add something like this
+    to the top of `bin/rails`, but below the "shebang" line (`#! /usr/bin/env
+    ruby`):
+
+    ```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](http://colszowka.github.com/simplecov/devise_result-0.5.3.png)
+![SimpleCov coverage report](https://cloud.githubusercontent.com/assets/137793/17071162/db6f253e-502d-11e6-9d84-e40c3d75f333.png)
 
 
 **Source file coverage details view:**
 
-![SimpleCov source file detail view](http://colszowka.github.com/simplecov/devise_source_file-0.5.3.png)
-
-
+![SimpleCov source file detail view](https://cloud.githubusercontent.com/assets/137793/17071163/db6f9f0a-502d-11e6-816c-edb2c66fad8d.png)
 
 ## Use it with any framework!
 
-Similarily to the usage with Test::Unit described above, the only thing you have to do is to add the simplecov
+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.
 
 Add the setup code to the **top** of `features/support/env.rb` (for Cucumber) or `spec/spec_helper.rb` (for RSpec).
@@ -114,8 +144,9 @@ 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.
+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.
 
 ### Notes on specific frameworks and test utilities
 
@@ -123,69 +154,75 @@ For some frameworks and testing tools there are quirks and problems you might wa
 to use SimpleCov with them. Here's an overview of the known ones:
 
 <table>
-<tr><th>Framework</th><th>Notes</th><th>Issue #</th></tr>
-<tr>
- <td>
-   <b>Test/Unit 2</b>
- </td>
- <td>
-  Test Unit 2 used to mess with ARGV, leading to 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/colszowka/simplecov/issues/45">SimpleCov #45</a> &
-  <a href="https://github.com/test-unit/test-unit/pull/12">Test/Unit #12</a>
- </td>
-</tr>
-<tr>
- <td>
-   <b>Spork</b>
- </td>
- <td>
-  Because of the how Spork works internally (using preforking) there used to be trouble when using SimpleCov
-  with it, but that apparently has been resolved with a specific configuration strategy. See
-  <a href="https://github.com/colszowka/simplecov/issues/42#issuecomment-4440284">this</a> comment.
- </td>
- <td>
-  <a href="https://github.com/colszowka/simplecov/issues/42#issuecomment-4440284">SimpleCov #42</a>
- </td>
-</tr>
-<tr>
- <td>
-   <b>parallel_tests</b>
- </td>
- <td>
-  SimpleCov does not detect parallel_test automatically yet but can be taught to do so
-  with a simple workaround explained at Issue #64.
- </td>
- <td>
-  <a href="https://github.com/colszowka/simplecov/issues/64">SimpleCov #64</a>
- </td>
-</tr>
-<tr>
- <td>
-   <b>Riot</b>
- </td>
- <td>
-  A user has reported problems with the coverage report using the riot framework. If you experience
-  similar trouble please follow up on the related Github issue.
- </td>
- <td>
-  <a href="https://github.com/colszowka/simplecov/issues/80">SimpleCov #80</a>
- </td>
-</tr>
-<tr>
- <td>
-   <b>RubyMine</b>
- </td>
- <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/colszowka/simplecov/issues/95">SimpleCov #95</a>
- </td>
-</tr>
+  <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/colszowka/simplecov/issues/64">#64</a> &amp;
+      <a href="https://github.com/colszowka/simplecov/pull/185">#185</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/colszowka/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/colszowka/simplecov/issues/42#issuecomment-4440284">this</a>
+      comment.
+    </td>
+    <td>
+      <a href="https://github.com/colszowka/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/colszowka/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/colszowka/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>
 
 ## Configuring SimpleCov
@@ -194,36 +231,35 @@ to use SimpleCov with them. Here's an overview of the known ones:
 
 * The most common way is to configure it directly in your start block:
 
-```ruby
-SimpleCov.start do
-  some_config_option 'foo'
-end
-```
-
+    ```ruby
+    SimpleCov.start do
+      some_config_option 'foo'
+    end
+    ```
 * You can also set all configuration options directly:
 
-```ruby
-SimpleCov.some_config_option 'foo'
-```
+    ```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:
 
-* If you do not want to start coverage immediately after launch or want to add additional configuration later on in a concise way, use:
-
-```ruby
-SimpleCov.configure do
-  some_config_option 'foo'
-end
-```
+    ```ruby
+    SimpleCov.configure do
+      some_config_option 'foo'
+    end
+    ```
 
 Please check out the [Configuration] API documentation to find out what you can customize.
 
-
 ## Using .simplecov for centralized config
 
-If you use SimpleCov to merge multiple test suite results (i.e. 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`.
+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`.
 
-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 and move the `SimpleCov.start` code with all your custom config options into `.simplecov`:
+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`:
 
 ```ruby
 # test/test_helper.rb
@@ -238,19 +274,69 @@ SimpleCov.start 'rails' do
 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.
+
+## Branch coverage (ruby "~> 2.5")
+Add branch coverage measurement statistics to your results. Supported in CRuby versions 2.5+.
+
+```ruby
+# or in configure or just SimpleCov.enable_coverage :branch
+SimpleCov.start do
+  enable_coverage :branch
+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.
+
+This comes in handy for instance 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:
+
+```ruby
+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.
+
+In the HTML report the lines of code will be annotated like `hit_count, positive_or_negative_branch`:
+
+* `2, +` - the positive branch was executed twice
+* `0, -` - the negative branch was never executed
+
+**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).
+
+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.
+
 ## 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 a billion of coverage reports for source files in the
-gems you are using.
+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.
 
-Of course you can define your own to remove things like configuration files, tests or whatever you don't need in your coverage
+You can define your own to remove things like configuration files, tests or whatever you don't need in your coverage
 report.
 
 ### Defining custom filters
 
-You can currently define a filter using either a String (that will then be Regexp-matched against each source file's path),
-a block or by passing in your own Filter class.
+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.
 
 #### String filter
 
@@ -262,6 +348,16 @@ end
 
 This simple string filter will remove all files that match "/test/" in their path.
 
+#### Regex filter
+
+```ruby
+SimpleCov.start do
+  add_filter %r{^/test/}
+end
+```
+
+This simple regex filter will remove all files that start with /test/ in their path.
+
 #### Block filter
 
 ```ruby
@@ -272,9 +368,10 @@ SimpleCov.start do
 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 then 5 lines of code.
+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.
 
 #### Custom filter class
 
@@ -288,17 +385,63 @@ end
 SimpleCov.add_filter 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.
+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.
+
+#### Array filter
+
+```ruby
+SimpleCov.start do
+  proc = Proc.new { |source_file| false }
+  add_filter ["string", /regex/, proc, LineFilter.new(5)]
+end
+```
+
+You can pass in an array containing any of the other filter types.
+
+#### Ignoring/skipping code
+
+You can exclude code from the coverage report by wrapping it in `# :nocov:`.
+
+```ruby
+# :nocov:
+def skip_this_method
+  never_reached
+end
+# :nocov:
+```
+
+The name of the token can be changed to your liking. [Learn more about the nocov feature.]( https://github.com/colszowka/simplecov/blob/master/features/config_nocov_token.feature)
+
+**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.
+
+## Default root filter and coverage for things outside of it
 
+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.
+
+Here's an example by [@lsaffie](https://github.com/lsaffie) from [#221](https://github.com/colszowka/simplecov/issues/221)
+that shows how you can achieve just that:
+
+```ruby
+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
+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, Libs and Plugins. Group definition works similar to Filters (and indeed 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.
+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:
 
@@ -309,16 +452,17 @@ SimpleCov.start do
   add_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
 end
 ```
 
 ## Merging results
 
-Normally, you want to have your coverage analyzed across ALL of your test suites, right?
+You normally want to have your coverage analyzed across ALL of your test suites, right?
 
 Simplecov automatically caches coverage results in your (coverage_path)/.resultset.json. Those results will then
-be automatically merged when generating the result, so when coverage is set up properly for cucumber and your
+be automatically merged 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.
 
@@ -326,17 +470,17 @@ There are two things to note here though:
 
 ### Test suite names
 
-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.
+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.
 
-If you have some non-standard setup and still want nicely labeled test suites, you have to give Simplecov a cue 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.
+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.
 
-So, 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:
+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:
 
 ```ruby
 # test/unit/some_test.rb
@@ -352,30 +496,50 @@ SimpleCov.command_name "test:integration"
 SimpleCov.command_name "features"
 ```
 
-Note that this has only to be invoked ONCE PER TEST SUITE, so even if you have 200 unit test files, specifying it in
-some_test.rb is fair enough.
+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.
+
+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:
+
+```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.
 
 ### Timeout for merge
 
 Of course, your cached coverage data is likely to become invalid at some point. Thus, 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
+`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".
+just `merge_timeout 3600`.
 
 You can deactivate merging altogether with `SimpleCov.use_merging false`.
 
-
 ## Running coverage only on demand
 
-The Ruby STDLIB Coverage library that SimpleCov builds upon is *very* fast (i.e. 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.
+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.
 
 Because of this, SimpleCov has no explicit built-in mechanism to run coverage only on demand.
 
-However, you can still accomplish this very easily by introducing a ENV variable conditional into your SimpleCov setup block, like this:
+However, you can still accomplish this very easily by introducing an ENV variable conditional into your SimpleCov setup
+block, like this:
 
 ```ruby
 SimpleCov.start if ENV["COVERAGE"]
@@ -387,11 +551,25 @@ Then, SimpleCov will only run if you execute your tests like this:
 COVERAGE=true rake test
 ```
 
+## Errors and exit statuses
+
+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:
+
+```
+SimpleCov failed with exit 1
+```
+
+This `STDERR` message can be disabled with:
+
+```
+SimpleCov.print_error_status = false
+```
 
 ## Profiles
 
-By default, Simplecov's only config assumption is that you only want coverage reports for files inside your project
-root. To save you from repetitive configuration, you can use predefined blocks of configuration, called 'profiles',
+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.
 
 You can then pass the name of the profile to be used as the first argument to SimpleCov.start. For example, simplecov
@@ -406,17 +584,16 @@ SimpleCov.profiles.define 'rails' do
   add_group 'Models', 'app/models'
   add_group 'Helpers', 'app/helpers'
   add_group 'Libraries', 'lib'
-  add_group 'Plugins', 'vendor/plugins'
 end
 ```
 
-As you can see, it's just a SimpleCov.configure block. In your test_helper.rb, launch simplecov with:
+As you can see, it's just a SimpleCov.configure block. In your test_helper.rb, launch SimpleCov with:
 
 ```ruby
 SimpleCov.start 'rails'
 ```
 
-**OR**
+or
 
 ```ruby
 SimpleCov.start 'rails' do
@@ -426,8 +603,8 @@ end
 
 ### Custom profiles
 
-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.
+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:
 
 ```ruby
 # lib/simplecov_custom_profile.rb
@@ -446,10 +623,9 @@ require 'simplecov_custom_profile'
 SimpleCov.start 'myprofile'
 ```
 
-
 ## Customizing exit behaviour
 
-You can define what simplecov should do when your test suite finishes by customizing the at_exit hook:
+You can define what SimpleCov should do when your test suite finishes by customizing the at_exit hook:
 
 ```ruby
 SimpleCov.at_exit do
@@ -467,6 +643,15 @@ You can define the minimum coverage percentage expected. SimpleCov will return n
 SimpleCov.minimum_coverage 90
 ```
 
+### Minimum coverage by file
+
+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.
+
+```ruby
+SimpleCov.minimum_coverage_by_file 80
+```
+
 ### Maximum coverage drop
 
 You can define the maximum coverage drop percentage at once. SimpleCov will return non-zero if exceeded.
@@ -491,66 +676,100 @@ You can use your own formatter with:
 SimpleCov.formatter = SimpleCov::Formatter::HTMLFormatter
 ```
 
-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!
+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!
 
 
 ## Using multiple formatters
 
-If you want to use multiple result formats, as of SimpleCov 0.7.0 you can use the built-in MultiFormatter:
+As of SimpleCov 0.9, you can specify multiple result formats:
 
 ```ruby
-SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+SimpleCov.formatters = SimpleCov::Formatter::MultiFormatter.new([
   SimpleCov::Formatter::HTMLFormatter,
   SimpleCov::Formatter::CSVFormatter,
-]
+])
 ```
 
-## Available formatters
+## Available formatters, editor integrations and hosted services
+
+  * [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)
+
+## Ruby version compatibility
+
+SimpleCov is built in [Continuous Integration] on Ruby 2.4+ as well as JRuby 9.2+.
+
+Note for JRuby => You need to pass JRUBY_OPTS="--debug" or create .jrubyrc and add debug.fullTrace=true
+
+## Want to find dead code in production?
+
+Try [Coverband](https://github.com/danmayer/coverband).
 
-Apart from the direct companion [simplecov-html], there are other formatters
-available:
+## Want to use Spring with SimpleCov?
 
-#### [simplecov-rcov](https://github.com/fguillen/simplecov-rcov)
-*by Fernando Guillen*
+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!
 
-"The target of this formatter is to cheat on Hudson so I can use the Ruby metrics plugin with SimpleCov."
+One solution is to [explicitly call eager
+load](https://github.com/colszowka/simplecov/issues/381#issuecomment-347651728)
+in your `test_helper.rb` / `spec_helper.rb` after calling `SimpleCov.start`.
 
-#### [simplecov-csv](https://github.com/fguillen/simplecov-csv)
-*by Fernando Guillen*
+```ruby
+require 'simplecov'
+SimpleCov.start 'rails'
+Rails.application.eager_load!
+```
 
-CSV formatter for SimpleCov code coverage tool for ruby 1.9+
+Alternatively, you could disable Spring while running SimpleCov:
 
-#### [simplecov-vim](https://github.com/nyarly/Simplecov-Vim)
-*by Judson Lester*
+```
+DISABLE_SPRING=1 rake test
+```
 
-A formatter for Simplecov that emits a Vim script to mark up code files with coverage information.
+Or you could remove `gem 'spring'` from your `Gemfile`.
 
-#### [simplecov-single_file_reporter](https://github.com/grosser/simplecov-single_file_reporter)
-*by [Michael Grosser](http://grosser.it)*
+## Troubleshooting
 
-A formatter that prints the coverage of the file under test when you run a single test file.
+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.
 
-#### [simplecov-json](https://github.com/vicentllongo/simplecov-json)
-*by Vicent Llongo*
+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.
 
-JSON formatter for SimpleCov
+```ruby
+# my_code.rb
+class MyCode
 
-#### [simplecov-badge](https://github.com/matthew342/simplecov-badge)
-*by Matt Hale*
+  puts "MyCode is being loaded!"
 
-A formatter that generates a coverage badge for use in your project's readme using ImageMagick.
+  def my_method
+    # ...
+  end
+end
 
-## Ruby version compatibility
+# 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:
+
+```
+SimpleCov started successfully!
+MyCode is being loaded!
+```
 
-[![Build Status](https://secure.travis-ci.org/colszowka/simplecov.png)](http://travis-ci.org/colszowka/simplecov)
+then it's good otherwise you likely have a problem :)
 
-Only Ruby 1.9+ ships with the coverage library that SimpleCov depends upon. SimpleCov is built against various other Rubies,
-including Rubinius and JRuby, in [Continuous Integration], but this happens only to ensure that SimpleCov does not make your
-test suite crash right now. Whether SimpleCov will support JRuby/Rubinius in the future depends solely on whether those Ruby
-interpreters add the coverage library.
+## Code of Conduct
 
-SimpleCov is built in [Continuous Integration] on 1.8.7, ree, 1.9.2, 1.9.3.
+Everyone participating in this project's development, issue trackers and other channels is expected to follow our
+[Code of Conduct](./CODE_OF_CONDUCT.md)
 
 ## Contributing
 
@@ -562,4 +781,4 @@ Thanks to Aaron Patterson for the original idea for this!
 
 ## Copyright
 
-Copyright (c) 2010-2012 Christoph Olszowka. See MIT-LICENSE for details.
+Copyright (c) 2010-2017 Christoph Olszowka. See MIT-LICENSE for details.