
----------------------------------------------------------

BPELUnit - A BPEL testing framework
www.bpelunit.org

----------------------------------------------------------

Welcome to BPELUnit!

BPELUnit is a framework for testing BPEL compositions. BPEL stands for Business Process Execution Language
and is an XML-based language for composing, or orchestrating, web services. BPEL programs are
called Business Processes.

The BPELUnit framework allows testing of BPEL processes by specification of a test harness for the BPEL
process. The test harness consists of sequences of input/output operations which are executed
by the framework on behalf of the client and every partner of the BPEL process, thus forcing the BPEL
process to execute a certain path. A test case passes if all operations have been carried out successfully 
in a test run.

BPELUnit test cases are grouped into test suites, which reside in Test Suite Specification files (.bpts).
These specification files are XML-based and may be created and edited in any text editor. The BPELUnit
runners, like the command line client and the ant launcher in this package, take .bpts files as input.

The test suite specification format is described in the file testspec.txt.

This package contains two clients for BPELUnit. Installation is described below.

* The command line client allows calling BPELUnit from the command line.
* The Ant launcher allows calling BPELUnit from Ant build files.


CONTENTS
---------------------

1. Installation of the framework
2. Installation of deployers
3. Using the command line client
4. Using the Ant launcher


1. INSTALLATION OF THE FRAMEWORK
---------------------

Unzip the BPELUnit package somewhere on your disk. Add a BPELUNIT_HOME env variable.
The BPELUNIT_HOME env must point to the base directory of the BPELUnit package (not
to any bin or lib directy) and should be separated by a trailing slash.

2. INSTALLATION OF DEPLOYERS
---------------------

BPELUnit is a real-life testing tool, meaning the BPEL processes to be tested are actually
deployed into an engine and invoked there. The BPELUnit framework contains deployers for
two BPEL engines: The ActiveBPEL engine (www.activebpel.org) and the Oracle BPEL Process Server
(http://www.oracle.com/technology/products/ias/bpel/).

The ActiveBPEL deployer does not need any special configuration.

The Oracle deployer must first be installed. The "BPELUnit OracleUnDeployer" is a small script/java app which 
deploys and undeploys processes to an Oracle BPEL server. The script is designed to live inside an Oracle 
BPEL Server installation, like the internal Oracle tools.

The installation steps are described in the file /OracleUnDeploy/INSTALL.


3. USING THE COMMAND LINE CLIENT
---------------------

The BPELUnit command line client allows you to call BPELUnit from the command line. The BPELUnit
runner will execute a specified Test Suite Specification, producing either a plain informational
message (indicating how many tests passed, failed, and errored) or a more detailed, but still
human-readable progress report, depending on the command line options.

To use the command line runner, simply call bpelunit in the $BPELUNIT_HOME directory with the
test suite file name as a parameter. You must call bpelunit from the directory of the test suite
file if you have relative paths specified in your .bpts file, otherwise these files will not
be found.

The optional command line flag "-v", specified before the test suite specification file name, enables
a more detailed progress report.


4. USING THE ANT LAUNCHER
---------------------

The BPELUnit Ant launcher allows you to call BPELUnit from inside a build script. The BPELUnit
Ant task will execute a specified Test Suite Specification, producing either a plain informational
message (indicating how many tests passed, failed, and errored) or a rich XML format which contains
all details of the test run and can then be transformed by XLST or processed by other means.

To use the BPELUnit Ant task in your build files, you must first copy the lib/truezip-6.jar file into
your Ant library directory. Once you're done, you need to  declare the task in your build.xml file:

	<typedef name="bpelunit" classname="net.bpelunit.framework.ui.ant.BPELUnit">
		<classpath>
			<fileset dir="${BPELUNIT_HOME}/lib" />
		</classpath>
	</typedef>
	
As you can see, the typedef contains an internal classpath element, which points to the lib directory
of BPELUnit. The task will thus find its libraries, there is no need to have them on the CLASSPATH when
starting Ant.

Afer the declaration, you may use the BPELUnit ant task like this:

	<bpelunit testsuite="somedir/someSuite.bpts" bpelunitdir="${BPELUNIT_HOME}">
			<output style="XML" file="xmloutput.xml" />
			<logging level="DEBUG" file="logoutput.txt" />
	</bpelunit>

The "testsuite" and "bpelunitdir" attributes are required. Inside of the bpelunit task, you may
use the following two sub-elements, which may each occur multiple times:

* <output style="style" file="file"? />. Each output declaration produces a report of the test run. There are two styles available:
  XML (meaning a rich XML format which contains all details of the test run) or PLAIN, a simpler
  human-readable format which does not contain the details. If the file element is not specified, the
  output is sent to the command line; if it is specified, the output is sent to the specified file.
  
* <logging level="level" file="file"? />. Each logging declaration sends the BPELUnit runtime log to the specified location. You may
  specify a level of logging (these are log4j levels, see below) and an optional file. If the file
  element is not specified, the output is sent to the command line.
  
  The possible log levels are: 
  
   	* SEVERE (highest value)
	* WARNING
	* INFO
	* CONFIG
	* FINE
	* FINER
	* FINEST  (lowest value)	

  In most cases, the INFO level should be sufficient.
  
  

