coco
Code coverage tool for ruby 1.9.3, 2.0 and 2.1.
Features
- Use it from rspec or test/unit with a simple
require 'coco'
- Works with Rails
- Display names of uncovered files on console
- Simple html report only for uncovered files
- Report sources that have no tests
- UTF-8 compliant
- Configurable via a simple yaml file
- Colorized console output (nix only)
Install
In your Gemfile:
gem coco
Or directly:
gem install coco
Usage
Require the coco library at the beginning of your tests:
require 'coco'
Usually you do this only once, by putting this line in an spec_helper.rb, or test_helper.rb (or whatever you named it).
View report
After your tests, coco will display a short report in the console window, like this one:
$ rake test
[...]
26 examples, 0 failures
0% /home/xavier/project/lib/iprune.rb
0% /home/xavier/project/lib/iprune/iprune.rb
46% /home/xavier/project/lib/parser/prunille.rb
$
If there is some files reported in the console, coco will create a coverage/
folder at the root of the project. Browse the coverage/index.html
to access
a line by line report.
Be careful! Any coverage
folder at the root of your project will be
deleted without warning!
Note: files with a coverage of 0% are only listed in index.html ; there is no line by line report for such files.
Configuration
Configuration is done via a YAML file. You can configure:
- threshold: the percentage threshold
- directories: the directories from where coco will search for untested source files
- excludes: a list of files to exclude from the report
- single_line_report: the report's style
By default, threshold is set to 100 and directories is set to 'lib'.
To change the default coco configuration, put a .coco.yml
file at the root of your project.
Sample config for a Rails project
:directories:
- app
- lib
:excludes:
- spec
- config/initializers
:single_line_report: true
Note: YAML is very punctilious with the syntax. In particular, paid attention to not put any leading spaces or tab at all.
See more examples on the wiki.
Advanced configuration
See coverage of all files in the console
By default, Coco will display only the files with a coverage above the threshold. And as the threshold is 100% by default, nothing will be displayed if your test suite is 100% covered. This could be annoying for some people, or worst, you could even feel like Coco doing something the wrong way.
So, to display in green the covered files,
put this in your .coco.yml
configuration file:
:exclude_above_threshold: false
When to start coco, and when not to start it
For projects whose complete test suite runs in a matter of seconds, running code coverage with every test is fine. But when the test suite takes longer to complete, we typically start to run a single test more often than the complete suite. In such cases, the behavior of coco could be really annoying: you run a single test and coco reports a infinite list of uncovered files. The problem here is this is a lie. To avoid this behavior, I recommend to run code coverage only from time to time, and with the entire test suite. To do so, coco provide the following configuration key:
always_run: If true, coco will run every time you start a test.
If false, coco will run only when you explicitly set an
environement variable named COCO
with something other than false
,
0
or the empty string.
Example
Put this in your .coco.yml
configuration file:
:always_run: false
Now, when you run:
rspec spec/
coco will no start. To start it, you have to set the
environement variable COCO
, like this:
COCO=1 rspec spec/
Index page URI in your terminal
If your terminal supports opening an URI with a double-clic (or any other method), you may want to display the URI of the report's index page. For that, you have to set the show_link_in_terminal key.
Example
Put this in your .coco.yml
configuration file:
:show_link_in_terminal: true
Now, when running tests, you will see something like the following:
$ rspec spec
.............
[...]
97% /path/to/bad/tested/file.rb
See file:///path/to/your/coverage/index.html
Dependencies
ruby >= 1.9.3
Contributing
- Fork it.
- Create your feature branch from the development branch:
git checkout development
git pull origin development
git checkout -b my-new-feature
- Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a Pull Request.
License
GPLv3, see COPYING.
Questions and/or Comments
Feel free to email Xavier Nayrac with any questions, or contact me on twitter.