Creating a replaying agent

You can create a custom agent that records and replays user interaction with a Flex application. This process is considerably more complex than simply recording user interaction for the purpose of metrics logging.

You cannot use this custom agent with agents that use different environment information, such as the QTP agent that is included with the Flex automation feature. Therefore, if you use this agent, do not use QTP to record and play back scripts.

Using the AutoQuick example

The AutoQuick example is available as a separate download (autoquick_src.zip file) at http://www.adobe.com/go/flex_automation_agent_apps.

Before you write a custom replaying agent, you should try the AutoQuick example, which shows you what type of information an agent must record so that it can play back the user interaction.

The AutoQuick example shows you how to specify codecs in the XML file and create a map of codecs that you can use for value translation.

Download and expand the autoquick_src.zip file: http://www.adobe.com/go/flex_automation_agent_apps.
Build the AutoQuick.swc file by using the instructions in Building the AutoQuick.swc file.
Copy the AutoQuick.swc file to a location that is accessible by your application's compiler.
Include the AutoQuick.swc libraryin your Flex application.
If you are using Flex Builder, add the AutoQuick.swc file by selecting Project > Properties > Flex Build Path > Library Path. Make sure that the Merged Into Code option is enabled.

If you are using the command-line compiler, add an entry in your flex-config.xml file that points to this SWC file; for example:
```
<include-libraries>
    <library>c:/myfiles/flex3/agent/simpler_replay/AutoQuick.swc</library>
</include-libraries>
```
Alternatively, on the command line, you can add the files by using the include-libraries option; for example:
```
mxmlc -C:\home\dev\depot\flex\sdk\bin>mxmlc -include-libraries+=c:/myfiles/flex3/agent/simpler_replay/AutoQuick.swc c:/myfiles/flex3/agent/myreplay/ReplayExample.mxml
```
Be sure to use the += operator to add the SWC file; this ensures that you do not replace other SWC files in your library path, but rather append this SWC file to the path.

Create a sample application that allows some kind of user interaction. For example, you could create a simple application that has just a Button control:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
            private function clickHandler():void {
                b1.label = "clicked";
            }
        ]]>
    </mx:Script>
    <mx:Button id="b1" label="click me" click="clickHandler()"/>
</mx:Application>

Flex Builder creates an HTML wrapper for you. If you use the command-line compiler, you must create one manually. You can use the following sample wrapper:

<html lang="en">
 <head> 
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>ReplayExample</title>
 </head>
 <body>
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
 id="ReplayExample" width="100%" height="100%"
 codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab">
 <param name="movie" value="ReplayExample.swf" />
 <param name="quality" value="high" />
 <param name="allowScriptAccess" value="sameDomain" />
 <embed src="ReplayExample.swf" quality="high" 
width="100%" height="100%" name="applicationReplayExample"
quality="high"
allowScriptAccess="sameDomain"
type="application/x-shockwave-flash"
pluginspage="http://www.macromedia.com/go/getflashplayer">
 </embed>
</object>
 </body>
</html>

Copy the wrapper and the application SWF file to your web server. You must deploy your sample application to a web server.
Copy the AutoQuickEnv.xml file from the autoquick_src.zip file to the same directory on your web server as your sample application SWF and wrapper files.

Now that you have created an application that uses the AutoQuick toolbar, you can record and play back events with it.

Record with the AutoQuick toolbar

Request the application SWF file. For example:
```
http://localhost:8100/replay/default.htm
```
The application opens with a Button control and the Automation pop-up window.
Click the Record button in the Automation pop-up window.
Click the button that you created in your application. The button's label should change from "click me" to "clicked".
Click the Stop button in the Automation pop-up window. The text area of the Automation pop-up window now contains the recorded interaction with the Flex application.

Copy the text from the Automation pop-up window to a text editor. It should look like the following:

<Records>
 <Step 
    id="automationClassName{FlexApplication
        string}automationName{ReplayExample string}label{
        string}automationIndex{index:-1 string}id{ReplayExample string}
        className{ReplayExample string}|automationClassName{FlexButton
        string}automationName{click%20me string}label{click%20me
        string}automationIndex{index:0 string}id{b1 string}className
        {mx.controls.Button string}" 
    method="Click">
<Args value=""/>
 </Step>
</Records>

The <Records> tag wraps the entire script. Each event in the script is represented by a <Step> tag. Within the step tag, <Args> child tags can describe arguments to the event. For example, if the event is a MouseClick event, the <Args> child tags define what keys were pressed at the time of the event.

The id attribute of the <Step> tag contains the entire control hierarchy for each target of an event. Each object in the id attribute is separated by a pipe (|), with the top-most object in the hierarchy occurring first. For example, in an application that has a TextInput control inside an HBox container, you would have an id attribute similar to the following:

Application | HBox | TextInput

Each object in the hierarchy is defined by a set of properties that use the following syntax:

property_name{value type}

The ReplayExample sample shows the following information about the application:

automationClassName{FlexApplication string}
automationName{ReplayExample string}
label{string}
automationIndex{index:-1 string}
id{ReplayExample string}
className{ReplayExample string}

It also shows the following information about the Button control, including the label:

automationClassName{FlexButton string}
automationName{click%20me string}
label{click%20me string}
automationIndex{index:0 string}
id{b1 string}
className{mx.controls.Button string}

The object definitions contain values for all of the attributes that are defined in the AutoQuickEnv.xml file for objects of that type. This ensures that the object can be uniquely identified in the script. This entry in the id attribute identifies the Button control as an object with the automationClassName property set to FlexButton, automationName set to label, label is "click me", automationIndex is 0, id is b1, and the canonical classname is mx.controls.Button.

The method attribute of the <Step> tag defines the event that was recorded.

Play back the recorded session with the AutoQuick toolbar

Restart your Flex application by either refreshing the browser or closing and reopening the browser.
Copy the recorded script from your text editor and paste it into the Automation pop-up window's text area.
Click the Play button. The Button control's label should change from "click me" to "clicked."

About the AutoQuick example

The AutoQuick example uses a variety of assets:

AQToolBar.mxml -- Defines the floating window that provides record, stop, and play functions. This component calls the methods of the helper classes.
AQAdapter.as -- Defines the agent class for the AutoQuick example. This class is a mixin, which triggers a call to its static init() method from the SystemManager class when the application starts up.
AutoQuickEnv.xml -- Defines what components and their methods, properties, and events can be recorded with the automation API. This is similar to the AutomationGenericEnv.xml file that is used by the CustomAgent example.
codec.* class files -- The classes in the codec package are used to convert ActionScript types to agent-specific types; you can think of these classes as providing serialization for the ActionScript types. For example, the AutoQuick example uses the DatePropertyDecode class to convert Date objects to an encoded form. The serialized object can then be loaded by the agent at run time.

Customizing the AutoQuick example

Two classes that you will probably customize are the AQToolBar.mxml file and the AQAdapter.as file.

Adding functionality to the AQToolBar.mxml file is just like editing any other custom Flex component. You can rebrand it, resize it, or change any of its properties to make it work within your application framework. For example, you could add an HTTPService call to a PHP page that logs the results of the recording. This would let you create a web-based, reusable event recording tool, similar to the CustomAgent example.

You can also customize the AQAdapter class; for example, you could add information to what is recorded. The <Step> and <Args> data is defined in the recordHandler() method of this class. You can edit this class to add properties. For example, the <Args> values are currently represented as numeric values. If the user holds the Shift key down while clicking a Button control, the agent records <Args value="2"/>. You could add logic to that class that includes human-readable values, such as <Args value="ShiftKey"/>.

After you have customized the AutoQuick example's source files, you must rebuild the SWC file. For more information, see Building the AutoQuick.swc file.

Building the AutoQuick.swc file

The autoquick_src.zip file contains all of the classes that you need to build the AutoQuick.swc file. When you first unzip the file, or if you make changes to the source files, you will need to build your own SWC file.

To build your own AutoQuick.swc file from the AutoQuick source files, compile the custom SWC file by using the following compc command:

C:\flex\sdk\bin>compc 
    -source-path+=c:/myfiles/flex3/agent/replay/AutoQuick 
    -output c:/myfiles/flex3/agent/replay/AutoQuick.swc 
    -include-classes AQAdapter custom.CustomAutomationClass AQEnvironment 
        custom.CustomAutomationEventDescriptor custom.CustomAutomationMethodDescriptor 
        custom.CustomAutomationPropertyDescriptor custom.utilities.EnvXMLParser 
        IAQCodecHelper IAQMethodDescriptor IAQPropertyDescriptor codec.ArrayPropertyCodec 
        codec.AssetPropertyCodec codec.AutomationObjectPropertyCodec     
        codec.ColorPropertyCodec codec.DatePropertyCodec codec.DateRangePropertyCodec
        codec.DateScrollDetailPropertyCodec codec.DefaultPropertyCodec codec.HitDataCodec
        codec.KeyCodePropertyCodec codec.KeyModifierPropertyCodec codec.ListDataObjectCodec 
        codec.ScrollDetailPropertyCodec codec.ScrollDirectionPropertyCodec
        codec.TabObjectCodec codec.TriggerEventPropertyCodec

The exact file paths may be different on your computer.

Adobe Flex 3 Help

Creating a replaying agent

Using the AutoQuick example

About the AutoQuick example