|
| Sun ONE Connector Builder 2.0 Developer's Guide |
Testing the Generated Resource AdapterThis module describes the following topics:
- Introduction to TestClient
- Building Test Cases
- Configuration Files
- Deploying the Test Servlet Router
- Running the TestClient
- Running the TestClient with Sample Adapters
Introduction to TestClient
TestClient is a test harness provided by Connector Builder specially designed to test generated resource adapters on a wide variety of Connector Builder supported deployment platforms in both managed and non-managed environments.
Key Features of TestClient
The key features of TestClient are:
- Built-in test harness specially designed to test resource adapters in various modes. There is no need to configure or plug-in any third-party test harness.
- Provides basic infrastructure to easily develop tests for a resource adapter.
- Supports execution of tests in different containers, namely, web servers and application servers containers. These tests can be executed in any of supported containers by configuring the test harness.
- Provides a base test class which the developer extends to create test programs.
- Supports multi-user test environment so that the tests developed for unit testing can be used for load testing.
- Supports a configurable test environment including the execution of single, multiple, and repetitive tests, and the ability to exclude specific tests.
- Generates test-related configuration files as part of resource adapter generation.
- Generates detailed and summary test results to facilitate analysis of the test results. The summary report also includes average transaction processing time, which can be used for performance analysis.
- Provides a facility to re-run the failed tests.
- Provides a wide variety of sample test programs with sample resource adapters that can be used as a reference to build your own tests.
Key Components of TestClient
TestClient has two components:
Test Harness
This is the logical client-side component of the test client that reads the set of properties files and prepares the sequence of the execution of tests. This component also writes the log files.
Test Servlet Router
The Connector Builder Test Servlet Router is a test vehicle that executes test cases. The Test Servlet Router component is deployed with the adapter and resides on the server side - either in a web server or application server. There are two separate packages of the Test Servlet Router; one for deployment into an application server and the other for deployment into a web server. The application server Test Servlet Router can be used to test the adapter in either managed or non-managed mode. The web server Test Servlet Router can be used to test the adapter in non-managed mode.
TestClient Runtime Processing
When you run the TestClient, it executes the tests by performing the following steps:
- The Test harness prepares the test execution list and calls the Connector Builder Test Servlet Router.
- The Test Servlet Router executes the test case and returns the result to the test harness.
- The Test harness prepares the execution report when all the tests are completed.
The rest of the module describes how to install and configure the TestClient, develop test cases for generated resource adapter, and run the tests to verify the resource adapter is functioning correctly.
Building Test Cases
A test case is a single action that tests the adapter. This section covers:
The configuration files that TestClient requires are generated, with known default values, as part of the resource adapter generation. The configuration files are located under test/config directory of the resource adapter base directory. The naming convention of the generated files is: <ALN><config_file_name>, where <ALN> is the Adapter Logical Name that was specified when the resource adapter was generated. See "Creating the Resource Adapter", Step 3 - Entering Adapter General Information. For the COTS sample resource adapter, the following files are generated:
- COTStestrun.properties — Contains a list of runtime properties.
- COTStestlist.txt — Contains the list of tests to be executed.
- COTSexcludelist.txt — Contains the list of tests to be excluded.
- COTStestsetup.properties — Contains the main configuration parameters.
You may need to modify your generated files to reflect your testing environment. For more information, refer to the section about Configuration Files.
Developing Test Cases
The Connector Builder provides a framework for writing test cases. The framework related Java classes are defined in the com.sun.appinteg.adapter.test package. One template class is generated as part of each adapter and is located in the <adapterLogicalName>\test\src\<packageName>\test directory.
To write your own test cases, extend the ICONTest class and override the following methods to take advantage of Sun ONE Connector Builder TestClient functionality:
- public void setup(Properties prop) throws Exception
- public void test() throws Exception
- public void cleanup() throws Exception
public void setup(Properties prop) throws Exception
This method is called automatically just before the actual test method execution. Any initialization that is required before the test method execution can be performed in this method, for example JNDI context setup. The framework allows you to pass test related parameters from an external properties file. You need to specify the fully qualifies external properties files in the test run configuration file
public void test() throws Exception
You can implement this method or define and implement your own methods in the ICONTest subclass. If you do write your own test methods, you must indicate the status by having the method throw an exception as the test() method does. The test harness relies on this mechanism to report the test status.
You must indicate (to the test harness) which tests you want to run by listing them in the test list file in the following format:
<fully_qualified_class_name> <method name> <jndi name>
where <method_name> is the name of a method implemented in your test class. If you do not specify a value for <method_name>, the test harness calls the test() method by default. In that case, you must implement this method or the test harness throws an exception.
public void cleanup() throws Exception
This cleanup method is automatically called after execution of each test method. You can override the implementation of this method to perform test specific cleanup.
Example of a Test Case
The following code displays an example of the Test Case:
Packaging and Deploying Test Cases
The Sun ONE Connector Builder constructs a directory structure for test development for each resource adapter you create.
<ALN>/test is the root directory for tests, where <ALN> is the Adapter Logical Name specified when you generated the resource adapter. This test root directory contains the following subdirectories:
<ALN>/test/config: Contains the generated TestClient related configuration files.
<ALN>/test/src/<package>/test: Contains the generated test template, where <package> is the package specified for the generated resource adapter. Use the generated test template to develop your own tests.
It is strongly recommended to use the above directory structure and package for building tests. This facilitates automatic handling of compile and package tests with each resource adapter.
Use the `Build' and `Build All' menu actions available for the generated resource adapter node in the IDE to compile your tests along with adapter.
You must use the `Package with Tests' or `Package with SOAP and Tests' menu action to package the tests along with the resource adapter, so that the tests can be deployed automatically while deploying the resource adapter.
Configuration Files
The TestClient uses a set of configuration files that are generated as a part of adapter generation. The following files contain the necessary information about running the tests.
- Test List - Contains the list of tests to be executed.
- Exclude List - Contains the list of tests to be excluded. This is optional.
- TestSetup Properties - Properties defined in this file are made available for all tests at runtime. These properties can be accessed within setup() method of test class. This is optional.
- Testrun Parameters - This is the main configuration file and passed as an input to ictstclnt command used to start the test client.
Test List File
The Test List configuration file contains the list of tests to be executed. The file format is as follows:
- Contains an entry for each test to be executed.
- The format of the entry should be:
<fully qualified test class name><space><method name><space><jndi_name> If the method name is omitted, then 'test' is used by default. If the jndi_name is omitted, then 'ICONEJB' is used as the default value.
- An entry that starts with the # character is ignored.
The code below provides an example of the Test List file
.
In the third example, only the test class name is specified so the test harness runs the 'test' method in this class.
Exclude List File
This configuration file contains a list of tests to be excluded from run. Some tests may need to be excluded because the tests have been determined to be invalid.
The file format is as follows:
- Contains an entry for each test to be excluded from run.
- Each entry should be in the following format:
<fully qualified test class name><space><method name><space><jndi_name> format.
If the method name and jndi_name are omitted, then `test' is assumed as the method name and `ICONEJB' is assumed as the jndi_name.
- An entry starts the with the # character is ignored for exclusion process.
The code example below displays sample code for the exclude file list.
Exclude File List Example
Exclude File List Example
#
# Sun ONE Connector Builder v2.0 TestClient ExcludeList file
#
com.sun.appinteg.samples.cots.test.COTSTest test my EBJB
TestSetup Properties File
Sometimes tests must be run with different parameter values, for example, JNDI lookup name, UserName, Password. In this case, you can define these properties in the TestSetup properties file. This file follows the standard Java properties file format. All the properties (key=value) defined in this file are accessible within setup() method of test class.
The code example below displays sample code for the TestSetup Properties File.
TestSetup Properties File Example
#
# Sun ONE Connector Builder v2.0 TestClient TestSetup Properties file
#
# All the sample tests uses COTS for connection factory lookup name
JNDILOOKUP=COTS
Testrun Parameters File
The testrun parameters file is the main configuration file and is passed as an input to ictstclnt command. This testrun parameters file controls the behavior of TestClient for:
- Which tests to run
- How to execute the tests
- Where to put the results
This file follows the standard Java properties file format. The supported key and their values are listed below:
Mode of Execution Parameter
TestClient supports execution of tests in various containers, namely, Servlet, EJB.
Parameter Name: icon.test.mode
Valid Values: SERVLET, EJB
When to use SERVLET/ EJB:
If you are testing the resource adapter in managed mode, then the tests run in EJB mode. If you are testing the resource adapter in non-managed mode, test run in SERVLET mode.
To test the resource adapter in managed mode, you need to deploy the correct version of the Test Servlet Router. See "Deploying the Test Servlet Router" for more information.
The table below lists the valid values. The left column lists the value. The right column describes when to use the value.
All the test cases that can be run under servlet mode can also be run under EJB mode, but some of the test cases that run in EJB mode can not be run under servlet mode. For example, DBMSContainerTransTest1.java test case, which is packaged along with the DBMS sample application, should be run only in EJB mode (managed environment). This test case tests the local transaction mechanism of the adapter requires the application servers transaction services provided by Service Provider Interface.
Test Servlet Router URL Parameter
The Test Servlet Router URL parameter is the url by which the test servlet router is invoked by the test harness. If this url is placed on browser it displays a successful test servlet router deployment message.
Parameter Name: icon.test.url
Valid values: url to access test servlet router.
- Open the browser and point it to:
For Sun ONE Application Server 7:
http://<hostname:port>/icbtest/ICONTestServletRouter
For iAS 6.5:
http://<hostname:port>/NASApp/icbtest/ICONTestServletRouter
For iWS 6.0:
http://<hostname:port>/icbtest/ICONTestServletRouter
For RI 1.3:
http://<hostname:port>/icbtest/ICONTestServletRouter
Test Base Directory Parameter
The test base directory parameter is the base directory for tests and the parameter is not directly used. It is used as substitution parameter to define other parameter values.
Substitution provides a means of making the value of one entry depend on the value of another. When TestClient looks up a value, if the value contains the string ${name} in a file, TestClient substitutes that string with the value associated with name in the same file. It does not matter if the value is explicitly defined or inherited within that file.
Parameter Name: icon.test.testdir
Valid Values: Any valid directory
TestList File Parameter
Name of a fully qualified testlist file. This file contains the list of fully qualified tests to run.
Parameter Name: icon.test.testlist
Valid Values: <fully qualified testlist file name>
Example: ${icon.test.testdir}/COTStestlist.txt
ExcludeList File Parameter
Name of a fully qualified exclude list file. This file contains the list of tests to be excluded from run. This is optional.
Parameter Name: icon.test.excludelist
Valid Values: <fully qualified excludelist file name>
Example: ${icon.test.testdir}/COTSexcludelist.txt
Number of Clients Parameter
The Number of Clients Parameter defines the number of simultaneous users to be used while running the tests. Normally you increase this number to perform load testing.
Parameter Name: icon.test.clients
Valid Values: Any positive integer value
Default Value: 1
Number of Iterations Parameter
Defines the number of times each individual test is to be executed. Normally you wanted to set it to greater than 1 to perform load/longevity testing.
Parameter Name: icon.test.iterations
Valid Values: Any positive integer value
Default Value: 1
Thinktime Parameter
This is the idle/thinktime between any two requests in milliseconds.
Parameter Name: icon.test.thinktime
Valid Value: Any positive integer value
Default Value: 1000 milliseconds
Timeout Parameter
The timeout parameter allows you to set a time limit, in milliseconds, to be applied to each test that is executed. TestClient waits the specified time before it times out the request.
Parameter Name: icon.test.timeout
Valid Value: Any positive integer value
Default Value: 0 - no timeout
TestSetup Properties File Parameter
Name of a fully qualified testsetup properties file name. This is optional.
Parameter Name: icon.test.setupprop
Valid Values: <fully qualified file name>
Example: ${icon.test.testdir}/COTStestsetup.properties
Log/Report Directory Parameter
This is the base log/report directory to keep the TestClient generated summary and detailed reports for the test execution. All these files are kept under a timestamp subdirectory created for each test execution.
Parameter Name: icon.log.logdir
Valid Value: Any valid directory for which you have read and write access.
Log Level Parameter
Optionally you can set log level to control the amount of information that is written to log or report files.
Parameter Name: icon.test.loglevel
Valid Values: ERROR, WARNING, INFO, DEBUG, and OFF
Random Flag Parameter
This parameter is applicable only if number of clients and iterations parameters are set to a value greater than 1. In this configuration, if this value is set to true, the TestClient randomly picks one test from the list of tests for each iteration per client else all the tests are executed for each iteration per client.
Parameter Name: icon.test.random
Valid Values: true, false
Deploying the Test Servlet Router
The TestClient component is part of the Sun ONE Connector Builder Tools module and was installed if you selected this option when you installed the Sun ONE Connector Builder. If you did not select this option when you installed Sun ONE Connector Builder, then you should rerun the installation and select only the Sun ONE Connector Builder Tools module. The TestClient related libraries and commands are installed in the lib and bin directory of the Sun ONE Connector Builder installation directory.
You need to deploy the Test Servlet Router into the deployment platform before you begin using the Test Client. You should deploy either the .war or .ear package of the Test Servlet Router depending on whether you are testing the resource adapter in managed or non-managed mode. To test the resource adapter in managed mode, you must deploy the icbtest.ear package.
The icbtest.ear file contains the EJB vehicle, a stateless container managed session bean. When the adapter is deployed in a J2EE1.3 compatible application server like Sun ONE Application Server 7, it runs in managed mode. In this mode the application server takes care of pooling, transactions and security. For example, if you want to test the adapter's transaction capability, you must use Test Client in EJB mode. When you test the adapter, you can substitute different values for the transaction parameter (trans-attribute) in the EJB's deployment descriptor. By doing so, you can test the adapter with or without a transaction.
To Deploy Test Servlet Router into Sun ONE Application Server 7
In Sun ONE Application Server 7, adapters work in managed mode, and the icbtest.ear package is used for deploying the Test Servlet Router. Refer to the Sun ONE Application Server 7 documentation for details on how to deploy ear files.
The Test client supports both EJB and SERVLET mode.
To Deploy Test Servlet Router into iPlanet Application Server 6.5
In iPlanet Application Server 6.5, adapters work only in non managed mode, therefore, use the icbtest.war package for deploying the Test Servlet Router. Refer to the iPlanet Application Server 6.5 documentation for details on how to use the iPlanet Application Server 6.5 Deployment Tool.
The Test client supports only SERVLET mode.
To Deploy Test Servlet Router into iPlanet Web Server 6.0
In iPlanet Web Server 6.0, adapters work only in non managed mode, therefore use icbtest.war package for deploying Test Servlet Router.
Test client supports only SERVLET mode.
Windows:
Set IWS_SERVER_HOME=<web_server_home_directory>.
For example, SET IWS_SERVER_HOME=d:\iPlanet\Servers.
cd to <web_server_home_directory>\bin\https\httpadmin\bin.
Run the command: wdeploy deploy -u /icbtest -i <webserver_instance_name> -v <virtual_server_id> <connector_builder_install_root>\lib\icbtest.war
For example: wdeploy deploy -u /icbtest -i https-myhost.acme.com -v https-myhost.acme.com d:\sun\lib\icbtest.war
Solaris:
Set IWS_SERVER_HOME=<web_server_home_directory>.
For example, setenv IWS_SERVER_HOME /usr/iplanet/servers.
cd to <web_server_home_directory>/bin/https/httpadmin/bin.
Run the command: wdeploy deploy -u /icbtest -i <webserver_instance_name> -v <virtual_server_id> <connector_builder_install_root>/lib/icbtest.war
For example: wdeploy deploy -u /icbtest -i https-myhost.acme.com -v https-myhost.acme.com /usr/sun/lib/icbtest.war
The server should be restarted for the changes to take effect. Refer to iPlanet Web Server documentation for details on how to deploy web applications.
To Deploy Test Servlet Router into J2EE RI Server (j2sdkee1.3.1)
In the J2EE Reference Implementation (RI) Server you can run the adapter in managed mode, therefore use the icbtest.ear package to deploy the Test Servlet Router. Refer to the J2EE RI documentation for more details.
Test client supports both EJB and SERVLET modes.
Verifying Successful Deployment of the Test Servlet Router
The Test Servlet Router is ready to use after you complete deployment and restart the server.
To check whether the Connector Builder Test Servlet Router is deployed successfully:
- Open the browser and point it to:
For Sun ONE Application Server:
http://<hostname:port>/icbtest/ICONTestServletRouter
For iPlanet Application Server 6.5:
http://<hostname:port>/NASApp/icbtest/ICONTestServletRouter
For iPlanet Web Server 6.0:
http://<hostname:port>/icbtest/ICONTestServletRouter
For J2EE RI Server 1.3.1:
http://<hostname:port>/icbtest/ICONTestServletRouter
If the Test Servlet Router is configured properly, the following message is displayed:
`Please use Sun ONE Connector Builder TestClient to run tests'.
Running the TestClient
Use ictstclnt command available under the bin directory of the Connector Builder installation directory to start TestClient. This command can be executed either from <connector_builder_install_root>/bin or from any directory provided <connector_builder_install_root>/bin directory is set in the PATH environment variable.
The syntax of the command is as follows:
ictstclnt [-h] [-v] -i <testrun_parameters_file>
The command ictstclnt takes testrun parameters file as an input. The testrun parameters file is the main configuration file which the TestClient reads and executes the tests. The results of the tests are stored in a summary file. The location of summary file is specified in the testrun_parameter_file.
Examining the Test Results
TestClient generates summary and detailed reports for each test execution. These files are placed under a subdirectory created for each test run under the log base directory specified in Testrun Parameters file. The subdirectory is named with timestamp value.
You should use the generated report/log files to analyze the test results. Here is the list of summary files generated by TestClient:
- summary.txt
Contains summary of test execution. It includes the list of testrun parameters used for test execution, the list of tests, average processing time per client and total number of tests passed and failed.
- testlist.list
Contains the list of tests considered for test execution by considering the exclude list.
- testlist.fail
Contains the list of test failed. You can reuse this file as a testlist file to re-run the failed tests. This file will not be generated when the tests are run in multi-client mode.
- icontest.log
Contains additional debug messages if the log level is set to DEBUG.
In addition to above summary report files, TestClient also generates detailed test execution report for each client with name client#<no>.log under `logs' subdirectory of summary report location.
Running the TestClient with Sample Adapters
The Connector Builder includes two comprehensive samples to illustrate its key features:
- Customer Order Tracking System (COTS) Sample
- DBMS Sample
Several test cases, included with these two sample adapters, can be used as a reference to build tests for resource adapter for your own backend system.
You can find test related source and configuration files for these sample adapters at:
<connector_builder_install_root>/samples/cots/adapters/COTS/test for the COTS resource adapter and <connector_builder_install_root>/samples/dbms/adapters/DBMS/test for the DBMS resource adapter.
You must deploy the sample adapters prior to running the TestClient using tests provided with sample adapters. Refer to AppendixModule B for more details on deploying the sample adapters.
The following commands that are located in icb_home\bin should be used in order to run the TestClient:
for COTS:
icbtest.bat -i <icb_home>\samples\cots\adapters\COTS\test\config\ COTStestrun.properties
for DBMS:
icbtest.bat -i <icb_home>\samples\dbms\adapters\DBMS\test\config\ DMBStestrun.properties