Automating custom components

If you have custom components in your application you may need to perform additional steps to fully support the automation. If you have merely used built-in components and changed some minor behaviour of the component you probably will not need to do anything special. RIATest will recognize the derived component and will identify it as its closest built-in ancestor class.

Instrumenting custom components

However if your new component adds new properties or events to the built-in component it is derived from or you create a completely new component derived from a UIComponent then you will need to prepare your component and RIATest for automation. This preparation of the custom component for automation is called 'instrumentation' and is described in depth in the Flex documentation. Follow these guidelines to instrument your component and make it ready for automation.

Preparing class information

The next step is to let RIATest know about your custom component. There are two ways to do it:

• you can create an XML file that provides class information of the component
• you can implement the getClassInfoXML() function in your delegate class that will return class information.

Let us first see how to create an XML file that provides class information of your component. The class information file contains information regarding all properties and events that the custom component introduces. The class information file also declares which built-in or other custom component this component extends to. This lets you omit the properties and events derived from the ancestor classes. The following is an example of a class information file that describes the RandomWalk custom component from Adobe's RandomWalk sample:

<?xml version="1.0" encoding="UTF-8"?>
<AllClasses>
  <ClassInfo Name="FlexRandomWalk" Extends="FlexUIComponent">
    <Internal Class="RandomWalk"/>
    <Events>
      <Event Name="Select">
        <Internal Class="randomWalkClasses::RandomWalkEvent" Type="itemClick"/>
        <Property Name="itemRenderer">
          <PropertyType Type="String" Codec="automationObject"/>
        </Property>
      </Event>
    </Events>
    <Properties>
      <Property Name="automationClassName" Describes="true">
        <PropertyType Type="String"/>
      </Property>
      <Property Name="automationName" Describes="true">
        <PropertyType Type="String"/>
      </Property>
      <Property Name="className" Describes="true">
        <PropertyType Type="String"/>
      </Property>
      <Property Name="id" Describes="true" Verify="true">
        <PropertyType Type="String"/>
      </Property>
      <Property Name="automationIndex" Describes="true">
        <PropertyType Type="String"/>
      </Property>
      <Property Name="openChildrenCount" Verify="true" DefVerify="true">
        <PropertyType Type="Integer"/>
      </Property>
    </Properties>
	 <Methods> 
      <Method Name="methodWithoutParams"> 
        <Internal Type="methodWithoutParams"/> 
      </Method> 
    </Methods>
  </ClassInfo>
</AllClasses>

The format of the class information file is the following:

The class information XML file can have any name ending with an .xml extension and must be placed in the classinfo sub-directory of the RIATest installation directory. RIATest reads all XML files in this directory on start-up. For any changes to have effect you will need to restart RIATest.

You can also place the class information XML file in the classinfo sub-directory of your project directory. RIATest attempts to read all XML files in this directory when opening the project. This allows you to have per-project class information files that describe custom components specific for the project. For any changes to have effect you will need to reopen the project (no need to restart RIATest).

Specifying class properties

You can specify properties in class definition file. This serves a few purposes: the property appears in the list of properties in the Inspector window, the property will appear in auto-complete lists in script editor and you can set the propery to be used by default for verification when Verify button is clicked in the Inspector window.

You can use one of the predefined Codecs to convert property value before sending it from your application to RIATest IDE. Codecs are provided for various data types (see PropertyType tag description in the above table). If you do not want to perform any conversion of the value you can use object codec which will access property value as is even if the property value is a not a primitive type. Anonymous objects and arrays will be available natively to RIATest. Non-anonymous objects will be converted to equivalent anonymous objects. For example when a property myProp contains a complex object it can be verified in the script like this:

verifyEqual(FlexControl("unique")=>myProp,{prop1:"val1",prop2:123});

Implementing getClassInfoXML() in a delegate class

Important: The usage of getClassInfoXML() function in the delegate class as described in this section is only applicable when you use static compilation of RIATest Agent with your application. This will not work for applications that use Runtime Loading scheme.

If you do not want to create and maintain separate XML files you can embed the same XML information in the delegate class that you implement for your component. To do this the delegate must implement a getClassInfoXML function that will return XML class information. The structure of the XML is exactly as described above. For example if you have a MyButton component derived from Button and which has a myProp property you could implement the delegate class as follows:

[Mixin]
public class MyButtonDelegate extends ButtonAutomationImpl
{
    public static function init(root:DisplayObject):void 
    {
        // Pass the component and delegate class information.
        Automation.registerDelegateClass(MyButton, MyButtonDelegate);
    }

    public function MyButtonDelegate(obj:Button)
    {
        super(obj);
    }
    
    public static function getClassInfoXML(): XML
    {
        return <ClassInfo Name="MyButton" Extends="FlexButton">                
                 <Internal Class="MyButton"/>
                  <Properties>
                   <Property Name="myProp" DefVerify="true" Verify="true">
                    <PropertyType Type="Boolean"/>
                  </Property>
                </Properties>
              </ClassInfo>;
    }
}

Note that RIATest caches XML class information that you define in class delegates in the _cachedClassInfo.xml file located in the classinfo subdirectory of a RIATest project file. The cache is updated when the RIATest Agent connects to the RIATest IDE. If you remove any custom class from your application you will need to remove its definition from _cachedClassInfo.xml manually or simply delete the cache file and it will be re-created automatically.

For more examples of class definition files see flex_classes.xml in the RIATest installation directory. This file describes all built-in components of Flex 3.

See also

• Exposing events of custom components
• Exposing methods of custom components
• Automating custom components that contain other components