coverband 0.0.19 → 0.0.20

data/README.md

@@ -4,12 +4,14 @@ A gem to measure production code coverage. Coverband allows easy configuration t
 
 * Allow sampling to avoid the performance overhead on every request.
 * Ignore directories to avoid overhead data collection on vendor, lib, etc.
-* Take a baseline to get inital app loading coverage.
+* Take a baseline to get initial app loading coverage.
 
 At the moment, Coverband relies on Ruby's `set_trace_func` hook. I attempted to use the standard lib's `Coverage` support but it proved buggy when sampling or stoping and starting collection. When [Coverage is patched](https://www.ruby-forum.com/topic/1811306) in future Ruby versions it would likely be better. Using `set_trace_func` has some limitations where it doesn't collect covered lines, but I have been impressed with the coverage it shows for both Sinatra and Rails applications.
 
 ###### Success:
-After running in production for 30 minutes, we were able very easily delete 2000 LOC after looking through the data. We expect to be able to clean up much more after it has collected more data.
+After running in production for 30 minutes, we were able very easily delete 2000 LOC after looking through the data. We expect to be able to clean up much more after it has collected more data. 
+
+This has now been running in production on many applications for months. I will clean up configurations, documentation, and strive to get a 1.0 release out soon.
 
 ## Installation
 
@@ -33,7 +35,7 @@ $ gem install coverband
 
 ## 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 formater. 
+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)
@@ -52,59 +54,49 @@ Details on a example Sinatra app
 
 ## Usage
 
-After installing the gem. There are a few steps to gather data, view reports, and cleaing up the data.
+After installing the gem. There are a few steps to gather data, view reports, and for cleaning up the data.
 
-1. First configure Rake, with helpful tasks. See the section below
-	* `rake coverband_baseline` helps you to record a baseline of your apps initialization process
-	*  `rake coverband` after you have setup coverband on a server and started recording data this generates the report and opens it in your browser.
-2. Setup the rack middleware, the middleware is what makes coverband gather metrics when your app runs. See below for details
-	* I setup coverband in my rackup `config.ru` you can also set it up in rails middleware, but it may miss recording some code coverage early in the rails process. It does improve performance to have it later in the middleware stack. So there is a tradeoff there.
-	* To debug in development mode, I recommend 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 effect performance.
-3. Start your server with `rackup config.ru` If you use `rails s` make sure it is using your `config.ru` or coverband won't be recording any data. 
-4. Hit your development server exercising the endpoints you want to verify Coverband is recording.
-5. Now to view changes in live coverage run `rake coverband` again, previously it should have only shown the baseline data of your app initializing. After using it in development it hsould show increased coverage from the actions you have exercised.
+1. First configure cover band options using the config file, See the section below
+2. Then configure Rake, with helpful tasks. Make sure things are working by recording your Coverband baseline. See the section below
+3. Setup the rack middleware, the middleware is what makes Coverband gather metrics when your app runs. See below for details
+	* I setup Coverband in my rackup `config.ru` you can also set it up in rails middleware, but it may miss recording some code coverage early in the rails process. It does improve performance to have it later in the middleware stack. So there is a tradeoff there.
+	* To debug in development mode, I recommend 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 effect performance.
+4. Start your server with `rackup config.ru` If you use `rails s` make sure it is using your `config.ru` or Coverband won't be recording any data. 
+5. Hit your development server exercising the endpoints you want to verify Coverband is recording.
+6. Now to view changes in live coverage run `rake coverband:coverage` again, previously it should have only shown the baseline data of your app initializing. After using it in development it should show increased coverage from the actions you have exercised.
 
-#### Configuring Rake
+#### Configure Coverband Options
 
-Either add the below to your `Rakefile` or to a file included in your Rakefile
+You need to configure cover band you can either do that passing in all configuration options to `Coverband.configure` in block format, or a much 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 Sinatra app:
 
 ```ruby
-require 'coverband'
+require 'json'
+
+baseline = if File.exist?('./tmp/coverband_baseline.json')
+  JSON.parse(File.read('./tmp/coverband_baseline.json'))
+else
+  {}
+end
+
 Coverband.configure do |config|
-  config.redis             = Redis.new
-  # merge in lines to consider covered manually to override any misses
-  # existing_coverage = {'./cover_band_server/app.rb' => Array.new(31,1)}
-  # JSON.parse(File.read('./tmp/coverband_baseline.json')).merge(existing_coverage) 
-  config.coverage_baseline = JSON.parse(File.read('./tmp/coverband_baseline.json'))
+  config.root              = Dir.pwd
+  if defined? Redis
+    config.redis             = Redis.new(:host => 'redis.host.com', :port => 49182, :db => 1)
+  end
+  config.coverage_baseline = baseline
   config.root_paths        = ['/app/']
   config.ignore            = ['vendor']
-end
-
-desc "report unused lines"
-  task :coverband => :environment do
-  Coverband::Reporter
-end
-	
-desc "get coverage baseline"
-task :coverband_baseline do
-  Coverband::Reporter.baseline {
-    #rails
-    require File.expand_path("../config/environment", __FILE__)
-    #sinatra
-    #require File.expand_path("./app", __FILE__)
-  }
+  config.percentage        = 60.0
+  if defined? Statsd
+    config.stats             = Statsd.new('statsd.host.com', 8125)
+  end
+  config.verbose           = true
 end
 ```
-    
-#### Configure rack middleware
 
-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.
+Here is a alternative configuration example:
 
 ```ruby
-require File.dirname(__FILE__) + '/config/environment'
-	
-require 'coverband'
-
 Coverband.configure do |config|
   config.root              = Dir.pwd
   config.redis             = Redis.new
@@ -117,6 +109,51 @@ Coverband.configure do |config|
   config.startup_delay     = 10
   config.percentage        = 15.0
 end
+```
+
+#### Configuring Rake
+
+Either add the below to your `Rakefile` or to a file included in your Rakefile such as `lib/tasks/coverband` if you want to break it up that way.
+
+```ruby
+require 'coverband'
+Coverband.configure
+require 'coverband/tasks'
+```
+This should give you access to a number of cover band tasks
+
+```bash
+bundle exec rake -T coverband
+rake coverband:baseline      # record coverband coverage baseline
+rake coverband:clear         # reset coverband coverage data
+rake coverband:coverage      # report runtime coverband code coverage
+```
+
+The default Coverband baseline task will try to load the Rails environment. For a non Rails application you can make your own baseline. Below for example is how I take a baseline on a Sinatra app.
+
+```ruby
+namespace :coverband do
+  desc "get coverage baseline"
+  task :baseline_app do
+    Coverband::Reporter.baseline {
+      require 'sinatra'
+      require './app.rb'
+    }
+  end
+end
+```
+
+To verify that rake is working run `rake coverband:baseline` and then run `rake coverband:coverage` to view what your baseline coverage looks like before any runtime traffic has been recorded.
+    
+#### Configure rack middleware
+
+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.
+
+```ruby
+require File.dirname(__FILE__) + '/config/environment'
+	
+require 'coverband'
+Coverband.configure
 
 use Coverband::Middleware
 run ActionController::Dispatcher.new
@@ -124,9 +161,9 @@ run ActionController::Dispatcher.new
 	
 #### Configure Manually (for example for background jobs)
 
-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.
+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.
 
-For example if you had a base resque class, you could use the `before_perform` and `after_perform` hooks to add Coverband
+For example if you had a base Resque class, you could use the `before_perform` and `after_perform` hooks to add Coverband
 
 ```ruby
 def before_perform(*args)
@@ -147,7 +184,7 @@ def after_perform(*args)
 end
 ```
 
-In general you can run coverband anywhere by using the lines below
+In general you can run Coverband anywhere by using the lines below
 
 ```ruby
 require 'coverband'
@@ -173,11 +210,11 @@ coverband.sample {
 ## Clearing Line Coverage Data
 
 After a deploy where code has changed. 
-The line numbers previously recorded in redis may no longer match the curernt state of the files. 
+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 inconsistancy for some files.
+you can live with minor inconsistency for some files.
 
-As often as you like or as part of a deploy hook you can clear the recorded coverband data with the following command.
+As often as you like or as part of a deploy hook you can clear the recorded Coverband data with the following command.
 
 ```ruby
 # defaults to the currently configured Coverband.configuration.redis
@@ -185,19 +222,21 @@ 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.
+
 
 ## TODO
 
-* Improve the configuration flow (only one time redis setup etc)
-  * a suggestion was a .coverband file which stores the config block (can't use initializers because we try to load before rails)
-  * this is a bit crazy at the moment
+* Improve the baseline task, hard coded for rails, for Sinatra you need to override.
+  * perhaps allow in the config to pass in baseline_requires array? If not present do the rails thing?
 * Fix performance by logging to files that purge later
 * Add support for [zadd](http://redis.io/topics/data-types-intro) so one could determine single hits versus multiple hits on a line, letting us determine the most executed code in production.
 * Add stats optional support on the number of total requests recorded
 * Possibly add ability to record code run for a given route
-* Add default rake tasks so a project could just require the rake tasks
-* Improve client code api, particularly around configuration, but also around manual usage of sampling
-* Provide a better lighter example app, to show how to use coverband.
+* Improve client code api, around manual usage of sampling (like event usage)
+* Provide a better lighter example app, to show how to use Coverband.
+  * blank rails app
+  * blank Sinatra app 
 
 ## Resources
 

data/lib/coverband/reporter.rb

@@ -34,6 +34,7 @@ module Coverband
     def self.clear_coverage(redis = nil)
       redis ||= Coverband.configuration.redis
       redis.smembers('coverband').each{|key| redis.del("coverband.#{key}")}
+      redis.del("coverband")
     end
 
     def self.current_root

data/lib/coverband/tasks.rb

@@ -3,7 +3,7 @@ namespace :coverband do
   desc "record coverband coverage baseline"
   task :baseline do
     Coverband::Reporter.baseline {
-      require File.expand_path("../config/environment", __FILE__)
+      require File.expand_path("../config/environment", Dir.pwd)
     }
   end
 

data/lib/coverband/version.rb

@@ -1,3 +1,3 @@
 module Coverband
-  VERSION = "0.0.19"
+  VERSION = "0.0.20"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coverband
 version: !ruby/object:Gem::Version
-  version: 0.0.19
+  version: 0.0.20
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-16 00:00:00.000000000 Z
+date: 2014-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -184,7 +184,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4134366731001694755
+      hash: 834847330280210116
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -193,7 +193,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4134366731001694755
+      hash: 834847330280210116
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23