WMQTest interface
Tests written for IBM® MQ Explorer must belong to a Java™ class that extends the provided WMQTest class. This topic explains the interface and the operation of the provided methods.
- Test attributes - attributes for your test object
- Creating the test - the constructor for test objects
- Test structure - the beginning and end of the test
- Running the test - the main body for tests
- User preferences - accessing the preferences
- Completing the test - marking a test as complete
- Creating a test result - create test results
- Dealing with canceling - what happens if the user wants to cancel a test
- Test documentation - providing more information about the test
Test attributes
Define a test in the plug-in manifest file (plugin.xml) by using a collection of attributes. The attributes for a test are listed in the following table.
Attribute | Description |
---|---|
id | A string that provides a unique identifier for the test. |
name | A meaningful name for the test. |
class | The name of the Java class that contains the test source code. |
testset | A string that defines the group in which to display the test; for example, wmq, which displays the test in the Queue manager tests category. |
testsubset | A string that defines the sub-group in which to display the test; for example, queues, which displays the test in the Queues category. |
description | A short description that describes what the test does. |
furtherinfo | The location of an HTML or XHTML document that contains more information about the test. This document is displayed in IBM MQ Explorer when you double-click the test in the Run Tests dialog or a test result in the Test Results view. |
You specify the values of these attributes in the plugin.xml file to define the test. These attributes can also be accessed programmatically using the WMQTest methods listed in the following table.
Method | Description |
---|---|
getTestID() |
Returns the test ID. |
getTestName() |
Returns the name of the test. |
getDescription() |
Returns the description of the test. |
getTestSet() |
Returns a handle for the test set object that was created to be a parent for the test. |
getFurtherInfoPath() |
Returns the location of the XHTML or HTML document that contains more information about the test. |
Creating the test
The IBM MQ Explorer Tests engine instantiates the test
object using the provided constructor WMQTest()
. There is no need to subclass this
constructor.
Test structure
The WMQTest
method runTest
defines
the body of the test, and is called to start a test running.
The
end of the runTest
method does not imply the end
of the test; you must explicitly specify the end of the test using
the testComplete
method. You can implement tests
so that they get the object data asynchronously.
The runTest
method
submits a request to get data about objects and the test runs from
the listener method that receives the reply. This enables the test
to wait for data without you needing to implement thread waiting;
this is demonstrated in Sample 3.
If a manual wait (sleep) is needed as a part of a test, you can use the object monitor for the
test object to use the Java
wait
and notify
methods. The threading of the test engine is
implemented without using the object monitors of individual test objects.
Running the test
The IBM MQ Explorer Tests engine calls
runTest(WMQTestEngine, IProgressMonitor,contextObjects, treeNode)
to start the test
running. The main body of your test must be here.
- WMQTestEngine
- The WMQTestEngine parameter provides a handle
to the test engine that is running the test.
This is provided to allow tests to return results while a test is in progress using the test engine's
returnResult(WMQTestResult[], WMQTest)
method.The first parameter of this method (
WMQTestResult[]
) contains the results to be returned, and the second parameter (WMQTest
) must be 'this
', so that the test engine knows where the results have come from. Using the WMQTestEngine parameter to return interim results is optional - alternatively, test results can be returned on test completion (see Completing the test). - IProgressMonitor
- The IProgressMonitor parameter provides a handle
to the GUI feedback monitor being used for the current test run. This
allows your test to provide both textual feedback on the task and
subtasks currently running, and a progress bar for current completion.
The handle to the Progress Monitor is cached by the default implementation of
runTest
, so if this has been used, a handle to the Progress Monitor can also be accessed using the WMQTest methodgetGUIMonitor()
.The Progress Monitor is a core Eclipse resource. See the Eclipse API documentation on the web for further advice on using it.
- contextObjects
- The contextObjects parameter provides an MQExtObject array. The parameter provides the context of the test to be run so that the relevant check boxes are pre-selected when the user opens the Run Tests dialog.
- treeNode
- The treeNode parameter records which folder or object in the Navigator view was clicked to run the default tests or to open the Run Tests dialog.
User preferences
Tests must conform to the user preferences provided using the Eclipse Preferences dialog. Use the following methods to access the preferences:
PreferenceStoreManager.getIncludeHiddenQmgrsPreference()
which returnstrue
if you include queue managers that have been hidden in IBM MQ Explorer in the test, orfalse
if they must be excluded.PreferenceStoreManager.getIncludeSysObjsPreference()
which returnstrue
if system objects (objects which have names beginning with SYSTEM.) must be included in the test, orfalse
if they must be excluded.
Completing the test
Complete
a test by calling testComplete(WMQTestResult[])
,
passing it an array of test result objects. See Creating a test result for guidance on test
result objects.
You can return results at completion using this method in addition to, or as an alternative to, returning test results during a test run (as explained in Running the test). However, any results that are returned twice are displayed twice.
Even if your test uses the WMQTestEngine
method returnResult
to
return all of its results, it must still call testComplete
on
completion. This is necessary to complete the test processing. You
can provide an empty array of WMQTestResult
objects
in the testComplete
method if there are no new results
to be returned.
For more information, see Test structure.
Creating a test result
Test
results are implemented as WMQTestResult
objects.
Create results using:
WMQTestResult(int severity, String description, String qmgrname, String objectType)
where:
severity
is an integer identifying the severity of the problem. Use one of the following severity levels:IMarker.SEVERITY_ERROR
,IMarker.SEVERITY_WARNING
orIMarker.SEVERITY_INFO
description
is the string explaining the problem found by the test, to be displayed in the Problems View.qmgrname
is the name of the queue manager where the problem was found.objectType
is string giving the class of object where the problem can be found, for example, "Queues" or "Channels".
For more information about what to do with the test result object when it has been created, see Completing the test.
Dealing with canceling
You can
cancel the test run while it is running. Use the method isCancelled()
to
check if a test must stop.
A good test must regularly check whether it has been canceled to avoid delaying a user unnecessarily.
If you try to cancel a test but the test fails to respond for an extended period of time, the test engine forces the test to stop by ending the thread that is running the test. Do not rely upon this method, it is preferable that a test responds in time allowing the test to clean up any resources it has used, and to return any test results that have been generated so far.
Test documentation
You can provide additional documentation to explain the results that they return, and provide guidance on what must be done to resolve the problem.
Provide documentation in HTML, with the location identified in the plugin.xml file for the plug-in providing the test. For details about defining tests in XML, see Creating a new test.
The location of the documentation HTML file can be:
- internal - Stored in the plug-in project providing the test itself. The location must be defined in the XML relative to the plugin.xml file itself. For example, doc/TestDoc.html
- external - Stored on a web-server, allowing maintenance of the documentation separately from the test itself. The location must be defined as a complete URL, beginning with 'http://'.