Setting the Flex automationName Property

The automationName property defines the name of a component as it appears in tests. The default value of this property varies depending on the type of component. For example, the automationName for a Button control is the label of the Button control. Sometimes, the automationName is the same as the id property for the control, but this is not always the case.

For some components, Flex sets the value of the automationName property to a recognizable attribute of that component. This helps testers recognize the component in their tests. Because testers typically do not have access to the underlying source code of the application, having a control's visible property define that control can be useful. For example, a Button labeled "Process Form Now" appears in the test as FlexButton("Process Form Now").

If you implement a new component, or derive from an existing component, you might want to override the default value of the automationName property. For example, UIComponent sets the value of the automationName to the component's id property by default. However, some components use their own methods for setting the value. For example, in the Flex Store sample application, containers are used to create the product thumbnails. A container's default automationName would not be very useful because it is the same as the container's id property. So, in Flex Store, the custom component that generates a product thumbnail explicitly sets the automationName to the product name to make testing the application easier.

Example

The following example from the CatalogPanel.mxml custom component sets the value of the automationName property to the name of the item as it appears in the catalog. This is more recognizable than the default automation name.

thumbs[i].automationName = catalog[i].name;

Example

The following example sets the automationName property of the ComboBox control to "Credit Card List"; rather than using the id property, the testing tool typically uses "Credit Card List" to identify the ComboBox in its scripts:

<?xml version="1.0"?>
<!-- at/SimpleComboBox.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
  <mx:Script>
    <![CDATA[ 
      [Bindable] 
      public var cards: Array = [
        {label:"Visa", data:1}, 
        {label:"MasterCard", data:2},
        {label:"American Express", data:3}
      ];

      [Bindable]
      public var selectedItem:Object;
      ]
   ]> 
  </mx:Script>
  <mx:Panel title="ComboBox Control Example">
    <mx:ComboBox id="cb1" dataProvider="{cards}"
      width="150"
      close="selectedItem=ComboBox(event.target).selectedItem" 
      automationName="Credit Card List" 
    />
    <mx:VBox width="250">
      <mx:Text width="200" color="blue" text="Select a type of credit card." />
      <mx:Label text="You selected: {selectedItem.label}"/>
      <mx:Label text="Data: {selectedItem.data}"/>
    </mx:VBox>
  </mx:Panel>
</mx:Application>

Setting the value of the automationName property ensures that the object name will not change at run time. This helps to eliminate unexpected results.

If you set the value of the automationName property, tests use that value rather than the default value. For example, by default, Silk4J uses a Button control's label property as the name of the Button in the script. If the label changes, the script can break. You can prevent this from happening by explicitly setting the value of the automationName property.

Buttons that have no label, but have an icon, are recorded by their index number. In this case, ensure that you set the automationName property to something meaningful so that the tester can recognize the Button in the script. After the value of the automationName property is set, do not change the value during the component's life cycle. For item renderers, use the automationValue property rather than the automationName property. To use the automationValue property, override the createAutomationIDPart() method and return a new value that you assign to the automationName property, as the following example shows:

<mx:List xmlns:mx="http://www.adobe.com/2006/mxml">
  <mx:Script>
    <![CDATA[ 
      import mx.automation.IAutomationObject; 
      override public function 
      createAutomationIDPart(item:IAutomationObject):Object { 
        var id:Object = super.createAutomationIDPart(item);
        id["automationName"] = id["automationIndex"]; 
        return id;
      } 
    ]]>
  </mx:Script>
</mx:List>

Use this technique to add index values to the children of any container or list-like control. There is no method for a child to specify an index for itself.