CodeCover

Command Line Interface

usage: codecover %command% [%options%]

CodeCover itself, without using a command, supports the two options:

Option	Explanation
`-h, --help`	shows all available commands or, if followed by a command, the help page of this command
`-V, --version`	shows version information.

Command Overview

Command	Description
`as, alter-session`	changes information of a test session
`at, alter-test-case`	changes information about a test case
`an, analyze`	inserts a coverage log into a test session container
`cs, copy-sessions`	copies test-sessions from one session container to another
`h, help`	a help page containing this command overview or an option and parameter overview for a given command.
`info`	shows information about a session container
`ii, instrumenter-info`	prints information about available instrumenters
`in, instrument`	instruments source files
`ms, merge-sessions`	merges test-sessions within the same session container
`mt, merge-test-cases`	merges test cases of the same session
`rs, remove-sessions`	removes test-sessions from a session container
`rt, remove-test-cases`	removes test cases from a session container
`re, report`	generates a report from a test-session
`touch-container`	reads and rewrites all given test session containers

General Options

For every command a set of general options is supported. In addition to specific command options, all commands support the following parameterless options. They are not required but change the behavior of the software when used.

Option	Explanation
`-v, --verbose`	Orders the software to print more information as usual. For example this can be a description of the actions being done. This option is the opposite of `--quiet`.
`-q, --quiet`	Orders the software not to print information to the shell. This option is the opposite to `--verbose`.
`-p, --pretend`	Orders the software not to perform any actions affecting the data persistently but to print information about what the software would do instead. Using `--pretend` the actor can make sure that his command has the correct syntax and would be successfully executed.
`-h, --help`	Prints an option and parameter overview of the given command. Has the same effect like `codecover help \%command\%`.
`--add-plugin-dir`	Uses all plugins in this directory.
`--no-default-plugin-dir`	Does not use the plugins from the default plugin directory.
`--progress-bar`	prints a progress bar
`--no-progress-bar`	prints no progress bar
`--show-stack-trace`	shows stack trace on errors

Instrumenter-Info

This command is used to get information of all available instrumenters. If there are two or more instrumenters available for a given programming language, you can get to know the unique keys of the possible instrumenters. These key can than be used for the option instrumenter of the instrument command.

Usage

codecover (instrumenter-info|ii) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-l, --language <lang>`	(`java` \| `cobol`)

Examples

codecover instrumenter-info -l java -v

Print out verbose information of all instrumenters, that support the programming language java.

Instrument

This command is used to instrument source code files so that the coverage will be measured when these files will be executed.

Usage

codecover (instrument|in) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the new session container	X
`-d, --destination <dir>`	the destination directory for the instrumented files	X
`-r, --root-directory <dir>`	the root directory of the source files	X
`-l, --language <lang>`	(`java` \| `cobol`)	X
`-a, --charset <charset>`	the character encoding of the source files
`-u, --copy-uninstrumented`	advices the software to copy all files of the root-directory, that where not instrumented, to the destination
`-o, --criterion <crit>`	one of (`all`, `st`, `br`, `co`, `lo`); this argument can occur more than one time -- once for every criterion
`-D, --directive`	arguments of the style `key=value` to enable special features of the instrumenter; the instrumenter-info command prints out a list of directives, an instrumenter supports.
`-e, --exclude <pattern>`	a relative exclude pattern; this argument can occur more than one time
`-x, --excludes-file <file>`	a file containing a list of relative exclude patterns separated by new line
`-i, --include <pattern>`	a relative include pattern; this argument can occur more than one time
`-f, --includes-file <file>`	a file containing a list of relative include patterns separated by new line
`-I, --instrumenter <key>`	the unique key of the instrumenter to use; use the command instrumenter-info to get the correct key

The arguments of option criteria stand for:

Criteria abbreviation	Explanation
`all`	all criteria
`st`	statement coverage
`br`	branch coverage
`co`	condition coverage
`lo`	loop coverage

Patterns

For a more detailed selection, include and exclude patterns can be used. These patterns allow wildcards and are adopted from the apache ant project (see their pattern description).

The wildcard ? matches one character. The wildcard * matches zero or more characters. Examples:

?.java matches x.java and A.java, but not .java or xyz.java (both don't have one character before .java).
*.java matches .java, x.java and FooBar.java, but not FooBar.xml (does not end with .java).

Combinations of *'s and ?'s are allowed.

To match a complete directory tree, or a file anywhere in the directory tree, use **. When ** is used as the name of a directory in the pattern, it matches zero or more directories. Example:

src/**/*.java matches all java files under src/, such as src/x.java, or src/foo/bar/MyObject.java, but not Main.java or test/AllTests.java (Do not lie under test}).

The instrumenter uses some ignore patterns for files, that are totally ignored:

**/*~, **/#*#, **/.#*, **/%*%", **/._*"
**/.svn/**, **/_svn/**, **/CVS/**, **/.cvsignore
**/SCCS/**, **/vssver.scc, **/.DS_Store, **/Thumbs.db

Examples

codecover instrument -r src/ 
                     -d bin/instr/ 
                     -c container.xml 
                     -l java

Find all java source files in the directory "src", parse and instrument these files into the directory "bin/instr/". The source files are instrumented for all criteria and the static information compiled during the instrumentation is stored in the "container.xml".

codecover instrument -r src/ 
                     -d bin/instr/ 
                     -i "org/pak1/**"
                     -e "**/*Test.java"
                     -c container.xml 
                     -l java
                     -I CodeCover_Java_1.5
                     -o st lo
                     -a UTF-8
                     -u

Find all java source files under the directory "org/pak1", exclude files ending with "Test.java", parse these files with the "UTF-8" charset and instrument them into the directory "bin/instr/". The source files are instrumented for statement and loop coverage, and the static information compiled during the instrumentation is stored in the "container.xml". All files under "src", which are not instrumented, are copied to "bin/instr/". The code cover instrumenter for java is used. It is specified by its unique key CodeCover\_Java\_1.5.

Analyze

This command is used to import a coverage-log, that was produced by an instrumented program, into a specified test-session container.

Usage

codecover (analyze|an) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the test-session container the coverage data should be added to	X
`-g, --coverage-log <file>`	the coverage log produced by the executed program	X
`-n, --name <name>`	the name of the new test-session containing the coverage results	X
`-m, --comment <text>`	a comment describing the test-session
`-a, --charset <charset>`	the character encoding of the coverage log file

Examples

codecover analyze -c container.xml
                  -g coverageLog.clf
                  -n "test-session 1"

Load the test-session container from "container.xml", as well as parse the generated coverage log "coverageLog.clf", and add the data contained in the coverage log to the test-session container under the name "test-session 1".

codecover analyze -c container.xml
                  -g coverageLog.clf
                  -n "test-session 2"
                  -m "Another test-session"

Load the test-session container from "container.xml", as well as parse the generated coverage log "coverageLog2.clf", and add the data contained in the coverage log to the test-session container under the name "test-session 2" and the comment "Another test-session".

Report

Creates a report of a test-session. A template which specifies the appearance and format is used to generate the report.

Usage

codecover (report|re) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the session container to use	X
`-s, --session <name>`	the name of the test-session for the report	X
`-t, --template <file>`	the template file containing transformation descriptions	X
`-d, --destination <file>`	the destination for the report	X

Examples

An example CodeCover report

Info

Shows information about a test-session container. The options allow to manipulate the output, as detailed in Examples.

Usage

codecover info [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the test-session container	X
`-s, --session <name>`	the name of a test-session
`-T, --test-cases`	showing test case information

Examples

General Example

The following shows the different information levels CodeCover provides. Calling the info command with only the test-session container, results in a list of all the test-session contained in this test-session container, with their name, and the date, they were created on. By naming test-sessions present in the test-session container, you can tailor the output to your specific needs.

root@deepthought:~> codecover info -c container.xml
---------------------------------------------------------------------
test-session container: container.xml

test-sessions:
name         | date                                        
---------------------------------------------------------------------
TestSession0 | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007)
TestSession1 | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007)
TestSession2 | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007)
---------------------------------------------------------------------

Example with `verbose`

Adding "verbose" as an option to the above call, additionally displays the comment of the test-sessions in the test-session container.

root@deepthought:~> codecover info --test-cases 
                                   -c container.xml 
                                   -s TestSession0
---------------------------------------------------------------------
test-session container: container.xml
=====================================================================
test-session name:    TestSession0
test-session date:    2007-05-18 17:47:32 +0200 (Fri, 18 May 2007)
test-session comment: 42

test cases:
name        | date                                        
---------------------------------------------------------------------
TestCase0   | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007)
TestCase99  | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007)
TestCase198 | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007)
TestCase297 | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007)
---------------------------------------------------------------------

Example with `test-cases` and `verbose`

As before, calling the info command with "test-cases" option, as well as the "verbose" option, adds the comments to the list of test cases in the given test-session

root@deepthought:~> codecover info --verbose 
                                   --test-cases 
                                   -c container.xml 
                                   -s TestSession0
---------------------------------------------------------------------
test-session container: container.xml
=====================================================================
test-session name:    TestSession0
test-session date:    2007-05-18 17:47:32 +0200 (Fri, 18 May 2007)
test-session comment: 42

test cases:
name        | date                                         | comment
---------------------------------------------------------------------
TestCase0   | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007) | 42
TestCase99  | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007) | 42
TestCase198 | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007) | 42
TestCase297 | 2007-05-18 17:47:32 +0200 (Fri, 18 May 2007) | 42
---------------------------------------------------------------------

Merge Sessions

This command is used to merge one or more test-sessions of a session container into a new test-session.

Usage

codecover (merge-sessions|ms) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the session container to use	X
`-s, --session <name>`	a name of a test-session participating in the merging; this argument can occur more than one time -- once for every participant	X
`-n, --name <name>`	the name of the merged test-session	X
`-m, --comment <text>`	a comment describing the merged test-session
`-R, --remove-old-test-sessions`	indicates, whether or not the test-sessions, that were merged, are removed after merging

Examples

codecover merge-sessions -c container.xml 
                         -n "Merged test-session" 
                         -s "test-session 1" "test-session 2"

Loads the test-session container from the file "container.xml" and merges the two test-sessions "test-session 1" and "test-session 2" into the new "Merged test-session". By default the merged test-sessions - "test-session 1" and "test-session 2" - are not deleted.

codecover merge-sessions --remove-old-test-sessions 
                         -c container.xml 
                         -s "test-session 1" "test-session 2"
                         -n "Merged test-session"

Adding the "remove-old-test-sessions" to the command performs the operation described above, but deletes the merged test-sessions - "test-session 1" and "test-session 2" - from the test-session container.

Alter Session

This command is used to modify the name and/or the comment of a test-session.

Usage

codecover (alter-session|as) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the session container to use	X
`-s, --session <name>`	the old name of the test-session	X
`-n, --name <name>`	a new name of the test-session
`-m, --comment <text>`	a new comment describing the test-session

Examples

codecover alter-session -c container.xml 
                        -s "Session 1"
                        -n "New Name" 
                        -m "New Comment"

Load the test-session container from "container.xml", rename the test-session with the name "Session 1" to "New Name" and change the comment of it to "New Comment". The option for the comment is not required, so a test-session can be renamed without changing its comment.

Copy Sessions

This command is used to copy one or more test-sessions from one session container to another.

If the destination test-session container does not exists, the source test-session container is copied to the location of the destination test-session container, while containing only the specified test-sessions.

If the destination test-session container already contains a test-session, that is to be copied into it, from the source test-session container, the copied test-session is renamed along the lines of "Test Session" to "Test Session (1)". The test-session that was already present in the destination test-session container is not modified.

Usage

codecover (copy-sessions|cs) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the source session container	X
`-s, --session <name>`	a name of a test-session participating at the copy; this argument can occur more than one time -- once for every participant	X
`-d, --destination <file>`	the destination session container	X

Examples

codecover copy-sessions -c container.xml 
                        -s "Session 1" 
                        -s "Session 3" 
                        -d container2.xml

Load the test-session containers from "container.xml", copies the sessions named "Session 1" and "Session 3" to the test-session container from "container2.xml".

Remove Sessions

This command is used to remove one or more test-sessions from a session container.

Usage

codecover (remove-sessions|rs) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the session container to remove from	X
`-s, --session <name>`	the name of the test-session to be removed; this argument can occur more than one time -- once for every test-session	X

Examples

codecover remove-sessions -c container.xml 
                          -s "Session 1"

Load the test-session container from "container.xml", remove the test-session with the name "Session 1" of the container.

Merge Test Cases

This command is used to merge one or more test-cases of a test-session into a new test-case.

Usage

codecover (merge-test-cases|mt) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the session container to use	X
`-s, --session <name>`	the name of the test-session	X
`-t, --test-case <name>`	a name of a test case participating in the merging; this argument can occur more than one time -- once for every participant	X
`-n, --name <name>`	the name of the merged test case	X
`-R, --remove-old-test-cases`	indicates, whether or not the test cases, that were merged, are removed after merging
`-m, --comment <text>`	a comment describing the merged test case

Examples

codecover merge-test-cases -c container.xml 
                           -s "Session 1"
                           -t "test-case 1" "test-case 2" 
                           -n "Merged test-case"

Loads the test-session container from the file "container.xml" and merges the two test-cases "test-case 1" and "test-case 2" into the new test-case "Merged test-case". By default the merged test-cases - "test-case 1" and "test-case 2" - are not deleted.

codecover merge-test-cases --remove-old-test-cases 
                           -c container.xml 
                           -s "Session 1"
                           -t "test-case 1" "test-case 2" 
                           -n "Merged test-case"

Adding the "remove-old-test-cases" to the command performs the operation described above, but deletes the merged test-cases - "test-case 1" and "test-case 2" - from the test-session container.

Alter Test Case

This command is used to modify the name and/or the comment of a test-case.

Usage

codecover (alter-test-case|at) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the session container to use	X
`-s, --session <name>`	the name of the test-session	X
`-t, --test-case <name>`	the old name of the test case	X
`-n, --name <name>`	the new name of the test case
`-m, --comment <text>`	a new comment describing the test case

Examples

codecover alter-test-case -c container.xml 
                          -s "Session 1"
                          -t "Test Case 1"
                          -n "New Name"
                          -m "New Comment"

Load the test-session container from "container.xml", rename the test-case with the name "Test Case 1" to "New Name" and change the comment of the test-case to "New Comment". The option for the comment is not required, so a test-case can be renamed without changing its comment.

Remove Test Cases

This command is used to remove a test-case from a test-session.

Usage

codecover (remove-test-cases|rt) [options]

Options

The following table lists all the options, that are available for use with this command.

Option	Description	Required
`-c, --container <file>`	the session container to use	X
`-s, --session <name>`	the name of the test-session	X
`-t, --test-case <name>`	the name of the test case to be removed; this argument can occur more than one time -- once for every test case	X

Examples

codecover remove-test-cases -c container.xml 
                            -s "Session 1"
                            -t "Test Case 1"

Load the test-session container from "container.xml", remove the test-case with the name "Test Case 1" of the session "Session 1".

Help

The help command can be used either to show a help page containing an overview of all command, or to show all information about one given command, including all options and parameters of it.

Usage

codecover (help|h) [\%command\%]

Options

The help command has no options (except --help telling exactly this)

Examples

codecover in --help

codecover h in

Show the usage, the available options and parameters of the instrument command. The output for this command will be:

root@deepthought:~> codecover in --help
usage: codecover instrument <options>
instruments source files

This command requires a root directory with all source files, a destination for
the instrumented source files, a container, where static information of the
source files are placed - the so called MAST (More Abstract Syntax Tree) and th

language of the source files - e.g. java or cobol.

To select the files to instrument more detailed, patters can be used. There are
include and exclude patterns. A file is instrumented, if it fits one of the
include patterns and none of the exclude patterns. These patterns are relative
paths under the root directory and can include wildcards:
 ? matches one character
 * matches zero or more characters
** matches zero or more directories in a path
see http://ant.apache.org/manual/dirtasks.html#patterns for details

REQUIRED options:
 -c, --container       the test session container to use
 -d, --destination     the destination file / directory
 -l, --language        e.g. java, cobol
 -r, --root-directory  the root directory of the source files (e.g. the default
                       package)

OPTIONAL options:
     --add-plugin-dir         use all plugins in this directory
 -a, --charset                the charset to use
 -u, --copy-uninstrumented    copy all files under the root directory that are
                              not instrumented
 -o, --criterion              one or more of (all, st, br, co, lo)
 -D, --directive              a directive for the instrumenter to enable
                              special features; has the form "key=value"
 -e, --exclude                a exclude pattern, can occur more than one time
 -x, --excludes-file          a file containing a list of exclude patterns -
                              separated by a line break
 -h, --help                   shows help-page
 -i, --include                a include pattern, can occur more than one time
 -f, --includes-file          a file containing a list of include patterns -
                              separated by a line break
 -I, --instrumenter           the unique key of the instrumenter; can be got by
                              using the command instrumenter-info
     --no-default-plugin-dir  do not use the plugins from the default plugin
                              directory
     --no-progress-bar        print no progress bar
 -p, --pretend                no data changes, only simulation
     --progress-bar           print a progress bar
 -q, --quiet                  print no information at all
     --show-stack-trace       show stack traces on errors
 -v, --verbose                print more information as usual

Touch Container

Reads and rewrites all given session containers.

Command Line Interface

Command Overview

General Options

Instrumenter-Info

Usage

Options

Examples

Instrument

Usage

Options

Patterns

Examples

Analyze

Usage

Options

Examples

Report

Usage

Options

Examples

Info

Usage

Options

Examples

General Example

Example with verbose

Example with test-cases and verbose

Merge Sessions

Usage

Options

Examples

Alter Session

Usage

Options

Examples

Copy Sessions

Usage

Options

Examples

Remove Sessions

Usage

Options

Examples

Merge Test Cases

Usage

Options

Examples

Alter Test Case

Usage

Options

Examples

Remove Test Cases

Usage

Options

Examples

Help

Usage

Options

Examples

Touch Container

Example with `verbose`

Example with `test-cases` and `verbose`