Dimitri Missoh
enthusiastic technologist and problem solver

February 15th, 2009

Nuts and bolts of the UI development: GUI Test of SWT and Eclipse Applications

To be honest, I’m not the programmer I’ve dreamed to be, the one that has 100% of his code test covered. As a GUI developer I had an excuse in the past, namely that there are no acceptable GUI testing frameworks one can rely on (open source and suitable for eclipse RCP Application). I tried some of them but wasn’t very happy:

Until the day I’ve found the SWTBot library developed by Ketan Padegaonkar. This library still under development but can already be used to write professional functional test for SWT and eclipse based applications. The API is simple, intuitive but powerfull. This framework has such a success, that in the meantime there is a proposal to move it to the eclipse.org foundation.

This tutorial describes step by step how to configure your IDE to be able to test your first RCP application. I hope that this warm-up will encourage beginners to adopt, put into practice and understand the importance of GUI testing in their daily work.

So let’s start:

System requirement:

  • The Java JRE 5.0 is installed on my PC
  • and I’am using the Eclipse IDE for Plug-in developer (Ganymed - version 3.4 SR1)

Step 1 - Installing SWTBot

  • Start your eclipse IDE and choose [Help/Install New Software...]
  • Than click Add Site and enter the following URl for the updatesite: http://swtbot.sourceforge.net/download.html. Than [OK]. You can also download the plug-ins directly if you prefere. See the SWTBot webpage for more details.
  • Select “SWTBot Eclipse Feature” and “SWTBot SWT Feature” and install them (your probably need to restart the workbench).

Step 2 - Download the Apache commons collection library

Since SWTBot depends on this library, it should be dowloaded and added in the next steps to the classpath.

Step 3 - Create the RCP application under test

  • We use the Mail Sample delivered with the IDE as the project under test. To create this project simple choose [File/New/Project/Plug-in Project] and enter the name “com.dmissoh.rcp.mail” or any name of your choice.
  • Access the next wizard page by clicking on next. In the “Plug-in options” group check the options “Generate an activator….” and “This plug-in will make contribution to the UI“.  Then check the option yes that corresponds to the question “Would you like to create a rich client application?
  • Choose “RCP Mail Template” on the next wizard page, and terminate with [Finish].

Step 4 - Create the test plug-in

  • As described in step 3 create a new plug-in project using [File/New/Project/Plug-in Project]
  • Do not use any template for this project
  • Name it “com.dmissoh.rcp.mail.test
  • Use the context menu on this project and add a the new folder “lib” as shown in fig. 1
  • Use the context menu on this project and add a the new folder “config
  • In the ‘config’ folder create a new file named log4j.properties and fill it with the content of the snippet below:
    log4j.rootCategory=DEBUG, R, O
     
    # Stdout
    log4j.appender.O=org.apache.log4j.ConsoleAppender
     
    # File
    log4j.appender.R=org.apache.log4j.RollingFileAppender
    log4j.appender.R.File=log4j.log
     
    # Control the maximum log file size
    log4j.appender.R.MaxFileSize=100KB
     
    # Archive log files (one backup file here)
    log4j.appender.R.MaxBackupIndex=1
     
    log4j.appender.R.layout=org.apache.log4j.PatternLayout
    log4j.appender.O.layout=org.apache.log4j.PatternLayout
     
    log4j.appender.R.layout.ConversionPattern=[%d{ISO8601}]%5p%6.6r[%t]%x - %C.%M(%F:%L) - %m%n
    log4j.appender.O.layout.ConversionPattern=[%d{ISO8601}]%5p%6.6r[%t]%x - %C.%M(%F:%L) - %m%n
  • Copy the jar file “commons-collections-3.2.1.jar” you previously unzip in step 2 into this “lib” folder.
  • Go the the plugins folder of your eclipse IDE (e.g. under “C:\Programme\eclipse3.5\eclipse\plugins”), and copy the following jars into the “lib” folder: net.sf.swtbot.eclipse.finder_1.2.0.921.jar, net.sf.swtbot.eclipse.spy_1.2.0.921.jar, net.sf.swtbot.eclipse.ui_1.2.0.921.jar, net.sf.swtbot.finder_1.2.0.921.jar as shown in fig.1.
  • Double click on the file “META-INF/MANIFEST.MF” of the project “com.dmissoh.rcp.mail.test”, select the tab “runtime” and use the “Add…” button to add the five jar that we’ve copied into the lib folder of this project. At the end, it should look like on fig. 2.
  • We now need to add some dependencies to our test plug-in. Click on the MANIFEST.MF file located in the META-INF folder of the test plug-in org.dmissoh.rcp.mail.test and open the tab Dependencies. Use the Add button to add both org.apache.log4j (bundle-version=”1.2.13″) and org.junit (bundle-version=”3.8.2″) to the dependencies. Fig. 3 show how it should looks like.

P.S.: This is the quick and dirty way to add third party jars into your project. It is always better to add all the jar file your project depends on in a another plug-in, and add this library plug-in as a dependency to your main plug-in.

Figure 1 - Project structure in the eclipse IDE

Figure 2 - The classpath after jars have been added.

Figure 3 - Project Dependencies

Step 5 - Writing the test class

It is now the time to write the test case.

  • Use the context menu on the ’src’ folder of the ‘org.dmissoh.rcp.mail.test’ plug-in project to add the new package org.dmissoh.rcp.mail.test
  • In this package create a new class RcpMailTestCase and fill it with the snippet below. P.S.: This Test Case class should extends the SWTBotEclipseTestCase. As you can see, this test cases checks the some of the basic functionalities the mail RCP application contains like the tree viewer and the about dialog.

package org.dmissoh.rcp.mail.test;
 
import net.sf.swtbot.eclipse.finder.SWTBotEclipseTestCase;
 
/**
 * A test case to run some basic unit tests on the Mail RCP sample.
 * @author Dimitri Missoh.
 */
public class RcpMailTestCase extends SWTBotEclipseTestCase {
 
	/**
	 * Test the about dialog
	 * @throws Exception
	 */
	public void testAboutDialog() throws Exception {
		/*
		 * Check that we can open the about dialog,
		 * the plug-in details dialog and
		 * the configuration details dialog.
		 * */
		bot.menu("Help").menu("About RCP Product").click();
		bot.button("Plug-in Details").click();
		bot.button("OK").click();
		bot.button("Configuration Details").click();
		bot.button("Close").click();
		bot.button("OK").click();
	}
 
	/**
	 * Test the dialog and the corresponding menu's command
	 * @throws Exception
	 */
	public void testDialog() throws Exception {
		/*
		 * Try to open the dialog using the menu.
		 * This is a way to make sure that this menu option is available.
		 * Also make sure that the dialog can be closed
		 * */
		bot.menu("File").menu("Open Message").click();
		bot.button("OK").click();
	}
 
	/**
	 * Test the navigation tree
	 * @throws Exception
	 */
	public void testTree() throws Exception {
		/*
		 * Now we try to navigate the tree.
		 * Make sure that the first tree node has 3 children
		 * */
		bot.tree().select("me@this.com");
		assertEquals(1, bot.tree().getTreeItem("me@this.com").getNodes().size());
		bot.tree().expandNode("me@this.com");
		assertEquals(3, bot.tree().getTreeItem("me@this.com").getNodes().size());
		/*
		 * Make sure that the second tree node has only one child
		 * */
		bot.tree().select("other@aol.com");
		assertEquals(1, bot.tree().getTreeItem("other@aol.com").getNodes()
				.size());
		bot.tree().expandNode("other@aol.com");
		assertEquals(1, bot.tree().getTreeItem("other@aol.com").getNodes()
				.size());
	}
 
	/**
	 * Test view related functions
	 * @throws Exception
	 */
	public void testView() throws Exception {
		/*
		 * Check that we have only two view opened on start:
		 * - the message view
		 * - the navigation view
		 * Than open one additional message view and check that we have one view more.
		 * At the end we close both message view and make sure that we have only one view left
		 * i.e. the navigation view.
		 */
		assertEquals(2, bot.views().size());
		bot.menu("File").menu("Open Another Message View").click();
		assertEquals(3, bot.views().size());
		bot.view("Message").close();
		bot.view("Message").close();
		assertEquals(1, bot.views().size());
	}
}

Step 6 - Running the test

Running the SWT bot test is as simple as running a classic JUnit test. Expect that we have to set the path to the log4j.configuration file in the corresponding Debug Configuration Dialog.

  • Click right on the RcpMailTestCase class in the package explorer and select [Run As/SWTBot Test], which is a new entry that should appears if the SWTBot feature as been successfully installed as described in Step - 1.
  • The test run will failed because the the path to the Log4J configuration file is missing.
  • Select from the menu [Run/Debug Configurations...] to open the debug configuration dialog
  • Select the corresponding SWTBot test (I’v called it MailTest)
  • In the Test-Tab select JUnit 3
  • In the Main-Tab select org.dmissoh.rcp.mail.product under [Program to Run/Run a Product:]
  • In the Arguments-Tab add the following entry to VM Arguments as shown on fig. 4:
    -Dlog4j.configuration=${project_loc:org.dmissoh.rcp.mail.test}/config/log4j.properties

Figure 4 - Debug Configuration

If all test runs without failure you should see the pleasant JUnit green bar at the end.

For those who are interested in the use of JUnit in general for RCP and OSGi applications, the following blog entries can be useful:

In his article Running Unit Tests for RCP and OSGi Applications, Patrick describes how sets of tests across multiple plug-ins or fragments can be run without using test suites. In one of his previous articles (Testing Plug-ins with Fragments) he explains how fragments can be used to separate the test code from the business code.

Download Projects Files.

January 25th, 2009

Interested in any key events of an SWT Application?

There is actually a way to achieve that. In an appropriate location of your code add:

Display.getDefault().addFilter(SWT.KeyDown, listener);

where the listener to implement can look like:

1
2
3
4
5
Listener listener = new Listener() {
   public void handleEvent(Event event) {
      // do some amazing things with the event
   }
};

Don’t forget to unregister your listener on dispose.

January 18th, 2009

How to get the MIME Type of a file in Java

Have you ever been confronted with the problem of getting the right MIME type for a given file? Using the file extension is not necessarily the best way, since the file can simply not have any extension such as on a Unix system (on Unix systems, file extensions are optional). On this kind of systems, other methods are used to identify the format of a file. One of them is the use of magic numbers. A magic number is a 2 bytes identifier at the beginning of the document.

There are some Java libraries that combine the use of file extension and magic number (also known as magic header) to determine the MIME type of a file. My favorite one is mime-util. The main benefit of this library is, that it consists of a single jar file without any dependencies to third party libraries.

To use this library in your code:

  • Download the jar file from http://sourceforge.net/projects/mime-util,
  • add the jar file to your project dependencies (i.e. add it to the CLASSPATH) and
  • call the static helper method MimeUtil.getMimeType(File) as shown in the snippet below:
1
2
3
4
5
6
7
8
9
10
11
12
13
import eu.medsea.util.MimeUtil;
 
public class Tester {
   public String getMimeType(String fileName){
      File file = new File(fileName);
      String unknownMimeType = "application/x-unknown-mime-type";
      String mimetype = MimeUtil.getMimeType(file);
      if (mimetype == null) {
	mimetype = unknownMimeType;
      }
      return mimetype;
   }
}

Additional information:

For an extensive list of MIME types with their corresponding RFC please check out the following sites:

The online article http://www.rgagnon.com/javadetails/java-0487.html adresses this issue in detail.

November 2nd, 2008

Disable or enable actions sets on perspective change in an Eclipse RCP application

Here is the challenge: I would like to enable or disable some action-sets according to the perspective the user activates. This should be done through a customization plug-in, because I’m not allowed to directly modify the code of the RCP application. I can only contribute my modifications through a new plug-in. Let’s walk through the necessary implementation steps. First we need to register our plug-in as a perspective change listener.  The second step will be to find a way to programmatically enable or disable a given action-set according to the new perspective.

Since I cannot modify the code of the existent application, I will create a new plug-in and extend the early start-up extension point org.eclipse.ui.startup to be able to run some code when the workbench starts. This extension point requires a class that implements the org.eclipse.ui.IStartup interface. The following snippet shows how the plug-in descriptor file plugin.xml should look like:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
   <extension
         point="org.eclipse.ui.startup">
      <startup
            class="perspectiveactionsets.startup.EarlyStartup"></startup>
   </extension>
</plugin>

To be notified on a perspective change event, a org.eclipse.ui.IPerspectiveListener will be registered to the active window of the workbench IWorkbenchWindow in the form of an anonymous class. I use the org.eclipse.ui.PerspectiveAdapter which provides default implementations for the methods described by the IPerspectiveListener interface. There is a very important point we should not forget when trying to retrieve the active workbench window (IWorkbenchWindow) using the static call PlatformUI.getWorkbench().getActiveWorkbenchWindow(). Let’s seek the javadoc for the getActiveWorkbenchwindow() method of the WorkbenchWindow class:

/**
* Returns the currently active window for this workbench (if any). Returns
* <code>null</code> if there is no active workbench window. Returns
* <code>null</code> if called from a non-UI thread.
*
* @return the active workbench window, or <code>null</code> if there is
*         no active workbench window or if called from a non-UI thread
*/
public IWorkbenchWindow getActiveWorkbenchWindow();

That is, we have to retrieve the active workbench window within the UI thread. Here is approximately how the earlyStartup() looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/* (non-Javadoc)
* @see org.eclipse.ui.IStartup#earlyStartup()
*/
public void earlyStartup() {
  /*
  * The registration of the listener should have been done in the UI thread
  * since  PlatformUI.getWorkbench().getActiveWorkbenchWindow() returns null
  * if it is called outside of the UI thread.
  * */
  Display.getDefault().asyncExec(new Runnable() {
    /* (non-Javadoc)
    * @see java.lang.Runnable#run()
    */
    public void run() {
      final IWorkbenchWindow workbenchWindow = PlatformUI.getWorkbench().getActiveWorkbenchWindow();
        if (workbenchWindow != null) {
          workbenchWindow.addPerspectiveListener(new PerspectiveAdapter() {
            /* (non-Javadoc)
            * @see org.eclipse.ui.PerspectiveAdapter#perspectiveActivated(org.eclipse.ui.IWorkbenchPage, org.eclipse.ui.IPerspectiveDescriptor)
            */
            @Override
            public void perspectiveActivated(IWorkbenchPage page, IPerspectiveDescriptor perspectiveDescriptor) {
              super.perspectiveActivated(page, perspectiveDescriptor);
              // TODO implement the task to execute when the perspective change
            }
          });
        }
    }
  });
}

Now let us face the second problem. I would like to disable or enable some action-sets on perspective change.
In the eclipse IDE, you can customize a given perspective using the right mouse click on the corresponding perspective icons (see the screenshot below).

Customize a perspective using the context menu on the correpsonding icon

Customize a perspective using the context menu on the correpsonding icon

This opens a dialog where you can select the command groups (e.g. action-sets) that should be disabled in the workbench as shown in the following screenshot.

Disable command groups with the Customize Perspective Dialog

Disable command groups with the Customize Perspective Dialog

If we can manually customize it, it should also be possible to achieve this task with some lines of code. Let us consult the best eclipse book ever, i.e. the eclipse code itself. A quick search reveals that the problem has been solved in the class org.eclipse.ui.internal.dialogs.CustomizePerspectiveDialog. Having a look at the okPressed() in this class gives us the solution: a method turnOnActionSets() can be used on the perspective object to enable or disable an action-set.

After some modifications, the earlyStartup() method has now the form:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
/* (non-Javadoc)
* @see org.eclipse.ui.IStartup#earlyStartup()
*/
public void earlyStartup() {
  /*
  * The registration of the listener should have been done in the UI thread
  * since  PlatformUI.getWorkbench().getActiveWorkbenchWindow() returns null
  * if it is called outside of the UI thread.
  * */
  Display.getDefault().asyncExec(new Runnable() {
    /* (non-Javadoc)
    * @see java.lang.Runnable#run()
    */
    public void run() {
      final IWorkbenchWindow workbenchWindow = PlatformUI.getWorkbench().getActiveWorkbenchWindow();
        if (workbenchWindow != null) {
          workbenchWindow.addPerspectiveListener(new PerspectiveAdapter() {
            /* (non-Javadoc)
            * @see org.eclipse.ui.PerspectiveAdapter#perspectiveActivated(org.eclipse.ui.IWorkbenchPage, org.eclipse.ui.IPerspectiveDescriptor)
            */
            @Override
            public void perspectiveActivated(IWorkbenchPage page, IPerspectiveDescriptor perspectiveDescriptor) {
              super.perspectiveActivated(page, perspectiveDescriptor);
                if (perspectiveDescriptor.getId().indexOf("org.eclipse.debug.ui.DebugPerspective") &gt; -1) {
                  if (workbenchWindow.getActivePage() instanceof WorkbenchPage) {
                    WorkbenchPage worbenchPage = (WorkbenchPage) workbenchWindow.getActivePage();
                    // Get the perspective
                    Perspective perspective = worbenchPage.findPerspective(perspectiveDescriptor);
                    ArrayList toRemove = new ArrayList();
                      if (perspective != null) {
                        for (IActionSetDescriptor actionSetDescriptor : perspective.getAlwaysOnActionSets()) {
                          if (actionSetDescriptor.getId().indexOf("org.eclipse.search.searchActionSet") &gt; -1) {
                            // Add the action set descriptor to the list of the action sets to remove
                            toRemove.add(actionSetDescriptor);
                          }
                        }
                      perspective.turnOffActionSets((IActionSetDescriptor[]) toRemove.toArray(new IActionSetDescriptor[toRemove.size()]));
                    }
                  }
                }
            }
          });
        }
    }
  });
}

P.S.: In the example above, all search related actions (denoted by the ID ‘org.eclipse.search.searchActionSet‘) will disappear if you set the debug perspective (denoted by the ID ‘org.eclipse.debug.ui.DebugPerspective‘) as the active one.

For more details check out the source code of the project PerspectiveActionSets from the google code repository http://homeworks.googlecode.com/svn/trunk/ or download the plug-in project under the link below.

Download Projects Files.

October 20th, 2008

Use conditional breakpoints to simulate a bug or system out in third party code

Suppose you want to system out the value of a variable your are interested in or even change it value to simulate a bug during a debug session in a third party code, e.g. in a packaged library. We assume that you download the source code and attach it to your library. Since you are compiling your code again the library, you can neither change any part of the code located in the library nor compile it to see the effect of your change. You can easily achieve this task in eclipse using conditional breakpoints. Just double click to add a breakpoint as usual and use the context menu on this breakpoint to open the “Breakpoint Properties” dialog. The default option stops the debugger at a conditional break point only if it returns true. So terminate you code block with a return false, to no interrupt the code execution. Screenshots show two use cases. In the first one we use this feature to system out the value of a given label, and in the second example we use conditional break point to set the value of the variable window to null to simulate a bug and see how our code react on a null pointer exception.

System out with conditional breakpoints

Set a variable to null with conditional breakpoint