Oracle Application Server PDK Test Harness
Getting Started

Introduction

This is a quick start guide designed to help you get up and running with the Portal Studio Test Harness in as little time as possible. The Test Harness can be used to both performance test and unit test your web provider without the need for an OracleAS Portal instance. The Test Harness achieves this by sending HTTP requests to a given target and recording the responses obtained from that target, along with the time it took to receive that response. These responses are logged to a file in an XML format for analysis. A performance statistics file is also produced, and a number of other optional output files are available. The Test Harness reads the definition of a test from a Test Definition file. The Test Definition, which follows an XML format, lists Request Instances to be sent to a target web provider in order to test that provider. A Test Definition may or may not reference a Request Library file to obtain request details. This is another XML file that contains a number of requests that various Test Definition files may access to enable requests to be re-used. For more information about the configuration concepts used by the Test Harness, please see the Terms and Definitions section.

The Test Harness includes a number of sample Test Definitions and Request Libraries whose requests access portlets from the PDK Java sample provider.

Assumptions

You have set up and installed the PDK Java sample provider.

Sections

Terms and Definitions
Sample Configuration Files
Running Tests
A Note for UNIX Users

Terms and Definitions

This document introduces a number of terms specific to the test harness. The most important terms are defined below. To see working examples of the terms defined, please see the example test definitions and request libraries supplied with the test harness.

• Request Instance
  A Request Instance represents a HTTP request that can be sent by the Test Harness to a defined target (i.e. a Web Provider). Request instances are listed in XML format in a Test Definition file.
• Test Definition
  A Test Definition is an XML file that lists the Request Instances for a particular test. The details for Request Instances may be defined directly inside the Test Definition (known as 'inline') or the Request Instances can refer to a Request Library (see below), in order to obtain its details. If you reference a Request Library it is still possible to provide an inline definition, but in this case the inline definition will augment the details obtained from the Request Library definition. Request Instances are grouped into Request Groups (see below) within the Test Definition. In addition to Request Instances, other configuration information is included in a Test Definition, for example the host port and path of the target the requests are to be sent to, and any pre-processors (see below) that should be used.
• Request Group
  A Request Group is used in order to logically group Request Instances together within a Test Definition and provide a logical context for application logic such as cookie handling and specifying the number of cycles and threads of the Request Instances a Request Group to run. A Test Definition can have one or more Request Groups and and any number or combination of Request Groups from a single Test Definition can be run in a particular execution of the Test Harness.
• Request Library
  A Request Library is simply a file that lists Request Definitions (see below) in XML format. These Request Definitions can be referred to by any number of Request Instances. Therefore the Request Definitions in a Request Library are re-usable, saving time and effort when configuring Test Harness tests.
• Request Definition
  A Request Definition is similar to an inline Request Instance in a Test Definition in that it is XML representing a HTTP request that can be sent by the Test Harness. The difference is that it is referred to and used by any number of Test Definitions in order to create a Request Instance
• Pre-processor
  A pre-processor enables application specific logic to be included in Request Instances at run-time in the Test Harness. For example, the Portal Pre-processor will check the validity of XML in SOAP messages. In other situations a Request Instance may need changes to be made based on the last response received (when a single Request Instance is run multiple times), for example the Validation Based Caching pre-processor needs to extract a header from a response and include it in the next run of the request to successfully use the validation based caching features of OracleAS Portal. The Test Harness supplies three pre-processors:
  • Portal pre-processor, which makes some Portal specific changes to Request Instances if necessary.
  • Validation Based Caching pre-processor, which updates Request Instances to make use of validation based caching features in OracleAS Portal.
  • HMAC pre-processor, which updates Request Instances to make use of the HMAC (Hashed Message Authentication Checksum) features of OracleAS Portal.

Sample Configuration Files

Test Definition Files

A number of test definition files are provided to demonstrate the features of the Test Harness and give you a starting point for creating your own test definitions. The test definitions include:

• sanityTest.xml
  Basic sanity tests for a single portlet in a web provider
• loadTest.xml
  Basic load tests for a single portlet in a web provider
• hmacTest.xml
  Tests for a web provider using HMAC authentication
• vcacheTest.xml
  Tests for a web provider Hello World portlet using Validation Based Caching

All example Test Definitions are contained in the pdktest\examples directory.

Request Library Files

Each of the Test Definition files listed above make use of a Request Library file. Two such files have been provided, one for 309 Portal requests and one for 902 portal requests. The Test Definitions are set up to use the 902 Request Library. They are contained in the pdkTest\rlib directory.

Note: if you create your own request libraries, placing them in this directory will mean that they are automatically available to the Test Harness.

• ptl309.xml
  Contains requests in the format sent by a 309 portal
• ptl902.xml
  Contains requests in the format sent by a 902 portal

Running Tests

Setting Up Your Environment

To set up your environment to run the Test Harness, unzip the pdktest.zip file to a convenient location. This will place a directory called pdktest on your machine that contains all of the Test Harness files. Set an environment variable called PDKTEST_HOME to point to this location. For example, if you extracted to D:\ you would now have a directory called D:\pdktest, which is the value that PDKTEST_HOME should be set to.

The Test Harness provides executable scripts in the bin directory, so to ensure they can be run from anywhere on your file system, append PDKTEST_HOME\bin to your PATH environment variable.

Setting Up The Test Definition Files

In the Test Definition files you need to set the defaultHost, defaultPort and defaultPath elements to match the location of your sample web provider. The Test harness comes with two sample Request Libraries, and the sample Test Definitions are set to use the ptl902.xml library.

To decide which Request Library to use you need to consider two things - the version of PDK Java used by the web provider and the versions of OracleAS Portal instances that regularly access it. If the version of the PDK Java used is 3.0.9.x or lower then you should use the sample 309 library (ptl309.xml) . If it's version 9.0.2.x or higher you should use the sample 902 library (ptl902.xml), unless the provider is regularly accessed by a portal version 3.0.9.8.x, in which case you should use the sample 309 library.

If you do need to change your Test Definition file to use the sample 309 library, simply replace references to 'ptl902' in the Test Definition to 'ptl309'.

Running The Test Harness

To run the Test Harness issue the following command:

• runTest <<options>> <<TestDefinition>>

Options

When running the test harness you can specify the following options (you can see these options by running the test harness with no arguments)

Examples

Running all tests in the sanity Test Definition, using the test name 'myTest' and accepting all defaults

• runTest -n myTest --all-groups $PDKTEST_HOME\examples\sanityTest.xml

Running the register and show groups in the sanity Test Definition, using the test name 'myTest' and switching off performance statistics generation.

• runTest -n myTest -g register,show --no-perf $PDKTEST_HOME\examples\sanityTest.xml

Running all groups in the sanity test definition, and generating a csv file and no performance statistics file:

• runTest --all-groups -c results.csv --no-perf sanityTest.xml

Running the register group in the HMAC test definition, with minimum response output and using defaults on everything else:

• runTest -g register -v MIN hmacTest.xml

Running the register, load_20 and deregister groups in the loadTest test definition, specifying verbose output and the minimum response log level and generating a ctl script.

• runTest -g register, show_20, deregister -v MIN -s results.ctl --verbose

A Note For UNIX Users

If the Test Harness is to be run on a UNIX based platform, you will need to grant execute permissions to the shell script runTest which can be found in $PDKTEST_HOME/bin before you try to run the Test Harness. For example, if you are already in the $PDKTEST_HOME directory, issue the following command:

• chmod a+x bin/runTest