****************************************************************************************
*                                                                                      *
*                                   L A T T U                                          *
*                                                                                      *
****************************************************************************************

Framework for testing Eclipse RCP Applications. It can run both Unit and Functional tests.
Essentially, it is an Eclipse Plug-in which provides Fitnesse extension to run unit and acceptance
tests. It uses JUnit for unit testing, fitnesse for functional acceptance tests and Abbot for
UI tests.

Why another framework?
When I started building eclipse RCP applications, there was no decent way to run my JUnit tests
from an ant build. There were some frameworks available out there, but all they gave back after
a test run was some weird numbers to signify the test results. Clearly we needed a better way to
run our tests and publish its results.

Also there were no acceptance testing tools available for specifying business rules for RCP
applications. Since we were using Fitnesse for other acceptance tests, we extended Fitnesse to
run our acceptance tests.

With the power of this framework and ant we were able to completely automate our RCP build.
We were able to build products out of our plug-ins and run JUnit tests against them. Next we
needed some framework to run some sample UI tests, to make sure the UI does come up after a build.

We extended the same framework by using Abbot's SWT port under the covers to perform our UI tests.

What we ended up with was a framework to run JUnit and Acceptance tests (both UI and non-UI based).

Installing Lattu:
SourceForge has 2 files per Lattu release. One is the source file called
lattu-<version>-src.zip and the other is just the plug-in called lattu-<version>.zip

lattu-<version>-src.zip contains the whole Lattu project. It has the source code,
sample plugins, build files, etc. Click here to see a demo of the Lattu plugin at work.

lattu-<version>.zip contains the plug-ins and Fitnesse configuration files used by RCP
applications to automate tests. If you want to use Lattu plug-in to run the tests against
the RCP application, you need to unpack the zip into your target eclipse plug-ins folder.

To use Lattu:
Create a test plug-in per production plug-in. Each test plug-ins that contains Fitnesse/JUnit
tests that will test an Eclipse UI should have a dependency on the Lattu plug-in.  Additionally,
the test plug-ins should contribute an extension to the lattu.fitnesse.to.rcp.LattuPlug-in
extension point provided by the Lattu plug-in.

Example:
<plugin>
   ...
   <extension point="lattu.fitnesse.to.rcp.LattuPlugin">
      <FitPlugin pluginId="org.eclipse.swt.examples.controls.test"/>
   </extension>
   ...
</plugin>

The plug-inId must be the same the test plug-in's id. This allows Lattu to load the test
classes from the plug-in's classloader using this ID to execute the tests. In order for
acceptance UI tests to work, Eclipse needs to be launched before running Fitnesse tests.

Organization of RCP plug-ins:
We recommend a plug-in structure for development that keeps the production and test plug-ins
independent of each other. Each production plug-in has an independent test plug-in where the
unit test and acceptance test cases reside.

The following are the characteristics of the production plug-in:
* Have dependencies on Eclipse RCP plug-ins.
* Should not have dependency on JUnit or Fitnesse or other test plug-ins.
* Should not have unit test or acceptance test cases.
* Export all the packages but restrict access only to its test plug-in if that package should
  not be accessed from another plug-in. A good practice is to have these private classes in an
  internal package like com.x.y.z.rcp.internal.something by Eclipse standard. This will allow
  the test cases in the test plug-in to access the internal packages of the production plug-in.

The following are the characteristics of the test plug-in:
* Depends on the production plug-in.
* Depends on test plug-ins org.junit and lattu.fitnesse.to.rcp plug-ins.
* Unit test and acceptance test cases reside in the test plug-in.
* The name of the test plug-in should be post fixed with ".test" to the production plug-in name.
  For example, if the production plug-in name is org.eclipse.swt.examples.controls, then the test
  plug-in name will be org.eclipse.swt.examples.controls.test.
* The test plug-in should have the same package names as the production plug-in.
* No packages should be exported from the test plug-in.

The advantages of this structure are:
1.  The production code is independent from test code.
2.  The production code does not have any dependencies on test plug-ins like junit and fitnesse
    and can be delivered as it is.
3.  Easy to manage, build and package.

Acceptance testing using Fitnesse and Abbot:
Fitnesse is an automated acceptance testing tool.  Abbot is a Java GUI testing framework that
works with SWT.  Acceptance testing for Eclipse-based UI’s involves the creation of a Fitnesse
test suite containing fixtures (test code) that make both Eclipse RCP and Abbot calls to test
the UI as it is delivered.  This is different from JUnit testing in that JUnit tests do not
require the UI framework to be up and running; they simply instantiate the unit they’re testing,
make calls on it, and throw it away.  Acceptance tests test the UI as a product would be run.

Although all automated acceptance tests should be run as Fitnesse tests, not all UI acceptance
tests will use Abbot.  Abbot can be used for SWT manipulation (menu items, controls, dialogs,
etc.), but not for RCP manipulation (perspectives, editors, views).  Many tests (fixtures) will
likely have a mix of Eclipse RCP and Abbot calls to perform the appropriate actions the test
requires.  For example, in a single test Eclipse RCP calls could be made to set a perspective,
and choose an item off the menu.  Then Abbot calls could be made to find a text box, write to
it, initiate a dialog, and click a button on the dialog.  Then Eclipse RCP calls could be made
to check values on a view or close an editor.
Refer to org.eclipse.swt.examples.controls.test.fixture.CheckAboutMenu for an example.

When building your test plug-in in the Eclipse IDE, test plug-ins need the Fitnesse jars
(fitnesse.jar  and fitlibrary.jar) to be included in their plug-in project’s java build path.
If the Test plug-in is also using Abbot, the Abbot jars (abbot.jar, abbot.swt.eclipse.jar,
abbot.swt.example.jar, abbot.swt.jar, abbot.swt.test.jar) will also need to be included in
the plug-in project’s java build path.   These jars are located in the lib directory of the
Lattu plug-in (the java build path can point to this location).  When building with ant and at
runtime these dependencies are resolved by the dependency on the Lattu plug-in.

Download Lattu
You can download the latest version of Lattu from Lattu @ SourceForge