Page History

...

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.serverEnabledrestServerEnabled=true
jtest.agent.includes=com/myapp/data,com/myapp/common/**
jtest.agent.excludes=com/myapp/transport/*,com/myapp/autogen/**

...

...

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

...

Anchor
dotTESTCoverageAgent dotTESTCoverageAgent

dotTEST Coverage Agent

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

Web Applications

The application under test (AUT) must be running on a machine using IIS version 7.5 or higher.

To attach the coverage agent to the AUT:

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. To launch the dotTEST application coverage UI, run the agent client in the console using the following command:

   Code Block
   agent_client.exe

4. Choose IIS Web Application and click Next.
5. (Optional) Configure the following settings:
   • Application URL: Specifies the URL of an application which you will be able to run from the application coverage UI.
   • Advanced settings:
     
     • Enable simultaneous collection of coverage for multiple users: Enables collecting coverage information for multiple users.
     • Coverage output directory: Specifies the path to the coverage data output directory.
     • Coverage scope file: Specifies the path to the coverage scope configuration file. It is required if the scope is other than the default.
     • Agent REST API port: Specifies the custom port number to use when starting the coverage agent if the default port is unavailable.
     • Agent connection timeout (milliseconds): Specifies the timeout for a connection with the coverage agent. The default value is 1500 ms. 

       Info
       If you provide 0 or a negative value, the connection attempt will not timeout, which may lead to a considerable slowdown or cause the tool to hang indefinitely.

     • Data flushing interval (milliseconds): Specifies the frequency at which collected coverage data is written to disk.
     • Maximum number of coverable lines: Specifies a limit for the number of lines that can be covered.
     • Skip SSL for connecting to the agent: Enables connecting via HTTPS.
     • Skip SSL certificate validation: Enables using a self-signed SSL certificate.
       • Certificate path: Specifies the path to a PFX file that stores the SSL certificate.
       • Certificate hash: Specifies the hash of the SSL certificate for the port that is used by the coverage agent.
       • Certificate password: Specifies the password for the SSL certificate stored in a PFX file.
6. Click Next. Coverage will be collected for all applications residing on the IIS server.
7. (Optional): Perform tests on the specified application and view the coverage API:
   • Start Application - Allows you to run the specified application and perform tests on it.
   • Swagger - Allows you to view coverage API in Swagger, start/stop a session, and download a coverage file.
   • Scalar - Allows you to view coverage API in Scalar, start/stop a session, and download a coverage file.
8. 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.

9. 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}

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.

11. Click Stop Coverage Agent to finish collecting coverage from all applications.
12. Click Finish to close the application coverage UI, or New Session to configure a new coverage collection session.

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.

You can define a separate coverage agent for each of your applications. 

1. Go to the <INSTALL_DIR>\integration\coverage\agent directory and edit the agent_config.json file.
2. Configure the properties for individual applications in the "apps" section, and global properties at the beginning of the file. If no apps are configured, a common session for all applications runs on the web server.
   

   Note: The application name specified as an entry name in the "apps" section must match the actual or expected application name, defined as follows:

   • For IIS applications
   • As the PARASOFT_DOTTEST_MONITORED_APP_NAME environment variable, or
   • As the APP_POOL_ID variable set by the IIS based on the Application Pool name.
   • For standalone applications
   • As the PARASOFT_DOTTEST_MONITORED_APP_NAME environment variable, or
   • As the process name (without the file extension).

   Global properties
   

   • reconnectDelayMs - Specifies the delay, in milliseconds, between reconnection attempts when the connection to the coverage agent is lost.
   • maxReconnectAttempts - Specifies the maximum number of reconnection attempts to the coverage agent after a connection failure.
   • useDurableSubscriptions - Enables the use of durable subscriptions.
   • heartbeat - Specifies the outgoing and incoming heartbeat intervals used to keep the connection to the coverage agent alive and detect broken connections.
   • skipCertificateValidation - Enables using a self-signed SSL certificate.
   • useSsl - Enables connecting via HTTPS.
   • connectionTimeout - Specifies the timeout, in milliseconds, for a connection with the coverage agent. The default value is 2000 ms. 

     Info
     If you provide 0 or a negative value, the connection attempt will not timeout, which may lead to a considerable slowdown or cause the tool to hang indefinitely.

   • certificateHash - Specifies the hash of the SSL certificate for the port that is used by the coverage agent.
   • certificatePath - Specifies the path to a PFX file that stores the SSL certificate.
   • certificatePassword- Specifies the password for the SSL certificate stored in a PFX file.
   • coverageFlushingInterval - Specifies the frequency, in milliseconds, at which collected coverage data is written to disk. To update the interval, set a value greater than 1000 ms.
   • skipRegistration - Enables running the application without registering the coverage service port. It is assumed that the port is already registered. This option allows running the application without admin privileges.
   • nonInteractive - Disables all user input in the command line interface after the application starts.

   Application-level properties

   • appPath - Specifies the
3. Copy the <INSTALL_DIR>/coverage/dotNET/dottest_agent folder to the machine where you intend to run the standalone application.
4. To launch the dotTEST application coverage UI, run the agent client in the console using the following command:

   Code Block
   agent_client.exe

5. Choose Desktop Application and click Next.
6. Configure the following settings:
   • Full path to the tested application: Specifies the full path to the tested application for which coverage will be collected. You will be able to run this application from the application coverage UI.
     
   • Application command-line arguments: appArguments - Specifies the application command line arguments.
     
   • appWorkingDirectory - Application working directory: Specifies the path to the working directory.
     
   • (Optional) Advanced settings:
     
   • Enable simultaneous collection of coverage for multiple users: Enables collecting coverage information for multiple users.
   Coverage output directory: coverageDataDirectory - Specifies the path to the coverage data output directory.
   
   • Coverage scope file: appCoverageScope - Specifies the path to the coverage scope configuration file. It is required if the scope is other than the default.
   • Agent REST API port: Specifies the custom port number to use when starting the coverage agent if the default port is unavailable.
   • Agent connection timeout (milliseconds): Specifies the timeout for a connection with the coverage agent. The default value is 1500 ms. 

     Info
     If you provide 0 or a negative value, the connection attempt will not timeout, which may lead to a considerable slowdown or cause the tool to hang indefinitely.

   • Data flushing interval (milliseconds): Specifies the frequency at which collected coverage data is written to disk.
   • Maximum number of coverable lines: Specifies a limit for the number of lines that can be covered.
   • Skip SSL for connecting to the agent: Enables connecting via HTTPS.
   • Skip SSL certificate validation: Enables using a self-signed SSL certificate.
     • Certificate path: Specifies the path to a PFX file that stores the SSL certificate.
     • Certificate hash: Specifies the hash of the SSL certificate for the port that is used by the coverage agent.
     • Certificate password: Specifies the password for the SSL certificate stored in a PFX file.
7. Click Next. The specified application will be run and coverage will be collected. Perform tests on the application.
8. (Optional): View the coverage API:
   • Swagger - Allows you to view coverage API in Swagger, start/stop a session, and download a coverage file.
   • Scalar - Allows you to view coverage API in Scalar, start/stop a session, and download a coverage file.
9. Click Stop Coverage Agent to finish collecting coverage from the application.
Click Finish to close the application coverage UI, or New Session to configure a new coverage collection session
10. • other than the default.
      
    • maxCoverableLines - Specifies a limit for the number of lines that can be covered.
      
    • multiUser - Enables collecting coverage information for multiple users that are simultaneously accessing the same web application server. By default, coverage information is collected for a single user.
      
    • ctp.websocket.url - Specifies the WebSocket URL used to establish a connection to the CTP (Continuous Testing Platform).
      
    • ctp.subscription.queue - Specifies the queue destination that the coverage agent subscribes to over WebSocket to receive coverage-related messages from the CTP.
      
    • appInclude - Specifies the path to a file or directory containing application assemblies. This path is used to calculate checksums — either for each method within the assemblies, or for the entire application. Ant-style wildcards can be used to specify patterns. Alternatively, you can specify a .lst file containing a list of paths or patterns (each line in the file will be treated as a single entry).
      
    • appExclude - Narrows the scope defined by the -appInclude property by excluding specified items.
      
    • restServicePort - Specifies the custom REST service port number to use when starting the coverage agent if the default port is unavailable.
      
    • dtpProject - Specifies the project name.
      
    • dtpFilterId - Specifies DTP filter ID.
      
    • dtpBuildId - Specifies the build ID.
      
    • dtpCoverageImages - Specifies tags that will be used to fill in coverage images in DTP (separated by semicolons). DTP supports up to 3 coverage images per report. 
      
    • restServerEnabled - Enables REST server communication. It is disabled by default.

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 multiUser is enabled in the agent.config.json file.

...