In this section:
You can monitor and collect coverage data during manual or automated functional tests performed on a running web application server. You can also send coverage data and test results to DTP, which merges and correlates the data. The application coverage information can be displayed in the DTP Coverage Explorer (see the "Coverage Explorer" chapter in the DTP user manual), which provides insights about how well the application is tested, as well as the quality of your tests.
The following components are required for collecting coverage:
Java JDK 8 line break calculations in bytecode are inconsistent with previous Java versions. This may lead to inconsistencies in coverage results.
If you use a source control system, ensure that your source control settings are properly configured; see Source Control Settings.
Jtest DTP Engine ships with a component called the coverage agent. The coverage agent is attached to the application under test (AUT) and monitors the code being executed as the AUT runs. When the coverage agent is attached to the AUT, a REST API is exposed that enables you to mark the beginning and end of each test and test session.
Metadata about the lines of code that can be covered (static coverage data) is collected by running a dedicated test configuration as part of the application build process. During test execution, interactions with the coverage agent are written to a dynamic coverage map, which contains markers that specify which lines of code were touched.
Jtest processes the dynamic coverage map and static coverage data. A coverage.xml file, which contains the coverage information, is produced and sent to DTP. When DTP receives the coverage data, it's loaded into a coverage image, which is a special tag that enables you to aggregate coverage data from runs with the same build ID. The coverage image enables you to associate coverage information with specific tests.
Test results are also sent to DTP from the tool executing the tests (i.e., SOAtest, tests executed by the DTP Engine, manual tests, etc.) in a report.xml file. If the build IDs for the coverage data file and the report match, DTP is able to correlate the data and display the coverage information.
The following steps are required to prepare the application under test (AUT):
The package that contains the static coverage file is created during the build process by the Jtest Maven, Gradle or Ant plugin. It must be generated on the build machine that contains the source code. The static coverage file can be used until the code changes.
In order to generate the package that contains the static coverage file, you need to execute an appropriate command in the AUT's main directory.
mvn package jtest:monitor
gradle assemble jtest-monitor -I [INSTALL]/integration/gradle/init.gradle
ant -lib [INSTALL]/integration/ant/jtest-ant-plugin.jar -listener com.parasoft.Listener jtest-monitor
Ant requires all classes to be compiled before the monitor task is executed. Modify your project prior to the build and configure the task to ensure the correct sequence. The following example shows how the target can be configured:
The monitor.zip package will be generated and placed into the build output directory. The path to the location will be printed on the console.
The package contains the following:
Run the agent.sh/agent.bat script from the monitor package to generate the Jtest Java agent VM arguments. The scripts output the
-javaagent VM argument to the console. You will need this argument to connect the agent to the AUT, which will result in the runtime_coverage subdirectory:
Jtest Agent VM argument: -javaagent:"[path to agent dir]\agent.jar"=settings="[path to agent properties file]\agent.properties",runtimeData="[path to monitor dir]\monitor\ runtime_coverage"
-javaagentflag to the application server’s startup script and restart the server (see step 5c in Web Application Coverage Tutorial). Attaching the coverage agent to the AUT exposes a REST API for controlling the agent.
Application servers usually contain more than one application. Additionally, common server classes or application libraries do not need to be instrumented. The Jtest DTP Engine only needs to collect coverage for application source code. Instrumenting all classes would be too time-consuming.
The application on the server is already built, so we cannot gather information about which classes come from the source code. For this reason, properly setting the scope of the coverage agent is very important.
You can configure the coverage agent with:
The agent.properties file is generated in the monitor.zip package ( see Generating the Static Coverage File). It contains properties that can be modified to properly configure the coverage agent. The following example shows how the coverage agent can be configured with the agent.properties.file:
jtest.agent.runtimeData=[path to runtime_coverage directory] jtest.agent.includes=com/myapp/data,com/myapp/common/** jtest.agent.excludes=com/myapp/transport/*,com/myapp/autogen/** jtest.agent.autostart=false
Adding properties to
-javaagent requires modifying their names by removing the "jtest.agent" prefix, for example:
-javaagent:"[path to agent dir]\agent.jar"=settings="[path to agent properties file]\agent.properties",autostart=true
Properties provided as arguments to
The following table describes all properties that can be used to configure the coverage agent:
Specifies where the runtime data will be stored. The following example will create files in the in ‘C:/tmp/myapp/’ directory with
A coma-separated list of patterns that specify classes to be instrumented. The following wildcards are supported:
In the following example, all classes from the
Coma separated list of patterns that specify classes to be excluded from instrumentation. The following wildcards are supported:
In the following example, all classes from the
|Enables/disables automatic runtime data collection; the default is |
|Sets up agent communication port; the default is |
|Enables/disables verbose output to console; the default is |
|Enables/disables collecting coverage information for test cases. The default value is |
Enables/disables collecting web application coverage for multiple users; the default value is
Setting this property to true allows you to collect multi-user coverage with Coverage Agent Manager. See the "Coverage Agent Manager (CAM) section of the DTP documentation for details.
You can use SOAtest to run functional tests (refer the Application Coverage chapter of the SOAtest documentation to set up the test configuration), as well as execute manual tests. At the end of the test session, coverage will be saved in
runtime_coverage_[timestamp].data files in the directory specified in SOAtest. This information will eventually be merged with the static coverage data to create a
coverage.xml file and uploaded to DTP.
For tests executed by SOAtest, the SOAtest XML report will need to be uploaded to DTP. See the "Uploading Rest Results to DTP" section in the Application Coverage topic in the SOAtest documentation for details.
report.coverage.images- Specifies a set of tags that are used to create coverage images in DTP. A coverage image is a unique identifier for aggregating coverage data from runs with the same build ID. DTP supports up to three coverage images per report.
session.tag- Specifies a unique identifier for the test run and is used to distinguish different runs on the same build.
build.id- Specifies a build identifier used to label results. It may be unique for each build, but it may also label several test sessions executed during a specified build.
Calculate Application Coverage test configuration using the following arguments:
jtestcli -staticcoverage [path to static_coverage.xml file] -runtimecoverage [path/dir] -config "builtin://Calculate Application Coverage" -publish
This ensures that Jtest has access to the runtime coverage data generated during test execution, as well as the static coverage data, which is required to fill the coverage.xml file with runtime coverage data,
You can use the Coverage Explorer in DTP to review the application coverage achieved during test execution. See the DTP documentation for details on viewing coverage information.