junit.extensions.abbot
Class ComponentTestFixture

java.lang.Object
  junit.framework.Assert
      junit.framework.TestCase
          junit.extensions.abbot.ComponentTestFixture

All Implemented Interfaces:

Test

Direct Known Subclasses:

ArrowButtonTest, CelsiusConverterTest, LabeledListTest, ResolverFixture

public abstract class ComponentTestFixture
extends TestCase

Fixture for testing AWT and/or JFC/Swing components under JUnit. Ensures proper setup and cleanup for a GUI environment. Provides methods for automatically placing a GUI component within a frame and properly handling Window showing/hiding (including modal dialogs). Catches exceptions thrown on the event dispatch thread and rethrows them as test failures.

Use showFrame(Component) when testing individual components, or showWindow(Window) when testing a Frame, Dialog, or Window.

Any member fields you define which are classes derived from any of the classes in DISPOSE_CLASSES will be automatically set to null after the test is run.

WARNING: Any tests which use significant or scarce resources and reference them in member fields should explicitly null those fields in the tearDown method if those classes are not included or derived from those in DISPOSE_CLASSES. Otherwise the resources will not be subject to GC until the TestCase itself and any containing TestSuite is disposed (which, in the case of the standard JUnit test runners, is never).

Nested Class Summary

protected class	ComponentTestFixture.ComponentMatcher Simple matcher that may be used to verify that a specific component is found by a given ComponentFinder.
class	ComponentTestFixture.EventDispatchException

Field Summary

protected static Class[]	DISPOSE_CLASSES Any member data derived from these classes will be automatically set to null after the test has run.
static int	EVENT_GENERATION_DELAY Typical delay to wait for a robot event to be translated into a Java event.
static int	POPUP_DELAY
static int	WINDOW_DELAY

Constructor Summary

ComponentTestFixture()
Default Constructor.

ComponentTestFixture(String name)
Construct a test case with the given name.

Method Summary

protected Hierarchy	createHierarchy() Provide for derived classes to provide their own Hierarchy.
protected void	disposeAll() Deprecated. This functionality is now deferred to AWTFixtureHelper
protected void	disposeWindow(Window w) Synchronous, safe dispose of a window.
protected void	fixtureSetUp() Ensure proper test harness setup and teardown that won't be inadvertently overridden by a derived class.
protected void	fixtureTearDown() Handles restoration of system state.
protected ComponentFinder	getFinder() Obtain a component finder to look up components.
protected Hierarchy	getHierarchy() Obtain a consistent hierarchy.
protected Robot	getRobot() Return an Abbot Robot for basic event generation.
protected WindowTracker	getWindowTracker() Return a WindowTracker instance.
protected void	hideWindow(Window w) Synchronous, safe hide of a window.
protected void	installPopup(Component invoker, JPopupMenu popup) Install the given popup on the given component.
protected void	invokeAndWait(Runnable runnable) Convenience for getRobot().invokeAndWait(Runnable).
protected void	invokeLater(Runnable runnable) Convenience for getRobot().invokeLater(Runnable).
protected boolean	isShowing(String id) Returns whether a Component is showing.
void	runBare() Override the default junit.framework.TestCase#RunBare() to ensure proper test harness setup and teardown that won't likely be accidentally overridden by a derived class.
protected void	setModifiers(int modifiers, boolean pressed) Convenience method to set key modifiers.
protected Frame	showFrame(Component comp) This method should be invoked to display the component under test.
protected Frame	showFrame(Component comp, Dimension size) This method should be invoked to display the component under test, when a specific size of frame is desired.
protected Dialog	showModalDialog(Runnable showAction) Display a modal dialog and wait for it to show.
protected Dialog	showModalDialog(Runnable showAction, Component contents) Deprecated. Use showModalDialog(Runnable) instead.
protected void	showPopup(JPopupMenu popup, Component invoker) Safely install and display a popup in the center of the given component, returning when it is visible.
protected void	showPopup(JPopupMenu popup, Component invoker, int x, int y) Safely install and display a popup, returning when it is visible.
protected void	showWindow(Window w) Safely display a window with proper EDT synchronization.
protected void	showWindow(Window w, Dimension size) Safely display a window with proper EDT synchronization.
protected void	showWindow(Window w, Dimension size, boolean pack) Safely display a window with proper EDT synchronization.
protected void	sleep() Convenience method to sleep for a UI interval (same as getRobot().sleep()).
protected void	waitForWindow(Window w, boolean visible) Return when the window is ready for input or times out waiting.

Methods inherited from class junit.framework.TestCase

countTestCases, createResult, getName, run, run, runTest, setName, setUp, tearDown, toString

Methods inherited from class junit.framework.Assert

assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, fail, fail

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

EVENT_GENERATION_DELAY

public static final int EVENT_GENERATION_DELAY

Typical delay to wait for a robot event to be translated into a Java event.

See Also:

Constant Field Values

WINDOW_DELAY

public static final int WINDOW_DELAY

See Also:

Constant Field Values

POPUP_DELAY

public static final int POPUP_DELAY

See Also:

Constant Field Values

DISPOSE_CLASSES

protected static final Class[] DISPOSE_CLASSES

Any member data derived from these classes will be automatically set to null after the test has run. This enables GC of said classes without GC of the test itself (the default JUnit runners never release their references to the tests) or requiring explicit null-setting in the TestCase.tearDown() method.

Constructor Detail

ComponentTestFixture

public ComponentTestFixture(String name)

Construct a test case with the given name.

ComponentTestFixture

public ComponentTestFixture()

Default Constructor. The name will be automatically set from the selected test method.

Method Detail

getRobot

protected Robot getRobot()

Return an Abbot Robot for basic event generation.

getWindowTracker

protected WindowTracker getWindowTracker()

Return a WindowTracker instance.

sleep

protected void sleep()

Convenience method to sleep for a UI interval (same as getRobot().sleep()).

showFrame

protected Frame showFrame(Component comp)

This method should be invoked to display the component under test. The frame's size will be its preferred size. This method will return with the enclosing Frame is showing and ready for input.

showFrame

protected Frame showFrame(Component comp,
                          Dimension size)

This method should be invoked to display the component under test, when a specific size of frame is desired. The method will return when the enclosing Frame is showing and ready for input.

Parameters:

comp -

size - Desired size of the enclosing frame, or null to make no explicit adjustments to its size.

showWindow

protected void showWindow(Window w)

Safely display a window with proper EDT synchronization. This method blocks until the Window is showing and ready for input.

showWindow

protected void showWindow(Window w,
                          Dimension size)

Safely display a window with proper EDT synchronization. This method blocks until the Window is showing and ready for input.

showWindow

protected void showWindow(Window w,
                          Dimension size,
                          boolean pack)

Safely display a window with proper EDT synchronization. This method blocks until the window is showing. This method will return even when the window is a modal dialog, since the show method is called on the event dispatch thread. The window will be packed if the pack flag is set, and set to the given size if it is non-null.

Modal dialogs may be shown with this method without blocking.

waitForWindow

protected void waitForWindow(Window w,
                             boolean visible)

Return when the window is ready for input or times out waiting.

Parameters:

w -

hideWindow

protected void hideWindow(Window w)

Synchronous, safe hide of a window. The window is ensured to be hidden (ComponentEvent.COMPONENT_HIDDEN or equivalent has been posted) when this method returns. Note that this will not trigger a WindowEvent.WINDOW_CLOSING event; use WindowTester.actionClose(Component) if a window manager window close operation is required.

disposeWindow

protected void disposeWindow(Window w)

Synchronous, safe dispose of a window. The window is ensured to be disposed (WindowEvent.WINDOW_CLOSED has been posted) when this method returns.

setModifiers

protected void setModifiers(int modifiers,
                            boolean pressed)

Convenience method to set key modifiers. Using this method is preferred to invoking Robot.setModifiers(int,boolean) or Robot.keyPress(int), since this method's effects will be automatically undone at the end of the test. If you use the Robot methods, you must remember to release any keys pressed during the test.

Parameters:

modifiers - mask indicating which modifier keys to use

pressed - whether the modifiers should be in the pressed state.

invokeAndWait

protected void invokeAndWait(Runnable runnable)

Convenience for getRobot().invokeAndWait(Runnable).

invokeLater

protected void invokeLater(Runnable runnable)

Convenience for getRobot().invokeLater(Runnable).

installPopup

protected void installPopup(Component invoker,
                            JPopupMenu popup)

Install the given popup on the given component. Takes care of installing the appropriate mouse handler to activate the popup.

showPopup

protected void showPopup(JPopupMenu popup,
                         Component invoker)

Safely install and display a popup in the center of the given component, returning when it is visible. Does not install any mouse handlers not generate any mouse events.

showPopup

protected void showPopup(JPopupMenu popup,
                         Component invoker,
                         int x,
                         int y)

Safely install and display a popup, returning when it is visible. Does not install any mouse handlers not generate any mouse events.

showModalDialog

protected Dialog showModalDialog(Runnable showAction)
                          throws ComponentSearchException

Display a modal dialog and wait for it to show. Useful for things like JFileChooser.showOpenDialog(Component) or JOptionPane.showInputDialog(Component,Object), or any other instance where the dialog contents are not predefined and displaying the dialog involves anything more than show()/setVisible(true (if show()/setVisible(true) is all that is required, use the showWindow(Window) method instead).

The given Runnable should contain the code which will show the modal Dialog (and thus block); it will be run on the event dispatch thread.

This method will return when a Dialog becomes visible which contains the given component (which may be any component which will appear on the Dialog), or the standard timeout (10s) is reached, at which point a RuntimeException will be thrown.

For example,

     final Frame parent = ...;
     Dialog d = showModalDialog(new Runnable) {
         public void run() {
             JOptionPane.showInputDialog(parent, "Hit me");
         }
     });
     

Throws:

ComponentSearchException

See Also:

showWindow(java.awt.Window), showWindow(java.awt.Window,java.awt.Dimension), showWindow(java.awt.Window,java.awt.Dimension,boolean)

showModalDialog

protected Dialog showModalDialog(Runnable showAction,
                                 Component contents)
                          throws Exception

Deprecated. Use showModalDialog(Runnable) instead.

Similar to showModalDialog(Runnable), but provides for the case where some of the Dialog's contents are known beforehand.

Throws:

Exception

isShowing

protected boolean isShowing(String id)

Returns whether a Component is showing. The ID may be the component name or, in the case of a Frame or Dialog, the title. Regular expressions may be used, but must be delimited by slashes, e.g. /expr/. Returns if one or more matches is found.

fixtureSetUp

protected void fixtureSetUp()
                     throws Throwable

Ensure proper test harness setup and teardown that won't be inadvertently overridden by a derived class.

Throws:

Throwable

fixtureTearDown

protected void fixtureTearDown()
                        throws Throwable

Handles restoration of system state. Automatically disposes of any Components used in the test.

Throws:

Throwable

disposeAll

protected void disposeAll()

Deprecated. This functionality is now deferred to AWTFixtureHelper

Dispose of all extant windows.

runBare

public void runBare()
             throws Throwable

Override the default junit.framework.TestCase#RunBare() to ensure proper test harness setup and teardown that won't likely be accidentally overridden by a derived class.

If any exceptions are thrown on the event dispatch thread, they count as errors. They will not, however supersede any failures/errors thrown by the test itself unless thrown prior to the main test failure.

Overrides:

runBare in class TestCase

Throws:

Throwable

createHierarchy

protected Hierarchy createHierarchy()

Provide for derived classes to provide their own Hierarchy.

getFinder

protected ComponentFinder getFinder()

Obtain a component finder to look up components.

getHierarchy

protected Hierarchy getHierarchy()

Obtain a consistent hierarchy.