Migration to 0.40

Version 0.40 (and 0.33.5, 0.28.12, 0.25.9, 0.22.9 branches) of gwt-test-utils introduces the support for GWT overlay types.

Although many current users won't care, it is a major improvement, which opens a lot of possibilities to support GWT DOM related features in a better way.

Why now ?

Until today, there were (very) hugly hacks in gwt-test-utils¨ to avoid ClassCastException when some GWT's code does some JavaScriptObject upcasting. And when some people asked how to test code which relies directly on overlay types feature, we had to tell them to use GWTTestCase.. (see here for example).

We were aware of the fact that supporting overlays would include some changes in gwt-test-utils public API.
More important, it would introduce some overhead at the loading of your custom classloader, since overlay types emulation in the JVM is not possible without an iteration through every class in the GWT frontend and in your module(s), searching for JavaScriptObject subtypes and SingleJsoImpl annotated classes in order to make the necessary (and heavy) bytecode modifications. For us, it was not acceptable to wait 4-5 secondes to launch our tests.

But today, we realized avoiding overlay types support is not possible anymore : a lot of coming features, such as Elemental (GWT 2.5) or XElement (GXT 3.0) directly rely on overlays and we can't use our existing ugly hacks to make them work.

While we continue to focus on achieving great test performances, we don't want you to be stuck on using some old GWT or GXT version because of gwt-test-utils.
Don't be afraid, gwt-test-utils still remains about 10 times faster than GWTTestCase ! It still doesn't need to run the entire GWT stack.

If you realize the new latency won't be acceptable (because you're doing TDD for example), you definitely should considere using Infinitest in addition to gwt-test-utils, it would solve the problem :-)

How to migrate

Since we need more informations at the very beginning of a test class instanciation, we had to make some breaking changes in the way gwt-test-utils is setup. Following thoses steps, migration would take you less than five minutes :

• Update your gwt-test-utils dependency (it's a good way to start !)

• The GwtTest.getModuleName() abstract method does not exist anymore. Instead, you have to annotate your GwtTest sublclasses like that :

@GwtModule("com.googlecode.gwt.test.SampleModule")
public class SampleTest extends GwtTest { ... }

Note : GwtModule is an inherited annotation, which means you can use it on an parent test class if you have one.

• In your META-INF/gwt-test-utils.properties configuration file, the value 'module-file' value is not supported anymore. You have to change lines such as :

      com/googlecode/gwt/test/SampleModule.gwt.xml = module-file 

to :

      com.googlecode.gwt.test.SampleModule = gwt-module

• If you had some 'substitute-class' or 'remove-method' entries in your META-INF/gwt-test-utils.properties, you can now remove them (it was the ugly hacks I was speaking about).

Future

By using gwt-dev internal features to load modules data (see ModuleDef and CompilationState), we've opened the way to support some other features gwt-test-utils was unable to handle, such as code Generators, which a lot of GWT APIs rely on.

Before version 0.40, some of those features were already supported, relying on lot of custom Java proxies (UiBinder, ClientBundle), which needs to be modified whenever the API changes between two version of GWT. Now, gwt-test-utils can start relying on GWT's Generator to support others features. It's the case for Editors which are finally supported starting 0.40 !

In future releases, It would be great if gwt-test-utils could transparently create, compile and run the Java code from every Generators.It would guaranty every new GWT features would be supported by gwt-test-utils, without any change !