coverband 3.0.0 → 4.0.0

data/README.md

@@ -4,249 +4,145 @@ Build Status: [![Build Status](https://travis-ci.org/danmayer/coverband.svg?bran
 
 <p align="center">
   <a href="#key-features">Key Features</a> •
-  <a href="#coverband-demo">Coverband Demo</a> •
-  <a href="#how-to-use">How To Use</a> •
   <a href="#installation">Installation</a> •
   <a href="#configuration">Configuration</a> •
+  <a href="#coverband-demo">Coverband Demo</a> •
+  <a href="#how-to-use">How To Use</a> •
   <a href="#usage">Usage</a> •
   <a href="#license">License</a> •
   <a href="/changes.md">Change Log / Roadmap</a>
 </p>
 
-A gem to measure production code usage, showing each line of code that is executed. Coverband allows easy configuration to collect and report on production code usage. It can be used as Rack middleware, wrapping a block with sampling, or manually configured to meet any need (like usage during background jobs).
+A gem to measure production code usage, showing a counter for the number of times each line of code that is executed. Coverband allows easy configuration to collect and report on production code usage. It reports in the background via a thread or can be used as Rack middleware, or manually configured to meet any need.
 
-Note: Coverband is not intended for test code coverage, for that just check out [SimpleCov](https://github.com/colszowka/simplecov).
+__Note:__ Coverband is not intended for test code coverage, for that we recommended using [SimpleCov](https://github.com/colszowka/simplecov).
 
 ## Key Features
 
 The primary goal of Coverband is giving deep insight into your production runtime usage of your application code, while having the least impact on performance possible.
 
 * Low performance overhead
-* Various controls from sampling, data collection rate, etc to further control performance
-* Ignore directories to avoid overhead data collection on vendor, lib, etc.
+* Very simple setup and configuration
+* Out of the box support for all standard code execution paths (web, cron, background jobs, rake tasks, etc)
+* Easy to understand actionable insights from the report
 * Development mode, offers deep insight of code usage details (number of LOC execution during single request, etc) during development.
-* Easy setup for any Ruby Rack based web framework (Rails, Sinatra, etc)
-* Allows for integration with any other Ruby application flows (background jobs, crons, scripts)
-
-## Coverband Demo
-
-Take Coverband for a spin on the live Heroku deployed [Coverband Demo](https://coverband-demo.herokuapp.com/). The [full source code for the demo](https://github.com/danmayer/coverband_demo) is available to help with configuration and understanding of basic usage.
-
-# How To Use
-
-Below is my Coverband workflow, which hopefully will help other best use this library.
-
-* install coverband
-* start your app and hit a few endpoints
-* validate data collection and code coverage with  `rake coverband:coverage`
-* test setup in development (hit endpoints and generate new report)
-* deploy to staging and verify functionality
-* deploy to production and verify functionality
-* every 2 weeks or so, with major releases
-   * clear old coverage: `rake coverband:clear`
-   * deploy and verify coverage is matching expectations
-* __COVERAGE DRIFT__
-   * we are working to address this early in the 3.0.x feature set
-      * https://github.com/danmayer/coverband/issues/118  
-   * if you never clear you have lines of code drift from when they were recorded
-   * if you clear on every deploy you don't capture as useful of data
-   * there is a tradeoff on accuracy and data value
-   * I recommend clearing after major code changes, significant releases, or some regular schedule.
-
-## Example Output
-
-Since Coverband is [Simplecov](https://github.com/colszowka/simplecov) output compatible it should work with any of the `SimpleCov::Formatter`'s available. The output below is produced using the default Simplecov HTML formatter.
-
-Index Page
-![image](https://raw.github.com/danmayer/coverband/master/docs/coverband_index.png)
-
-Details on a example Sinatra app
-![image](https://raw.github.com/danmayer/coverband/master/docs/coverband_details.png)
+* Mountable web interface to easily share reports
 
 
 # Installation
 
-Follow the below section to install and configure Coverband.
-
-![coverband installation](https://raw.githubusercontent.com/danmayer/coverband/master/docs/coverband-install-resize.gif)
-
-## Prerequisites
-
-* Coverband 3.0 requres Ruby 2.3+
+Coverband should be near zero config for Rails apps, if you have an issue with that, please [file an issue](https://github.com/danmayer/coverband/issues).
 
 ## Gem Installation
 
-Add this line to your application's Gemfile:
+Add this line to your application's `Gemfile`, remember to `bundle install` after updating:
 
 ```bash
 gem 'coverband'
 ```
 
-And then execute:
-
-```bash
-$ bundle
-```
-
-Or install it yourself as:
-
-```bash
-$ gem install coverband
-```
-
-# Configuration
+## Rails
 
-After you have the gem, you will want to setup the needed integration:
+The Railtie integration means you shouldn't need to do anything anything else.
 
-1. Coverband Config File Setup
-2. Configure Rake
-3. Insert Coverband Rack Middleware
+* By default Coverband will try to stored data to Redis
+	* Redis endpoint is looked for in this order: `ENV['COVERBAND_REDIS_URL']`, `ENV['REDIS_URL']`, or `localhost`
 
-### 1. Coverband Config File Setup
+## Sinatra
 
-You need to configure cover band you can either do that passing in all configuration options to `Coverband.configure` in block format, or a simpler style is to call `Coverband.configure` with nothing while will load `config/coverband.rb` expecting it to configure the app correctly. Below is an example config file for a Rails 5 app:
+For the best coverage you want this loaded as early as possible. I have been putting it directly in my `config.ru` but you could use an initializer, though you may end up missing some boot up coverage. To start collection require Coverband as early as possible.
 
 ```ruby
-#config/coverband.rb
-Coverband.configure do |config|
-  config.root              = Dir.pwd
-  config.store             = Coverband::Adapters::RedisStore.new(Redis.new(url: ENV['REDIS_URL'])) if defined? Redis
-  config.ignore            = %w[vendor .erb$ .slim$]
-  # add paths that you deploy to that might be different than your local dev root path
-  config.root_paths        = []
-
-  # reporting frequency, how often coverage data is sent to the store
-  # if you are debugging changes to coverband I recommend setting to 100.0
-  config.reporting_frequency = Rails.env.production? ? 1.0 : 100.0
-  config.logger              = Rails.logger
+require 'coverband'
+require File.dirname(__FILE__) + '/config/environment'
 
-  # config options false, true, or 'debug'. Always use false in production
-  # true and debug can give helpful and interesting code usage information
-  # they both increase the performance overhead of the gem a little.
-  # they can also help with initially debugging the installation.
-  # config.verbose           = 'debug'
-end
+use Coverband::Middleware
+run ActionController::Dispatcher.new
 ```
 
-### 2. Configure Rake
+# Report Generation
 
-Either add the below to your `Rakefile` or to a file included in your Rakefile such as `lib/tasks/coverband.rake` if you want to break it up that way.
+There are two primary ways to generate and view the report
 
-```ruby
-require 'coverband'
-Coverband.configure
-require 'coverband/utils/tasks'
-```
-This should give you access to a number of Coverband tasks
+## Rake Tasks
+
+After installing the gem in Rails you should have these Rake tasks
 
 ```bash
 rake -T coverband
-rake coverband:clear         # reset coverband coverage data
-rake coverband:coverage      # report runtime coverband code coverage
+rake coverband:coverage      # report runtime Coverband code coverage
+rake coverband:clear         # reset Coverband coverage data, helpful for development, debugging, etc
 ```
 
-### 3. Configure Rack to use the Coverband middleware
+You can view the report different ways, but the easiest is the Rake task which opens the SimpleCov formatted HTML.
 
-The middleware is what makes Coverband gather metrics while a webapp app runs.
+`rake coverband:coverage`
 
-#### For Rails apps
+This should auto-open in your browser, but if it doesn't the output file should be in `coverage/index.html`
 
-There are a number of options for starting Coverband and when to insert it into your middleware stack. At the moment this is my recommendation, to ensure you capture usage data on any files required by other plugins.
+## Viewing the Report in App
 
-Then add the middleware to your Rails rake middle ware stack:
+First setup Coverband to [write reports to S3](#writing-coverband-results-to-s3) you can host the S3 file with a built in rack app in Coverband. Just configure your Rails route `config/routes.rb`
 
-```ruby
-# config/application.rb
-[...]
-
-module MyApplication
-  class Application < Rails::Application
-    [...]
-
-    # Coverband needs to be setup before any of the initializers to capture usage of them
-    require 'coverband'
-    Coverband.configure
-    config.middleware.use Coverband::Middleware
-
-    # if one uses before_eager_load as I did previously
-    # any files that get loaded as part of railties will have no coverage
-    config.before_initialize do
-       Coverband.start
-    end
-  end
+```
+Rails.application.routes.draw do
+  # ... lots of routes
+  mount Coverband::Reporters::Web.new, at: '/coverage'
 end
 ```
 
-#### For Sinatra apps
+__NOTE__: ADD PASSWORD PROTECTION OR YOU CAN EXPOSE ALL YOUR SOURCE CODE
 
-For the best coverage you want this loaded as early as possible. I have been putting it directly in my `config.ru` but you could use an initializer, though you may end up missing some boot up coverage.
+It is easy to add basic protection around the coverage data, below shows how you can use devise or basic auth, by adding a bit of code to your `config/routes.rb` file.
 
-```ruby
-require File.dirname(__FILE__) + '/config/environment'
+```
+# protect with existing Rails devise configuration
+devise_constraint = lambda do |request|
+  request.env['warden'] && request.env['warden'].authenticate? && request.env['warden'].user.admin?
+end
 
-require 'coverband'
-Coverband.configure
+# protect with http basic auth
+# curl --user foo:bar http://localhost:3000/coverage
+Rails.application.routes.draw do
+  # ... lots of routes
 
-use Coverband::Middleware
-run ActionController::Dispatcher.new
+  # Create a Rack wrapper around the Coverband Web Reporter to support & prompt the user for basic authentication.
+  AuthenticatedCoverband = Rack::Builder.new do 
+    use Rack::Auth::Basic do |username, password|
+      username == 'foo' && password == 'bar'
+    end
+
+    run Coverband::Reporters::Web.new 
+  end
+
+  # Connect the wrapper app to your desired endpoint.
+  mount AuthenticatedCoverband, at: '/coverage'
+end
 ```
 
 # Verify Correct Installation
 
 * boot up your application
+* run app and hit a controller (via a web request, at least one request must complete)
 * run `rake coverband:coverage` this will show app initialization coverage
-* run app and hit a controller (hit at least +1 time over your `config.startup_delay` setting default is 0)
+* make another request, or enough that your reporting frequency will trigger
 * run `rake coverband:coverage` and you should see coverage increasing for the endpoints you hit.
 
-## Installation Session
+# Coverband Demo
 
-These are the steps taken to install and configure Coverband
+Take Coverband for a spin on the live Heroku deployed [Coverband Demo](https://coverband-demo.herokuapp.com/). The [full source code for the demo](https://github.com/danmayer/coverband_demo) is available to help with installation, configuration, and understanding of basic usage.
 
-```
-rails new coverage_example
-cd coverage_example
-atom .
-
-# open Gemfile, add lines
-gem 'redis'
-gem 'coverband', '>= 3.0.0.alpha2', require: false
-
-bundle install
-
-# create config/coverband.rb
-# copy the config from the readme
-# If you don't set REDIS_URL, remove that to use default localhost
-
-# Make some code so we can look at the coverage
-rails generate scaffold blogs
-rake db:migrate
-
-# open Rakefile, add lines
-require 'coverband'
-Coverband.configure
-require 'coverband/utils/tasks'
-
-# verify rake
-rake -T coverband
-
-# configure config/application.rb
-# copy lines from readme
-
-# start up your app
-rake coverband:coverage
-# view boot up coverage
-
-rails s
-
-open http://localhost:3000/blogs
-
-# click around some to trigger usage
+# How To Use
 
-# view updated coverage
-rake coverband:coverage
-```
+Below is my Coverband workflow, which hopefully will help other best use this library.
 
-# Usage
+* <a href="#installation">Install Coverband</a>
+* Start your app and hit a few endpoints
+* Validate data collection and code coverage with  `rake coverband:coverage`
+* If you see app startup and recent visits showing, setup is correct
+* I generally configure the mountable web endpoint to [view the data via the web-app](https://github.com/danmayer/coverband#viewing--hosting-s3-coverband-results-in-app)
+* After Coverband has been verified to be working on production, I let it run for a few weeks.
+* Then I view the report and start submitting PRs for the team to review delete large related sets of code that no longer are in use.
 
 ### Example apps
 
@@ -254,132 +150,92 @@ rake coverband:coverage
 - [Sinatra app](https://github.com/danmayer/churn-site)
 - [Non Rack Ruby app](https://github.com/danmayer/coverband_examples)
 
-### View Coverage
+### Example Output
 
-You can view the report different ways, but the easiest is the Rake task which opens the SimpleCov formatted HTML.
-
-`rake coverband:coverage`
-
-This should auto-open in your browser, but if it doesn't the output file should be in `coverage/index.html`
-
-### Clear Coverage
-
-If your code has changed and your coverage line data doesn't seem to match run time. You probably need to clear your old line data... You will need to run this in the environment you wish to clear the data from.
-
-`rake coverband:clear`
-
-### Automated Clearing Line Coverage Data
-
-After a deploy where code has changed significantly. This is to avoid coverage drift
+Since Coverband is [Simplecov](https://github.com/colszowka/simplecov) output compatible it should work with any of the `SimpleCov::Formatter`'s available. The output below is produced using the default Simplecov HTML formatter.
 
-The line numbers previously recorded in Redis may no longer match the current state of the files.
-If being slightly out of sync isn't as important as gathering data over a long period,
-you can live with minor inconsistency for some files.
+Index Page
+![image](https://raw.github.com/danmayer/coverband/master/docs/coverband_index.png)
 
-As often as you like or as part of a deploy hook you can clear the recorded Coverband data with the following command.
+Details on a example Sinatra app
+![image](https://raw.github.com/danmayer/coverband/master/docs/coverband_details.png)
 
-```ruby
-# defaults to the currently configured Coverband.configuration.redis
-Coverband::Reporter.clear_coverage
-# or pass in the current target redis
-Coverband::Reporter.clear_coverage(Redis.new(:host => 'target.com', :port => 6789))
-```
-You can also do this with the included rake tasks.
+### Advanced Coverband Config
 
-### Manual Configuration (for example for background jobs)
+You may need to configure Coverband you can either do that passing in all configuration options to `Coverband.configure` in block format, or a simpler style is to call `Coverband.configure` with no params which will load `config/coverband.rb` expecting it to configure the app correctly.
 
-It is easy to use Coverband outside of a Rack environment. Make sure you configure Coverband in whatever environment you are using (such as `config/initializers/*.rb`). Then you can hook into before and after events to add coverage around background jobs, or for any non Rack code.
+* See [lib/coverband/configuration.rb](https://github.com/danmayer/coverband/blob/master/lib/coverband/configuration.rb) for all options
+* I strongly recommend setting up the S3 report adapter, which can't be automatically configured
+* By default Coverband will try to stored data to Redis
+	* Redis endpoint is looked for in this order: `ENV['COVERBAND_REDIS_URL']`, `ENV['REDIS_URL']`, or `localhost`
 
-For example if you had a base Resque class, you could use the `before_perform` and `after_perform` hooks to add Coverband
+ Below is an example config file for a Rails 5 app:
 
 ```ruby
-require 'coverband'
-Coverband.configure
-Coverband.start
+#config/coverband.rb
+Coverband.configure do |config|
+  # configure S3 integration
+  config.s3_bucket = 'coverband-demo'
+  config.s3_region = 'us-east-1'
+  config.s3_access_key_id = ENV['AWS_ACCESS_KEY_ID']
+  config.s3_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
 
-def after_perform(*args)
-  if @recording_samples
-     Coverband::Collectors::Coverage.instance.report_coverage
-  end
+  # config options false, true, or 'debug'. Always use false in production
+  # true and debug can give helpful and interesting code usage information
+  # they both increase the performance overhead of the gem a little.
+  # they can also help with initially debugging the installation.
+  config.verbose = false
 end
 ```
 
-or sidekiq middleware:
+### Writing Coverband Results to S3
+
+If you add some additional Coverband configuration your coverage html report will be written directly to S3, update `config/coverband.rb` like below.
 
-```ruby
-  # capture code usage in background jobs
-  class CoverbandMiddleware
-    def call(_worker, _msg, _queue)
-      Coverband.start
-      yield
-    ensure
-      Coverband::Collectors::Coverage.instance.report_coverage
-    end
-  end
-  
-  ...
-  chain.add Sidekiq::CoverbandMiddleware
+```
+  # configure S3 integration
+  config.s3_bucket = 'coverband-demo'
+  config.s3_region = 'us-east-1'
+  config.s3_access_key_id = ENV['AWS_ACCESS_KEY_ID']
+  config.s3_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
 ```
 
-In general you can run Coverband anywhere by using the lines below. This can be useful to wrap all cron jobs, background jobs, or other code run outside of web requests. I recommend trying to run both background and cron jobs at 100% coverage as the performance impact is less important and often old code hides around those jobs.
+Alternatively, Coverband if you don't set via the `config.s3_*` accessor methods will look for the standard S3 environment variables.
 
+```
+ENV['AWS_BUCKET']
+ENV['AWS_REGION']
+ENV['AWS_ACCESS_KEY_ID']
+ENV['AWS_SECRET_ACCESS_KEY']
+```
 
-```ruby
-require "coverband"
-Coverband.configure
-Coverband.start
+### Clear Coverage
 
-# do whatever
-Coverband::Collectors::Coverage.instance.report_coverage
+Now that Coverband uses MD5 hashes there should be no reason to manually clear coverage unless one is testing, changing versions, possibly debugging Coberband itself.
 
-```
+`rake coverband:clear`
 
-### Manual Configuration (for cron jobs / Raketasks)
+### Adding Rake Tasks outside of Rails
 
-A question about [supporting cron jobs and Rake tasks](https://github.com/danmayer/coverband/issues/106) was asked by [@ndbroadbent](https://github.com/ndbroadbent), there are a couple ways to go about it including his good suggestion.
+Rails apps should automaticallly include the tasks via the Railtie.
 
-He extended the Coverband Rake tasks by adding `lib/tasks/coverband.rake` with support to wrap all Rake tasks with coverband support.
+For non Rails apps, either add the below to your `Rakefile` or to a file included in your `Rakefile` such as `lib/tasks/coverband.rake` if you want to break it up that way.
 
-```
+```ruby
 require 'coverband'
 Coverband.configure
 require 'coverband/utils/tasks'
-
-# Wrap all Rake tasks with Coverband
-current_tasks = Rake.application.top_level_tasks
-if current_tasks.any? && current_tasks.none? { |t| t.to_s.match?(/^coverband:/) }
-  current_tasks.unshift 'coverband:start'
-  current_tasks.push 'coverband:stop_and_save'
-end
-
-namespace :coverband do
-  task :start do
-    Coverband.start
-  end
-
-  task :stop_and_save do
-    Coverband::Collectors::Coverage.instance.report_coverage
-  end
-end
 ```
 
-That is a interesting approach and if you Run all your cron jobs as Rake tasks might work well for you. In a production application where we run Coverband, we run all of our Cron jobs with the `rails runner` script. We took this alternative approach which will wrap all runner jobs with Coverband recording, by creating `lib/railties/coverage_runner.rb`.
+Verify it works
 
-```
-require 'rails'
-
-# Capture code coverage during our cron jobs
-class CoverageRunner < ::Rails::Railtie
-  runner do
-    Coverband.start
-    at_exit do
-      Coverband::Collectors::Coverage.instance.report_coverage
-    end
-  end
-end
+```bash
+rake -T coverband
+rake coverband:clear         # reset coverband coverage data
+rake coverband:coverage      # report runtime coverband code coverage
 ```
 
-### safe_reload_files: Forcing Coverband to Track Coverage on Files loaded during boot
+### Forcing Coverband to Track Coverage on files loaded during boot `safe_reload_files`
 
 The way Coverband is built it will record and report code usage in production for anything `required` or `loaded` after calling `Coverband.start`. This means some of Rails initial files and Gems are loaded before you can generally call `Coverband.start` for example if you use the `application.rb` to initialize and start Coverband, that file will be reported as having no coverage, as it can't possibly start Coverband before the file is loaded. 
 
@@ -399,20 +255,18 @@ By adding any files above you will get reporting on those files as part of your
 
 By default Coverband has assumed you are trying to track your application code usage not all the supporting framework and library (Gems) code usage. There has been some good points and reasons folks want to track library usage, for example to find out which Gems they aren't actually using in production. See some of the discussion on [issue 21](https://github.com/danmayer/coverband/issues/21).
 
-* Using the Tracepoint Collector
-   * just make sure to set `Coverband.configuration.include_gems = true` in your config options
-   * note by tracking all the additional usage this can have significant performance impacts of the Tracepoint implementation
-* Using the Coverage Collector
-   * use the `safe_reload_files` feature to add the path of all gem files you wish to track
-   * --- or ---
-   * ensure you call `Coverband.start` before loading all your gems
-      * while possible this is currently hard as Rails and most environments load your whole Gemfile
-      * looking for an improve and easier way to support this.  
+How to collect gem usage with Coverband:
+
+* use the `safe_reload_files` feature to add the path of all gem files you wish to track
+* --- or ---
+* ensure you call `require 'coverband'` which triggers `Coverband.start` before loading all your gems
+   * while possible this is currently hard as Rails and most environments load your whole Gemfile
+   * we are looking for an improve and easier way to support this.
 
 
 ### Verbose Debug / Development Mode
 
-Note: To debug issues getting coverband working. I recommend running in development mode, by turning verbose logging on `config.verbose = true` and passing in the Rails.logger `config.logger = Rails.logger` to the Coverband config. This makes it easy to follow in development mode. Be careful to not leave these on in production as they will affect performance.
+Note: To debug issues getting Coverband working. I recommend running in development mode, by turning verbose logging on `config.verbose = true` and passing in the Rails.logger `config.logger = Rails.logger` to the Coverband config. This makes it easy to follow in development mode. Be careful to not leave these on in production as they will affect performance.
 
 ---
 
@@ -434,58 +288,6 @@ If you are trying to debug locally wondering what code is being run during a req
       ...
      [517, 1617], [516, 38577]]
 
-### Writing Coverband Results to S3
-
-If you add some additional Coverband configuration your coverage html report will be written directly to S3, update `config/coverband.rb` like below.
-
-```
-  # configure S3 integration
-  config.s3_bucket = 'coverband-demo'
-  config.s3_region = 'us-east-1'
-  config.s3_access_key_id = ENV['AWS_ACCESS_KEY_ID']
-  config.s3_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
-```
-
-### Viewing / Hosting S3 Coverband results in app
-
-Beyond writing to S3 you can host the S3 file with a build in Sintatra app in Coverband. Just configure your Rails route `config/routes.rb`
-
-```
-Rails.application.routes.draw do
-  # ... lots of routes
-  mount Coverband::Reporters::Web.new, at: '/coverage'
-end
-```
-
-__NOTE__: ADD PASSWORD PROTECTION OR YOU CAN EXPOSE ALL YOUR SOURCE CODE
-
-It is easy to add some basic protect around the coverage data, below shows how you can use devise or basic auth, by adding a bit of code to your `config/routes.rb` file.
-
-```
-# protect with existing Rails devise configuration
-devise_constraint = lambda do |request|
-  request.env['warden'] && request.env['warden'].authenticate? && request.env['warden'].user.admin?
-end
-
-# protect with http basic auth
-# curl --user foo:bar http://localhost:3000/coverage
-basic_constraint = lambda do |request|
-  return true if Rails.env.development?
-  if ActionController::HttpAuthentication::Basic.has_basic_credentials?(request)
-    credentials = ActionController::HttpAuthentication::Basic.decode_credentials(request)
-    email, password = credentials.split(':')
-
-    email == 'foo' && password = 'bar'
-  end
-end
-
-Rails.application.routes.draw do
-  # ... lots of routes
-  constraints basic_constraint do
-    mount Coverband::Reporters::Web.new, at: '/coverage'
-  end
-end
-```
 
 ### Conflicting .Simplecov: Issue with Missing or 0% Coverage Report
 
@@ -511,6 +313,11 @@ You could see some confusing results... To avoid this issue Coverband has a Rake
 
 This will build the report after disabling any `.simplecov` applied settings.
 
+# Prerequisites
+
+* Coverband 3.0.X+ requires Ruby 2.3+
+* Coverband currently requires Redis for production usage
+
 # Contributing To Coverband
 
 If you are working on adding features, PRs, or bugfixes to Coverband this section should help get you going.
@@ -526,7 +333,9 @@ If you are working on adding features, PRs, or bugfixes to Coverband this sectio
 
 If you submit a change please make sure the tests and benchmarks are passing.
 
-* run tests: `rake`
+* run tests: 
+   * `bundle exec rake` 
+   * `BUNDLE_GEMFILE=Gemfile.rails4 bundle exec rake` (Same tests using rails 4 instead of 5)
 * view test coverage: `open coverage/index.html`
 * run the benchmarks before and after your change to see impact
    * `rake benchmarks` 
@@ -534,7 +343,7 @@ If you submit a change please make sure the tests and benchmarks are passing.
 ### Known Issues
 
 * __total fail__ on front end code, because of the precompiled template step basically coverage doesn't work well for `erb`, `slim`, and the like.
-  * related it will try to report something, but the line numbers reported for `ERB` files are often off and aren't considered useful. I recommend filtering out .erb using the `config.ignore` option. 
+  * related it will try to report something, but the line numbers reported for `ERB` files are often off and aren't considered useful. I recommend filtering out .erb using the `config.ignore` option. The default configuration excludes these files
 * If you have SimpleCov filters, you need to clear them prior to generating your coverage report. As the filters will be applied to Coverband as well and can often filter out everything we are recording.
 * coverage doesn't show for Rails `config/application.rb` or `config/boot.rb` as they get loaded when loading the Rake environment prior to starting the `Coverage` library.