Google Web Toolkit
Search Google Code:

# 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

- Asynchronous Testing
  How to test event-driven features such as server calls or timers.
- Benchmarking
  How to use GWT's JUnit support to create and report on benchmarks to help you optimize your code.