Getting Started

Swingcorder setup is simple, requiring only minor changes to your Swing application to enable playback and recording. Specifically, the steps you need to take are:

  1. Download the Swingcorder JAR and add it to the class path of your Swing application.
  2. Activate the Swingcorder functionality for your application by having it invoke the static SwingcorderMain.activate() method.
  3. Install the plugin for Eclipse using the installation site.
  4. Display the Swing > Swingcorder plugin view.
These steps are described in more detail below, and once they're completed you're ready to begin using Swingcorder to record and play back scripts. Steps 2-4 may be omitted if you do not intend to control script recording and playback through an Integrated Development Environment (IDE). For example, if you only plan to replay scripts in a continuous integration (CI) environment such as Jenkins, then only the first step is required. For users planning to create and run new scripts locally, however, all four steps must be completed.

Playback-Only Activation For Automated Environments

If you don't need to control script activities from an IDE, the only required step is to add the Swingcorder library to your Swing application's class path, and with that JAR file included on the class path you can use an instance of UserSimulation to simulate user input. That class is extended by scripts created by Swingcorder, but a class need not extend UserSimulation in order to be used for playback: you can instead simply create an instance of UserSimulation and invoke the methods it provides for simulating user input. Additional information on how to use UserSimulation is provided later.

Recording and Playback Through A Plugin

Enabling full Swingcorder script functionality for a Java application -- including plugin-based control of script recording and playback -- requires the completion of an additional step related to your Swing application. Specifically, besides adding the Swingcorder library to your application's classpath you must also call the static SwingcorderMain.activate() method from within the Java virtual machine (JVM) in which your Swing application is executing. Invoking that method makes your application visible to a Swingcorder IDE plugin running on the same host, allowing you to use the plugin to initiate script recording and playback for that application. For example, you can enable communication with the IDE by including a statement like the one shown below in your Swing application's initialization code:
If you do not have access to your Swing application's source code or do not wish to modify it, an alternative approach to activating Swingcorder's functionality is also supported that is transparent to the application code, and that approach is described below.

Installing the Swingcorder Plugin

To control Swingcorder script recording and playback from an IDE, you must install the appropriate Swingcorder plugin. Currently the only Swingcorder plugin available is for the Eclipse IDE. It supports Eclipse 3.5 (Galileo) and later releases, and can be installed in either of two ways:

The plugin includes a Swingcorder view that can be displayed by opening the Show View dialog (accessed through the Window / Show View / Other menu path) and selecting the Swingcorder item under the Swing node as shown below:

With the Swingcorder plugin displayed, you're ready to start using Swingcorder to record and play back scripts. The plugin will automatically detect any running Java applications for which the Swingcorder functionality has been activated, and you can use the plugin view to control the creation and playback of scripts in those applications. For more information on using the plugin, see the information here.

Activating Swingcorder Transparently

If you don't have access to your application's source code or if you prefer not to modify it, an alternative approach can be used to activate Swingcorder when your application is started. Specifically, you can simply call the SwingcorderMain.main() method instead of your application's static main() method, passing as the first argument the name of your application's entry point class. For example, suppose that you have a Swing application with the following characteristics:

Given these parameters, you would normally start your Swing application with a command like the one shown below:
> java -cp ./lib/acct-1.2.3.jar com.acme.MySwingApp ../appdata
To enable Swingcorder for your application without modifying your application code, you simply add the Swingcorder library to your class path and insert the name of the SwingcorderMain class as the first parameter passed to the Java virtual machine as shown below:
> java -cp ./lib/acct-1.2.3.jar;./lib/swingcorder.jar com.kandor.swingcorder.SwingcorderMain com.acme.MySwingApp ../appdata
The static SwingcorderMain.main() method activates the Swingcorder functionality and then calls the static main() method of the application class you specified (com.acme.MySwingApp in this case), passing it the original command line arguments but excluding the user class name. In other words, in this example the static MySwingApp.main() method will be called and passed the single "../appdata" parameter that was originally specified on the command line.

UserSimulation Class

Script playback within Swincorder is facilitated by UserSimulation, and most of the methods defined in that class fall into one the following categories:

Note that the property accessor methods are important because Swing is not thread-safe, and Swingcorder scripts are expected to be executed using a thread other than Swing's Event Dispatch Thread (EDT). In fact, Swingcorder scripts must not be run using the EDT and playback methods will throw an exception if called by the EDT.

Scripts generated by Swingcorder are always thread-safe, but if you modify a generated script or you create one manually, you must ensure that the script is thread-safe by using the methods provided in UserSimulation or through some other appropriate mechanism. What this means in practice is that you should not modify or access component properties directly from within a script. For example, the following code is thread-safe:
UserSimulation simulation = new UserSimulation(); JFileChooser chooser = simulation.findFileChooserInModalDialog(); File file = simulation.getFileChooserCurrentDirectory(chooser);
In contrast, the following code is not thread-safe, because it accesses a file chooser property (the current directory) directly from a thread other than the EDT and does so without using the thread-safe accessor method defined in UserSimulation:
UserSimulation simulation = new UserSimulation(); JFileChooser chooser = simulation.findFileChooserInModalDialog(); File file = chooser.getCurrentDirectory();

Related Resources