TPTP Automated GUI Recorder Architecture Document
TPTP Automated GUI Recorder Architecture Document

The following document provides an overview of the Architecture of TPTP's Automated GUI Recorder.

Table of Contents:
0.1 Introduction - Description and Purpose
0.2 Overview of the TPTP's Test Project
0.3 Obtaining Source Code
1.0 Plug-in Architecture
1.1 Recording Execution Flow
1.2 Playback Execution Flow
1.3 Macro Semantics
1.4 Class Diagrams

0.1 Introduction - Description and Purpose

This document is intended for developers wishing to modify or extend the Automated GUI Recorder (AGR) feature in TPTP. The following sections will explain the steps necessary to obtain and modify the source code for the AGR. In addition, this document will provide detailed information about the program flow during execution. For a higher-level summary on how to use the AGR, including examples, please see "An Introduction To Using TPTP's Automated GUI Recorder".


0.2 Overview of the TPTP's Test Project

The AGR is part of a larger project within TPTP called the Test Project. The Test Project is built on top of TPTP's Platform project and provides a Test framework which is extensible and can be used to create new testing tools. The Test framework includes common elements which extend across the different test types. These common elements are composed of the Eclipse UI (perspective, views, navigators, editors and wizards), distributed execution framework, distributed data collection, automated services framework and EMF models. The Test framework also provides extension points, enabling custom extensions to be built on top of it.

There are four test types included in the TPTP Testing tools: JUnit, plug-in, manual, and URL. The AGR test type is a fifth test type available as a Technology Preview. Technology Preview items are not included in the standard TPTP package and must be downloaded and installed separately. The purpose of Technology Previews is to showcase new components which are still being developed in order to gain valuable user feedback while the development process is underway.

Although some components are unique to a particular test type, there are also some which are shared across the Test Project. These include:

  1. Common perspectives and views for interacting with target systems and resources.
  2. Reference navigators, viewers, editors and wizards through extension points.
  3. Standard EMF data model, query framework and assets repository.
  4. Common data collection and execution framework on local and remote targets.
0.3 Obtaining Source Code

For contributors who wish to modify the source code, the following sequence of steps describes how to check out the AGR Plug-in from TPTP's CVS repository.

  1. Add a new repository location in CVS: Switch to the CVS repository > Right click the CVS repositories view and select New > Repositories Location
  2. Enter TPTP's CVS repository location: Enter Host: dev.eclipse.org Repository Path: /cvsroot/tptp User: anonymous > Finish
  3. The HEAD stream is used for development builds. This branch is recommended to be used if developing new features or implementing fixes for a development build. Make sure that the Eclipse workbench used contains the latest copy of TPTP's development plug-ins.
    Check out the Automated GUI Recorder Plug-in: Expand the location > Expand 'HEAD' > Expand 'test' > Check-out org.eclipse.tptp.test.auto.gui
This will give you access to the source code and allow you to make modifications and create patches in your workspace. For more detailed instructions on accessing the source code, please see: http://www.eclipse.org/tptp/home/documents/process/development/code_CVS.html.

1.0 Introduction To AGR Architecture

Now that you have access to the source code, the following sections will review the architecture of the AGR plug-in by detailing the execution flow for both event recording and playback. Furthermore, a discussion of the semantics of the Macros will be given, followed by Class Diagrams.


1.1 Recording Execution Flow

From a userís perspective, the creation and playback of an AGR test are the two most important use cases for the component . Creating a fully functional test involves first creating a test suite, adding test cases and then recording a series of UI actions which will serve as the test itself, to be played back later to test that the UI still conforms to the original recording. A Macro script in XML format is also generated during recording, creating a textual representation of the UI actions recorded. The source code must therefore contain classes capable of capturing all events which take place during recording. Figure 1.0 shows the structure of the source code responsible for carrying out a recording as well as creating the Macro for a test case.

  1. Case A - Registering Listeners: The MacroManager must register the event listeners for each event type. When recording begins, the MacroManager class calls the method startRecording() which initializes the display Object by calling the method hookListeners() and passing in the current display. The display Object then calls addFilter() for each SWT event type, passing in a listener of type DisplayListener. The addFilter() method ensures that the given listener will receive events from all widgets of the type of event passed in. If position-based recording is turned on, it will register the events by calling hookPositionBasedListener().
  2. Case B- Capturing Events When an Event e is fired from a widget, the DisplayListener Object handles the Event e by calling the MacroManager class. The MacroManager then adds this event to the current Macro for this recording by calling addEvent().
  3. Case C- Macro Creation When the Macro receives an Event to add, it calls addEvent() and then calls the MacroCommandShell method createCommand() which deciphers which type of event was called and then creates a new command based on the type. The type will always be an instance of AbstractMacroCommand. Once the new command has been created and added, it is written out to the Marco Command Shell and saved there. Each event that is fired continues on this way, with a command being generated and added to the Macro.


Figure 1.0 - Key Recording Steps

After the test case is created and saved, execution of a test case is carried out by playing it back in a given context. The Macro created during recording determines which commands are executed and in what order. The playback generates a test execution similar to those of the other test types. Figure 1.1 shows the two main steps in playback.

  1. Case A - Finding Targets: Once a playback command has been initiated, the MacroCommandShell must use the recorded Macro to find the targets in the display for executing each command. It does this by calling the MacroObjectLocator to locate the targets. The MacroObjectLocator deciphers the contextId of the part we are looking for and uses that to locate that part within the display.
  2. Case B- Playing Commands on Targets Once the targets have been found the next step is to carry out the actions on the widgets associated with these targets. As an example, the BooleanSelectionCommand class must get each target's widgetId from the CommandTarget class in order to identify the correct widget and perform the actions stored in the Macro on that widget.

Figure 1.1 - Key Playback Steps

1.3 Macro Semantics
The test Macro is saved as a script in XML format. The table below shows the semantics of the generated script. It only covers elements corresponding to 'commands':

Command Type Purpose Child Elements and Their Attributes Root Attributes
select Indicates a selection Element: selected-item (item selected)
Attribute: path (the path of the item selected)

Element: parent (the parent element leading to the selection)
Attribute: widgetId (the id of the parent)
contextId (the id of the context)
widgetId (the id of the widget)
x-coord (used for drop down toolbar buttons only)
y-coord (used for drop down toolbar buttons only)
detail (the detail of the event)
selection (indicates whether item is enabled or disabled)
item-check Indicates a check box item Element: item (the item checked)
Attribute: path (the path of the item selected)
contextId (the id of the context)
widgetId (the id of the widget)
value (indicates whether the check box was checked or unchecked)
choice-select A choice selection such as choosing a specific tab or a combo box item None contextId (the id of the context)
widgetId (the id of the widget)
choiceId (the id of the selection)
item-expand Indicates that an item is expanded (such as a tree item) Element: item (the item checked)
Attribute: path (the path of the item selected)
contextId (the id of the context)
widgetId (the id of the widget)
value (indicates whether item is expanded or collapsed)
focus An item gains focus None contextId (the id of the context)
widgetId (the id of the widget)
modify A modification by the user None contextId (the id of the context)
widgetId (the id of the widget)
default-select A default selection Element: item (the item selected)
Attribute: path (the path of the item selected)
contextId (the id of the context)
widgetId (the id of the widget)
item-select Custom selection by user Element: item (the item selected)
Attribute: path (the path of the item selected)
contextId (the id of the context)
widgetId (the id of the widget)
verification A verification point None contextId (the id of the editor, view, etc...)
location (the location containing the verification class)
resource (verification class name)
hook (the method signature corresponding to the verification hook)
wait If the time-to-wait attribute appears, then the runner waits x number of milliseconds before proceeding to the next command (x is the value of the attribute). If the attribute is not present, then the runner waits until all user Eclipse jobs are completed before proceeding to the next command None time-to-wait (This optional attribute indicates a time in milli-seconds that the runner should sleep until it proceeds to the next command)
close-workbenchpart Close workbench parts (e.g. editors, views) None contextId (indicates whether the context is an editor or a view)
widgetId (the identifier for the workbench part)
key-up A position-based command used to indicate keyword up events None detail (indicates the key that corresponds to the key up event)
ischarset (takes the string literal 'true' or 'false' as value to indicate whether Event.character (if true) or Event.keyCode (if false) should be used)
key-down A position-based command used to indicate keyword down events None detail (indicates the key that corresponds to the key down event)
ischarset (takes the string literal 'true' or 'false' as value to indicate whether Event.character (if true) or Event.keyCode (if false) should be used)
key-press A position-based command used to have the same effect as a key-down followed by a key-up command None detail (indicates the key that corresponds to the key down event)
ischarset (takes the string literal 'true' or 'false' as value to indicate whether Event.character (if true) or Event.keyCode (if false) should be used)
mouse-up A position-based command used to indicate mouse up events None detail (indicates the mouse button that send the mouse up event)
x-coord (x-coordinate for the cursor location)
y-coord (y-coordinate for the cursor location)
mouse-down A position-based command used to indicate mouse down events None detail (indicates the mouse button that send the mouse down event)
x-coord (x-coordinate for the cursor location)
y-coord (y-coordinate for the cursor location)
mouse-click A position-based command used to have the same effect as a mouse-down followed by a mouse-up command None detail (indicates the mouse button that send the mouse down event)
x-coord (x-coordinate for the cursor location)
y-coord (y-coordinate for the cursor location)
1.4 Class Diagrams and Plug-in Structure

The class diagram below illustrates the class structure of the classes responsible for locating Objects and creating the Macro. It is notable that the MacroManager class plays a central role in communicating with the various listeners waiting for events to be fired.


Figure 1.2 - Class Diagram Showing Macro Class Relationships

The class diagram below shows the relationship between the Macro class, the MacroCommandShell class and several specific command types such as FocusCommand, ChoiceSelectionCommand and ExpansionCommand. As can be seen, the Macro class uses the MacroCommandShell class which communicates with each specific command type. During playback, the MacroCommandShell class calls the specific playback method in each command type class so that the current command is executed according to the command type.

/
Figure 1.3 - Class Diagram Showing MacroCommandShell Relationship with Command Classes

The JavaDoc for this component can be found at: http://www.eclipse.org/tptp/home/documents/resources/javadoc.html#v430 under Testing Tools> Internal Code.