CodeCover

HOWTO Use CodeCover with the command-line interface

This section contains step-by-step instructions on how to use CodeCover with the command-line interface. A piece of software is instrumented, compiled and executed. The measured coverage data is then collected in an HTML report.

General Preconditions

• The name of the software used in this example is SimpleJavaApp.
• SimpleJavaApp is written in Java.
• SimpleJavaApp's sources are encoded using UTF-8.
• CodeCover is executed with the codecover command.
• CODECOVER_HOME$ refers to the installation directory of CodeCover.
• You can get the SimpleJavaApp here, as .zip or .tar.bz2.

Instrument

The first step is the instrumentation ofSimpleJavaApp with the following command:

codecover instrument --root-directory SimpleJavaApp/src
                     --destination SimpleJavaApp/instrumentedSrc 
                     --container SimpleJavaApp/test-session-container.xml
                     --language java 
                     --charset UTF-8

• The option root-directory refers to the directory of the software that holds the top-level package(s) of the code to be instrumented.
• The option destination refers to the directory where the instrumented source files are stored.
• The option container refers to the test session container that holds the static information about the instrumented code, as well as the collected coverage data.
• The option language refers to the language of the code to be instrumented.
• The option charset refers to the character set, in which the source files are saved.

You will begin the instrumentation process with the execution of this command. The duration depends on the size of the given source code. As a result a number of new, instrumented source files are created in the specified destination. Also, a test session container file is created which holds the static information about the source code.

Compile

The instrumentation of the software is followed by the compilation of the instrumented source code. As this exceeds the scope of CodeCover, this is your job. It must be noted that any additional source files created by CodeCover must be compiled with the instrumented source code.

Execute

You can now execute the compiled program and perform your test activities. The termination of the program will result in a coverage log file. This file holds the coverage data measured during the execution. In the next step it will be entered into the created test session container.

Analyze

To enter the created coverage log file into the test session container use the following command:

codecover analyze --container SimpleJavaApp/test-session-container.xml 
                  --coverage-log SimpleJavaApp/instrumentedSrc/coverage_log.clf 
                  --name TestSession1 
                  --comment "The first test session"

• The option container refers to the test session container into which the coverage data shall be inserted, usually the test session container created during the instrumentation process.
• The option coverage-log refers to the coverage log file whose coverage data shall be inserted into the test session container.
  The option name refers to the name of the test session the coverage data is attributed to.
• The option comment refers to an optional comment that can be added to a test session.

You will enter the coverage data of the coverage log file into the test session container with the execution of this command. The coverage log file is no longer needed after the successful completion of the command.

Interlude

You can now repeat the execution of the software and enter any resulting coverage log into further test sessions. CodeCover provides you with a command that can merge existing test sessions into a single test session. If you did not create multiple test sessions, or do not want to merge the test sessions, then you can skip the following step and go on to the creation of the report.

Merge test sessions

Multiple test sessions can be merged into a single test session, by the following command:

codecover merge-sessions --container SimpleJavaApp/test-session-container.xml 
                         --session TestSession1 
                         --session TestSession2 
                         --name "TestSession1+2"
                         --comment "TestSession1 and TestSession2"

• The option container refers to the test session container which holds the test sessions to be merged.
• The option session refers to individual test sessions that are to be merged. It is assumed here that you created a second test session with the name "TestSession2".
• The option name refers to the name of the merged test session.
• The option comment refers to an optional comment that can be added to the merged test session.

Execution of this command creates a new test session with the name "TestSession1+2", that holds all the coverage data of the previously separate test sessions.

Generate Report

Finally CodeCover can generate a report of one of the test sessions in the test session container with the following command:

codecover report --container SimpleJavaApp/test-session-container.xml 
                 --destination SimpleJavaApp/report/SimpleJavaAppReport.html 
                 --session "TestSession1+2"
                 --template CODECOVER_HOME/report-templates/HTML_Report_hierarchic.xml

• The option container refers to the test session container which holds the test session from which a report is generated.
• The option destination refers to the HTML file that servers as the initial page of the report.
• The option session refers to the name of the test session from which a report is generated. In this case it is assumed that you merged two test sessions into the given one. Was this not the case, simply substitute the name of the test session with one of a test session from which you want to generate a report.
• The option template refers to the template used in the generation of the report.

Execution of this command will generate a report of the given test session at the specified location, for you to examine and concludes this tutorial.