Unregistering references to test objects

Helper script methods refer to an object in the application-under-test by using the test object map. Rational® Functional Tester finds such mapped objects each time a method is called on the object. In some cases; however, you might not want Rational® Functional Tester to do this.

For instance, you might want to call many methods directly on the same object, and it would lose time for Rational® Functional Tester to find the object each time a method was called on it. You can use the TestObject.Find method to find an object without Rational® Functional Tester calling any methods on the object. TestObject.Find returns a new TestObject containing a different kind of reference to the object in the application-under-test. This reference is sometimes called a bound reference, a found reference, or a non-mapped reference.

A bound reference retains access to the object in the application-under-test until you explicitly unregister the reference. Rational® Functional Tester unregisters bound references only when the entire playback ends, not when the script ends. As long as a bound reference to the object exists, Rational® Functional Tester may prevent the object in the application from being entirely free. For example, while you hold a bound reference to a Java™ object, the Java™ object is not garbage collected. You must explicitly unregister any bound references you create as soon as you do not need them any more.

In a normal Functional Test script, the only TestObjects containing mapped references are the methods from the helper scripts. All other TestObjects contain bound references and must be unregistered. For example, the method TestObject.GetTopParent is explicitly declared to return a TestObject. Other methods are declared to return a System.Object, but can return a TestObject that must be unregistered -- for example, TestObject.GetProperty.

RationalTestScript contains several methods that remove references to TestObjects, including net.Rational.Test.Ft.Script.RationalTestScript.Unregister and UnregisterAll. (See the Rational® Functional Tester API Reference for information on these methods.)

Objects that are returned from the application-under-test that are not TestObjects are objects that represent a value. The type of such an object is referred to as a value class. A value class is a copy of the object in the application-under-test, not a reference to an object in the application-under-test. Common examples of value classes are Integer and System.Drawing.Rectangle.

The Rational® Functional Tester recorder and wizards only generate code that returns value classes. For example, a property that you see in the Object Properties test case is a property whose value is a value class. You can call TestObject.GetNonValueProperties to find the reference properties available for a particular object. You can call TestObject.GetMethods to see the list of all the methods that you could invoke by calling TestObject.Invoke.

Use caution when dealing directly with TestObjects that contain references to objects in the application-under-test, because doing so may create instability in the application. Unregister these TestObjects as soon as possible.