In this section:

Introduction

You can monitor and collect coverage data from managed code during manual or automated functional tests performed on a running web application that is deployed on IIS server. You can also send coverage data and test results to DTP. 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.

Prerequisites

The following components are required for collecting coverage:

• Internet Information Services (IIS) version 7.5 or higher
• Coverage Agent Manager (CAM) (contact your Parasoft representative) or SOAtest

Process Overview

dotTEST 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. During test execution, interactions with the coverage agent and AUT are written to a dynamic coverage data file, which contains markers that specify which lines of code were touched.  

The steps that follow:

• dotTEST processes the dynamic coverage data and static coverage data, and merges them to create coverage.xml file. 
• A coverage.xml file, which contains the coverage information, is 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 that executes the tests (i.e., SOAtest, tests executed by dotTEST, manual tests, etc.) in a report.xml file. If the build IDs for the coverage.xml file and the report match, DTP is able to correlate the data and display the coverage information.

Configuring the Application Under Test for Coverage

The following steps are required to prepare the application under test (AUT):

1. The static coverage file must be generated. The static coverage file contains metadata about user classes, methods, and lines; see Generating the Static Coverage File.
2. The coverage agent must be attached to the AUT; see Attaching the Coverage Agent to the AUT.

Generating the Static Coverage File

Run the following test configuration on the solution:

dottestcli.exe -config "builtin://Collect Static Coverage" -solution SOLUTION_PATH

The dottestcli console output indicates where the static coverage data is saved, for example:

Saving static coverage information into: 'C:\Users\[USER]\Documents\Parasoft\dotTEST\Coverage\Static\[FILE].data

Customizing Scope of Coverage

By default, coverage is measured for the entire application. To narrow down the scope of collecting static coverage:

1. Provide paths to the selected parts of the application with the -solution, -resource, -include, and/or -exclude options. The -resource option points to a path inside the solution; the -include and -exclude options specify paths in the file system (see Configuring the Test Scope for details). Your command line may resemble the following:

   dottestcli.exe -config "builtin://Collect Static Coverage" 
   -solution "C:\Devel\FooSolution\FooSolution.sln" 
   -resource "FooSolution/QuxProject" 
   -include "C:\Devel\FooSolution\src\QuxProject\**\*.cs" 
   -exclude "C:\Devel\FooSolution\src\QuxProject\**\tests\**\*.cs"

   When static coverage is generated, the scope information is stored in a scope configuration file. The output from the console indicates the location of the scope configuration file, for example:

   Saving static coverage scope configuration into: 'C:\Users\[USER]\Documents\Parasoft\dotTEST\Coverage\Static\scope.instrumentation.txt'

2. Pass the path to the scope configuration file to the dotTEST IIS Manager tool (see Attaching the Coverage Agent to the AUT) with the -scope option, for example:

   dottest_iismanager.exe -scope 'C:\Users\[USER]\Documents\Parasoft\dotTEST\Coverage\Static\scope.instrumentation.txt'

You don' need to modify the content of the scope configuration file. However, if you collect coverage for large applications, you may want to additionally fine-tune the scope for collecting dynamic coverage (i.e. coverage collected while interacting with the application under test) to optimize performance. To customize collecting dynamic coverage, open the scope.instumentation.txt file and remove the the assemblies for which you do not want to collect coverage data from the list of assemblies.

Attaching the Coverage Agent to the AUT 

1. Copy the [INSTALLATION_DIR]\integration\IIS directory to the machine were IIS is installed and the web application is deployed.
2. Run a console as an Administrator

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

   dottest_iismanager.exe

   You may need to configure the dotTEST IIS Manager with additional options, see IIS Manager Options.

   dottest_iismanager 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:  

   Write 'exit' and hit Enter to close dottest_iismanager 

   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. Open the website or application.

6. Go to the following address to check the status of the coverage agent: http://host:8050/status
   You should receive the following response:

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

Connecting with the Coverage Agent via HTTPS

By default, the coverage agent is available via the HTTP protocol. To connect via HTTPS, you need to bind an SSL certificate to the port used by the coverage agent. This can be achieved in one of the following ways:

• By adding your SSL certificate to a storage accessible from the Netsh.exe tool and passing the hash of the certificate and the port number to dottest_iismanager.exe:

  dottest_iismanager.exe -port 8050 -useSsl -certificateHash <SSL certificate hash>

• By passing the path and password to an SSL certificate stored in a .pfx file and the port number to dottest_iismanager.exe:

  dottest_iismanager.exe -port 8050 -useSsl -certificatePath <path to PFX> -certificatePassword <password>

• By configuring a port with an SSL certificate and the appid of the dotTEST IIS Manager for the Netsh.exe tool. The dotTEST IIS Manager has the following ID:

  {ed344e08-fab7-4dfb-9d07-68f2c2c9e373}

  When the SSL certificate is configured in the Netsh.exe tool, you can connect via HTTPS by launching the dotTEST IIS Manager with the -port and -useSsl switches:

  dottest_iismanager.exe -port 8050 -useSsl

To use a self-signed certificate, you must add the -skipvalidation option.

You can use an SSL certificate in the in PFX or PKCS12 format.

Removing an SSL Certificate

By default, the dotTEST IIS Manager automatically handles certificates configured for the coverage agent. To manually remove a certificate, launch the Certmgr.exe tool and remove the certificate stored in Personal> Certificates.

If you manually unregister the coverage service port using the dotTEST IIS Manager with the -unregister switch, you need to add the -useSsl and -removeCertificate switches to remove the SLL certificate:

dottest_iismanager.exe -unregister -port 8050 -useSsl -removeCertificate

This will delete the SSL certificate from the port number. You can now manually remove the certificate from the storage.

Collecting Coverage from Multiple Users

You can collect coverage information for multiple users that are simultaneously accessing the same web application server. This requires launching the dotTEST IIS Manager with the -multiuser switch:

dottest_iismanager.exe -multiuser

See the Coverage Agent Manager (CAM) section of the DTP documentation for details.

Changing IIS Idle Timeouts

By default, IIS application pool processes are recycled after 20 minutes of idle time, which can have negative consequences on a test session. You can prevent this behavior by changing the default value so that people working with the application do not experience unexpected stops and restarts during a test session.

1. Start the Internet Information Services (IIS) Manager.
2. Open the Application Pools node.
3. Choose the pool for your web application.
4. Click Advanced Settings in the Actions panel.
5. In Process Model section, change the Idle Time-out (minutes) setting to a value better-suited to your testing practices.

IIS Manager Options

Executing Tests to Collect Runtime Coverage

You can use SOAtest to run functional tests, as well as execute manual tests with Coverage Agent Manager (CAM). Refer to the SOAtest user guide or CAM documentation for details about performing test sessions.

When tests are being performed:

• SOAtest will collect runtime coverage, then merge it with static coverage, and upload the merged data to DTP.
• CAM will collect runtime coverage and test results, which must be manually downloaded.  Next, you need to:
  • manually upload test results to DTP; see Uploading Test Results to DTP.
  • merge the runtime coverage with static coverage and upload the merged data to DTP; see Merging Static and Runtime Coverage and Uploading the Data to DTP.

Uploading Test Results to DTP

If you use dotTEST with CAM:

1. Go to Report Center in the DTP interface.
2. Click the gear icon and choose Report Center Settings> Additional Settings> Report Center Administration> Tools> Data Collector Upload Form (requires admin permissions).
3. Click Choose File and browse for the report.xml file you downloaded from CAM.
4. Click the Upload button to upload the file to DTP.

If you use dotTEST with SOAtest, test results are automatically sent to DTP during test execution. See the Application Coverage section in the SOAtest user guide at https://docs.parasoft.com.

Merging Static and Runtime Coverage and Uploading the Data to DTP

If you use dotTEST with CAM:

1. Ensure that dotTEST is properly configured, including DTP, scope and authorship settings. See Connecting to DTP, Sending Results and Publishing Source Code to DTP, Configuration.
2. Configure the following settings in the dottestcli.properties file in order to properly merge coverage data:
   - 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.

3. Copy the runtime coverage and static coverage files to the same machine and run dottestcli with the following switches:

   • -runtimeCoverage: Specifies the path to runtime coverage that you download with CAM (see Coverage Agent Manager (CAM) section of the DTP documentation for details). You can provide a path to an individual .data file with coverage information from one testing session, or a path to a folder that contains many .data files from multiple testing sessions.
   • -staticCoverage: Specifies the path to the static coverage file (see Generating the Static Coverage File).
   • -publish: Sends the merged coverage to DTP.

   dottestcli.exe -runtimeCoverage [path] -publish -staticCoverage [path]

If you use dotTEST with SOAtest, static and dynamic coverage data are merged and sent to DTP during test execution. See the Application Coverage section in the SOAtest user guide at https://docs.parasoft.com.

Stopping Dynamic Coverage Data Collection

You can stop the process of collecting dynamic coverage data in one of the following ways:

1. Write exit in the open console when the following message will be printed to the output to stop dottest_iismanager:

   Write 'exit' and hit Enter to close dottest_iismanager

2. Send a request to the service by entering the following URL in the browser: http://host:port/shutdown

If any errors occur when dottest_iismanager exits, which prevent the clean-up of the Web Server environment, then execute dottest_iismanager with the -stop option to bring back the original Web Server environment and settings: 

dottest_iismanager.exe -stop

Reviewing Coverage in DTP

You can use the Coverage Explorer in DTP to review the application coverage achieved during test execution.  For details on viewing coverage information, see the DTP user guide at https://docs.parasoft.com.

Known Limitations

• You can download coverage information that was collected in a test session. Coverage data collected when no test session was active cannot be downloaded.
• If multiple users are simultaneously accessing the same web application, the coverage data they collect may be mixed. To ensure that coverage is properly associated with individual users, the multiuser mode must be enabled (see Collecting Coverage from Multiple Users).
• The HTTP or HTTPS protocols are required to enable the multiuser mode, as the user-specific information must be provided within the HTTP header.
• In the multiuser mode, collecting coverage for WCF-based applications requires that they have the ASP.NET compatibility mode enabled.
• In the multiuser mode, 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.
• In the multiuser mode, assigning coverage collected for multithreaded application to individual users is limited. Coverage data for child threads is not assigned to the user who is actually accessing the application, but to the "default" user.
• Coverage data collected web initialization is not assigned to a specific user, but to the "default" user.
• The application coverage scope file cannot be used for WebSite projects as they may get recompiled by IIS server and change the name of the target assembly. Scope files can be safely used for Web Applications.