JDemo: Interactive Testing Refactored
Pages: 1, 2

Organizing Demos Hierarchically

Just like JUnit test cases, JDemo demo cases can be arranged in suites. Demo suites use the composite pattern in order to create a new demo containing multiple demo classes. A demo suite can then be passed to the DemoRunner in order to have more than one demo class available for execution.

Here is a simple example:

package de.jdemo.examples.dice.demo;

import de.jdemo.framework.DemoSuite;
import de.jdemo.framework.IDemo;

public class AllDemos {

  public static IDemo suite() {
    DemoSuite suite = new DemoSuite(
	  "All Demos for MyDice");
    suite.addDemo(new DemoSuite(MyDiceDemo.class));
    return suite;
  }
}

This example creates a demo suite only containing our MyDiceDemo demo class. Of course, demo suites themselves can then be added to other suites, and so on. A well-maintained set of demos will then form a tree hierarchy. Figure 5 shows a demo tree for a more complex example application.

Figure 5. A well-structured tree of demos for a more realistic software example

Demos as Index to Existing Software Libraries

Let's have another look at the demos in Figure 5. Such a complete set of demos can also be very valuable when you have to work on existing code libraries. You do not need to start the complete application, log in to a database, and load example data, all in order to have a look at the export dialog. Instead you just start the demos and select the relevant component from the DemoRunner.

You also will not have to crawl the source code to find the relevant code; with JDemo, you can link the demo source code to the DemoRunner application. Let's try this for our MyDice example by specifying the path to the source code as sourcepath when starting the DemoRunner application:

java de.jdemo.swingui.DemoRunner -sourcepath . de.jdemo.examples.dice.demo.MyDiceDemo

Similar to the CLASSPATH, the sourcepath is a list of directories or .zip or .jar files. Here we have specified the current directory to contain the source code. Now we have a context menu item, Show source code, at each demo in the DemoRunner (see Figure 6).

Figure 6. A menu item for showing the source code from within the DemoRunner

By default, the JDemo DemoRunner shows the source-code syntax highlighted (using the Java2Html library) in a separate window (see Figure 7). Note that when you are using the JDemo plugin available for the Eclipse IDE, the source code will be shown directly in the development environment.

Figure 7. Syntax highlighted source code as shown by the DemoRunner

Automatically Capturing Demo Output

The JDemo framework provides many options and advanced techniques that cannot all be covered in this article. However I want to give a quick introduction to one of the most interesting techniques: capturing demo output automatically.

As each demo shows its object for demonstration using a show...() method from the framework, it is not very hard to capture this output automatically. For GUI-based demos, the captured output is a screenshot taken by using the java.awt.Robot class.

The following Ant build script shows how we can take a screenshot from our MyDice demo:

<project default="screenshot">
  <taskdef name="demoGuiCapture"
    classname=
      "de.jdemo.capture.anttasks.GuiDemoCaptureTask"
    classpath="jdemo.jar"
  />

  <target name="screenshot">
    <demoGuiCapture
      demoId=
        "de.jdemo.examples.dice.demo.MyDiceDemo:demo6Dice"
      outputFile="dice_screenshot.png"
      includeTitle="false"
    />
  </target>
</project>

First a new Ant task, demoGuiCapture, is defined. Again, we have to make sure that jdemo.jar is on the specified CLASSPATH. The screenshot target uses the demoGuiCapture task for taking a screenshot from the 6Dice demo. Also note that by setting the includeTitle option to false, we only capture the MyDice component, not the complete frame. Figure 8 shows the captured image.

Figure 8. Screenshot automatically taken of the 6Dice demo

As a matter of fact, all of the screenshots in this article were taken automagically by using JDemo (even Figure 6, which actually is a composition of two demos).

Beyond Swing

JDemo is not limited to Swing-based demos. The framework comes with four base classes for different kinds of demos:

JDemo base class	Description
de.jdemo.framework.DemoCase	Demos showing text (java.lang.CharSequence) or File objects.
de.jdemo.extensions.AwtDemoCase	Demos based on components from the Java AWT (Abstract Windowing Toolkit).
de.jdemo.extensions.SwingDemoCase	Swing-based demos--as described in this article. Since Swing is based on AWT, SwingDemoCase subclasses AwtDemoCase.
de.jdemo.extensions.SwtDemoCase	Demos based on the Eclipse SWT (Standard Widget Toolkit).

In practice, when writing demos, you will probably subclass one of the provided classes directly. Usage examples can be found in the examples folder of the JDemo download package. Their API is described in detail in the JavaDoc API documentation and the JDemo online documentation.

Wrap-Up

In this article we have learned how the JDemo framework can be used to organize demonstration and example code by writing demo case classes. Like JUnit test cases, JDemo demo cases can be organized in suites and run from the provided DemoRunner application.

We also have seen that demos are not only useful during the development of a software component, but can also be very valuable later. Demos can be used to directly access all of the software components in a large library. They also provide example code for how to use the API properly. As an additional benefit, GUI demos can be used for automatically taking screenshots; e.g., for documentation purposes.

This article could only show a few aspects of the framework. In order to learn more about it and its capabilities, I recommend reading the detailed online documentation or just checking JDemo out on your next software project.

Resources

• JDemo home page containing the framework and example code for this article in the download package
• Detailed online documentation
• Jonathan Simon's article about simulators

Markus Gebhard works as software engineer at disy Informationssysteme GmbH, in Karlsruhe, Germany.

---

Return to ONJava.com.