Command Line Reference
Cobertura can be used either from the command line or via ant tasks. You can even mix and match the command line and ant tasks. This document describes how to use Cobertura from the command line.
Instrumenting
cobertura-instrument.bat [--basedir dir] [--datafile file] [--destination dir] [--ignore regex] classes [...]
Note: Classes may be specified individually, or as a directory tree containing multiple classes.
| Parameter | Required? | Description | Default Value |
|---|---|---|---|
| --basedir | No | Specify the base directory containing the classes you want to instrument. This command line parameter should appear before any classes. If you are instrumenting classes in different directories, you should specify multiple basedirs. | No default value. |
| --datafile | No | Specify the name of the file to use for storing the metadata about your classes. This is a single file containing serialized Java classes. It contains information about the names of classes in your project, their method names, line numbers, etc. It will be updated as your tests are run, and will be referenced by the Cobertura reporting command. | "cobertura.ser" in the current directory |
| --destination | No | Specify the output directory for the instrumented classes. | If no destination directory is specified, then the uninstrumented classes will be overwritten with their instrumented counterparts. |
| --ignore | No | Specify a regular expression to filter out certain lines of your source code. This is useful for ignoring logging statements, for example. You can have as many <ignore/> statements as you want. | No files are ignored. |
Example:
cobertura-instrument.bat --destination C:\MyProject\build\instrumented C:\MyProject\build\classes
Running Tests
You can basically run your tests the same way you always do. The only changes you need to make are to your classpath:
- Include cobertura.jar
- Add the directory containing the instrumented classes BEFORE the directory containing the uninstrumented classes. The order is very important.
Your tests do not have to be JUnit tests. They don't even have to be automated. If your application is a program with a GUI, you could fire it up, perform a few actions, then exit. Cobertura updates its data file whenever your instrumented classes are accessed.
Example:
java -cp C:\cobertura\lib\cobertura.jar;C:\MyProject\build\instrumented;C:\MyProject\build\classes;C:\MyProject\build\test-classes -Dnet.sourceforge.cobertura.datafile=C:\MyProject\build\cobertura.ser ASimpleTestCase
Reporting
cobertura-report.bat [--datafile file] [--destination dir] [--format (html|xml)] source code directory [...] [--basedir dir file underneath basedir ...]
| Parameter | Required? | Description | Default Value |
|---|---|---|---|
| --basedir | No | Specify a directory containing source code. All files listed after this are assumed to be underneath this directory. This should only be used if you want to include only a few specific files underneath a source tree and exclude all other files. | No default value. |
| --datafile | No | Specify the name of the file containing metadata about your classes. | "cobertura.ser" in the current directory |
| --destination | Yes | Specify the output directory for the report. | No default value. |
| --format | No | The type of report you want to generate. | html |
The source code directories are used to calculate the cyclomatic code complexity of each class. The HTML reports are also made of annotated versions of each source file, showing which lines of code were excercised.
Example:
cobertura-report.bat --format html --datafile C:\MyProject\build\cobertura.ser --destination C:\MyProject\reports\coverage C:\MyProject\src
Checking Coverage
cobertura-check.bat [--datafile file] [--branch 0..100] [--line 0..100] [--totalbranch 0..100] [--totalline 0..100] [--regex regex:branchrate:linerate]
This can be run after your JUnit tests to show which classes do not have adequate test coverage. Note: If no parameters are specified then all values will be set to 50%
| Parameter | Required? | Description | Default Value |
|---|---|---|---|
| --branch | No | Specify the minimum acceptable branch coverage rate needed by each class. This should be an integer value between 0 and 100. | 0 |
| --datafile | No | Specify the name of the file containing metadata about your classes. | "cobertura.ser" in the current directory |
| --line | No | Specify the minimum acceptable line coverage rate needed by each class. This should be an integer value between 0 and 100. | 0 |
| --regex | No | For finer grained control, you can optionally specify minimum branch and line coverage rates for individual classes using any number of regular expressions. | None. |
| --packagebranch | No | Specify the minimum acceptable average branch coverage rate needed by each package. This should be an integer value between 0 and 100. | 0 |
| --packageline | No | Specify the minimum acceptable average line coverage rate needed by each package. This should be an integer value between 0 and 100. | 0 |
| --totalbranch | No | Specify the minimum acceptable average branch coverage rate needed by the project as a whole. This should be an integer value between 0 and 100. | 0 |
| --totalline | No | Specify the minimum acceptable average line coverage rate needed by the project as a whole. This should be an integer value between 0 and 100. | 0 |
Example:
cobertura-check.bat --datafile C:\MyProject\build\cobertura.ser --branch 50 --totalline 70 --regex com.example.rabidsquirrel.*:65:65
The above example specifies that each class must have a branch coverage rate of 50 or higher, the average line coverage rate for the entire project must be 70 or higher, and any classes in the package com.example.rabidsquirrel must have a line coverage and a branch coverage of 65 or greater.
Merging Datafiles
cobertura-merge.bat [--datafile file] datafile [...]
This can be run after your JUnit tests to merge multiple data files into a single data file.
| Parameter | Required? | Description | Default Value |
|---|---|---|---|
| --datafile | No | Specify the name of the file containing metadata about your classes. This is the "destination" file into which the contents of the other data files will be merged. | "cobertura.ser" in the current directory |
Example:
cobertura-merge.bat --datafile C:\MyProject\build\cobertura.ser C:\MyProject\testrundir\server\cobertura.ser C:\MyProject\testrundir\client\cobertura.ser
The above example merges a 'cobertura.ser' file from a server process and from a client process into one combined file in the build directory. You can then use cobertura-report to create a report based on this new data file.