coco

— «If it's well-covered it doesn't mean it's well-tested!» —

Code coverage tool for ruby 2.x

Install

In your Gemfile:

gem 'coco'

Or directly:

gem install coco

NOTE: If you're using a Gemfile, don't :require => false

And in case you want to test the latest development:

gem 'coco', github: 'lkdjiin/coco', branch: 'development'

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 very short report in the console window, like this one:

$ rake test
[...]
26 examples, 0 failures

Rate 82% | Uncovered 0 | Files 7
$

coco will also create a coverage/ folder at the root of the project. Browse the coverage/index.html to access a line by line report.

Note: files with a coverage of 0% are only listed in index.html ; there is no line by line report for such files.

Basic Configuration

Configuration is done via a YAML file. You can configure:

• theme: Choose between a light and a dark theme for the HTML report
• threshold: the percentage threshold
• include: the directories from where coco will search for untested source files
• exclude: a list of files and/or directories to exclude from the report, if any
• single_line_report: style of the report in the console

By default, threshold is set to 100, the list of directories is set to ['lib'], no files are excluded and the console report is a single line one.

To change this default configuration, put a .coco.yml file at the root of your project.

Theme

You can choose between a light and a dark theme. The light theme is the default one. For a dark theme, add this line in the configuration file:

:theme: dark

Light theme

Dark theme

Threshold

Add the following line to your .coco.yml file to set the threshold to 80%.

:threshold: 80

Only files under 80% of coverage will be directly reported in the report. I strongly advice to use the default threshold (100%).

Directories Included

Add the following lines to your .coco.yml file to set the directories to both 'lib' and “ext':

:include: 
- lib
- ext

Files and Directories Excludes

Add the following lines to your .coco.yml file to exclude a file from the report:

:exclude:
- lib/project/file1.rb

Add the following lines to your .coco.yml file to exclude a whole folder's content from the report:

:exclude:
- config/initializers

Of course you can mix files and folders:

:exclude:
- path/to/file1
- path/to/file2
- folder1
- path/to/folder2

Single line report

By default, the console's reports a brief, one line, summary. If instead, you want to display the coverage of all files under the threeshold, put this line in your .coco.yml file:

:single_line_report: false

Advice: Don't do this!

Sample config for a Rails project

:include: 
- app
- custom_dir
- lib
:exclude:
- config/initializers

Note: YAML is very punctilious with the syntax. In particular, paid attention to not put any leading spaces or tab at all.

## Advanced configuration

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

…Coco will no start. To start it, you have to set the environement variable COCO, like this:

COCO=1 rspec

Premature exit if coverage is under a particular threshold

If you're using some kind of continuous integration, there is some chance you would like the build to fail if the coverage is under a particular threshold. In such case you want to set the exit_if_coverage_below option.

Example

Put this in your .coco.yml configuration file:

:exit_if_coverage_below: 95

This will make coco fail if the coverage percentage is below 95%.

Change the output directory

The HTML output goes into a folder named coverage. This is fine 99.9% of the time. For the remaining 0.1% this is customisable.

Example

Put this in your .coco.yml configuration file:

:output_directory: 'code_coverage'

Or even outside of the current folder if you need to :

:output_directory: '../outside/coverage'

See coverage of all files in the console

By default, with a multilines report style on the console, 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

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

How is this different than SimpleCov ?

I designed Coco from the start to have only the features I need. And I don't need much: 95% of the time, all I want is a tiny one line summary in my console.

It's easier. Add a single line of code at the start of your spec helper and you are good to go.

It's faster. Because Coco has no dependencies and less features, analyzing and reporting are so fast you don't even notice them.

To synthesize, if you have big needs, give SimpleCov a try ; if you have small needs, give Coco a try.

Contributing

1. Fork it.
2. Create your feature branch
   • git pull origin master
   • git checkout -b my-new-feature
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a Pull Request.

License

MIT, see LICENSE.

Questions and/or Comments

Feel free to email Xavier Nayrac with any questions, or contact me on twitter.