In this section:

Introduction

The following tutorial will guide you through collecting application coverage with the Jtest. It includes information about basic topics, such as running the server and deploying applications, so that beginners and advanced users can benefit. 

Prerequisites

Web Application Coverage can be collected on any server that can accept Java Agents. The following requirements are only necessary to complete this tutorial:

  • Java JDK 1.8
  • Apache Maven build system
  • Calculator example, which is an extremely basic web application. You can find this example in the [INSTALL]/examples directory.
  • One of the following application servers:
    - Apache Tomcat (this scenario has been verified with versions 6.0, 7.0, 8.0) 
    - JBoss/WildFly 
    - Oracle WebLogic

Step 1: Preparing Calculator Example

Build the WAR file. The application must be packaged into a WAR file (Web Application Archive) on the server. Use the maven-war-plugin shipped with Jtest to package the application. The plugin automatically builds applications with the correct WAR structure. Execute the following command in the application directory:

mvn clean install

Step 2: Deploying Example to an Application Server

Deploy the application to an application server. See Deploying Example to Tomcat,  Deploying Example to WildFly/JBoss and Deploying Example to Oracle WebLogic for information about deploying the Calculator example to different application servers.

Deploying to Tomcat Application Server

There are many ways to deploy application servers, but in this tutorial, we demonstrate how to deploy remotely using the Tomcat Manager web application. 

  1. Add a new user to the server by opening [Apache Tomcat Installation Directory]/conf/tomcat-users.xml and add the following line in the <tomcat-users> section: 

    <user username="tomcat" password="tomcat" roles="tomcat, manager-gui"/>

  2.  Run the server by executing the following command:
    Windows

    [Your apache-tomcat installation directory]/bin/startup.bat

    Linux

    [Your apache-tomcat installation directory]/bin/startup.sh

  3. Open the following URL in a browser and enter the username and password set in step 1 (tomcat/tomcat):

    http://localhost:8080/manager/html
  4. In the WAR file, click Choose File and browse to Calculator.war to deploy the section.

  5. Click Deploy; the application will be available at the following URL:

    http://localhost:8080/calculator
  6. Interact with the application to test its functionalities

Deploying Example to WildFly/JBoss Application Server

There are many ways to deploy WildFly/JBoss application servers, but we demonstrate deployment in this tutorial by using the JBoss web console. These instructions can be applied to JBoss AS 7.1.1, JBoss EAP 6.4, and WildFly 8.2 and 9.0 servers.

  1. Add a new user to the server by running the add-user script on Windows:

    [JBoss installation directory]/bin/add-user.bat

  2. Choose Management User when prompted to choose a type of user:

    What type of user do you wish to add?
 a) Management User (mgmt-users.properties)
 b) Application User (application-users.properties)
(a): a

  3. Enter a username and password when prompted leaving the Realm field blank:

    Enter the details of the new user to add.
Realm (ManagementRealm) :
Username : admin
Password : 1adm-adm-adm

  4. Run the server by executing the following script: 

    [JBoss installation directory]/bin/standalone.bat

  5. Open the following URL in a browser and enter the username and password specified in step 3 (admin/1adm-adm-adm):

    http://localhost:9990/console/App.html#deployments
  6. Click Add (or Add Content for JBoss 7.1.1) and browse to the Calculator.war file.
  7. Click Next and click Save.

  8. Enabled the Calculator.war file in the Deployments list and open the following URL in a browser: 

    http://localhost:8080/Calculator
  9. Interact with the application to test its functionalities

Deploying Example to Oracle WebLogic Server

There are many ways to deploy WebLogic application server, but in this tutorial, we demonstrate how to deploy remotely using the Admin Console. This scenario has been verified with versions 12.2.1 and 10.3.6.

This tutorial assumes that you have already installed the WebLogic server and created your server domain.

  1. Go to Administration Console (http://localhost:7001/console).
  2. In the Domain Structure panel menu, click Deployments to open the Summary of Deployments section.
  3. In the Deployments table, click the Install button.
  4. Specify the path to your WAR file in the Arguments field.
  5. Click Next.
  6. Choose the Install this deployment as an application option.
  7. Click Next.
  8. Click Finish.
  9. Interact with the application to test its functionalities (http://localhost:7001/Calculator)

Step 3: Preparing Metadata Files

Execute the following command in the example application’s main directory:

mvn package jtest:monitor

The goal generates the monitor.zip package, which contains artifacts necessary for collecting application coverage. 

Step 4: Generating the javaagent VM Argument

Extract the contents of the monitor.zip package to the server machine and run the agent.bat (Windows) or agent.sh (Linux) script. This will generate the javaagent flag that will be printed to the console. 

Your javaagent flag may resemble the following:

-javaagent:"E:\Parasoft\JTest\examples\calculator\target\jtest\monitor\monitor\agent.jar"=settings="E:\Parasoft\JTest\examples\calculator\target\jtest\monitor\monitor\agent.properties",runtimeData="E:\Parasoft\JTest\examples\calculator\target\jtest\monitor\monitor\runtime_coverage"

If the OpenTelemetry Java agent is already configured and attached to the project, then the jtest.agent.autoloadMultiuserLibs property must be disabled. Additionally, a path to the Jtest extension must be configured: 

-Dotel.javaagent.extensions=path_to/jtest-otel-ext.jar

Step 5: Collecting Runtime Data from an Application Server

Collect runtime data from your application server: Tomcat, WildFly/JBoss or Oracle WebLogic.

Collecting Runtime Data from Apache Tomcat

  1. Open the script file:Windows

    [Your apache-tomcat installation directory]/bin/catalina.bat

    Linux

    [Your apache-tomcat installation directory]/bin/catalina.sh

  2. Place the javaagent flag at the beginning of the script.

    Windows

    if "%1"=="stop" goto skip_instrumentation
set JAVA_OPTS=%JAVA_OPTS% [generated javaagent flag]
:skip_instrumentation

    Linux

    if [ "$1" = "start" -o "$1" = "run" ]; then
export JAVA_OPTS="$JAVA_OPTS [generated javaagent flag]"
fi

    The -javaagent flag must be placed in a single line (cannot be split).

  3. Restart the server and open the following URL in a browser:

    http://localhost:8080/Calculator
  4. Interact with the application and stop the server

The Jtest Agent will write runtime data according to the runtimeData property of the -javaagent flag generated by the mvn package jtest:monitor goal. By default, the runtime data be written to the [path to monitor dir]/monitor/runtime_coverage directory.

Collecting Runtime Data from JBoss and WildFly

Standard Java hierarchical class loaders are not suitable for J2EE servers because all JAR files are always loaded, whether they are used or not; the application cannot load JAR files on demand. Additionally, an adequate solution for restricting visibility between JAR files is not available, which frequently causes conflicts between two versions of one library. This also leads to the creation of big class loaders that contain everything. 

JBoss and WildFly servers use JBoss Modules to overcome these challenges. The implementation of modular, non-hierarchical class loading is also the basis of JBoss OSGi and JBoss Java EE implementations. 

The advantages of this class loader, however, introduces new problems in terms of collecting runtime data from these servers. The Jtest Agent library must be visible to application classes, but it is prevented by JBoss Modules. This is one reason for adding the -javaagent flag. Failing to do so will return ClassNotFoundException. 

For this reason, the jboss.modules.system.pkgs system property should also be used. But there is another problem: JBoss sets this flag in its own scripts. This behavior complicates integration between JBoss and the Jtest Agent because these scripts may overwrite previously set scripts. 

JBoss AS 7.1/JBoss EAP 6.4/WildFly 8.2/9.0

  1. Add the -javaagent flag to the startup script.

    Windows
    a) Open [Your jboss installation directory]/bin/standalone.conf.bat and add the javaagent flag to JAVA_OPTS at the end of the file:

    set "JAVA_OPTS=%JAVA_OPTS% [generated javaagent flag]"

    - Leave ":JAVA_OPTS_SET" as the last line in the file.

    - Place the -javaagent flag in one line (it cannot be split).

    - Add the -XX:-UseSplitVerifier flag to JAVA_OPTS for servers working on Java 7.


    b) Add javaagent classes to jboss.modules.system.pkgs settings by changing the following section from: 

    set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman"

    to

    set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager,com.parasoft.jtest.instrumentation,shaded_parasoft_jtest.com.parasoft.jtest.runtime -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:[JBOSS-INSTALL-DIR]/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-2.1.14.Final.jar -Xbootclasspath/p:[JBOSS-INSTALL-DIR]/modules/system/layers/base/org/wildfly/common/main/wildfly-common-1.5.1.Final.jar"

    Where [JBOSS-INSTALL-DIR] should be replaced with your current JBoss/WildFly installation directory. Also, ensure that the following jars: [JBOSS-INSTALL-DIR]/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-2.1.14.Final.jar and [JBOSS-INSTALL-DIR]/modules/system/layers/base/org/wildfly/common/main/wildfly-common-1.5.1.Final.jar have correct names. The presented versions in the example above are valid only for WildFly 18.0.1-Final version of the application server.
    c) Restart the server using the standalone.bat script.

    Linux

    a) Open [Your jboss installation directory]/bin/standalone.conf and add the javaagent flag to JAVA_OPTS at the end of the file:

    set "JAVA_OPTS=$JAVA_OPTS [generated javaagent flag]"

    - Place the -javaagent flagin one line (it cannot be split).

    - Add the -XX:-UseSplitVerifier flag to JAVA_OPTS for servers working on Java 7.

    b) Add javaagent classes to jboss.modules.system.pkgs settings by changing the following section from:  

    JBOSS_MODULES_SYSTEM_PKGS="org.jboss.byteman"

    to

    JBOSS_MODULES_SYSTEM_PKGS="-Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager,com.parasoft.jtest.instrumentation,shaded_parasoft_jtest.com.parasoft.jtest.runtime -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:[JBOSS-INSTALL-DIR]/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-2.1.14.Final.jar -Xbootclasspath/p:[JBOSS-INSTALL-DIR]/modules/system/layers/base/org/wildfly/common/main/wildfly-common-1.5.1.Final.jar"
    Where [JBOSS-INSTALL-DIR] should be replaced with your current JBoss/WildFly installation directory. Also, ensure that the following jars: [JBOSS-INSTALL-DIR]/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-2.1.14.Final.jar and [JBOSS-INSTALL-DIR]/modules/system/layers/base/org/wildfly/common/main/wildfly-common-1.5.1.Final.jar have correct names. The presented versions in the example above are valid only for WildFly 18.0.1-Final version of the application server.

    c) Restart the server using the standalone.sh script.

  2. Open to the following URL in a web browser:  

    http://localhost:8080/Calculator/
  3. Interact with the application and stop the server.

The Jtest Agent will create a runtimeData.data file in the Jtest target maven directory (target/jtest).The location is written into the .json data file, so you do not need to remember it.

JBoss 6.1/5.1

The jboss.modules.system.pkgs property does not need to be set for older versions of JBoss.

Windows

  1. Open [Your jboss installation directory]/bin/run.conf.bat and add the javaagent flag to JAVA_OPTS at the end of the file: 

    set "JAVA_OPTS=%JAVA_OPTS% [generated javaagent flag]"

    - Leave ":JAVA_OPTS_SET" as the last line in the file.

    - Place the -javaagentflag in one line (it cannot be split).

  2. Restart the server using the run.bat script.

Linux

  1. Open [Your jboss installation directory]/bin/run.conf.bat and add the javaagent flag to JAVA_OPTS at the end of the file:

    set "JAVA_OPTS=$JAVA_OPTS [generated javaagent flag]"

    - Place the -javaagentflag in one line (it cannot be split).

  2. Restart the server using the run.sh script.

Collecting Runtime Data from Oracle WebLogic

  1. Open the script file:Windows

    [Your weblogic installation directory]/user_projects/domains/[your domain]bin/startWebLogic.cmd

    Linux

    [Your weblogic installation directory]/user_projects/domains/[your domain]bin/startWebLogic.sh

  2. Add the -javaagent flag to JAVA_OPTIONS (in the section that starts with the START WEBLOGIC comment). The -javaagent flag must be placed in a single line:
    Windows

    @REM START WEBLOGIC
set JAVA_OPTIONS=%JAVA_OPTIONS% [generated javaagent flag]

    Linux

    # START WEBLOGIC
export JAVA_OPTIONS=$JAVA_OPTIONS [generated javaagent flag]

  3. Restart the server and open the following URL in the browser: 

    http://localhost:7001/Calculator
  4. Interact with the application.
  5. Stop the server.

The Jtest Agent will write runtime data according to the runtimeData property of the -javaagent flag generated by the mvn package jtest:monitor goal. By default, the runtime data be written to the [path to monitor dir]/monitor/runtime_coverage directory.

Step 6: Produce Coverage Report 

Run the Calculate Application Coverage test configuration and pass the static_coverage.xml file and directory to the runtime coverage data using the dedicated -static and -runtime parameters:

java -jar jtestcov.jar -static [path to static_coverage.xml file] -runtime [path/dir]

The path to the static_coverage.xml file must point to the extracted contents of the monitor.zip package, which contains this file.

The path to the runtime_coverage directory is printed to the console as the runtimeData property of the -javaagent VM argument.

  • No labels

Need assistance? Visit our support page