BWUnitUser GuideVersion 16.49

Contents

• Introduction
  • Testing Terminology and Conventions
  • Resources
• License
• System Requirements
• Using BWUnit
  • Configuration Settings
• Targets
  • designer
  • designer-sit
  • designer-st
  • build
  • clean
  • clean-license-settings
  • configure-ear
  • create-mirror
  • create-license-mirror
  • deploy
  • ear
  • obfuscate-input
  • projlib
  • promote
  • publish-config
  • publish-snapshot
  • report-integration-tests
  • report-system-integration-tests
  • report-system-tests
  • report-unit-tests
  • run-functional-tests
  • run-integration-tests
  • run-system-integration-tests
  • run-system-tests
  • run-unit-tests
  • validate
• Customising and Extending BWUnit
• Related Software
  • Apache Ant
  • TIBant
  • H2
  • Apache ActiveMQ
• Conventions
• Installation
  • System Requirements
  • Installation Steps
  • Overriding Project Settings
• Testing Quick Start
  • Create a Test Suite
  • Create a Test Case
  • Create a Test
  • Run a Test
  • Implement Your Own Test Logic
• Using the Example Projects
  • Creating Tests and A Testing Hierarchy
  • Generating Test Reports
  • Generating Test Coverage Reports
  • Continuous Integration
• Further Reading
  • Continuous Delivery
  • xUnit Test Patterns
• Copyright
• Apache Ant Macros
  • bw-start
  • bw-stop
  • convert-to-html-results
  • convert-to-junit-results
  • convert-to-nunit-results
  • designer
  • install-license-local
  • run-tests
  • validate-project

Introduction

You have made the right choice using TIBCO BusinessWorks™ as your Integration Platform.

Now you have made the right choice on how you deliver your TIBCO BusinessWorks integration projects.

Windy Road BWUnit allows you to apply to your software delivery process the same business process automation techniques that you use every day to improve your company’s business processes.

Its primary focus is on removing waste in the process, removing the steps in your software delivery process that do not add value and automating the steps that are worth automating.

BWUnit provides automation tooling for the build, deployment and testing of your TIBCO BusinessWorks projects.

On the testing side, BWUnit supports a vast array of protocols, such as TIBCO Rendezvous, JMS, HTTP and JDBC using SOAP, XML or native formats. You name it – if BusinessWorks can integrate with it, then BWUnit can test it.

BWUnit not only builds, tests and deploys your BusinessWorks (BW) engines, it also offers a range of innovative features including Designer Launch Control, Property File to Engine Configuration Translation and Service WSDL Generation.

Designer Launch Control allows you to launch TIBCO Designer from Ant, and working on a project-by-project basis from within each project’s build script, will specify and control your file aliases, class paths and other settings. No more need to waste valuable time on incorrect file-aliases.

Property File to Engine Configuration Translation gives you the ability to specify BusinessWorks engine properties in simple property files. BWUnit then lets you use these files to generate AppManage-compatible configuration files for each of your environments and is even smart enough to tell you when you’ve forgotten to set a global variable, such as a database password for the production environment.

Service WSDL Generation saves time and money by removing the manual steps currently required to produce a concrete WSDL for Service defined within your project. Even more importantly, because it allows you to specify the global variables to use when generating the WSDL, you will be able to generate a correct WSDL for each environment.

This document will guide you through:

• the installation process for Windy Road BWUnit on UNIX and Windows systems,
• how to use the BWUnit examples,
• how to setup your own project to use BWUnit for testing, and finally
• how to add testing with BWUnit to your Continuous Integration Build Process.

Testing Terminology and Conventions

Throughout this document there are references to various testing phases, of which tend to have sligtly different meanings within different organisations.

For the purpose of clarity, we have decided to standardise based on their definition on Wikipedia as detailed below.

While the name used for the various testing phases are far from ideal (e.g., Integration Testing has a very different meaning for most integration developers), we consider them far better than custom phase names that no-one would be familiar with.

Unit Testing

http://en.wikipedia.org/wiki/Unit_testing

Unit testing seeks to tests individual units of source code within a software project.

For TIBCO BusinessWorks, we regard a process as a unit and your unit tests should focus on testing your processes, not the end-points that expose them to other systems.

Within this context, it is very important to decouple the processes you are testing from the external systems they are dependant on, through the use of test doubles (stubs, fakes, mocks, etc). Decoupling is a very important step as unit test failures should indicate errors within the processes you are testing and not be dependant on components outside of the control of the BW project you are testing.

Failure to decouple the processes you are testing from their external systems can result in slow-running tests, erratic tests and test-run-wars.

More information on erratic tests and slow running tests and their impact is available at http://xunitpatterns.com/Erratic%20Test.html and http://xunitpatterns.com/Slow%20Tests.html .

Integration Testing

http://en.wikipedia.org/wiki/Integration_testing

Integration testing seeks to combine individual software modules and tests them as a group. This term leads to much confusion within the BW development world (due to it's strong focus on integration of disparat systems) and should not be confused with integrating your software modules with external systems, the testing of which takes place in system testing.

For TIBCO BusinessWorks, we regard integration testing as the testing of your BW processes integrated with the starter processes or services that expose them to other systems and your integration tests should focus on testing the end-points that these starter processes or services expose.

As per unit testing, it is very important to decouple the _processes) you are testing from the external systems they are dependant on, through the use of test doubles (stubs, fakes, mocks, etc).

Integration test failures should indicate errors within the project's starter processes or services, assuming the processes they call have passed unit testing.

System Testing

http://en.wikipedia.org/wiki/System_testing

System testing of software or hardware is testing conducted on a complete, integrated system to evaluate the system's compliance with its specified requirements.

As a rule, system testing takes, as its input, all of the "integrated" software components that have passed integration testing. The purpose of integration testing is to detect any inconsistencies between the software units that are integrated together (called assemblages). System testing is a more limited type of testing; it seeks to detect defects both within the "inter-assemblages" and also within the system as a whole.

For TIBCO BusinessWorks, we regard system testing as testing of your BW processes integrated with the starter processes or services that expose them to other systems and the systems that your project depends on.

Assuming the end-systems are operating correctly, system test failures should indicate errors within your sub-processes for communicating with those systems.

NOTE: Typically the interfaces tested and the tests used during System Testing are the same as those used during Integration testing, with the difference being the use of test doubles (stubs, fakes, mocks, etc) during Integration Testing and real backend systems during System Testing.

System Integration Testing

http://en.wikipedia.org/wiki/System_integration_testing

In the context of software systems and software engineering, system integration testing (SIT) is a testing process that exercises a software system's coexistence with others. With multiple integrated systems, assuming that each have already passed system testing, SIT proceeds to test their required interactions.

For TIBCO BusinessWorks, we regard system integration testing as testing the systems that depend on the end-points exposed by your project along with the systems that your project depends on. This is often referred to as end-to-end testing.

Assuming the systems that depend on your project are operating correctly and the end-systems your project depends on are operating correctly, system integration test failures should indicate errors with how your end-points are exposed to the consumers that invoke them. Typically this results from misunderstandings regarding interface specifications.

Acceptance Testing

http://en.wikipedia.org/wiki/Acceptance_testing

In engineering and its various subdisciplines, acceptance testing is a test conducted to determine if the requirements of a specification or contract are met.

Specifically, acceptance tests are test that describe the behaviour of the system(s) from a business or end-user point of view. They should clearly articulate the behaviour of the integrated systems.

When System Integration tests are written so that they desribe and test the behaviour of the integrated systems then the System Integration tests can and should be considered acceptance tests.

More information on this approach can be found at http://en.wikipedia.org/wiki/Behavior-driven_development

Please see the SalesLeads project for examples of behavioural tests: https://github.com/windyroad/SalesLeads

Resources

The BWUnit homepage can be found at http://windyroad.com.au/software/bwunit/ . Community discussion forums for BWUnit can be found at http://windyroad.com.au/discussion/ and the Windy Road team is looking forward answer your support questions at http://windyroad.com.au/support/ .

More information about Apache Ant can be found at http://en.wikipedia.org/wiki/Apache_Ant and full documentation for Apache Ant can be found at http://ant.apache.org/manual/index.html

License

Please see either the BWUnit Lite End User License Agreement or the BWUnit Pro End User License Agreement supplied with this software. If a copy of BWUnit Lite End User License Agreement or BWUnit Pro End User License Agreement was not provided with this software, you may request a copy from http://windyroad.org/support/ .

System Requirements

BWUnit is compatible with the following software:

BWUnit should also work with newer versions of Apache Ant versioned as 1.X.Y and newer versions of BusinessWorks versioned as 5.X.Y, however at the time of this writing we have not tested BWUnit against any such newer versions. If you have any issues using BWUnit with newer versions of Apache Ant or TIBCO BusinessWorks, please contact Windy Road Support for assistance.

BWUnit is supported on the following platforms that BusinessWorks is supported on

• Windows

• Solaris
• Red Hat Enterprise Linux

BWUnit should also work on versions of HPUX and AIX that BusinessWorks is supported on, however we do not explicitly test BWUnit on those platforms. If you have any issues using BWUnit on HPUX or AIX please contact Windy Road Support for assistance.

Using BWUnit

Step one: Pick a BW project

Step two: Create a file called build.xml in a folder above the BW project. e.g. We usually have the build.xml located somewhere like <SomePath>\MyCoolBWProject\build.xml and the actual BW code at <SomePath>\MyCoolProject\src\main\bw\MyCoolProject

Step three: Add the following content to the build.xml

<?xml version="1.0" encoding="UTF-8"?>
<project default="designer" name="MyCoolProject">
    <import>
        <url url="http://windyroad.com.au/bwunit-importer/%%version%%/full.xml" />
    </import>
</project>

Step four: If you haven't already, install Apache Ant (http://ant.apache.org). Version 1.8.2 or newer will do. Make sure it's installed correctly by opening a command prompt and running ant -version.

Step five: From the same directory as your build.xml run ant -p on the command line to get a list of targets you can run. You'll be asked a number of questions. If you make a mistake, it stores the answers in the Configuration Settings files desribed below, which you can fix with a text editor.

Step six: From the same directory as your build.xml run ant designer, ant ear and ant validate. They should all just work.

Configuration Settings

When you run BWUnit, it will look for configuration settings in the following files:

Where:

• ${user.home} is your home directory

• ${ant.project.name} is the value of the /project/@name in your build.xml
• ${basedir} is the directory containing your build.xml

If TIBant is unable to find the configuration setting it is looking for, it will ask you for the correct value for that setting and store the value in either ${user.home}/build.properties or ${basedir}/build.properties.

NOTE: The following files should be added to you source control for the project

• ${basedir}/build.xml

• ${basedir}/build.properties
• ${basedir}/ivy.xml
• ${basedir}/ivysettings.xml

NOTE: All paths are relative to your ${basedir} unless otherwise specified

NOTE: bwda.pipeline.version, bwda.deployment.domain and bwda.pipeline.${bwda.deployment.domain}.config.version are not persisted by BWUnit and should be passed in from the command line or by your CI server.

ivysettings.xml

BWUnit assumes that you will be using a shared directory to upload and download artifacts and dependencies. However ${basedir}/ivysettings.xml can be modified to instead use a Maven-compatible artifact repository (e.g. JFrog's Artifactory), ssh, sftp, subversion and more. Please see http://ant.apache.org/ivy/history/latest-milestone/settings/resolvers.html and https://code.google.com/p/ivysvn/ for more details or contact Windy Road support if you have any questions about artifact storage.

ivy.xml

BWUnit will automatically download JAR files and PROJLIB files that are specified as dependencies in your ${basedir}/ivy.xml and configure designer, buildear, etc to use these files. Please see http://ant.apache.org/ivy/history/latest-milestone/ivyfile/dependencies.html for more details on specifiying dependencies or contact Windy Road support if you have any questions about specifying dependencies.

You can search for public JAR files that you can add as dependencies at http://search.maven.org/ or http://mvnrepository.com/

Targets

As of BWUnit v16, BWUnit provides a number of Apache Ant targets for performing typical tasks for a BW project.

designer

Opens the project in TIBCO Designer. BWUnit will automatically retrieve the project's dependencies (PROJLIB files and JAR files) as specified in the project's ${basedir}/ivy.xml file and configure Designer's classpath, design time libraries and file aliases accordingly.

Additional JAR files and PROJLIB file that cannot be downloaded/copied from your artifact repository can be configured as file aliases by adding properties to ${basedir}/build.properties in the following format:

engine.aliases.<NAME>.projlib=Z:/SomePath/To/<NAME>.projlib

or

engine.aliases.<NAME>.jar=Z:/SomePath/To/<NAME>.jar

designer-sit

Opens the project in TIBCO Designer with the tester pre-configured to use global variables and engine settings for the specificed system integration testing (SIT) environment.

NOTE: Typically we do not recommend connecting TIBCO Designer directly to SIT environments, however we do recognise that sometimes it is required for debugging purposes.

designer-st

Opens the project in TIBCO Designer with the tester pre-configured to use global variables and engine settings for the specificed system testing (ST) environment.

NOTE: Typically we do not recommend connecting TIBCO Designer directly to ST environments, however we do recognise that sometimes it is required for debugging purposes.

build

Builds the project's EAR files and PROJLIB files. BWUnit will automatically determine what to build based on the .archive files and .libbuilder files in your project. It will also automatically retrieve the project's dependencies (PROJLIB files and JAR files) as specified in the project's ${basedir}/ivy.xml file.

Additional JAR files and PROJLIB file that cannot be downloaded/copied from your artifact repository can be configured as file aliases by adding properties to ${basedir}/build.properties in the following format:

engine.aliases.<NAME>.projlib=Z:/SomePath/To/<NAME>.projlib

or

engine.aliases.<NAME>.jar=Z:/SomePath/To/<NAME>.jar

The built files will be created in ${bwda.build.dir}.

clean

Removes all the files in ${bwda.build.dir}.

clean-license-settings

Removes the BWUnit license settings from ${user.home}/build.properties. Execution of BWUnit Pro targets will prompt you for your BWUnit license settings again.

configure-ear

Retrieves the version of the project's EARs specified by ${bwda.pipeline.version}, extracts the template configuration files, and builds configuration files for the TIBCO Administrator domain specified by ${bwda.deployment.domain}.

create-mirror

Creates a copy of the BWUnit artifacts in the releases repository as specified by he project's ivysettings.xml

The target repository can be controlled via the ${bwda.mirror.repo} property.

Once a mirror has been created, projects may set ${bwda.local.resolve.only} to true in order to completely remove the windy road artifactory repositories from dependency resolution.

create-license-mirror

Performs the same function as create-mirror, but just for the specified BWUnit license.

deploy

Retrieves the version of the project's EARs specified by ${bwda.pipeline.version}, the version of the project's configuration specified by, ${bwda.deployment.domain} and ${bwda.pipeline.${bwda.deployment.domain}.config.version} and deploys them to the TIBCO Administrator domain specified by ${bwda.deployment.domain}.

If you are using TRA 5.7.3 or later, the deploy target will first upload the EARs and their configuration without restarting the BW engines. It will then proceed to perform a rolling restart of each BW instance, waiting for each instance to enter a state of "Running" before moving onto the next. In high availability (e.g. load balanced or fault tolterant) scenarios, this results in no-outage during the deployment.

If you are using an earlier version of the TRA, the deploy target will first upload the EARs and their configuration without restarting the BW engines. It will restart all of the BW instances belonging to the EAR, which will result in a short outage.

NOTE: The host on which this is run must be a member of the specified TIBCO Administrator domain.

NOTE: Even though the deploy target can provide a no-outage deployment in high availability secnarios, we strongly recommend that the deployment of critical systems into production environments be performed during a prescribed outage window, in-case there are any issues during the deployment, which result in an outage.

ear

As per the build target, except only EAR files will be built.

obfuscate-input

Takes a password as input and outputs an obfuscated result.

projlib

As per the build target, except only PROJLIB files will be built.

promote

Retrieves a "snapshot" version of a project's EARs and PROJLIBs specified by ${bwda.pipeline.version} and republishes them as "release" versions. This is used as a way to indicate that a version of a project's EARs and PROJLIBs have passed applicable quality gates and have been deemed fit for production deployment.

publish-config

As per configure-ear and additionally the generated configuration files are uploaded/copied to your artifact repository.

publish-snapshot

As per build and additionally the generated EARs and PROJLIBs are uploaded/copied to your artifact repository as "snapshot" versions.

report-integration-tests

Runs the BWUnit integration tests and generates reports indicating for each test if it passed or failed. Failed tests will not fail the build.

report-system-integration-tests

Runs the BWUnit system integration tests and generates reports indicating for each test if it passed or failed. Failed tests will not fail the build.

report-system-tests

Runs the BWUnit system tests (i.e. runs the integration tests against a deployed engine) and generates reports indicating for each test if it passed or failed. Failed tests will not fail the build.

report-unit-tests

Runs the BWUnit unit tests and generates reports indicating for each test if it passed or failed. Failed tests will not fail the build.

run-functional-tests

Runs all the BWUnit tests. Failed tests will fail the build.

run-integration-tests

Runs the BWUnit integration tests. Failed tests will fail the build.

run-system-integration-tests

Runs the BWUnit system integration tests. Failed tests will fail the build.

run-system-tests

Runs the BWUnit system tests (i.e. runs the integration tests against a deployed engine). Failed tests will fail the build.

run-unit-tests

Runs the BWUnit unit tests. Failed tests will fail the build.

validate

Validates the project. TIBant will automatically retrieve the project's dependencies (PROJLIB files and JAR files) as specified in the project's ${basedir}/ivy.xml file and configure Designer's classpath, design tiem libraries and file aliases accordingly.

As per build, additional file aliases can be configured using engine.aliases.* properties

Customising and Extending BWUnit

BWUnit is extremely customisable and extendable to suit your particular needs. The following sections detail the Apache Ant custom tasks and macros provided by BWUnit. An understanding of Apache Ant is assumed. If you need help customising or extending BWUnit, please contact Windy Road Support.

Related Software

BWUnit and it's example projects rely on the following software:

Apache Ant

Apache Ant is a software tool for automating the software build processes. Ant uses XML to describe the build process and its dependencies. More information about Apache Ant can be found at http://en.wikipedia.org/wiki/Apache_Ant and documentation for Apache Ant can be found at http://ant.apache.org/manual/index.html

Apache Ant is required both during the BWUnit installation when using BWUnit. Apache Ant 1.8.2 or later is required.

TIBant

TIBant provides a set of Apache Ant tasks for building and deploying TIBCO BusinessWorks projects. BWUnit builds upon TIBant, providing test automation capabilities and allowing you to create a completely automated continuous delivery pipeline for your BusinessWorks projects.

H2

H2 is a fast, light-weight Java SQL database. It's ability to run as an in-memory database makes it ideal for unit and integration testing (leaving the use of production like databases for system testing, system integration testing and beyond). We recommend using H2 as a stub for databases your projects depend on. This allows you to test the logic within your project, without requiring access to a production like database.

Alternativly, you can stub databases using the dependency injection pattern. The Currency example uses the dependency injection pattern to stub a SOAP web service. The same pattern can be used to stub any external integration, including databases.

NOTE: Dependency injection is the preferred mechanism for stubbing. The use of H2 is suggested for times when you want to test existing DB dependant code that has not been written with Dependency Injection in mind, which you do not wish to refactor at this time.

More information about H2 can be found at http://www.h2database.com/html/main.html and the documentation for H2 can be found at http://www.h2database.com/html/quickstart.html

Apache ActiveMQ

Apache ActiveMQ is an open source implementation of the supporting JMS 1.1 standard. It's support for running as an in-memory (A.K.A. embedded) JMS Server make it ideal for unit and integration testing (leaving the use of production like JMS implementations for system testing, system integration testing and beyond). We recommend using ActiveMQ as a stub for JMS intgrations your project depends on. This allows you to test the logic within your project, without requiring access to a the JMS clients your project depends on.

Alternativly, you can stub JMS integrations using the dependency injection pattern. The Currency example uses the dependency injection pattern to stub a SOAP web service. The same pattern can be used to stub any external integration, including JMS integrations.

NOTE: Dependency injection is the preferred mechanism for stubbing. The use of ActiveMQ is suggested for when you want to test existing JMS dependant code that has not been written with Dependency Injection in mind, which you do not wish to refactor at this time.

More information about Apache ActiveMQ can be found at http://activemq.apache.org/ and the documentation for Apache ActiveMQ can be found at http://activemq.apache.org/getting-started.html

Conventions

The following conventions are used within this user guide:

Installation

System Requirements

To use BWUnit, the following software and it's dependencies are required:

NOTE: Though BusinessWorks 5.2 is compatible with Java 1.4.2, BWUnit requires Java 1.5.0 or later. If you need support for a version of Java earlier than 1.5.0, please let us know at http://windyroad.com.au/support/ .

NOTE: The validate-project macro is not compatible with BW 5.2 as it uses the -a option on the validateproject executable for specifying file aliases, which was not introduced until later versions of BW.

NOTE: Most of the BWUnit examples require BW 5.8 or later. The exception is the HelloWorld example, which is compatible with BW 5.2 and later.

Installation Steps

We don't like complicated install processes. Simply copy the following into a build.xml file in a directory relative to your BW project

<?xml version="1.0" encoding="UTF-8"?>
<project default="designer" name="MyBWProject">
    <import>
        <url url="http://windyroad.com.au/bwunit-importer/16/importer.xml"/>
    </import>
</project>

and run ant -p from the command line (The Ant bin directory will need to be in your path) or from your IDE.

The first time you run Ant using this script, it will request input for a number of project specific BWUnit settings. These settings will be stored in ${user.home}/build.properties and ${ant.file.dir}/build.properties file (i.e. in the same directory as the build.xml file).

Alternatively, you can create the ${user.home}/build.properties and ${ant.file.dir}/build.properties files manually with the follow properties (all paths are relative to the build.xml file):

NOTE: The build.xml file and the ${ant.file.dir}/build.properties should be add to your source control repository (with your BW project), so that these settings can be shared between developers and with your continuous integration server

The first time you run your BWUnit tests from Ant, you will also be prompted for your the following BWUnit Pro license settings:

If you are using BWUnit Lite, the above settings do not apply and you are limited to executing tests individually from within TIBCO Designer. The Lite version does not allow you to run the tests in an automated manner, nor does it allow you use any of the Ant macros/targets except for launching TIBCO Desginer (i.e. it does not permit use of the macros/targets for automated build, validation, deployment, configuration, etc).

Overriding Project Settings

As a developer, if you need to change any of the project specific BWUnit settings and you do not want those settings to impact other developers, you can add the properties to either ${user.home}/${ant.project.name}.properties or ${basedir}/build.properties to have them apply to a specific project or all projects repectivly.

Testing Quick Start

To get started testing quickly with BWUnit, use the steps above to configure your project, launch TIBCO Desginer designer by running ant desginer from the command line (or run the desginer Ant target from your IDE), and follow the steps below.

Create a Test Suite

A Test Suite in BWUnit is used to logically group Test Cases and nested Test Suites. Create a Test Suite by creating a folder called "MyTestSuite" in your project in TIBCO Designer.

A Test Suite

Create a Test Case

A Test Case in BWUnit is used to logically group Tests and to share a fixture between tests. Create a Test Case by creating a folder called "MyTestCase" in the "MyTestSuite" folder in your project in TIBCO Designer.

A Test Case

Create a Test

The easiest way to create is to copy the Test template in the BWUnit DTL. In TIBCO Desinger, find BWUnit/Public/Templates/Test, right click and select "Copy". Go back to MyTestSuite/MyTestCase, right click and select "Paste".

A Test

Run a Test

Load the test you created in the TIBCO Designer Tester, by selecting the "Tester" tab, pressing the green right arrow button, selecting the "Test" process you created and clicking "Load Selected".

Selecting a Test To Run

Select Test.process in the Tester tab and click the "Create a job" button with the green process icon.

The Test.process will run and generate an error telling you test test has not been implemented

Selecting a Test To Run

Implement Your Own Test Logic

Stop the tester and delete the "AssertFail" activity in your test. Add a "Call Process" activity to your test and set the Process Name (in the Call Process "Configuration" tab) to a process you want to test; it's easiest to start with a process that produces an output that is determined by its' input. In the "Input" tab input some suitable test data.

Add an "AssertEqual" to your test by dragging it from "BWUnit/Public/Asserts/AssertEqual". Add transitions from "Start" to your "Call Process", from "Call Process" to "AssertEqual" and from "AssertEqual" to "End".

Implementing A Test

In the "Input" for "AssertEqual" map the output of "Call Process" to under "equal-input/actual". Build the output you expect from "Call Process" under "equal-input/expected".

Run the test like you did before and if your process produces the output you expected then the test will finish succefully. If not, the error will contain both the expected and actual values, which can be used to adjust the expected input.

Using the Example Projects

BWUnit comes with a number of example projects that demonstrate different ways BWUnit can be used to test your projects.

The HelloWorld example provides a very basic example of how BWUnit can be used to unit test a BusinessWorks process.

The Simple example demonstrates how a H2 in-memory database (http://h2database.com/html/main.html) can be used to replace the need for a production like database during unit and system testing and to ensure the tests are repeatable. Similarly, it uses Apache ActiveMQ (http://activemq.apache.org/) in an in memory (A.K.A. embedded) mode to replacer the need for a production like JMS implementation during unit and system testing. It also contains a small number of tests to demonstrate answers to questions on TIBCommunity (https://www.tibcommunity.com) and StackOverflow (http://stackoverflow.com/).

The Currency example demonstrates how dependency injection (http://xunitpatterns.com/Dependency%20Injection.html) can be implemented with BusinessWorks, so that stubs can be used during unit and system testing, instead of relying on seperate systems. The Currency example also demonstrates how Integration Contract Tests (http://www.martinfowler.com/bliki/IntegrationContractTest.html) can be implemented, so that you can ensure that your stubs behave in a similar mannar to the systems they are stubs of.

Finally, the SelfTest example shows how BWUnit is used to test BWUnit.

== Advanced Configuring ==

Setting Engine Properties from Ant

BW engine properties to be used when the run-functional-tests target is run can be set from within Ant by creating a properties prefixed with engine.properties.. For instance to enable job statistics, use:

<property name="engine.properties.bw.engine.jobstats.enable" value="true"/>

Preventing Process Starters from Running

Often it is neccesary to disable certain processes starters during a test run. This can be done using the Config.Primary.Partitions engine property to limit the processes that are loaded. However when using this approach you must include BWUnit.process and all of your tests. For example the following code will enable the BWUnit process starter, all of the tests, their dependencies and no other process starters.

    <pathconvert property="engine.properties.Config.Primary.Partitions" dirsep="/" pathsep=",">
        <map from="${bwda.bw.project.path}" to="" />
        <path>
            <pathelement location="${bwda.bw.project.path}/BWUnit.process" />
            <fileset dir="${bwda.bw.project.path}" includes="**/*TestSuite/*TestCase/*.process" />
        </path>
    </pathconvert>

Setting Global Variables from Ant

Global Variables to be used when testing in Desginer and when the run-functional-tests target is run, can be set from within Ant by creating a properties prefixed with engine.gvars.. For instance to set the DirLedger global variable use:

<property name="engine.gvars.DirLedger" location="${bwda.build.dir}/ledgers"/>

Setting File Aliases from Ant

File Aliases to be used by Designer or when the run-functional-tests, validate or ear targets are run, are automatically set to the files within ${bwda.aliases.dir}. You can add libraries in additional locations by creating properties prefixed with engine.aliases.. For instance to add Z:\shared\common-1.7.11.projlib as an alias use:

<property name="engine.aliases.common-1.7.11.projlib" location="Z:/shared/common-1.7.11.projlib"/>

Otherwise, for complete control over the file aliases, create a propertyset with the id bwengine.aliases. e.g.

<propertyset id="bwengine.aliases">
    <propertyref prefix="myproject.aliases." />
    <mapper type="glob" from="myproject.aliases.*" to="*"/>
</propertyset>

Controlling the Class Path from Ant

Jar files located in ${bwda.classpath.dir} will be automatically added the the class path for Designer and when you run the ear and validate targets. Alternatively for finer control, you can set the bwda.bwengine.classpath property to the desired classpath. For instance

    <pathconvert property="bwda.bwengine.classpath">
        <fileset dir="${bwda.classpath.dir}">
            <include name="*.jar" />
        </fileset>
        <fileset dir="Z:/shared/jars">
            <include name="*.jar" />
        </fileset>
    </pathconvert>

Creating Tests and A Testing Hierarchy

BWUnit Tests are arranged in a hierarchy, comprised of folders. Test Suites can contain Test Cases and other Test Suites. Test Cases can contain Tests and optionally a Fixture.

Example Testing Hierarchy

Creating Test Suites

Test Suites represent a collection of Test Cases. To create a Test Suite, create a folder ending with TestSuite.

Creating Test Cases

Test Cases represent a collection of Tests that shared a common Fixture. To create a Test Case, create a folder within a Test Suite ending with TestCase.

Creating Tests

Tests contain the logic that verifies if your processes behave in the manner they are expected to. They provide a mechanism for encoding the requirements for the processes they test.

To create a Test:

1. Copy the BWUnit/Public/Templates/Test.process into a Test Case.
2. Rename the copy. Any name except Fixture is permitted.
3. Modify it to call a process (or processes) you want to test.
4. Enter specific input to the process (or processes).
5. Add Asserts to check the output generated is what it is expected.

Example Tests

Example of a Simple Test

In the example above, a Call Process activity is used to link a specific customer to an account. Another Call Process activity is then used to retrieve the accounts linked to that customer. An Assert Equals is then used to check the the customer is linked to the correct number of accounts.

Example of a More Complex Test

The example above is a unit test for AssertDoesNotEqual. Each instance of AssertDoesNotEqual is provided with a different input, to test different boundary conditions. When an error is expected, there is a success transition to an AssertFail and an error transition to an AssertEquals, which checks that the error generated matches the error we expect.

Adding Asserts to Tests

Asserts are used to confirm that the output of a call to a particular process is what is expected.

To add an assert to your test:

1. Drag the desired assert from the Project pane to your process
2. Create a transition to the assert from the desired activity
3. Set the desired input on the Assert
4. Create a transition from the Assert to the next desired Activity.

Generating Test Reports

BWUnit generates test reports via the supplied report-functional-tests Apache Ant target.

NOTE: TIBCO Hawk or TIBCO Administrator must have been configured for the local system using the domain name LOCAL

As described in the Installation Steps section, the bwda.results.bwunit.xml, bwda.results.bwunit.html and bwda.results.junit.xml properties are used to specify where you want BWUnit to create the reports.

Example HTML BWUnit Test Report

Generating Test Coverage Reports

BWUnit also generates test coverage reports for BusinessWorks projects via the supplied run-functional-tests Apache Ant target. As described in the Installation Steps section, the bwda.results.emma.xml property is used to specify where you want BWUnit to create the report.

The coverage report is in Emma xml format, which is compatible with popular tools like Jenkins.

The following table lists the mapping between BW code concepts and how their equvilent in the Emma report

NOTE: Coverage of transitions is not reported at this time.

Continuous Integration

BWUnit is designed to work with your Continuous Integration server, such as Hudson, Jenkins, Bamboo CruiseControl or ThoughtWorks Go. The provided report-functional-tests Apache Ant target produces JUnit compatible XML output, allowing your continuous integration server to clearly indicate which test(s) failed and why. Simply configure your continuous integration server to call the run-functional-tests target and specify that the path to the JUnit formated test results.

For example, to have Jenkins run the tests and parse the test report with the default BWUnit settings, use:

Hudson Dashboard for the BWUnit Project Showing a Test Result Trend from BWUnit Tests

The bwda.results.emma.xml property used by the report-functional-tests target specifies the location to create the Emma (http://emma.sourceforge.net/) compatible XML coverage report, which can also be integrated with your continuous integration server. The coverage reports show you which processes and activites were and were not executed during the test run, so you can see which parts or your code need more tests.

For example, to integrate the coverage reports with Jenkins using the default BWUnit settings:

1. Install the Emma plugin (https://wiki.jenkins-ci.org/display/JENKINS/Emma+Plugin)
2. Add a "Record Emma coverage report" post build action
3. Set the "Folders or files containing Emma XML reports" to build/test-results/coverage-*.xml

Further Reading

Continuous Delivery

The Continuous Delivery book sets out the principles and technical practices that enable rapid, incremental delivery of high quality, valuable new functionality to users. Through automation of the build, deployment, and testing process, and improved collaboration between developers, testers, and operations, delivery teams can get changes released in a matter of hours— sometimes even minutes–no matter what the size of a project or the complexity of its code base. The website for the book can be found at http://continuousdelivery.com/

xUnit Test Patterns

The xUnit Test Patterns book and website provide many unit testing patterns and approaches, along with anti-patterns or "smells". We highly recommend this book to anyone who is serious about unit testing. The website can be found at http://xunitpatterns.com/

Copyright

© Windy Road Technology Pty. Limited 2009-2016. All Rights Reserved.

Apache Ant Macros

The following section details each of the Apache Ant macros provided by BWUnit

• bw-start
• bw-stop
• convert-to-html-results
• convert-to-junit-results
• convert-to-nunit-results
• designer
• install-license-local
• run-tests
• validate-project

bw-start

Starts a BusinessWorks engine locally, with BWUnit aliases

Attributes

Parameters specified as attributes.

bw-stop

Invokes a SOAP operation on a BWUnit BW engine to stop it

Attributes

Parameters specified as attributes.

convert-to-html-results

_(Deprecated. Automatically coverted by the run-tests macro.)_ Converts the specified BWUnit results file into HTML format

Attributes

Parameters specified as attributes.

convert-to-junit-results

_(Deprecated. Use the results-junit attribute in the run-tests macro.)_ Converts the specified BWUnit results file into JUnit format

Attributes

Parameters specified as attributes.

convert-to-nunit-results

Converts the specified BWUnit results file into NUnit format

Attributes

Parameters specified as attributes.

designer

Opens a project in TIBCO Designer, with BWUnit aliases

Attributes

Parameters specified as attributes.

install-license-local

Installs a BWUnit license locally

Attributes

Parameters specified as attributes.

run-tests

Starts a BusinessWorks engine locally and executes the project's BWUnit tests.

Attributes

Parameters specified as attributes.

validate-project

Allows you to validate resources within a TIBCO BusinessWorks Project, with BWUnit aliases.

NOTE: On Linux based systems an X-server is required to run the validate executable that this macro uses. On headless systems Xvfb can be used to meet this requirement: http://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml

(Available since version 1.6)

Attributes

Parameters specified as attributes.