JUnit Integration

GWT includes a special GWTTestCase base class that provides JUnit integration. Running a compiled GWTTestCase subclass under JUnit launches an invisible GWT browser.

By default, tests run in hosted mode as normal Java bytecode in a JVM. Overriding this default behavior requires passing arguments to the GWT shell. Arguments cannot be passed directly through the command line, because normal command-line arguments go directly to the JUnit runner. Instead, define the system property gwt.args to pass arguments to GWT. For example, to run in web mode, declare -Dgwt.args="-web" as a JVM argument when invoking JUnit. To get a full list of supported options, declare -Dgwt.args="-help" (instead of running the test, help is printed to the console).

Creating a Test Case

GWT includes a handy junitCreator tool that will generate a starter test case for you, plus scripts for testing in both hosted mode and web mode. But here are the steps if you want to set it up by hand:

  1. Define a class that extends GWTTestCase.
  2. Create a module that causes the source for your test case to be included. If you are adding a test case to an existing GWT app, you can usually just use the existing module.
  3. Implement the method GWTTestCase.getModuleName() to return the fully-qualified name of the module.
  4. Compile your test case class to bytecode (using javac or a Java IDE).
  5. When running the test case, make sure your classpath includes:
    • your project's src directory
    • your project's bin directory
    • gwt-user.jar
    • gwt-dev-windows.jar (or gwt-dev-linux.jar)
    • junit.jar

Example

Write the com.example.foo.client.FooTest test case. 
public class FooTest extends GWTTestCase {

  /*
   * Specifies a module to use when running this test case. The returned
   * module must cause the source for this class to be included.
   * 
   * @see com.google.gwt.junit.client.GWTTestCase#getModuleName()
   */
  public String getModuleName() {
    return "com.example.foo.Foo";
  }

  public void testStuff() {
    assertTrue(2 + 2 == 4);
  }
}
Create the com.example.foo.Foo module. 
<!--                                                                        -->
<!-- Copyright 2007 Google Inc.                                             -->
<!-- Licensed under the Apache License, Version 2.0 (the "License"); you    -->
<!-- may not use this file except in compliance with the License. You may   -->
<!-- may obtain a copy of the License at                                    -->
<!--                                                                        -->
<!-- http://www.apache.org/licenses/LICENSE-2.0                             -->
<!--                                                                        -->
<!-- Unless required by applicable law or agreed to in writing, software    -->
<!-- distributed under the License is distributed on an "AS IS" BASIS,      -->
<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or        -->
<!-- implied. License for the specific language governing permissions and   -->
<!-- limitations under the License.                                         -->

<module>
  <!-- Module com.example.foo.Foo -->

  <!-- Standard inherit.                                           -->
  <inherits name='com.google.gwt.user.User'/>

  <!-- implicitly includes com.example.foo.client package          -->

  <!-- OPTIONAL STUFF FOLLOWS -->

  <!-- It's okay for your module to declare an entry point.        -->
  <!-- This gets ignored when running under JUnit.                 -->
  <entry-point class='com.example.foo.FooModule'/>

  <!-- You can also test remote services during a JUnit run.       -->
  <servlet path='/foo' class='com.example.foo.server.FooServiceImpl'/>
</module>

Tip
You don't need to create a separate module for every test case. In the example above, any test cases in com.example.foo.client (or any subpackage) can share the com.example.foo.Foo module.

Advanced Topics