This document is the API specification for the Abbot automated GUI testing framework and associated support packages.

See:
Description

Abbot GUI Automation

abbot	Provides testing support for Java GUIs.
abbot.finder	Provides component search and lookup facilities.
abbot.finder.matchers	Provides various types of Matcher implementations for use in component searches.
abbot.i18n	Provides internationalization support for Abbot and Costello.
abbot.tester	Provide component-specific actions and tests.
abbot.util

Abbot JUnit Extension

junit.extensions.abbot

Provide support for running scripts and UI-oriented unit tests as test cases under JUnit.

Scripting Support

abbot.script	Provides basic elements for constructing a test script.
abbot.script.parsers	Provide explicit conversions from String to another class, for use by the interpreter when evaluating stringified values in scripts.

Costello Script Editor

abbot.editor	Provides support for editing Abbot test scripts.
abbot.editor.actions
abbot.editor.editors
abbot.editor.recorder	Provide recording support for component-specific user actions.
abbot.editor.widgets

Example Code

abbot.tester.extensions	Extensions to ComponentTester to provide support for custom components.
example	Miscellaneous examples demonstrating Abbot usage.

This document is the API specification for the Abbot automated GUI testing framework and associated support packages.

Abbot is a Java GUI testing framework and JUnit extension. The framework may be invoked directly from Java code (unit tests), or in a more simple, structured way using XML-based scripts. Both methods are designed to be used with the JUnit testing framework. You can launch a GUI, invoke arbitrary user actions on it, and examine its state.

The Abbot framework also includes the Costello editor, which facilitates editing scripts. The editor supports recording arbitrary user actions into a script.

Top Abbot Home API w/FRAMES

The Abbot Framework

Abbot provides a framework for testing your GUI regardless of the current state of your code. If you are doing test-first development with lots of unit testing, then Abbot can provide the developer the tools needed to write individual unit tests. If you have an existing code base without existing unit tests, you can use the scripting level of Abbot to start building functional test scaffolding around your application until it is sufficiently stable to support refactoring and addition of unit tests.

In general, testing with Abbot consists of getting references to GUI components and either performing user actions on those components or making some assertions about their state. To facilitate this process, the framework provides ComponentReferences to get a handle on a GUI component (even when it may not yet exist), and extended Robot-like objects, which know how to perform user-level actions on various GUI components. These operations may be done from either a high-level script (useful for functional/acceptance testing) or directly from Java code (for example in a JUnit TestCase method).

• Robot (the user event generator, and the root of all Testers)

  This is the fundamental component of Abbot, "A Better 'Bot". It provides basic component-level events upon which more complex tester objects can be built. In the absence of a specific tester object for a given component, the events provided by the Robot class are sufficient to reconstruct any user actions.

  For each Component to be tested, there is a Tester class which provides user actions and tests (assertions) specific to that component. This is the class to extend when you need to provide access to a custom GUI component. The base class, abbot.tester.ComponentTester, provides default actions for most common user actions, including clicking a mouse button, selecting from a menu, and typing text. The tester system is easily extensible to provide more specific actions or property lookup for custom components; for example, JTableTester provides an action which selects the cell at a given row, column location. JPopupMenuTester provides a method which returns a list of all the menu items currently on a popup menu.

• ComponentLocation

  Abbot represents locations within a given component with a dedicated data type, the ComponentLocation. This means that any component with internal substructure (cells in a table, rows in a tree, items in a list, etc) may identify a substructure location with a class derived from ComponentLocation. For example, a JTableLocation may be constructed with a Point (raw coordinates), a [row, col] pair, or a String representation of the value in the desired cell. Using these location types avoids a proliferation of API methods, so you can simply have one method per type of user action, like this:
  

      public void actionClick(Component, ComponentLocation);
      public void actionDrag(Component, ComponentLocation);
      public void actionShowPopupMenu(Component, ComponentLocation);
  

  instead of many like this:
  

      public void actionClick(Component c, Point where);
      public void actionClick[Cell](JTable c, int row, int col);
      public void actionClick[Row](JTree c, int row);
      public void actionClick[Value](JTable c, String value);
      // Repeat for actionDrag, actionDrop, actionShowPopupMenuAt, etc
  

  From a script, these are automatically generated as needed; in general you can use (x,y), [index], [row,col], or "value" notations depending on how you want to refer to a particular substructure element. When recording, the String value of a location will be used by default.

• ComponentReferences

  ComponentReferences allow you to use a few known attributes of a component to refer to that component, whether or not the component currently exists or is visible. The framework provides automatic lookup, so that you don't have to clutter your object API with accessors like getOKButton and getCancelButton. When tests are run, component references may be converted to the actual Component they represent just in time, at the point where the component itself is actually needed. Component lookup is fuzzy, such that minor changes in attributes (such as position, parent or size of a component) generally won't break the script.

• Scripts

  Scripts are the basic units of test execution in the Abbot framework. In general these consist of component lookup information, component actions (such as menu selections, typed text, etc.), and assertions regarding the GUI's state. Scripts for unit tests may be very simple, while scripts for functional testing may be far more lengthy and complex. See the abbot.script package for more details.

  When using a script, all information required to run the test is encapsulated within the script itself, to provide independence from any particular testing environment. This facilitates running the scripts under either the script editor, JUnit, or some other harness.

  The ScriptFixture provided for use with JUnit derives from TestCase and is a very simple wrapper to adapt the script to the JUnit testing framework. Scripts may be grouped into a test suite by using the ScriptTestSuite class, which can automatically collect a group of tests into a suite based on file hierarchy, filenames, or other criteria. The preferred method of creating a suite is to derive your test class from ScriptFixture, then have the static "suite" method for that derived class create an instance of ScriptTestSuite which selects for the scripts you wish to group. See the ScriptTestSuite API documentation for details.

• Other Features

  • GUI Test Fixture

    A ComponentTestFixture is provided for testing GUI components and groups of components directly from Java code. This fixture extends TestCase, so you can manually write unit tests using any of the facilities of the framework.

    This fixture takes care of providing a clean environment for instantiating, operating on, and examining GUI components, which includes properly disposing of all instantiated components at the end of each test. This avoids the tediousness of having to keep track of everything you displayed and tracking down anything that might have been displayed that you didn't know about (common when testing already-developed code). It also provides methods for looking up desired components in the hierarchy.

  • Editor (Costello)

    A script editor is provided to facilitate creation and maintenance of Abbot scripts. The editor supports live recording of user events to facilitate writing scripts, and can also play them back for debugging.

  • Recorders

    Recorders provide a means for the script editor to capture high-level semantic information instead of basic mouse and key events. Recorders are provided for most standard Swing components, but events will be captured properly even in the absence of a customized Recorder for a given component. The editor supports plug-in recorders to support additional custom components.

    The primary Recorder class is the EventRecorder, which calls out to specific instances of SemanticRecorder to record component-specific actions.

Goals of the Abbot Framework

Aside from the primary goal of reliably automating tests of GUIs and GUI components, the Abbot framework has the following goals:

• Reliable reproduction of user input for tests
  One reason GUIs don't get tested is because it's usually not easy for a developer to simulate user input. Problem solved, no more excuses for not unit testing your GUI components.

• Scripted control of actions and inspection
  Rather than writing new code which requires compilation, the test scripts are dynamically interpreted, which is more appropriate for this level of tests. All functionality, of course, is available for direct invocation in Java unit test code.

• Loose component bindings
  GUI layouts tend to change over time. A raw event recorder/playback mechanism will likely break if you're operating in absolute coordinates; different platforms generally size their components differently, so tests may not work cross-platform. Abbot for the most part doesn't care where components are positioned, as long as it can look them up dynamically with a few tagging identifiers.

• Specify high-level semantic actions, but use low-level OS events to implement them.
  The java.awt.Robot class is capable of directly reproducing user events. Unfortunately, it is far too basic to be easy to use for unit tests. Abbot builds a level of abstraction on top of java.awt.Robot, mirroring the way Swing Components are a level of abstraction above basic windows. At this level, tests are much easier to maintain since you can deduce from a glance what a set of instructions will do. It should be plain which of the following groups of instructions it is easier for a human to parse:

  Click on 100, 100
  Move to 110, 110
  Press down key
  Press down key
  Click on 110, 110
  
  Select "blue" from the color list
  

• Support live recording of high-level semantic events.
  While you can always write XML by hand, or edit each script step individually, it makes more sense to leave it to the computer to do the grunt work. The Costello editor can automatically record a sequence of user actions and save them to a script.

• Extensible user action recording and generation
  Tester and Recorder objects (as well as several other framework components) are extensible to support any additional components you'd like to test, although the basic Robot support can be used to test just about anything without further modification. What you gain by adding extensions is a layer of abstraction similar to calling ClickRow(10) instead of Click(x, y), where (x,y) is the center of row 10.