Version 3
Created by jpeterka on Apr 5, 2011 7:05 AM. Last modified by jpeterka on Apr 5, 2011 10:01 AM.

    Testing visual parts in JBT

    Document goal

    This article should provide basic overview of SWTBot test development for various GEF based eclipse parts and other graphical representations.

    GEF Introduction for SWTBot test developers

    Graphical Editing Framework (GEF) is widely used in JBoss Tools Editors as well as many others 3rd party plugins. So there is a need for testing GUI based on it. API provided by SWTBot for GEF parts is available in org.eclipse.swtbot.eclipse.gef* packages. Top classes are:

    • SWTBotEclipseTestCase
    • SWTGefBot

    SWTBotEclipseTestCase encapsulates SWTGefBot for usage in GEF based tests. SWTBotGef provides high level methods for finding editor, view and viewer. These particular classes are located in gef.finder.widgets package, namely:

    • SWTBotGefEditor
    • SWTBotGefView
    • SWTBotGefViewer

    Usual scenario for GEF bot test:

    • Locate GEF editor
    • Access some element
    • Check state
    • Perform operation on it
    • Check if operation is done

    Example of basic GEF usage

    SWTGefBot gefBot = new SWTGefBot();
    SWTBotGefEditor editor = gefBot.gefEditor("simple");
    SWTBotMultiPageEditor multi = new SWTBotMultiPageEditor(editor.getReference(), gefBot);
    multi.activatePage("Diagram");
    editor.getEditPart("start").select();

    SWTBotExt Limitations

    There are several known issues related to GEF SWTBot:

    • some elements can't be found via SWTGefBot
    • context menu item is not always triggered successfully
    • different platform issues
    • timing and synchronization
    • missing API for particular operations
    • unreachable elements attributes from the bot

    SWTBotExt GEF

    SWTBotExt GEF API tries to solve/workaround some of these limitations/issues and provides fine-grained approach for some operations. It can be found in org.jboss.tools.ui.bot.ext.gef package in org.jboss.tools.ui.bot.ext plug-in. It provides these basic classes:

    • SWTBotGefEditorExt - uses SWTBotGefEditor and provides additional routines for figures manipulation
    • SWTBotGefViewerExt - provides methods for finding root figure
    • SWTBotGefFigure - provides access to GEF figure and it's attributes
    • SWTBotGefFinder - can finds particular elements like editor canvas, etc.
    • SWTBotGefMouse - general mouse controller for GEF Canvas. Can be used in your GEF api or outside as well
    • SWTGefContextMenuExt - context menu controller resolving bot GEF context menu issues
    • SWTArranger - provides facility for arranging figures on canvas like resolving empty area, etc.

    Example changing label on a figure

    SWTBotGefEditorExt editor = new SWTBotGefEditorExt("simple");
    SWTBotGefFigure label = editor.labelFigure("text");
    editor.setLabelText(label, "new_text");
    editor.save();

    Zest components

    GEF Zest API provides draw2d based components for visual data representation without editing features. Since SWTBot doesn't provide API for Zest manipulation SWTBotExt tries to cover this area

    • SWTBotZestBot
    • SWTBotZestGraph
    • SWTBotZestContextMenu
    • SWTBotZestNode
    • SWTBotZestConnection

    Basic example of Zest Bot usage

    SWTZestBot zestBot = new SWTZestBot();
    SWTBotZestGraph graph = zestBot.getZestGraph(0);
    SWTBotZestNode node = graph.node("Input Task");
    node.click();
    SWTBotZestContextMenu menu = node.contextMenu();
    menu.clickMenu("Add Task","Java Mapping");
    graph.node("Input Task").click();
    graph.connection(graph.node("Input Task"), graph.node("Java Mapping")).click();

    General approach for resolving issues

    Area of Visual representation used in Eclipse editors and viewers is quite wide and there can scenarios where SWTBot and even SWTBotExt API can fail (based on editors implementations, platform issues, etc). Specific treatment for these cases is often needed so there is some general approach how to resolve them. Let's say we need to manipulate some element on editor and we are not able to do that via SWTBot. General approach is to:

    • Get as deep as possible via SWTBot or SWTBotExt - to get at      least an editor
    • Find root figure - to be able to access rest of the element      figures
    • Find particular figures and get their boundaries
    • Perform needed operation (via SWTBotMouse for example)
    • if it's general problem, implement some API for further usage

    Other notes

    Since there are quite often changes related to SWTBot GEF API not everything described here must be necessary best approach. So please watch SWTBot for latest updates or use an approach which fits you best.

    Related links

    Further tasks related to GEF Bot Ext

    • Refactor and clean API
    • More generic approach
    • Separate from main BotExt plugin
    • Contribute into SWTBot if possible