...

1. Generating the static coverage file. When you have access to the application source code, the static coverage file should be generated by Jtest or dotTEST in .xml or .data format as this method comes with several advantages over the alternative. You can also generate the static coverage file by analyzing the application binaries using the coverage tool shipped with SOAtest when you do not have access to the application source code. See Generating the Static Coverage File below for more information.
2. Attaching the coverage agent to the application under test (AUT). The coverage agent ships with SOAtest and allows you to monitor the code being executed when the AUT is running.
3. Configuring SOAtest to connect to the coverage agent and collect runtime coverage and upload the data to DTP.
4. Executing tests with SOAtest as part of an automated process.
5. Reviewing the application coverage on DTP in the Coverage Explorer.

Anchor
GeneratingStaticCoverage GeneratingStaticCoverage

Generating the Static Coverage File

...

java -jar jtestcov.jar -soatest -app c:/<PATH_TO_APPLICATION>/parabank.war -include com/parasoft/parabank/parasoft/** -settings c:/<PATH_TO_LICENSE_FILE>/license.properties

...

# === LICENSE ===
 
# === END USER LICENSE AGREEMENT ===
# Set to true to accept the Parasoft End User License Agreement (EULA).
# Please review the EULA.txt file included in the product installation directory.
#parasoftparasoft.eula.accepted=falsetrue

# === LOCALNETWORK LICENSE ===
# Enables localnetwork license - be sure to configure DTP specifyserver passwordsettings.
#jtestsoatest.license.use_network=false

# Specifies password for the local license. 
#jtest.license.local.password=[LICENSE PASSWORD]true
soatest.license.network.edition=custom_edition
soatest.license.custom_edition_features=Command Line, Server API Enabled

# === NETWORKDTP SERVER LICENSESETTINGS ===
# Enables network license - be sure to configure DTP server settings.
#jtest.license.use_network=true

# Specifies typeURL of the networkDTP license (edition).
# Supported editions: desktop_edition, desktop_compliance_edition, server_edition, server_compliance_edition
#jtest.license.network.edition=server_edition

# Enables specific list of license features
#jtest.license.network.edition=custom_edition
#jtest.license.custom_edition_features=Jtest, Automation, Desktop Command Line, DTP Publish, Coverage, Test Impact Analysis


# === DTP SERVER SETTINGS ===

# Specifies URL of the DTP server in the form https://host[:port][/context-path]
#dtp.url=https://localhost:8443

# Specifies user name for DTP server authentication.
#dtp.user=admin

# Specifies password for DTP server authentication - use jtestcli -encodepass <PASSWORD> to encode the password, if needed.
#dtp.password=admin

# Specifies name of the DTP project - this settings is optional. 
#dtp.project=[DTP Project Name]

# === DTP REPORTING ===

# Enables reporting test results to DTP server - be sure to configure DTP server settings.
#report.dtp.publish=true

# Specifies a build identifier used to label results. It may be unique for each build
# but may also label more than one test sessions that were executed during a specified build.
#build.id=${dtp_project}-yyyy-MM-dd

# Specifies a tag which represents an unique identifier for the run, used to distinguish it from similar runs.
# It could be constructed as minimal combination of following variables that will make it unique or specified manually.
# e.g. ${config_name}-${project_module}-${scontrol_branch}-${exec_env}
#session.tag=[tag]

# Specifies a set of server in the form https://host[:port][/context-path]
#dtp.url=https://localhost:8443
 
# Specifies user name for DTP server authentication.
#dtp.user=admin
 
# Specifies password for DTP server authentication - use jtestcli -encodepass <PASSWORD> to encode the password, if needed.
#dtp.password=admin
 
# Specifies name of the DTP project - this settings is optional.
#dtp.project=[DTP Project Name]
 
# === DTP REPORTING ===
 
# Enables reporting test results to DTP server - be sure to configure DTP server settings.
#report.dtp.publish=true
 
# Specifies a build identifier used to label results. It may be unique for each build
# but may also label more than one test sessions that were executed during a specified build.
#build.id=${dtp_project}-yyyy-MM-dd
 
# Specifies a tag which represents an unique identifier for the run, used to distinguish it from similar runs.
# It could be constructed as minimal combination of following variables that will make it unique or specified manually.
# e.g. ${config_name}-${project_module}-${scontrol_branch}-${exec_env}
#session.tag=[tag]
 
# Specifies a set of tags that will be used to create coverage images in DTP server.
# Coverage images allow you to track different types of coverage, such as coverage for unit, functional, manual tests and others.
# There is a set of predefined tags that will be usedautomatically torecognized createby coverageDTP, imagessee inthe DTPexamples serverbelow.
# CoverageYou imagescan allowalso youspecify toother tracktags differentthat typeswill ofbe coverage,used suchto ascreate coverage for unit, functional, manual tests and others.
# There is a set of predefined tags that will be automatically recognized by DTP, see the examples below.
# You can also specify other tags that will be used to create coverage images.
images.
#report.coverage.images=${dtp_project}
#report.coverage.images=${dtp_project};${dtp_project}_Unit Test
#report.coverage.images=${dtp_project}
#report.coverage.images=;${dtp_project};${dtp_project}_Unit Test
#report.coverage.images=${dtp_project};${dtp_project}__Functional Test
#report.coverage.images=${dtp_project};${dtp_project}_Manual Test
 
# === CONSOLE VERBOSITY LEVEL ===
# Increases console verbosity level to high.
#console.verbosity.level=high

...

Application servers usually contain more than one application. Additionally, common server classes or application libraries do not need to be instrumented. The agent only needs to collect coverage for application source code. Instrumenting all classes would be too time consuming. For this reason, properly setting the scope of the coverage agent is very important. There are coverage agents for Jtest and dotTEST.

Anchor
JtestCoverageAgent JtestCoverageAgent

Jtest Coverage Agent

You can configure the Jtest coverage agent by modifying the properties in the agent.properties and passing the properties to the -javaagent argument. The agent supports several parameters (see Coverage Agent Parameters), but configuring the default settings is suitable for most cases:

jtest.agent.serverEnabled=true
jtest.agent.includes=com/myapp/data,com/myapp/common/**
jtest.agent.excludes=com/myapp/transport/*,com/myapp/autogen/**

Anchor
CoverageAgentParameters CoverageAgentParameters

Coverage Agent Parameters

The following table describes all properties that can be set for the agent:

When the properties are configured, add a -javaagent argument when starting your application server to attach the agent and include the agent configuration file:  

...

You can also check the directory you specified with the runtimeData property (/home/TIA/coverage_storage in the example above). The directory should contain a set of static coverage data files. The files are generated when the agent is startedfiles. The files are generated when the agent is started.

Additional Steps for Multiuser Mode

If you are enabling multiuser coverage and multiple users are simultaneously accessing the same web application, the coverage data they collect may be mixed. To prevent this, there are a few additional steps:

• Your tests need to inject the following HTTP header: 
  baggage: test-operator-id=<USER>

• Be sure that both jtest.agent.enableMultiuserCoverage and jtest.agent.autoloadMultiuserLibs are enabled (see Jtest Coverage Agent).

Also bear in mind that in multiuser mode:

• When jtest.agent.enableMultiuserCoverage is enabled, jtest-otel-ext.jar and opentelemetry-javaagent.jar will be automatically loaded from the agent.jar directory.
• The "default" user (the user who has not specified their ID) may collect extra coverage information from other users who are accessing the same web application.
• Coverage collected for multithreaded applications may, in some cases, not be assigned to individual users. This is related to OpenTelemetry limitations regarding context sharing between threads.
• Collecting coverage with the Jacoco engine is not supported.
• Coverage data collected for web application initialization is not assigned to a specific user, but to the "default" user.

dotTEST Coverage Agent

The dotTEST coverage agent can collect coverage for web applications and standalone applications. Each requires a different configuration.

...

1. Copy the <INSTALL_DIR>/coverage/dotNET/dottest_agent folder to the machine where IIS is installed and the web application is deployed.
2. Run a console as an Administrator on this machine.

3. Invoke the Agent Client tool on this machine to enable runtime coverage collection inside IIS:
   

   Code Block
   agent_client.exe

   Note: If you want to collect coverage information for multiple users that are simultaneously accessing the same web application server, invoke the Agent Client with the -multiuser switchInvoke the Agent Client tool on this machine to enable runtime coverage collection inside IIS:
   

   Code Block
   agent_client.exe -multiuser

   agent_client initializes the environment for the web server (IIS) and behaves like a service, enabling you to execute tests and collect coverage. The service is ready and waiting for commands as long as the following message is printed to the output:
   

   Code Block
   Write 'exit' and hit Enter to close agent_client

   Info
   A test session and test can be started even if the tested website or application has not been loaded yet.

4. Ensure that port 8050 (default port for the coverage agent) allows HTTP traffic in firewall settings on this machine. You can change the coverage agent port number if the default port is unavailable.

5. Start the application and verify that the agent is ready by opening <host>:8050/status in your browser. You should receive the following response:

   Code Block
   {"session":null,"test":null}

6. Configure soatest.properties to collect coverage for the AUT. Several application coverage parameters are supported (see Application Coverage Settings), but configuring the following settings is suitable for most cases:

   Code Block
   application.coverage.enabled=true application.coverage.agent.url=http://localhost:8050 application.coverage.binaries=c:/<PATH_TO_APPLICATION_PDB_FILES>/bin application.coverage.binaries.include=<INCLUDE_PATTERN> application.coverage.binaries.exclude=<EXCLUDE_PATTERN>

   Be sure the path for the application binaries

   .exclude=<EXCLUDE_PATTERN>

   Be sure the path for the application binaries is to the folder containing the application PDB files.

...

1. is to the folder containing the application PDB files.

Additional Steps for Multiuser Mode

If you are enabling multiuser coverage and multiple users are simultaneously accessing the same web application, the coverage data they collect may be mixed. To prevent this, there are a few additional steps:

• Your tests need to inject the following HTTP header: 
  baggage: test-operator-id=<USER>

Standalone Applications

Most users will collect coverage for web applications, but you can also collect coverage information from standalone applications.

1. Copy the <INSTALL_DIR>/coverage/dotNET/dottest_agent folder to the machine where you intend to run the standalone application.
2. Run the coverage_wizard.exe in that folder, specifying the following:
   • Full path the application
   • Command line arguments
   • Working directory
3. Select the .NET CLR version used by the application.
4. Enter the directory where the scripts generated by the wizard will be saved in the Target scripts directory field.
5. Enable the Use Coverage Agent option and enable or disable the Collect coverage without admin privileges option as appropriate.
   • By default, admin privileges are required to collect coverage with coverage agent, but you can configure the tool to collect coverage by users without admin privileges. Doing so will cause two additional .bat scripts to be generated: runCamAgentInit.bat and runCamAgentUninit.bat. Run the runCamAgentInit.bat script with admin privileges to setup and initialize the coverage agent. When testing is completed, run the runCamAgentUninit.bat script to stop the process.
6. Click Finish. The wizard will generate scripts in target script directory specified above.
7. Run a console as an Administrator on this machine and change directories to where the scripts were generated.
8. Execute runCamAgent.bat.
9. Run another console as an Administrator and execute monitorCoverage.bat.

10. Configure soatest.properties to collect coverage for the AUT. Several application coverage parameters are supported (see Application Coverage Settings), but configuring the following settings is suitable for most cases:

    Code Block
    application.coverage.enabled=true application.coverage.agent.url=http://localhost:8050 application.coverage.binaries=c:/<PATH_TO_APPLICATION_PDB_FILES>/bin application.coverage.binaries.include=<INCLUDE_PATTERN> application.coverage.binaries.exclude=<EXCLUDE_PATTERN>

    Be sure the path for the application binaries is to the folder containing the application PDB files.

Anchor
Configuring SOAtest to Collect and Upload Coverage Configuring SOAtest to Collect and Upload Coverage

Configuring SOAtest to Collect and Upload Coverage 

...