abbot.tester
Class ComponentTester

java.lang.Object
  |
  +--abbot.tester.Robot
        |
        +--abbot.tester.ComponentTester
Direct Known Subclasses:
ChoiceTester, ContainerTester

public class ComponentTester
extends Robot

Provide basic actions and assertions for anything of class Component. Derive from this class to implement actions and assertions specific to a given component class. Actions are generally user-driven actions such as menu selection, table selection, popup menus, etc. Assertions are either independent of any component (and should be implemented in this class), or take a component as the first argument, and perform some check on that component. Testers for any classes found in the JRE should be in the abbot.tester package. Extensions (testers for any Component subclasses not found in the JRE) must be in the abbot.tester.extensions package and be named the name of the Component subclass followed by "Tester". For example, the javax.swing.JButton tester class is abbot.tester.JButtonTester, and a tester for org.me.MyButton would be abbot.tester.extensions.MyButton.

All actions should have the following signature:
public void actionWhat(Component c, ...);
It is essential that the argument is of type Component; if you use a more derived class then the actual invocation becomes ambiguous since method parsing doesn't attempt to determine which identically-named method is the most-derived. NOTE: All actions should ensure that the actions they trigger are finished or will be finished before subsequent operations before returning. All assertions should have one of the following signatures:
public boolean assertWhat(...); public boolean assertWhat(Component c, ...);


FIXME need an explanation about how this assert (which returns boolean) is different from the Assert, which will throw
Property checks may also be implemented in cases where the component "property" might not be readily available or easily comparable, e.g. see JPopupMenuTester.getMenuLabels().
public Object getProperty(Component c); public boolean isProperty(Component c);

Be careful not to name any support methods with the property signature, since these are scanned dynamically to populate the editor's action menus.

There are two sets of event-generating methods. The internal, protected methods inherited from abbot.tester.Robot are for normal programmatic use within derived Tester classes. No event queue synchronization should be performed except when modifying a component.

The public actionX functions are meant to be invoked from a script or directly from a hand-written test. These actions are distinguished by name and number of arguments, but not by argument type. Therefore you should be very careful when overloading actionX method names. The actionX methods will be synchronized with the event dispatch thread when invoked, so you should only do synchronization with waitForIdle when performing several consecutively dependent steps.

Add-on tester classes should set the following system properties so that the actions provided by their tester can be properly displayed in the script editor. For an action "actionWiggle" provided by class abbot.tester.extensions.ExtendedTester, the following properties should be defined:

The simple class name is required for the args property to avoid collisions with other Testers which may have the same method.


Fields inherited from class abbot.tester.Robot
BUTTON_MASK, componentDelay, defaultDelay, dragMask, EM_AWT, EM_PROG, EM_ROBOT, MENU_SHORTCUT_KEYCODE, MENU_SHORTCUT_MASK, MENU_SHORTCUT_MODIFIER, MULTI_CLICK_INTERVAL, POPUP_MASK, POPUP_MODIFIER, POPUP_ON_PRESS, popupDelay, state, TERTIARY_MASK, TERTIARY_MODIFIER
 
Constructor Summary
ComponentTester()
           
 
Method Summary
 void actionClick(Component comp)
          Click on the center of the component.
 void actionClick(Component comp, int x, int y)
          Click on the component at the given location.
 void actionClick(Component comp, int x, int y, String buttons)
          Click on the component at the given location.
 void actionClick(Component comp, int x, int y, String buttons, int count)
          Click on the component at the given location.
 void actionDelay(int ms)
          Delay the given number of ms.
 void actionDrag(Component dragSource, int sx, int sy)
          Perform a drag action.
 void actionDrag(Component dragSource, int sx, int sy, String modifiers)
          Perform a drag action.
 void actionDrop(Component dropTarget, int x, int y)
          Perform a basic drop action (implicitly causing a preceding mouse drag).
 void actionFocus(Component comp)
          Set the focus on to the given component.
 void actionKeyPress(String kc)
          Used only for modifier keys.
 void actionKeyRelease(String kc)
          Usually used only for modifier keys.
 void actionKeyString(String string)
          Send events required to generate the given string.
 void actionKeyStroke(String kc)
          Send the given keystroke, which must be the KeyEvent field name of a KeyEvent VK_ constant to the program.
 void actionKeyStroke(String kc, String mods)
          Send the given keystroke, which must be the KeyEvent field name of a KeyEvent VK_ constant to the program.
 void actionSelectAWTMenuItemByLabel(Frame frame, String label)
           
 void actionSelectAWTPopupMenuItemByLabel(Component invoker, String label)
           
 void actionSelectMenuItem(Component item)
          Select the given menu item.
 void actionSelectPopupMenuItem(Component invoker, int x, int y, String itemName)
          Pop up a menu at the given location on the given component; Select the given item.
 void actionSelectPopupMenuItem(Component invoker, String itemName)
          Pop up a menu at the given location on the given component; Select the given item.
 void actionShowPopupMenu(Component invoker)
          Pop up a menu in the center of the given component.
 void actionShowPopupMenu(Component invoker, int x, int y)
          Pop up a menu at the given location on the given component.
 void actionWaitForIdle()
          Wait for an idle AWT event queue.
 boolean assertComponentShowing(ComponentReference ref)
          Return whether the Component represented by the given ComponentReference is available.
 boolean assertFrameShowing(String identifier)
          Returns whether a Window corresponding to the given String is showing.
 boolean assertImage(Component comp, File fileImage, boolean ignoreBorder)
          Return whether the component's contents matches the given image.
protected  String deriveAccessibleTag(AccessibleContext context)
          Derive a tag from the given accessible context if possible, or return null.
 String deriveTag(Component comp)
          Provide a String that is fairly distinct for the given component.
 Method[] getActions()
          Return a list of all actions defined by this class that don't depend on a component argument.
 Method[] getAssertMethods()
          Return a list of all assertions defined by this class that don't depend on a component argument.
 Method[] getComponentActions()
          Return a list of all actions defined by this class that require a component argument.
 Method[] getComponentAssertMethods()
          Return a list of all assertions defined by this class that require a component argument.
protected  ComponentFinder getFinder()
           
 Method[] getPropertyMethods()
          Return an array of all property check methods defined by this class.
static String getTag(Component comp)
          Return a reasonable identifier for the given component.
 Class getTestedClass(Class cls)
          Return the Component class that corresponds to this ComponentTester class.
static ComponentTester getTester(Class componentClass)
          Find the corresponding Tester object for the given component class, chaining up the inheritance tree if no specific tester is found for that class.
static ComponentTester getTester(Component comp)
          Return the appropriate Tester for the given object.
 boolean isExtension()
          Return whether this tester is an extension.
static void setTester(Class forClass, ComponentTester tester)
          Establish the given ComponentTester as the one to use for the given class.
static String stripHTML(String str)
          Quick and dirty strip raw text from html, for getting the basic text from html-formatted labels and buttons.
protected  void waitAction(String desc, Condition cond)
          Wait for the given condition, throwing an ActionFailedException if it times out.
 void waitForComponentShowing(ComponentReference ref)
          Wait for the Component represented by the given ComponentReference to become available.
 void waitForFrameShowing(String identifier)
          Convenience wait for a window to be displayed.
 
Methods inherited from class abbot.tester.Robot
, activate, bugCheck, canMoveWindows, canResizeWindows, capture, capture, capture, click, click, click, click, click, close, deiconify, delay, drag, drag, dragOver, drop, findFocusOwner, focus, focus, getAutoDelay, getBorderIntersection, getCanonicalClass, getCloseLocation, getEventID, getEventID, getEventMode, getEventPostDelay, getIconifyLocation, getKeyCode, getKeyCode, getKeyModifiers, getMaximizeLocation, getModifiers, getModifiers, getMouseModifiers, getMoveLocation, getPreferredRobotAutoDelay, getResizeLocation, hasHierarchyEventGenerationBug, hasKeyStrokeGenerationBug, hasMultiClickFrameBug, hasRobotMotionBug, iconify, invokeAction, invokeAndWait, isModifier, isOnPopup, isReadyForInput, isTertiaryButton, jitter, jitter, key, key, keyCodeToMask, keyPress, keyRelease, keyString, keyStroke, maskToKeyCode, maximize, mouseMove, mouseMove, mousePress, mousePress, mousePress, mousePress, mousePress, mouseRelease, mouseRelease, move, moveBy, normalize, postEvent, resetPointer, resize, resizeBy, sample, selectAWTMenuItem, selectAWTMenuItemByLabel, selectAWTPopupMenuItem, selectAWTPopupMenuItemByLabel, selectMenuItem, sendEvent, setAutoDelay, setEventMode, setEventPostDelay, setModifiers, showPopupMenu, showPopupMenu, simpleClassName, sleep, toString, toString, toString, userMovable, userResizable, useScreenMenuBar, wait, wait, wait, waitForIdle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ComponentTester

public ComponentTester()
Method Detail

setTester

public static void setTester(Class forClass,
                             ComponentTester tester)
Establish the given ComponentTester as the one to use for the given class. This may be used to override the default tester for a given core class. Note that this will only work with components loaded by the framework class loader, not those loaded by the class loader for the code under test.

getTester

public static ComponentTester getTester(Component comp)
Return the appropriate Tester for the given object.

getTester

public static ComponentTester getTester(Class componentClass)
Find the corresponding Tester object for the given component class, chaining up the inheritance tree if no specific tester is found for that class.

The abbot tester package is searched first, followed by the tester extensions package.


isExtension

public final boolean isExtension()
Return whether this tester is an extension.

getFinder

protected ComponentFinder getFinder()

deriveAccessibleTag

protected String deriveAccessibleTag(AccessibleContext context)
Derive a tag from the given accessible context if possible, or return null.

getTag

public static String getTag(Component comp)
Return a reasonable identifier for the given component.

deriveTag

public String deriveTag(Component comp)
Provide a String that is fairly distinct for the given component. For a generic component, attempt to look up some common patterns such as a title or label. Derived classes should absolutely override this method if such a String exists.

Don't use component names as tags.


actionWaitForIdle

public void actionWaitForIdle()
Wait for an idle AWT event queue. Will return when there are no more events on the event queue.

actionDelay

public void actionDelay(int ms)
Delay the given number of ms.

actionSelectAWTMenuItemByLabel

public void actionSelectAWTMenuItemByLabel(Frame frame,
                                           String label)

actionSelectAWTPopupMenuItemByLabel

public void actionSelectAWTPopupMenuItemByLabel(Component invoker,
                                                String label)

actionSelectMenuItem

public void actionSelectMenuItem(Component item)
Select the given menu item.

actionSelectPopupMenuItem

public void actionSelectPopupMenuItem(Component invoker,
                                      String itemName)
Pop up a menu at the given location on the given component; Select the given item.

actionSelectPopupMenuItem

public void actionSelectPopupMenuItem(Component invoker,
                                      int x,
                                      int y,
                                      String itemName)
Pop up a menu at the given location on the given component; Select the given item.

actionShowPopupMenu

public void actionShowPopupMenu(Component invoker)
Pop up a menu in the center of the given component.

actionShowPopupMenu

public void actionShowPopupMenu(Component invoker,
                                int x,
                                int y)
Pop up a menu at the given location on the given component.

actionClick

public void actionClick(Component comp)
Click on the center of the component.

actionClick

public void actionClick(Component comp,
                        int x,
                        int y)
Click on the component at the given location.

actionClick

public void actionClick(Component comp,
                        int x,
                        int y,
                        String buttons)
Click on the component at the given location. The buttons string should be the InputEvent field name for the desired masks, e.g. "BUTTON1_MASK|CTRL_MASK".

actionClick

public void actionClick(Component comp,
                        int x,
                        int y,
                        String buttons,
                        int count)
Click on the component at the given location. The buttons string should be the InputEvent field name for the desired masks, e.g. "BUTTON1_MASK|CTRL_MASK". This variation provides for multiple clicks.

actionKeyPress

public void actionKeyPress(String kc)
Used only for modifier keys. Otherwise, use actionKeyStroke instead.

actionKeyRelease

public void actionKeyRelease(String kc)
Usually used only for modifier keys. Otherwise, use actionKeyStroke instead.

actionKeyStroke

public void actionKeyStroke(String kc)
Send the given keystroke, which must be the KeyEvent field name of a KeyEvent VK_ constant to the program. Sends a key down/up, with no modifiers. Note that this does not affect the current focus.

actionKeyStroke

public void actionKeyStroke(String kc,
                            String mods)
Send the given keystroke, which must be the KeyEvent field name of a KeyEvent VK_ constant to the program. Sends a key down/up, with the given modifiers, which should be the InputEvent field name modifier masks optionally ORed together with "|". Note that this does not affect the current focus.

NOTE: on OSX, the wait for idle is not sufficient to process the entire keystroke.


actionKeyString

public void actionKeyString(String string)
Send events required to generate the given string.

actionFocus

public void actionFocus(Component comp)
Set the focus on to the given component.

actionDrag

public void actionDrag(Component dragSource,
                       int sx,
                       int sy)
Perform a drag action. Derived classes should provide more specific identifiers for what is being dragged, e.g. actionDragTableCell or actionDragListElement.

actionDrag

public void actionDrag(Component dragSource,
                       int sx,
                       int sy,
                       String modifiers)
Perform a drag action. Derived classes should provide more specific identifiers for what is being dragged, e.g. actionDragTableCell or actionDragListElement. The modifiers represents the set of active button modifiers when the drop is made.

actionDrop

public void actionDrop(Component dropTarget,
                       int x,
                       int y)
Perform a basic drop action (implicitly causing a preceding mouse drag). The modifiers represents the set of active modifiers when the drop is made.

assertImage

public boolean assertImage(Component comp,
                           File fileImage,
                           boolean ignoreBorder)
Return whether the component's contents matches the given image.

assertFrameShowing

public boolean assertFrameShowing(String identifier)
Returns whether a Window corresponding to the given String is showing. The string may be a plain String or regular expression and may match either the window title (for Frames or Dialogs) or its Component name.

waitForFrameShowing

public void waitForFrameShowing(String identifier)
Convenience wait for a window to be displayed. The given string may be a plain String or regular expression and may match either the window title (for Frames and Dialogs) or its Component name. This method is provided as a convenience for hand-coded tests, since scripts will use a wait step instead.

The property abbot.robot.component_delay affects the default timeout.


assertComponentShowing

public boolean assertComponentShowing(ComponentReference ref)
Return whether the Component represented by the given ComponentReference is available.

waitForComponentShowing

public void waitForComponentShowing(ComponentReference ref)
Wait for the Component represented by the given ComponentReference to become available. The timeout is affected by abbot.robot.component_delay, which defaults to 30s.

getActions

public Method[] getActions()
Return a list of all actions defined by this class that don't depend on a component argument.

getComponentActions

public Method[] getComponentActions()
Return a list of all actions defined by this class that require a component argument.

getPropertyMethods

public Method[] getPropertyMethods()
Return an array of all property check methods defined by this class. The first argument must be a Component.

getAssertMethods

public Method[] getAssertMethods()
Return a list of all assertions defined by this class that don't depend on a component argument.

getComponentAssertMethods

public Method[] getComponentAssertMethods()
Return a list of all assertions defined by this class that require a component argument.

stripHTML

public static String stripHTML(String str)
Quick and dirty strip raw text from html, for getting the basic text from html-formatted labels and buttons. Behavior is undefined for badly formatted html.

waitAction

protected void waitAction(String desc,
                          Condition cond)
                   throws ActionFailedException
Wait for the given condition, throwing an ActionFailedException if it times out.

getTestedClass

public Class getTestedClass(Class cls)
Return the Component class that corresponds to this ComponentTester class. For example, JComponentTester.getTestedClass(JLabel.class) would return JComponent.class.


Copyright © 2002-2003 Timothy Wall. All Rights Reserved.
Abbot is hosted on

SourceForge