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:
- Driver output -- same as standard driver tests
- Persistence DB -- persistent state in memory is compared against DB data
- Persistence output -- analogous to driver test output comparison, but content is a line item record of all persistence events, which is compared against the expected
output file (i.e. expected persistence events).
Here is a sample persistence output file: '''.out''' file
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: <alaska-bpelse>/bpeljbiadapter/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).
- Build a bpel project, with accompanying compapp project, and deploy.
- 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
- Add test files
- 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).
- 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).
- 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.
- <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:
Persistence Test Configuration
- 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.
- 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.
- 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.
# the operation, with input and output messages
# Input file contains the input message used to instantiate the BPEL instance
# Output file compared to the test's output message
# 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
# initiates the test, sending a message to be processed
# configures the engine channel to help complete the ME pattern executed by test
# initiates the test in recovery mode
# 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.
# A single or comma-delimited list of crash points
# The minimum number of persistence points which must occur before bpel
# can be successfully recovered.
# custom properties - specific to certain tests
# debug properties - launch/suspend debugger socket
#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
#A value of "yes" will skip persistence and just try to run the recover test runs
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:
|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.