How to create an automatable custom component?

Creating a delegate class

To instrument custom components with a delegate, you must do the following:

• Create a delegate class that implements the required interfaces. In most cases, you extend the UIComponentAutomationImpl class. You can instrument any component that implements IUIComponent.
• Register the delegate class with the AutomationManager.
• Define the component in a class definitions XML file.

The delegate class is a separate class that is not embedded in the component code. This helps to reduce the component class size and also keeps automated testing code out of the final production SWF file. All Flex controls have their own delegate classes. These classes are in the mx.automation.delegates.* package. The class names follow a pattern of ClassnameAutomationImpl. For example, the delegate class for a Button control is mx.automation.delegates.controls.ButtonAutomationImpl.

To instrument with a delegate class:

1. Create a delegate class.
2. Mark the delegate class as a mixin by using the [Mixin] metadata keyword.
3. Register the delegate with the AutomationManager by calling the AutomationManager.registerDelegateClass() method in the init() method. The following code is a simple example:

   [Mixin]
   public class MyCompDelegate {
   public static init(root:DisplayObject):void {
    // Pass the component and delegate class information.
    AutomationManager.registerDelegateClass(MyComp, MyCompDelegate);
   }
   }
   

   You pass the custom class and the delegate class to the registerDelegateClass() method.

4. Add the following code to your delegate class:
   1. Override the getter for the automationName property and define its value. This is the name of the object as it appears in QTP. If you are defining an item renderer, use the automationValue property instead.
   2. Override the getter for the automationValue property and define its value. This is the value of the object in QTP.
   3. In the constructor, add event listeners for events that QTP records.
   4. Override the replayAutomatableEvent() method. The AutomationManager calls this method for replaying events. In this method, return whether the replay was successful. You can use methods of the helper classes to replay common events.

      For examples of delegates, see the source code for the Flex controls in the mx.automation.delegates.* packages.

5. Link the delegate class with the application SWF file in one of these ways:
   • Add the following includes compiler option and link in the delegate class:

     mxmlc -includes MyCompDelegate -- FlexApp.mxml

     
     
   • Build a SWC file for the delegate class by using the compc component compiler:

     compc -source-path+=. -include-classes MyCompDelegate -output MyComp.swc

     
     

     Then include this SWC file with your Flex application by using the following include-libraries compiler option:

     mxmlc -include-libraries MyComp.SWC -- FlexApp.mxml

     
     

     This approach is useful if you have many components and delegate classes and want to include them as a single file.

6. After you compile your Flex application with the new delegate class, you must add the new component to QTP's custom class definition XML file.

Using the class definitions file

The TEAFlex.xml file contains information about all instrumented Flex components. This file provides information about the components to QTP, including what events can be recorded and played back, the name of the component, and the properties that can be tested.

The TEAFlex.xml file is located in the "QTP_plugin_install\Flex 2 Plug-in for Mercury QuickTest Pro" directory. QTP recognizes any file in that directory that matches the pattern TEAFlex*.xml, where * can be any string. This directory also contains a TEAFlexCustom.xml file that you can use as a starting point for adding custom component definitions.

The class definitions file describes instrumented components to QTP with the following basic structure:

   
       
       
       
           
           ...
       
       
           
           ...
       
   
 

The top level tag is . You define a new class that uses the tag, which is a child tag of the tag. The tag has child tags that further define the instrumented classes. The following table describes these tags:

Tag	Description
ClassInfo	Defines the class that is instrumented, for example, FlexButton. This is the name that QTP uses for the Button control. Attributes of this tag include Name, GenericTypeID, Extends, and SupportsTabularData.
Description	Defines the text that appears in QTP to define the component.
Implementation	Defines the class name, as it is known by the Flex compiler, for example, Button or MyComponent.
TypeInfo	Defines events for this class. Each event is defined in an child tag, which has two child tags: The child tag associates the operation with the actual event. Each operation can also define properties of the event object by using an child tag.
Properties	Defines properties of the class. Each property is defined in a child tag. Inside this tag, you define the property's type, name, and description. For each Property, if the ForDescription attribute is true, the property is used to uniquely identify a component instance in QTP; for example, the label property of a Button control. QTP lists this property as part of the object in QTP object repository. If the ForVerfication attribute is true, the property is visible in the properties dialog box in QTP. If the ForDefaultVerification tag is true, the property appears selected by default in the dialog box in QTP. This results in verification of the property value in the checkpoint.

The following example adds a new component, MyComponent, to the class definition file. This component has one instrumented event, click:

          Extends="FlexObject" SupportsTabularData="false">
       FlexMyComponent
       
       
                          ExposureLevel="CommonUsed">
                                  Type="click"/>
           
       
       
           
               
               This is MyComponent.
           
           
               
               The name used by QTP to id an object.
           
           
               
               To be written.
           
           
               
               Developer-assigned ID.
           
           
               
               The index relative to its parent.
           
       
   
   ...

You can edit the class definitions file to add a new recordable event to an existing component. To do this, you insert a new in the control's block. This includes the implementation class of the event, and any arguments that the event might take.

The following example adds a new event, MouseOver, with several arguments to the Button control:

When you finish editing the class definitions file, you must distribute the new file to QTP users. They must copy this file manually to the "QTP_plugin_install\Flex 2 Plug-in for Mercury QuickTest Pro" directory. When you replace the class definitions file in the QTP environment, you must restart QTP.