Skip Headers
Oracle® BPEL Process Manager Developer's Guide
10g (10.1.3.1.0)

Part Number B28981-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

20 Testing BPEL Processes

This chapter describes how to create, deploy, and run test cases that automate the testing of BPEL processes. Test cases enable you to simulate the interaction between a BPEL process and its Web service partners prior to deployment in a production environment. This helps to ensure that a process interacts with Web service partners as expected by the time it is ready for deployment to a production environment.

This chapter contains the following topics:

See Also:

BPEL test suite sample files located at:

20.1 Overview of the BPEL Test Framework

Oracle BPEL Process Manager provides an automated test suite framework for creating and running repeatable tests on a BPEL process.

The test suite framework provides the following features:

The following sections provide an overview of test suite concepts:

20.1.1 Test Cases Overview

The test framework supports two types of test cases:

  • Unit test — Represents a single test case in a test suite. For example, assume you have a BPEL process in which an offer for a product is submitted to two Web service suppliers. You can create a test in your test suite to emulate the behavior of these Web service partners in this interaction with your BPEL process.

  • Composite test — Consists of a test where BPEL partners are not emulated, but instead are invoked with test case information. For example, assume you have a BPEL process that calls a subprocess that contains a human workflow step. You may want to test the interactions between the two BPEL processes, but not have to manually perform the human workflow approval step. In this case, you can create a composite test for the main process by passing a test case name to the subprocess when it is invoked. This test case can emulate the human workflow step; this means that no human interaction is required.

20.1.2 Test Suites Overview

Test suites consist of a logical collection of one or more test cases. Each test case contains a set of commands to perform as the test instance is executed. The execution of a test suite is known as a test run. Each test corresponds to a single BPEL instance.

20.1.3 Emulations Overview

Emulations enable you to simulate the behavior of Web service partners with which your BPEL process interacts during execution. Instead of invoking a partner link, you can specify a response.

20.1.4 Assertions Overview

Assertions enable you to verify variable data or process flow. You can perform the following types of assertions:

  • Simple Value Assert — Compare the value of a selected string or number variable to an expected value. An error message that you define is displayed if a comparison fails.

  • XML Assert — Compare the element values of an entire XML document to the expected element values. An error message that you define is displayed if a comparison fails.

  • Activity Executed Assert — Execute an activity a specified number of times. This ensures that an activity executes the correct number of times. This is useful for verifying process flow.

20.1.5 Process Code Coverage Overview

Code coverage provides a method for calculating the completeness of the executed tests. This is calculated as the percentage of simple activities executed at least once, compared to the number of simple activities defined in the BPEL process. Simple activities are nonstructured activities such as invoke, receive, reply, and assign activities.

20.1.6 JUnit Support Overview

JUnit is an open source test framework to use for creating regression tests for Java applications. JUnit is an instance of the xUnit architecture for unit testing frameworks.

By default, the reports created during test suite execution are in JUnit XML format.

Note:

While reports display in JUnit XML format, the tests from which reports are created are Oracle BPEL Process Manager tests, and not JUnit tests.

See Also:

20.2 Components of a Test Suite

This section describes the test components that comprise a test case. The PriceFinder demonstration is used as an example. Methods for creating and importing these tests into your process are described in subsequent sections of this chapter.

This section contains the following topics:

See Also:

  • SOA_Oracle_Home\bpel\samples\demos\BPELTest\PriceFinder

  • SOA_Oracle_Home\bpel\samples\references\BPELTest

20.2.1 Process Initiation

You first define the operation of your process. The following section defines the operation of initiate to initiate the PriceFinder process. The initiation payload is also defined in this section:

<BPELTest processName="PriceFinderWithTests"
          xmlns="http://xmlns.oracle.com/bpel/instancedriver">
   <initiate operation="initiate">
      <inboundMessage>
         <part name="payload">
            <content>
               <PriceProviderProcessRequest
 xmlns="http://xmlns.oracle.com/PriceProvider">
                  <manufacturer
 xmlns="http://xmlns.oracle.com/PriceProvider">Oracle</manufacturer>
                  <ItemName xmlns="http://xmlns.oracle.com/PriceProvider">BPEL
 PM</ItemName>
                  <customerLocation
 xmlns="http://xmlns.oracle.com/PriceProvider">94065</customerLocation>
               </PriceProviderProcessRequest>
            </content>
         </part>
      </inboundMessage>
   </initiate>
. . .
. . .

20.2.2 Emulations

You create emulations to simulate the message data that your BPEL process receives from Web service partners. PriceFinder invokes two pricing services:

  • FlakyPriceProvider

  • FreeShippingPriceProvider

The following test code instructs Oracle BPEL Process Manager to first skip the outbound invocation to the FreeShippingPriceProvider service and then emulate receiving a response:

<BPELTest processName=LoanFlow" processRevision="1.0"
             xmlns="http://xmlns.oracle.com/bpel/instancedriver"
. . .
. . .
    <!-- *****************************************
         Skip outbound invoke 
         ***************************************** -->
    <activityDriver name="FreeShippingInvoke">
      <emulate/>
    </activityDriver>
    <!-- *****************************************
         Emulate the FreeShippingPriceProvider Service 
         ***************************************** -->
    <activityDriver name="FreeShippingReceive" firstIteration="1"
                   lastIteration="1">
      <emulate duration="PT">
         <inboundMessage>
            <part name="payload">
               <content>
<PriceProviderProcessResponse xmlns="http://xmlns.oracle.com/PriceProvider">
    <itemPrice>70</itemPrice>
    <shippingCost>0</shippingCost>
    <deliveryTime>P3D</deliveryTime>
</PriceProviderProcessResponse>
               </content>
            </part>
         </inboundMessage>
      </emulate>   </activityDriver>
. . .
. . .

In the first test, the emulate element is empty. This is because the activity is a one-way invoke, and is skipped. In the second test, a receive activity is emulated. This means you must specify the inbound message.

20.2.3 Assertions

You create assertions to validate a variable or an entire XML document at a point during BPEL process execution.

<BPELTest processName=LoanFlow" processRevision="1.0"
. . .
. . .
 <activityDriver name="choosePrice">
    <assertValue variableName="outputVariable" partName="payload"
                 comparisonMethod="number" fatal="true" patternMatch="false">
      <message>The item price is incorrect!</message>
      <actualPath>/ns2:PriceProviderProcessResponse/ns2:itemPrice</actualPath>
      <expected>65</expected>
    </assertValue>
. . .
. . .

This test tells Oracle BPEL Process Manager that after the choosePrice activity has completed, ensure that the item price content in the outputVariable variable matches the content specified.

Note:

Test case content can also be created from the audit trail in Oracle BPEL Control.

20.2.4 Include Files

Large portions of tests typically stay the same across different test cases. To avoid having to duplicate large sections of test files, tests can include other tests and then selectively override particular tests to create various test cases. These are known as baseline tests. Baseline tests do not run on their own; they exist only to be included by other tests.

Including a baseline test in a test case brings everything from the baseline test into the test case. If a particular action in the baseline file is not needed, it can be overridden in the test case.

For example, you can define the process operation and payload information shown in "Process Initiation" in a separate file named baseline.xml. The baseline test must be stored in the includes directory of your test suite in Oracle JDeveloper:

In your main test case file, you call this file as follows:

<BPELTest processName="PriceFinderWithTests"
          xmlns="http://xmlns.oracle.com/bpel/instancedriver"
   <include>baseline.xml</include>
. . .
. . .

See Also:

"Creating Test Suites in Oracle JDeveloper" for information about creating these test components

20.3 Creating Test Suites in Oracle JDeveloper

You first create a test suite in which you then create or import test cases. There are several methods for adding test cases to a test suite:

This section contains the following topics:

Note:

Do not enter a multibyte character string as a test suite name or test case name. Doing so causes an error to occur when the test is executed from Oracle BPEL Control.

20.3.1 Creating Test Suites in Oracle JDeveloper

This section describes how to create test suites for a BPEL process in Oracle JDeveloper.

  1. Expand the BPEL process in which to create a test suite in the Application Navigator.

    This displays the Test Suites folder under Integration Content.

  2. Right-click Test Suites and select Create Test Suite.

    Description of ts_create.gif follows
    Description of the illustration ts_create.gif

  3. Enter a test suite name (for example, logicTest).

  4. Click OK.

    The test suite is created beneath the Test Suites folder in the Application Navigator:

    Description of ts_dir.gif follows
    Description of the illustration ts_dir.gif

    The following operating system directory is also created:

    JDev_Oracle_Home\jdev\mywork\application_name\
    process_name\bpel\testsuites\test_suite_name
    
    

    Two subdirectories for adding additional test files are also created beneath test_suite_name: includes and messages. These subdirectories are represented by the Includes tab and Message Instance Files tab, respectively, of the Edit Test Suite window, which is described in Step 1 of "Importing Test Cases in Oracle JDeveloper".

    Note:

    You cannot create test suites within other test suites. However, you can organize a test suite into subdirectories.

20.3.2 Importing Test Cases in Oracle JDeveloper

This section describes how to import test cases into a test suite in Oracle JDeveloper.

  1. Right-click the test suite name you entered in Step 3 of "Creating Test Suites in Oracle JDeveloper" and select Edit Test Suite.

    This displays the Edit Test Suite window.

    Description of ts_edit.gif follows
    Description of the illustration ts_edit.gif

    You can create the content for test cases manually or through audit trail output from Oracle BPEL Control. You then import the files into Oracle JDeveloper. You can validate a test case in the Application Navigator by right-clicking it and selecting Validate XML.

    This window consists of the following tabs for importing test cases:

    Tab Description
    General The tab enables you to add test cases to your test suite.

    Add a test file by clicking Add. These files are added to the following directory:

    JDev_Oracle_Home\jdev\mywork\application_name\
    process_name\bpel\testsuites\test_suite_name
    

    You can also select to add this test file as a baseline test. A baseline test is a generic test that can be imported and used by other tests. These files enable you to factor out common testing actions so they do not need to be repeated in multiple files.

    Includes This tab enables you to add baseline (include) test cases.

    Add a baseline test file by clicking Add. These files are added to the following directory:

    JDev_Oracle_Home\jdev\mywork\application_name\
    process_name\bpel\testsuites\test_suite_name\includes
    

    Baseline files consist of generic tests that do not run on their own. Instead, these tests are imported and called by other tests.

    Including a baseline test in a test case brings everything from the baseline test into the test case. If a particular action in the baseline is not desired, it can be overridden in the test case.

    Message Instance Files This tab enables you to add emulated message instance test cases.

    Add a message instance test file by clicking Add. These files are added to the following directory:

    JDev_Oracle_Home\jdev\mywork\application_name\
    process_name\bpel\testsuites\test_suite_name\messages
    

    Message instance files provide a method for simulating the message data received back from Web service partners. You can manually enter the received message data into this XML file or copy it from audit trail output in Oracle BPEL Control.

    Importing message instance files enables you to reduce the test file size and improve readability.


  2. If you want to view the XML source of the test case, select the file in the Application Navigator and click Source.

  3. Edit the file as necessary.

20.3.3 Creating Test Cases in Oracle JDeveloper

You can create an empty test case in your test suite.

  1. Right-click the test suite name you entered in Step 3 of "Creating Test Suites in Oracle JDeveloper" and select Create BPEL Test.

  2. Enter the following details:

    Field Value
    Name Enter a name for the test case.
    Test Suite Select the test suite in which to place this test file.
    Add as Baseline Test Select this check box if you want to make this a baseline test case.

  3. Click OK.

  4. Select this file in the Application Navigator and click Source.

  5. Edit the file to include all necessary test details.

20.3.4 Editing Test Cases in Oracle JDeveloper

Test cases consist of emulations, assertions, and external calls. You can add these actions to test cases in the test mode of Oracle JDeveloper.

  1. Double-click a test case beneath the Test Suites folder in the Application Navigator.

    Description of ts_xml.gif follows
    Description of the illustration ts_xml.gif

    The BPEL process in Oracle JDeveloper is refreshed to display in test mode. This mode enables you to define test information. No other modifications, such as editing the property windows of activities, can be performed in this node.

    Activities on which these actions have already been defined display special icons in the upper right corner.

    Description of ts_icon.gif follows
    Description of the illustration ts_icon.gif

  2. Right-click an activity to display a list of test actions that can be performed.

    Description of ts_designer.gif follows
    Description of the illustration ts_designer.gif

  3. Select one of the following menu options and see the corresponding section for details:

20.3.4.1 Creating Emulations in Oracle JDeveloper

You create emulations to simulate either message data, fault data, or both types that your BPEL process receives from Web service partners. The fields that display on this window are based on the activity type selected (an invoke or receive are supported) and the radio buttons selected at the top of this window:

Notes:

  • One-way invokes can be skipped. This is because these types of invokes do not receive any data from the partner link.

  • You can override the emulations defined in the top-level test case added in the Edit Test Suite - General tab by clicking Override Included Emulation in the BPEL Test Settings - Emulate tab.

20.3.4.1.1 Emulating Inbound Messages

Select this check box to send an inbound message from a client, then select the type of return message data to simulate from the Web service partner. This feature is available for receive activities and two-way invoke activities.

  1. Select Emulate Inbound Message.

  2. Enter the following details:

    Field Value
    Operation This field is automatically completed with the operation type for the activity (for example, a process operation in an invoke activity).
    Message This field is automatically completed with the path to the inbound message.
    Part Select the part of the inbound message (for example, a payload).
    Value
    • Enter Manually

    • Load From File

    Create a simulated message to return from a Web service partner:

    Click to enter message data in the Enter Value field.

    Click the flashlight icon to load message data from a file.

    Duration Enter the amount of time to wait for the message to be delivered from the Web service partner. This field displays for two-way invoke activities.

    An example of this window with completed content is shown below:

    Description of ts_emul2.gif follows
    Description of the illustration ts_emul2.gif

20.3.4.1.2 Emulating Faults

Select this check box to send an inbound system fault from a client. Then, select the type of return fault message to simulate from the Web service partner. This enables you to test fault handling capabilities in your process. This feature is available for invoke activities.

  1. Select Emulate Fault.

  2. Enter the following details:

    Field Value
    Namespace URI A fault must have a unique qualified name (QName). This activity must provide a name for the fault and optionally provide a variable of data that provides further information about the fault.

    Click the flashlight icon to select the fault to monitor. The Namespace URI field is automatically completed with a URL path based on your fault selection.

    Local Part Displays the local part selection you make for the Namespace URI field. For example, if you select a Web service partner with an associated fault named NegativeCredit, then the name NegativeCredit is added to this field.
    Part Select the message part containing the fault (for example, a payload).
    Value
    • Enter Manually

    • Load From File

    Create a simulated fault message to return from a Web service partner:

    Click to enter message data in the Enter Value field.

    Click the flashlight icon to load message data from a file.


    An example of this window with completed content is shown below:

    Description of ts_emul3.gif follows
    Description of the illustration ts_emul3.gif

    Note:

    For one-way invokes, only system faults can be emulated. For two-way invokes, both system and user-defined business faults can be emulated.
20.3.4.1.3 Emulating BPEL or Partner Tests

In the case where the partner is a BPEL process, you can pass a test case for this partner to execute. This is useful if you want to test the interaction between your BPEL processes, but not any external partners. For example, assume you have a main BPEL process that calls a subprocess that in turn calls human workflow from a test for the main BPEL process. Instead of emulating the subprocess, you can invoke a test case of the subprocess that emulates the human workflow service. This enables you to test the interoperability of your BPEL processes without having to invoke the human workflow service. The name of this radio button is based upon the type of activity selected. For one-way invoke activities, the name is Call Partner Test. For two-way invoke activities, the name is Call BPEL Test. For receive activities, this radio button is disabled.

  1. Select Call Partner Test or Call BPEL Test.

  2. Enter the name and relative location of the test in the test suite to run.

    An example of this window with completed content is shown below:

    Description of ts_emul4.gif follows
    Description of the illustration ts_emul4.gif

20.3.4.2 Creating Assertions in Oracle JDeveloper

You perform assertions to verify variable data or process flow. Variable data assertions enable you to validate test data in a variable as a process is executed. This is done by extracting a value from a variable or an XML document and comparing it to an expected value. To verify process flow, you can assert the number of times that an activity has been executed.

  1. Click Create to display a list of tests.

    Description of ts_asserts.gif follows
    Description of the illustration ts_asserts.gif

  2. Select a test and see the corresponding section for details.

    Selection See Section...
    Value Assert "Creating Value Asserts"
    Activity Executed Assert "Creating an Activity Execution Assert"
    XML Assert "Creating XML Asserts"

20.3.4.2.1 Creating Value Asserts

This test compares the value of a selected string or number variable to an expected value. The XPath expression specified must resolve to a simple type (for example, string, number, and so on).

  1. Enter the following details:

    Field Value
    Variable Click the flashlight icon to select a variable XPath value. The value for this variable is extracted during testing and compared to the expected value defined below.
    Part Displays the part selection you make for the Variable field.
    Actual Path Displays the path selection you make for the Variable field.
    Comparison Method Select the variable value type to perform a string comparison or numerical comparison.
    Expected Enter the value you are expecting the variable to contain.
    Pattern Match Select if the value entered in the Expected field is a regular expression pattern that you want to compare (for example, [0-9]*).
    Error Message Enter a message to display if the assertion fails.
    Fatal Select this check box if you want the assertion to be fatal. This causes the instance to immediately terminate. If not selected, the instance continues to execute.

    Warning: For this release, fatal assertions are not supported at runtime. Create nonfatal assertions only. Test instances with fatal assertions hang and can impact Oracle BPEL Server performance.


    An example of this window with completed content is shown below:

    Description of ts_valueassert.gif follows
    Description of the illustration ts_valueassert.gif

20.3.4.2.2 Creating an Activity Execution Assert

This test executes an activity a specified number of times. This provides a method for verifying that an activity executes the correct number of times (for example, ensuring that a while activity executes the correct number of times).

  1. Enter a value for the number of times to execute this activity.

20.3.4.2.3 Creating XML Asserts

This test compares the element values of an entire XML document to the expected element values.

  1. Enter the following details:

    Field Value
    Variable Click the flashlight icon to select a variable XPath value. The element value for this variable is extracted during testing and compared to the expected element value defined below.
    Part Displays the part selection you make for the Variable field.
    Actual Path (Optional) Displays the path selection you make for the Variable field.
    Comparison Method Specify the strictness of the comparison. For most purposes, xml-similar is sufficient. xml-identical can be used when the comparison must be exact (for example, element ordering).
    Expected Value Select a method for comparing the values:
    • Enter Manually
    Select and manually enter the element value you are expecting the variable to contain.
    • Load From File
    Select and click the flashlight icon to choose a message file containing the element value you are expecting the variable to contain.
    Error Message Enter a message to display if the assertion fails.
    Fatal Select this check box if you want the assertion to be fatal. This causes the instance to immediately terminate. If not selected, the instance continues to execute.

    Warning: For this release, fatal assertions are not supported at runtime. Create nonfatal assertions only. Test instances with fatal assertions hang and can impact Oracle BPEL Server performance.


    An example of this window with completed content is shown below:

    Description of ts_xmlassert.gif follows
    Description of the illustration ts_xmlassert.gif

20.3.4.3 Creating External Calls in Oracle JDeveloper

External calls provide an advanced method for performing user actions during the execution of a test case. You specify a fully qualified Java class name for the command. When the test case reaches the activity where the external call is set, the specified Java class is called with the provided arguments. This class must implement the com.oracle.services.bpel.test.ITestCallHandler interface. At run time, this class must be in the ant classpath when running the task. Call handlers are not supported when running tests from Oracle BPEL Control.

  1. Click Create.

    The External Call window appears.

  2. Click Create to create a default argument name and value in the table.

  3. Place your cursor inside the default values for the Name and Value columns, remove the default values, and enter appropriate details.

  4. If you want to execute this command before this activity is executed, select the Do Before Activity check box. Otherwise, the call is executed after the activity.

    An example of this window with completed content is shown below:

    Description of ts_extcalls.gif follows
    Description of the illustration ts_extcalls.gif

  5. Click OK.

    When the call is executed, these arguments are passed to the Java class.

See Also:

  • Oracle BPEL Process Manager Client API Reference:

    SOA_Oracle_Home\bpel\docs\apidocs
    

20.3.5 Creating a Test Case from Oracle BPEL Control

You can create the contents for your test case through audit trail output from Oracle BPEL Control. This provides two benefits:

  • A quick method for creating a baseline test when first starting.

  • A method for converting an error scenario identified during development into a test case. You capture the use case that exposed the bug, add specific data assertions, and add the test to a test suite to run regularly as a regression test. This enables you to ensure that the bug does not re-appear in the future.

  1. Log into Oracle BPEL Control by selecting Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > BPEL Control.

  2. Log in as oc4jadmin/password.

    where password is the oc4jadmin password you entered during installation.

  3. Click Instances.

  4. Select a specific instance from which to create test file content.

  5. Click Test.

    If the instance has not yet completed or if the test was already initiated as a test case, you cannot save this instance as a test case.

  6. Select a method:

    1. Click Save as unit test (.xml) to save the contents to a test file. In this case, all partners are emulated.

    2. Click Save as composite test (.zip) to save the contents of multiple tests to a zip file. In this case, BPEL partners are called with test case information while other partners (like human workflow) are emulated.You must then unzip this file before importing the tests into Oracle JDeveloper. Note that with composite tests, tests can call other tests. If you change the name of a composite test file, ensure that you edit any test files that may call this file to include the correct name.

    Description of ts_consoleunittest.gif follows
    Description of the illustration ts_consoleunittest.gif

  7. Save the file as XML to a directory location.

  8. Return to Oracle JDeveloper.

  9. If you saved the file as a composite test file, unzip it.

  10. Right-click the Test Suites folder and select Import BPEL Test.

  11. Select the test suite in the BPEL process in which to import the test.

  12. Click the flashlight icon for the Imported Test URL field.

  13. Select the file saved in Step 7 and click Open.

  14. Click OK.

    The test is added to the selected test suite in the Application Navigator.

  15. Right-click the test suite and select Edit Test Suite.

    Note that the test and its contents now display in the Edit Test Suite window.

    Note:

    No assertions are created in test cases generated from Oracle BPEL Control.

20.4 Deploying a Test Suite

After creating a test suite of test cases, you deploy the test to Oracle BPEL Server. Two deployment methods are provided:

20.4.1 Deploying from Oracle JDeveloper

Oracle JDeveloper can be used to deploy test suites manually when you are first create them.

Follow these steps to deploy test suites from Oracle JDeveloper.

  1. Ensure that you first deploy the BPEL process with which the test suite is associated. The process and the test suite must be deployed separately and cannot be deployed together.

  2. Right-click the Test Suites folder and select BPEL Test Deployer.

    The BPEL Test Deployer window appears.

  3. Click the check box for the test suite to deploy.

  4. Expand test_suite_name - Deploy > Tests and select the specific test cases to deploy.

  5. Select the server to which to deploy the tests.

    Description of ts_deploy.gif follows
    Description of the illustration ts_deploy.gif

  6. Click Deploy to compile, validate, and deploy the selected test cases of the test suite.

    Deployment status messages display in the Status section.

20.4.2 Deploying from an ant Task

An ant task can be used to deploy test suites. This task is useful in an automated testing environment.

Note:

The BPEL process must be deployed before tests for a process can be deployed.

Follow these steps to deploy test suites from an ant task.

  1. View the ant task parameters used to deploy test suites in the build.xml file. This file is located in the Resources folder of your BPEL process.

    <target name="test" depends="deployTestSuites, bpelTest, report" /> 
    <target name="prepareTests">
        <echo>
    --------------------------------------------------------------
    | Preparing BPEL tests for deployment
    --------------------------------------------------------------
        </echo>
        <delete file="${process.dir}/output/bpeltest.zip" quiet="true"/>
        <zip basedir="${process.dir}/bpel/testsuites" filesonly="true"
            excludes="test_suites.xml, **/excludes/*"
            destfile="${process.dir}/output/bpeltest.zip"/>
    </target>
    <target name="deployTestSuites" depends="prepareTests">
        <echo>
    --------------------------------------------------------------
    | Deploying bpel tests ${process.name} on ${http.hostname}, port ${http.port}
    --------------------------------------------------------------
        </echo>
        <deployTestSuites
            user="${admin.user}"        password="${admin.password}"
            hostname="${http.hostname}" httpport="${http.port}"
            domain="${domain}"          process="${process.name}" 
            rev="${rev}"         
           testfile="${process.dir}/output/bpeltest.zip"/>
    </target>
    
    
  2. If you want to change the parameter values for this process, edit and uncomment appropriate parameters in the build.properties file located in the same Resources folder as the build.xml file. Note that this changes the values for this process only.

    #domain=default
    #rev=1.0
    #user=oc4jadmin
    #hostname=localhost
    #http.hostname=localhost
    #http.port=9700
    #j2ee.hostname=localhost
    #rmi.port=23791
    #oc4jinstancename=home
    #asinstancename=
    #opmn.requestport=6003
    #platform=ias_10g
    #platform=oc4j_10g
    bpeltest.callHandler=
    bpel.context.properties=${bpel.home}/samples/tutorials/102.InvokingProcesses/rmi/context.properties
    
    
  3. Open the developer's prompt by selecting Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > Developer Prompt.

  4. Change directories to the correct location and run ant to deploy the test suite:

    ant test
    
    

    where test is the target name defined in the build.xml file.

20.5 Running a Test Suite and Viewing Report Results

After deployment, you can run the test cases of a test suite on a BPEL process instance and view XML document reports. By default, report results are formatted as JUnit XML test results. Two methods are provided:

Note:

Test results are stored as binary large objects (BLOBs).

20.5.1 Running from Oracle BPEL Control

Oracle BPEL Control can be used to run tests manually and generate report results.

Follow these steps to run test suites and view report results from Oracle BPEL Control.

  1. Log into Oracle BPEL Control by selecting Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > BPEL Control.

  2. Log in as oc4jadmin/password.

    where password is the oc4jadmin password.

  3. Click BPEL Processes.

  4. Click the instance to test.

  5. Click Test Suites.

    If a test suite was deployed with this instance, the following window appears.

    Description of ts_testsuite1.gif follows
    Description of the illustration ts_testsuite1.gif

    If a test suite has not been deployed with this instance, this window does not appear. You must first deploy a test suite.

  6. Select the check box for the test suite (for this example, named main).

    Check boxes for the tests in the test suites appear.

  7. Select the XML tests you want to run.

    Description of ts_testsuite2.gif follows
    Description of the illustration ts_testsuite2.gif

    You can also undeploy test suites by clicking Undeploy Tests.

  8. Click Execute Tests.

    As tests complete, the window is updated with results in three sections:

    • Test details such as process name, test run dates, which suites ran, and the number of workers appear. A worker is the number of concurrent threads that can run one or more test cases. The number of workers controls how many test cases can be run simultaneously.

    • A summary report displays the outcomes of the tests and code coverage.

    • A detailed listing of all the tests and which assertions failed is displayed. Note the Display Failures Only check box. When checked, detailed information for successful tests is hidden. By default, this check box is checked.

    Description of ts_report.gif follows
    Description of the illustration ts_report.gif

  9. Click the percentage value link under Process Coverage to view the amount of source code executed.

  10. Click one of the following links in the upper right corner of Oracle BPEL Control to view specific code coverage details.

    Description of ts_coverage.gif follows
    Description of the illustration ts_coverage.gif

    Activities that were executed are framed in green and those that were not are framed in red.

    Description of ts_coverage2.gif follows
    Description of the illustration ts_coverage2.gif

  11. Click View Instance Flow to view additional details or click Back to BPEL Control.

20.5.2 Running from an ant Task

An ant task can be used to run test suites and generate report results. This task is useful in an automated testing environment. By default, the test results are formatted as JUnit XML test results. This format provides the following benefits:

  • Uses the junitreport task to produce a frames-based report.

  • Integrates your BPEL test results with other JUnit results (if you use JUnit to test your Java components).

  • Integrates with other third-party test suite frameworks that also use the JUnit report format.

Follow these steps to run tests and create reports from an ant task.

  1. View the ant task parameters used to run test cases and generate reports in the build.xml file. This file is located in the Resources folder of your BPEL process.

    <!-- "bpeltest" target runs deployed testsuites of a BPEL process -->    
    <target name="bpelTest">
        <echo>
    --------------------------------------------------------------
    Executing process ${process.name}(v.${rev}):
     minCoverage=${bpeltest.minCoverage}, timeout=${bpeltest.timeout} sec,
     numWorkers=${bpeltest.numWorkers}
    --------------------------------------------------------------        
        </echo>
        <delete dir="${bpeltest.results.dir}/xml/${process.name}" quiet="true"/>
        <bpeltest
            user="${admin.user}"          password="${admin.password}"
            hostname="${http.hostname}"   httpport="${http.port}"
            domain="${domain}"            process="${process.name}" 
            rev="${rev}"                  name="${process.name}Tests"
            timeout="${bpeltest.timeout}"
            numWorkers="${bpeltest.numWorkers}" 
            minCoverage="${bpeltest.minCoverage}"
            callHandler="${bpeltest.callHandler}"
            context="${bpel.context.properties}"
            resultsDir="${bpeltest.results.dir}/xml/${process.name}"
                resultsPropertyFile="${bpeltest.results.dir}/${process.name}.properties"/>
        <property file="${bpeltest.results.dir}/${process.name}.properties"/>
        <echo>
    --------------------------------------------------------------
    Executed ${test.total.count} test(s) for ${process.name} (v.${rev}) with
     ${test.failure.count} failure(s)
    --------------------------------------------------------------
        </echo>
    </target>
    . . .
    . . .
    
    
    <!-- "report" target creates JUnitReport for testsuites run by bpeltest. -->
        <target name="report">
            <echo>
    --------------------------------------------------------------
    Creating BPELTest JUnitReport at
     ${bpeltest.results.dir}${file.separator}html${file.separator}index.html
    --------------------------------------------------------------
            </echo>    
            <mkdir dir="${bpeltest.results.dir}/xml"/>
            <junitreport todir="${bpeltest.results.dir}/xml">
                <fileset dir="${bpeltest.results.dir}/xml">
                    <include name="*/TEST-*.xml" />
                    <include name="*/BPEL-*.xml" />
                </fileset>
                <report format="frames" todir="${bpeltest.results.dir}/html" />
            </junitreport>   
        </target>
        <!-- If pre-build.xml and post-build.xml exists, call its default target
     -->
        <condition property="exists.pre-build.xml">
            <available file="${process.dir}/pre-build.xml"/>
        </condition>
        <target name="pre-build" if="exists.pre-build.xml">
            <ant antfile="${process.dir}/pre-build.xml" inheritAll="false"/>
        </target>
        <condition property="exists.post-build.xml">
            <available file="${process.dir}/post-build.xml"/>
        </condition>
        <target name="post-build" if="exists.post-build.xml">
            <ant antfile="${process.dir}/post-build.xml" inheritAll="false"/>
        </target>    <!-- Convenience targets -->
        <target name="deploy_test" depends="deploy, test"/> 
        
    </project>
    
    
  2. If you want to change the parameter values for this process, See Step 2 for details.

  3. Open the developer's prompt by selecting Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > Developer Prompt.

  4. Change directories to the correct location and start ant to run the test suite and create the reports:

    ant bpelTest report
    
    

    where bpelTest and report are the target names defined in the build.xml file.

    Note:

    If you want to deploy the BPEL process, deploy the corresponding test cases, run the deployed test cases, and generate reports at the same time, run the following command:
    ant deployProcess test
    

    The following example shows an ant-generated report:

    Description of ts_junit1.gif follows
    Description of the illustration ts_junit1.gif

    Since JUnit is being used, several Java constructs such as packages and classes are included in the report. For Oracle BPEL Process Manager, the default package resolves to bpel.domain.process-revision, but this can be customized. Classes map to test suite names. Note the code coverage suite. This is added when you specify a minimum code coverage in the ant task. In the main pane, a summary of the test results is shown. If you package results from multiple processes in this report, there are more entries in the Packages table.

  5. Click the package name (BPEL process) to display report results.

    Description of ts_junit2.gif follows
    Description of the illustration ts_junit2.gif

20.6 Advanced Test Suite Design Features

This section describes several advanced test suite design features. Samples for some of these features are available in the SOA_Oracle_Home\bpel\samples\references subdirectories.

20.6.1 Setting Dynamic Values at Run Time

You may sometimes want to have messages that contain dynamic content. For example:

  • You want to emulate a message that contains the current date and time

  • You need a unique identifier

To support this, you add message updates to emulated messages. A message update consists of two main pieces of information:

  • An XPath function that generates a string value

  • An XPath expression that specifies the portion of the message to update

For example, assume you want to emulate the following message:

<dateTimeMessage xmlns="http://xmlns.oracle.com/SomeProcess">
  <theDateTime>current date time</theDateTime>
</dateTimeMessage>

Add an emulation with the following content in Oracle JDeveloper:

<dateTimeMessage xmlns="http://xmlns.oracle.com/SomeProcess">
  <theDateTime/>
</dateTimeMessage>

Since there is no graphical user interface support for message updates, switch to the source view and view the following generated emulation:

<activityDriver name="someActivity">
    <emulate>
      <inboundMessage>
        <part name="payload">
          <content>
            <dateTimeMessage xmlns="http://xmlns.oracle.com/SomeProcess">
              <theDateTime/>
            </dateTimeMessage>
          </content>
        </part>
      </inboundMessage>
    </emulate>
  </activityDriver>

Add a message update to the inboundMessage to set the date time at run time:

<activityDriver name="Invoke_2">
    <emulate duration="PT">
      <inboundMessage>
        <part name="payload">
          <content>
            <dateTimeMessage xmlns="http://xmlns.oracle.com/SomeProcess">
              <theDateTime/>
            </dateTimeMessage>
          </content>
          <update>
            <location>
              /client:dateTimeMessage/client:theDateTime
            </location>
            <XPathExpression>
              xp20:current-dateTime()
            </XPathExpression>
          </update>
        </part>
      </inboundMessage>
    </emulate>

Note that the update element contains an XPath location to the empty theDateTime element. The XPath expression element contains an XPath function that generates the current date time. When the test is run, this XPath function is called and the emulated message is updated with the current date time.

Note:

Namespace prefixes used in the XPath function and XPath query must be correctly defined in the test case XML document.

See Also:

The following message update sample:
SOA_Oracle_Home\bpel\samples\references\BPELTest\
Emulations\bpel\testsuites\main\demoMessageUpdate.xml

20.6.2 Asynchronous Event Emulation

It is possible to emulate asynchronous events. These events are captured in the onMessage or onAlarm branches in your BPEL process. There is no current design time support for event emulation.

See Also:

The following samples to see how to manually create these test cases:
  • SOA_Oracle_Home\bpel\samples\references\BPELTest\Alarms\bpel\testsuites\main

  • SOA_Oracle_Home\bpel\samples\references\BPELTest\OnMessage\bpel\testsuites\main

20.6.3 Verifying External Actions

You can extend your test cases beyond BPEL. For example, assume you have a BPEL process that alters an external system. You can write a test case that invokes an instance of the BPEL process and calls an API that verifies that the external system was updated appropriately. Since there is limited support for this in the BPEL test framework, you can write custom XPath functions to verify data and then use these functions in assertions. There is no design time support for this. To do this manually, write an assertion as follows:

<activityDriver name="Assign_1">
  <assertValue fatal="true">
    <message>exact text comparison</message>
    <actualPath>ns:extractExternalValue()</actualPath>
    <expected>theInput</expected>
  </assertValue>

In the bold section, note that an XPath function was used instead of the usual XPath query. This function can be implemented to extract a value from an external system The BPEL test framework then compares the value returned by the XPath function to theInput.

20.6.4 Custom Reporting

The ant task generates JUnit-style XML results by default. These results can then be passed to the junitreport task to generate a frames-based HTML report. If you want to present the results in a different format, set the xsl parameter of the bpelTest ant task to a URL or file path that points to an XSLT stylesheet you created. After tests have been executed, an XSL transformation is performed on the results XML document (specified by the XML schema defined in SOA_Oracle_Home\bpel\system\xmllib\BPELTestResult.xsd) using the stylesheet specified by the xsl attribute.

The following example shows the ant task using an XSL stylesheet accessible from a URL:

<bpelTest ... xsl="http://mycompany.com/myStyleSheet.xsl".../>

The following example shows the ant task using an XSL stylesheet accessible from the file system:

<bpelTest ... xsl="C:\xslDir\myStyleSheet.xsd" .../>

20.6.5 Database Views

The following database views enable you to query details about test results and test definitions.

20.6.5.1 admin_list_td

This view provides information about previously run test cases, as shown in Table 20-1.

Table 20-1 admin_list_td

Name Null Type Description
CIKEY N VARCHAR2(100) The BPEL process
CI_DOMAIN_REF N SMALLINT(5) The BPEL process domain
TEST_RUN_NAME N VARCHAR2(100) The name of the test run. This can stay constant across many test runs. This value is automatically generated unless the test run was initiated through the client code.
TEST_RUN_ID N VARCHAR2(100) The ID of the test run. This must be unique across test runs. This value is automatically generated unless the test run was initiated through the client code.
TEST_SUITE N VARCHAR2(100) The test suite of this test case
TEST_LOCATION N VARCHAR2(100) The location of the test case within the test suite. This is typically the name of the test case file.
TEST_STATUS N VARCHAR2(50) The status of this test case. This is either passed, failed, or running.
TEST_RESULT N BLOB The XML result of the test case. This column can be read using a DOM parser.

For example:

SQL> select cikey, ci_domain_ref, test_run_name from admin_list_td;

CIKEY | CI_DOMAIN_REF | TEST_RUN_NAME
------+---------------+--------------------------------------------
    4 |             0 | ca8f3d34e7fa93f2:53855ec5:10c02daf400:-7b46


SQL> select test_run_id from admin_list_td;

TEST_RUN_ID
-------------------------------------------
ca8f3d34e7fa93f2:53855ec5:10c02daf400:-7b46


SQL> select test_location, test_suite, test_status, test_result from admin_list_td;

TEST_LOCATION              | TEST_SUITE | TEST_STATUS | TEST_RESULT
---------------------------+------------+-------------+------------
testShippingConsidered.xml | logicSuite | failed      | <?xml vers

20.6.5.2 admin_list_tdef

This view provides information about deployed test cases, as shown in Table 20-2.

Table 20-2 admin_list_tdef

Name Null Type Description
PROCESS_ID N VARCHAR2(100) The BPEL process
REVISION_TAG N VARCHAR2(50) The BPEL process revision
DOMAIN_REF N SMALLINT(5) The BPEL process domain
TEST_SUITE N VARCHAR2(100) The test suite of this test case
LOCATION N VARCHAR2(100) The location of the test case within the test suite. This is typically the name of the test case file.
TYPE N VARCHAR2(10) The type of this file:
  • message — a message file

  • include — a baseline test case

  • test — a test case

  • properties — a properties file

CREATION_DATE N DATE The date this test was deployed
DEFINITION N BLOB The XML definition of the test case. This column can be read using a DOM parser.

SQL> select process_id, revision_tag, domain_ref, test_suite from admin_list_tdef;

PROCESS_ID           | REVISION_TAG | DOMAIN_REF | TEST_SUITE

---------------------+--------------+------------+-----------
PriceFinderWithTests | 1.0          |          0 | logicSuite
PriceFinderWithTests | 1.0          |          0 | logicSuite
Emulations           | 1.0          |          0 | main
Emulations           | 1.0          |          0 | main
Emulations           | 1.0          |          0 | main
Emulations           | 1.0          |          0 | main
Emulations           | 1.0          |          0 | main
Emulations           | 1.0          |          0 | main
Emulations           | 1.0          |          0 | main
Emulations           | 1.0          |          0 | main
Emulations           | 1.0          |          0 | main


SQL> select location, type, creation_date, definition from admin_list_tdef;

LOCATION                     | TYPE    | CREATION_DATE              | DEFINITION
-----------------------------+---------+----------------------------+-----------
baseline.xml                 | include | 2006-06-25 10:58:16.260000 | <?xml vers
testShippingConsidered.xml   | test    | 2006-06-25 10:58:16.260000 | <?xml vers
baseline.xml                 | include | 2006-06-27 16:09:08.025000 | <?xml vers
emulated.xml                 | message | 2006-06-27 16:09:08.025000 | <?xml vers
demoAsyncEmulation.xml       | test    | 2006-06-27 16:09:08.025000 | <?xml vers
demoBusinessFault.xml        | test    | 2006-06-27 16:09:08.025000 | <?xml vers
demoEmulationFromMessage.xml | test    | 2006-06-27 16:09:08.025000 | <?xml vers
demoMessageUpdate.xml        | test    | 2006-06-27 16:09:08.025000 | <?xml vers
demoPartnerTest.xml          | test    | 2006-06-27 16:09:08.025000 | <?xml vers
demoSyncEmulation.xml        | test    | 2006-06-27 16:09:08.025000 | <?xml vers
demoSystemFault.xml          | test    | 2006-06-27 16:09:08.025000 | <?xml vers

20.6.6 XML Schemas

The following XML schemas are provided in the SOA_Oracle_Home\bpel\system\xmllib directory:

  • InstanceDriver.xsd — Test case schema

  • BPELTestResult.xsd — Test results schema

20.6.7 Client APIs

A service defined in the com.oracle.services.bpel.test package enables you to use the Locator class to look up the test service and initiate test cases, get a list of deployed tests, or get the results of test cases already executed. This service can be looked up in a similar manner to the delivery service. For the service name, you can use com.oracle.services.bpel.test.ITestService.SERVICE_NAME.

See Also:

  • Oracle BPEL Process Manager Client API Reference:

    SOA_Oracle_Home\bpel\docs\apidocs