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 derived from a built-in component and changed some minor behavior of the component you most likely 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 built-in component it derives from or you create a completely new component derived from UIComponent then you will need to prepare your component and RIATest for automation. The preparation of the custom component for automation is called 'instrumentation' and is described in depth in Flex documentation. Follow these guidelines to instrument your component and make it ready for automation.

Preparing class information file

The next step is to let RIATest know about your custom component. To do so you create an XML file that provides class information of your component. The class information file contains information regarding all properties and events that custom component introduces. The class information file also declares which built-in or other custom component does this component extend. This lets you omit the properties and events derived from the ancestor classes. The following is an example 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>
  </ClassInfo>
</AllClasses>

The format of the class information file is the following:

AllClasses	This is the root tag of XML file
ClassInfo	Each custom component definition must be enclosed in this tag. Attributes of this tag are: Name - the name of the custom component as you want it to be known to RIATest and appear in test scripts. Extends - the name of the ancestor component class. See list of built-in classes known to RIATest. If you create a completely new component you will most likely derive from UIComponent and specify FlexUIComponent as the ancestor automation class name.
Internal	Defines internally class name of the custom component or an event. The Class attribute of this tag should contain the corresponding internal class name, e.g. for FlexUIComponent it is mx.core::UIComponent. Note the double semicolon separator between package and class name.
Event	Describes an event for the class. Name attribute defines the name of the event. Internal child tag defines internally class name (attribute Class) and the type name (attribute Type) of the event. Property child tags define the parameters of the event. Attributes are - Name, DefaultValue. Child tag PropertyType defines the type of parameter.
Property	Describes a property of the custom component or the parameter of the event. Attributes are: Name - name of the property Verify - boolean value indicating if this property can be used for verification Describes - boolean value indicating if this property can be used for describing this component DefVerify - boolean value indicating if this property should be used for default verification
PropertyType	Describes the type of the property of event parameter. Attributes are: Type - one of Boolean, Number, int, String. Codec - optional attribute used for describing the exact type of the value. One of keyCode, keyModifier, object, object[], color, color[], automationObject, automationObject[], asset, asset[], listDataObject, listDataObject[], dateRange, dateRange[], dateObject, event, tab, scrollDetail, dateScrollDetail, scrollDirection, adgCell[].

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

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

Next: Automating custom components that contain other components.