BPEL Persistence Tests

Please refer to the Deployment and Execution of BPELs to understand the basic JUnit testing. Persistence and recovery tests are a variation of the basic bpel execution tests.

Running a test in persistence mode involves crashing the test by invoking a System.exit(0) at specified intervals. The engine, running in its own thread, must then be restarted and the bpel's execution is expected to resume.

Persistence tests are evaluated three different ways to determine whether the test passed:

1. Driver output -- same as standard driver tests
2. Persistence DB -- persistent state in memory is compared against DB data
3. Persistence output -- analogous to driver test output comparison, but the file (.out extension) contains a record of the transactions that occured during the test. Each transaction typically has a number individual SQL operations each of which is performed on a specific table. Each line in the .out file represents an individual SQL operation. Each transaction corresponds to a persistence point in the BPEL SE. Since the engine can crash during any of these transactions, they are called CRASHPOINTS. The developer can specify which CRASHPOINTS to test using the test configuration file as shown ahead. It is important to note that the comparison against DB data occurs throughout the test whereas the output file comparison occurs (like the driver tests) at the conclusion of the test.

Persistence Test Setup

The <persist-test-home> directory is located at: open-jbi-components/ojc-core/bpelse/system-test/test/com/sun/jbi/engine/bpel/jbiadaptor/test/persistence
NOTE: Steps 2 and 3 can be accomplished using the TemplateGenerator (refer to Deployment and Execution of BPELs for details on its usage).

1. Build a bpel project, with accompanying compapp project, and deploy.
2. Copy the contents of the deployed composite application to <persist-test-home>/bpels/<test-case-name>/deployedFolder. For example, copy the contents of the folder <appserver-home>\domains\domain1\jbi\system\deployment\Invoke2WayCompApp\com.sun.bpelse-1.0-2_Invoke2WayCompApp-Invoke2Way should be copied to the
   <persist-test-home>/bpels/invoke2Way/deployedFolder.
3. Add test files
   1. Input file -- contains the input XML message, which conforms to JBI WSDL 1.1 message schema. If you're not comfortable writing it by hand,
      run the driver test for the deployed project (Step 1) and copy the XML from the server logs.
      The name of the file must match the INPUT property in the configuration file (see below).
   2. Output file -- contains the output XML message, again conforming to JBI WSDL 1.1 message schema.
      The name of the file must match the OUTPUT property in the configuration file (see below).
   3. Persistence output file -- contains persistence line item information, see sample.
      The name of this file must match the OPERATION property in the configuration file with an extension of ".out" (e.g. "mytestop.out").
      The first time the test is run, this file will be empty. The test writes the output to an identically-named ".out" file (used for comparison) in a "temp" folder,
      which is a sibling to the output folder.
      Note: the physical location of these folders is determined by how you run the tests.
      For example, when running in NB the folders will be in build/classes, but with Eclipse the folders will be where your workspace compiles your project.
   4. <test-case-name>.properties -- The persistence test configuration file. The name of this file should describe the test case and must end with the extension ".properties".
      Each occurence of a .properties file in the input folder will execute a persistence test. Details on how to configure this file are below.

After the above steps, your test project structure should look like the following:

• <persist-test-home>
  • bpels
    • <test-name-folder>
      • deployedFolder
      • <bpel-project>
      • input
        • input.xml
        • <test-case-name>.properties
      • output
        • output.xml
        • <test-operation>.out

Persistence Test Configuration

1. Modify caps.build.properties -- located in common folder (sibling to <persist-test-home>), this file must be updated to point to correct paths, for example.
   (This is the same file in jbicomps/nbbuild/; you can also copy that file to the above mentioned common folder before you run the tests).
   This file is needed because, recovery tests launch a new JVM and hence needs the appropriate classpath. This properties file helps build the classpath.
2. Add a test case method -- add a new test method to com.sun.jbi.engine.bpel.jbiadaptor.test.persistence.PersistenceTesterTest. See other test methods for examples.
3. Configure <test-case-name>.properties -- To run the persistent and recovery tests, the test framework needs to deploy the BPELs, send a message(s) to the engine, associate a delivery channel with the engine, respond on invocations on the channel, and recover. The persistence test framework uses reflection to execute these steps.
   The template configuration file, with detailed instructions follows:
   

# Information used to construct the input message and make a call to the engine.
# service and endpoint values are from the jbi.xml's connection portion.
SERVICE={http://enterprise.netbeans.org/bpel/ScopeVars}PartnerLink1
ENDPOINT=ScopePLinkTypeRole_myRole

# the operation, with input and output messages
OPERATION=ScopeOperation
IP_MESG_TYPE={http://enterprise.netbeans.org/wsdl/ScopeVars}ScopeMessage
OP_MESG_TYPE=
######

# Input file contains the input message used to instantiate the BPEL instance
INPUT=bpels/ScopeTest/scopeVars/input/Input.xml
# Output file compared to the test's output message 
OUTPUT=bpels/ScopeTest/scopeVars/output/Output.xml
DBSTEPS=ScopeVars.out
######

# Class and methods that help the simulator drive the testing and recovery. 
# Custom functionality can be acheived by user defined classes and methods
# Reflection is used to execute the specified methods on the specified class.
# Existing methods may suffice for some tests, but not all
CLASS=com.sun.jbi.engine.bpel.jbiadaptor.test.persistence.UtilityClass
# initiates the test, sending a message to be processed
METHOD=initiateBPInstance
# configures the engine channel to help complete the ME pattern executed by test 
CHANNEL_METHOD=associateInvokeChannel
# initiates the test in recovery mode
RECOVERY_METHOD=recover
######

# Recovery related properties
# This property hints at the stage of recovery development for the specific 
# feature being tested.  If commented out, recovery will not be tested.
#RECOVERY=In Development
# Specify a single, comma-delimited or a range (e.g 1-4). If unspecified, then by 
# default, recovery will be tested for all possible CRASHPOINTS (see the .out files) 
#CRASHPOINTS=
######

# debug properties - launch/suspend debugger socket
DEBUG=false
DEBUG_PORT=10001
#If the flag is "true", During debug mode, we will be able to attach to the 
# debugger only after the test crashed and is recovering the BP instances
SUSPEND_CRASH_ONLY=false

#A value of "yes" will skip persistence and just try to run the recover test runs
NO_PERSISTENCE_RUN=no

Tips on Running Persistence/Recovery (P/R) Tests Locally

Due to the complexity of the P/R test framework (i.e. launching a JVM, mimicking exchange of messages a la the NMR), here are some tips about how to ensure changes made in your development environment are reflected when running the tests locally:

Changes to:	Action:
Deployed resources (*.bpel,*.wsdl, et al.)	Run 'compile-test' target in bpelse
Test configuration (*.properties,*.out,*.xml)	Dependent on IDE; build project to ensure files are copied to output folder (e.g. 'build' in NB, 'output'/'bin' in Eclipse)
Test framework (PersistenceTesterTest,EngineDriver,etc.)	Build 'bpeljbiadapter' project in NB IDE (Note: Eclipse users should build in NB AND Eclipse)
BPEL Engine	Build 'bpelcore' project in NB IDE

TODO: Specify engine id when launching EngineDriver thread.
TODO: This junit framework can also be extended to support the random machine crashes.
TODO: Consider allowing multiple methods to be listed in *METHOD properties (to be executed in sequence).
TODO: Prepare high-level sequence diagram of persistence test execution.

This page (revision-8) was last changed on 10-Jan-08 18:11 PM, -0800 by Prashant Bhagat.
This page was created on 22-Mar-07 18:15 PM, -0700 by VinayMulakkayala.

More info...