Command Line Reference

Steven Christou edited this page Jul 26, 2013 · 2 revisions

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] [--auxClasspath classPath] [--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 statements as you want. No files are ignored.
--auxClasspath No Add any classes/jars that cobertura is unable to find during instrumentation. No default value.

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)] [--encoding encoding] 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
--encoding No Specify the encoding used to read the source. See javadocs for java.nio.charset.Charset for more details. Since 1.9.1. The default encoding.

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 exercised.

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.