This topic explains how to use SOAtest to perform runtime error detection on Java applications.

Sections include:

Runtime Error Detection Overview

SOAtest can perform runtime error detection as functional tests or penetration tests execute.

Runtime error detection exposes critical defects that occur as the application is exercised. Defects are reported with unprecedented accuracy. This is key for efficiently identifying defects that manifest themselves only at runtime (for example, file overwrites) and to pinpoint the root causes responsible for application crashes, performance degradation, and unpredictable behavior.

SOAtest correlates each reported error with the functional test that was being run when the error was detected. This correlation between violations and functional tests allows you to trace each reported error to particular use cases against your application.

Categories of errors detected include:

• Application crashes
• Eclipse development
• Exceptions
• Functional Errors
• File I/O
• Graphical User Interface
• Database
• Network
• Optimization
• Portability
• Security
• Servlets
• Threads & Synchronization

Preparing the Server

Before you can monitor an application, you must copy the appropriate jar files to the machine that is running your application server, then configure the application server to use the jars. This is done as follows:

1. Copy  insure.jar and insureimpl.jar from [Jtest_install_dir]/plugins/com.parasoft.xtest.jtest_[version]/resources/ to a directory on the server with the application you want to check.
2. If the server is running, stop it.
3. In your startup script, add the -javaagent command to the existing Java arguments.
   • For details, see javaagent Command Details.
   • Be sure to add the optional trace_to_xml parameter if you also want to monitor the application’s internal behavior as your functional tests execute. See the box below for details.
4. Restart the server.

The server will start as usual, but with the specified package classes instrumented.

javaagent  Command Details

Basics

The following invocation-time parameters are required:

For Applications Running from Eclipse or Application Servers

Applications that define their own class loaders (i.e. Eclipse, JBoss and Tomcat) need insure.jar added to the boot classpath. To monitor those applications, add to the launch VM arguments:
-javaagent:"<path_to_jar>\insure.jar=soatest,port=<port>",instrument=<my.package.prefix> -Xbootclasspath/a<path_to_jar>\insure.jar

For instance, you may use:
-javaagent:"/home/user/parasoft/insure.jar=soatest,port=5060",instrument=com.mycompany.onlinestore -Xbootclasspath/a:/home/user/parasoft/insure.jar

For other (Standalone) Java Applications

For other (standalone) Java applications,  you do NOT need to add insure.jar to the boot classpath. For instance, you may use:
java -javaagent:"C:\Program Files\Parasoft\insure.jar=soatest,port=5050",instrument=com.mycompany.myapp

Customizing the Test Configuration

Before you can perform runtime error detection, you need to customize a Test Configuration to specify which application you want to check and what errors you want to look for. To do this:

1. Create a new Test Configuration as described in Configuring Test Configurations and Rules for Policies.
2. In the Execution> Runtime Error Detection tab, do the following:
   1. Enable Perform runtime error detection.
   2. In the  Server agent host field, enter the host of the server running the application you want to check.
   3. In the Server agent port field, enter the port of the server running the application you want to check.
   4. Enable/disable rules to specify what types of errors you want detected.

Detecting Errors

To perform runtime error detection on your application:

1. Select the node for the functional tests you want to execute with runtime error detection.
2. Run the custom Test Configuration (described in the previous section).

Errors detected will be reported as follows:



The same detail is also provided in reports.

Note that SOAtest correlates each reported error with the functional test that was being run when the error was detected. This correlation between violations and functional tests allows you to trace each reported error to particular use cases against your application.

Tips on Configuring Specific Web Servers for Runtime Error Detection

This section provides detailed instructions for configuring popular Web application servers for use with SOAtest’s runtime error detection.

JBoss App Server 3.0.4

1. Make a backup of JBossInstallRoot/bin/run.bat (for Windows) or run.sh (for UNIX).
2. In the original file, add the JVM arguments to the JAVA_OPTS variable. For example:
   set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m -javaagent:[eventmonitor directory]/insure.jar=soatest,port=[port number],instrument=[class_name.method_name(jni_sig)],trace=[class_name.method_name(jni_sig)] -Xbootclasspath/a:[eventmonitor directory]/insure.jar

Sun Java System Application Server

1. Logon to the Admin Console (accessed through port 4848, by default).
2. Click the JVM Settings link.
3. Click the JVM Options link.
4. Click the Add JVM Options link.
5. Add the argument "-javaagent:[eventmonitor directory]/insure.jar=soatest,port=[port number],instrument=[class_name.method_name(jni_sig)],trace=[class_name.method_name(jni_sig) ] -Xbootclasspath/a:[eventmonitor directory]/insure.jar" in the newly-created text field.
6. Click Save.
7. Restart the server.

WebSphere 6.1

1. On a machine that can start the server/application, copy the entire eventmonitor directory from the SOAtest installation to the machine that is running the application you want to check (for instance, c:\eventmonitor).
2. Go to http://<HOST>:9060/ibm/console/ to view the WebSphere Application Server Administrative Console.
3. In the left panel, select Servers> Application Servers. A list of Application Servers will open.
   
   
   
   
4. In the list of Application Servers, click the name of the server you want to configure. The Configuration tab for the selected server will open.
   
   
   
   
5. Click the Process Definition property, which is listed under Server Infrastructure> Java and Process Management. The Process Definition controls will open.
   
   
   
   
6. In the Additional Properties area, select the Java Virtual Machine property. The Java Virtual Machine controls will open.
   
   
   
   
7. Enable Debug Mode and add the JVM arguments to the end of the current Debug Arguments. Use -javaagent:[eventmonitor directory]/insure.jar=soatest,port=[port number],instrument=[class_name.method_name(jni_sig)],trace=[class_name.method_name(jni_sig) ] -Xbootclasspath/a:[eventmonitor directory]/insure.jar
8. Scroll to the bottom of the page and click Apply to save your changes to the local configuration.
9. Click Save to save the change to the master configuration.

WebSphere 5.x

SOAtest will automatically configure the extra JVM arguments for WebSphere 5.1 local test environment servers that are launched from within the WSAD 5.1 IDE. To configure all other WebSphere 5.x servers for runtime error detection, use the following procedure:

1. Go to http://<Host>:9090/admin (default port is 9090) to view the WebSphere Application Server Administrative Console.
2. In the left panel, select Servers> Application Servers.
   
   
   
   
3. In the list of Application Servers, click the name of the server you want to configure. The Configuration tab for the selected server will open.
   
   
   
   
4. Click the Process Definition property, which is listed in the Additional Properties area. The Process Definition controls will open.
   
   
   
   
5. In the Additional Properties area, select the Java Virtual Machine property. The Java Virtual Machine controls will open.
   
   
   
   
6. Enable Debug Mode and add the JVM arguments to the Debug Arguments Use
   -javaagent:[eventmonitor directory]/insure.jar=soatest,port=[port number],instrument=[class_name.method_name(jni_sig)],trace=[class_name.method_name(jni_sig) ] -Xbootclasspath/a:[eventmonitor directory]/insure.jar
   • Websphere Application Server version 5 may also require the -Xnoagent JVM argument for operation with SOAtest. -Xnoagent will fix the java.lang.NoClassDefFoundError: sun/tools/agent/Agent WAS 5.x startup problem.
7. Scroll to the bottom of the page and click Apply to save your changes to the local configuration.
8. Click Save to save the change to the master configuration.

WebLogic 8.1 (using Sun JVM)

1. Make a backup of the startup script used to start the server.
   • To find the path, right-click the startup menu, then choose Properties from the short-cut menu. The path is typically C:\bea\user_projects\domains\mydomain\startWebLogic.cmd (Windows) or .sh (UNIX).
2. In the original script, append the JVM arguments to the set JAVA_OPTIONS  line (if this line is not yet added, add it now). For example:
   set JAVA_OPTIONS=-javaagent:[eventmonitor directory]/insure.jar=soatest,port=[port number],instrument=[class_name.method_name(jni_sig)],trace=[class_name.method_name(jni_sig) ] -Xbootclasspath/a:[eventmonitor directory]/insure.jar

JBossService

If you use JBossService.exe through the command line to start JBoss:

1. Download JavaService-2.0.7.zip from http://forge.objectweb.org/project/show-files.php?group_id=137&release_id=1267.
2. Unzip the file to any directory.
3. Copy and paste JavaService.exe to your application’s bin directory, then rename it JBossService.exe.
4. Modify run.bat as follows:
   1. Add the following line to set the  Java options, including the runtime error detection arguments (which can be cleaned up by setting globals).
      • Example for connecting to a running application:
        set JAVA_OPTS=-Dprogram.name=%PROGNAME% -Xms128m -Xmx512m "-Djava.endorsed.dirs=%JBOSS_ENDORSED_DIRS%" -javaagent:[eventmonitor directory]/insure.jar=soatest,port=[port number],instrument=[class_name.method_name(jni_sig)],trace=[class_ name.method_name(jni_sig)] -Xbootclasspath/a:[eventmonitor directory]/insure.jar
   2. Configure the script to invoke JBossService.exe with monitoring.

      • For example, for an application named Showcase, instead of calling "%JAVA%" %JAVA_OPTS% "-Djava.endorsed.dirs=%JBOSS_ENDORSED_DIRS%" -classpath "%JBOSS_CLASSPATH%" org.jboss.Main %*,add the following lines:

        rem install Showcase (routes system.out and system.err to the runtimeerrordetection directory) JBossService.exe -install Showcase "%JAVA_HOME%\jre\bin\server\jvm.dll" "-Djava.class.path=%JBOSS_CLASSPATH%" %JAVA_OPTS% -start org.jboss.Main -stop org.jboss.Main -params %* -method systemExit -out C:\runtimeerrordetection\stdoutJBOSS.log -err C:\runtimeerrordetection\stderrJBOSS.log -overwrite   rem start the Showcase service net start Showcase

        Note This installation should only be performed once. Ideally, the run.bat file should only contain the start command; the installation can be done through the command line. If the service has already been installed, you will need to reinstall it with the appropriate VM arguments. You can stop or uninstall the service with the following commands: net stop Showcase JBossService.exe –uninstall Showcase

5. Execute the run.bat file as normal. The command prompt that opens should display the following printout:
   
   **********
   The Showcase service is starting.
   The Showcase service was started successfully.
   **********
   
   Note that there is a delay when the printout finishes and when JBoss has actually been started. 

6. Execute some application transactions as normal, then verify that the monitoring is working.

   Note The start, stop, install, and uninstall commands can all also be executed through the command line as well as through run.bat.