merged cont.
[opensuse:yast-rest-service.git] / webyast / vendor / plugins / rails_rcov / README
1  = rails_rcov plugin for Rails
2
3 rails_rcov provides easy-to-use Rake tasks to determine the code coverage of
4 your unit, functional, and integration tests using Mauricio Fernandez's rcov
5 tool.
6
7 == Installation
8
9 First, install rcov from Mauricio's web site
10 [http://eigenclass.org/hiki.rb?rcov]. Make sure it's on your system path, so
11 that typing +rcov+ on the command line actually runs it. THIS PLUGIN DOESN'T DO
12 ANYTHING BESIDES GENERATE ERRORS UNLESS YOU INSTALL RCOV FIRST. RCOV CONTAINS
13 ALL THE MAGIC, THIS PLUGIN JUST RUNS IT.
14
15 Second, install this plugin. If your project is source-controlled by Subversion
16 (which it should be, really), the easiest way to install this is via Rails'
17 plugin script:
18
19   ./script/plugin install -x http://svn.codahale.com/rails_rcov
20
21 If you're not using Subversion, or if you don't want it adding
22 <tt>svn:externals</tt> in your project, remove the <tt>-x</tt> switch:
23
24   ./script/plugin install http://svn.codahale.com/rails_rcov
25
26 == Usage
27
28 For each <tt>test:blah</tt> task you have for your Rails project, rails_rcov
29 adds two more: <tt>test:blah:rcov</tt> and <tt>test:blah:clobber_rcov</tt>.
30
31 Running <tt>rake test:units:rcov</tt>, for example, will run your unit tests
32 through rcov and write the code coverage reports to
33 <tt>your_rails_app/coverage/units</tt>.
34
35 Running <tt>test:units:clobber_rcov</tt> will erase the generated report for the
36 unit tests.
37
38 Each rcov task takes two optional parameters: RCOV_PARAMS, whose argument is
39 passed along to rcov, and SHOW_ONLY, which limits the files displayed in the
40 report.
41
42 RCOV_PARAMS:
43   # sort by coverage
44   rake test:units:rcov RCOV_PARAMS="--sort=coverage"
45
46   # show callsites and hide fully covered files
47   rake test:units:rcov RCOV_PARAMS="--callsites --only-uncovered"
48
49 Check the rcov documentation for more details.
50
51 SHOW_ONLY is a comma-separated list of the files you'd like to see. Right now
52 there are four types of files rake_rcov recognizes: models, helpers,
53 controllers, and lib. These can be abbreviated to their first letters:
54
55   # only show files from app/models
56   rake test:units:rcov SHOW_ONLY=models
57   
58   # only show files from app/helpers and app/controllers
59   rake test:units:rcov SHOW_ONLY=helpers,controllers
60   
61   # only show files from app/helpers and app/controllers, with less typing
62   rake test:units:rcov SHOW_ONLY=h,c
63
64 Please note that rails_rcov has only been tested with a Bash shell, and any
65 other environment could well explode in your face. If you're having trouble
66 getting this to work on Windows, please take the time to figure out what's not
67 working. Most of the time it boils down to the different ways the Window shell
68 and the Bash shell escape metacharacters. Play around with the way rcov_rake
69 escapes data (like on line 73, or 78) and send me a fix. I don't have a working
70 Windows environment anymore, so leaving it up to me won't solve anything. ;-)
71
72 == Resources
73
74 === Subversion
75
76 * http://svn.codahale.com/rails_rcov
77
78 === Blog
79
80 * http://blog.codahale.com
81
82 == Credits
83
84 Written by Coda Hale <coda.hale@gmail.com>. Thanks to Nils Franzen for a Win32
85 escaping patch. Thanks to Alex Wayne for suggesting how to make SHOW_ONLY not be
86 useless.