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 we 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. We 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, we 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 method getGUIMonitor().
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 returns true if you include queue managers that have been hidden in IBM MQ Explorer in the test, or false if they must be excluded.
- PreferenceStoreManager.getIncludeSysObjsPreference() which returns true if system objects (objects which have names beginning with SYSTEM.) must be included in the test, or false 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.
We 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 or IMarker.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
We 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
We 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://'.