Package com.google.gwt.junit.client

Class GWTTestCase

  • All Implemented Interfaces:
    junit.framework.Test
    public abstract class GWTTestCase
extends junit.framework.TestCase
    Acts as a bridge between the JUnit environment and the GWT environment. We hook the run method and stash the TestResult object for later communication between the test runner and the unit test shell that drives the test case inside a hosted browser.

    There are two versions of this class. This version is the binary version that derives from JUnit's TestCase and handles all the work of starting up the GWT environment. The other version is a translatable class that is used within the browser. See the translatable subpackage for the translatable implementation.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  GWTTestCase.TestModuleInfo
      Information about a synthetic module used for testing.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.Map<java.lang.String,​GWTTestCase.TestModuleInfo> ALL_GWT_TESTS
      Records all live GWTTestCases by synthetic module name so we can optimize run they are compiled and run.
      protected junit.framework.TestResult testResult
      Object that collects the results of this test case execution.

    • Constructor Summary

      Constructors 
      Constructor Description
      GWTTestCase()
      A new instance of your subclass is constructed for each test method that is to be run.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      boolean catchExceptions()
      Determines whether or not exceptions will be caught by the test fixture.
      protected void delayTestFinish​(int timeoutMillis)
      Put the current test in asynchronous mode.
      protected void finishTest()
      Cause this test to succeed during asynchronous mode.
      static java.lang.String[] getAllTestModuleNames()
      Get the names of all test modules.
      static int getModuleCount()
      Get the number of modules.
      abstract java.lang.String getModuleName()
      Specifies a module to use when running this test case.
      com.google.gwt.junit.JUnitShell.Strategy getStrategy()
      Get the JUnitShell.Strategy to use when compiling and running this test.
      java.lang.String getSyntheticModuleName()
      Get the synthetic module name, which includes the synthetic extension defined by the JUnitShell.Strategy.
      static GWTTestCase.TestModuleInfo getTestsForModule​(java.lang.String syntheticModuleName)
      Get the set of all JUnitHost.TestInfo for the specified module.
      protected void gwtSetUp()
      A replacement for JUnit's setUp() method.
      protected void gwtTearDown()
      A replacement for JUnit's tearDown() method.
      boolean isPureJava()
      Returns whether this test case should be run in pure Java mode (non-GWT).
      protected void reportUncaughtException​(java.lang.Throwable ex)
      Reports an exception that might have escaped to the browser.
      void run​(junit.framework.TestResult result)
      Stashes result so that it can be accessed during runTest().
      protected void runTest()
      Runs the test via the JUnitShell environment.
      void setForcePureJava​(boolean forcePureJava)
      Specifies whether this test case should be always run in pure Java mode (non-GWT).
      void setName​(java.lang.String name)  
      protected void setUp()
      This method has been made final to prevent you from accidentally running client code outside of the GWT environment.
      protected void tearDown()
      This method has been made final to prevent you from accidentally running client code outside of the GWT environment.

      • Methods inherited from class junit.framework.TestCase

        countTestCases, createResult, getName, run, runBare, toString

      • Methods inherited from class junit.framework.Assert

        assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, fail, fail, failNotEquals, failNotSame, failSame, format

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • ALL_GWT_TESTS

        public static final java.util.Map<java.lang.String,​GWTTestCase.TestModuleInfo> ALL_GWT_TESTS
        Records all live GWTTestCases by synthetic module name so we can optimize run they are compiled and run. Ordered so that we can precompile the modules in the order that they will run.

      • testResult

        protected junit.framework.TestResult testResult
        Object that collects the results of this test case execution.

    • Constructor Detail

      • GWTTestCase

        public GWTTestCase()
        A new instance of your subclass is constructed for each test method that is to be run. You should avoid running code in your subclass constructor, initializer blocks, and field initializations, because if those code blocks must be runnable outside of the GWT environment. As an example of what could go wrong if you run code there, trying to run a JSNI method could generate an UnsatisfiedLinkError, and trying to call GWT.create(Class) could throw an UnsupportedOperationException. Instead, override gwtSetUp() and perform any initialization code there.

    • Method Detail

      • getAllTestModuleNames

        public static java.lang.String[] getAllTestModuleNames()
        Get the names of all test modules.
        Returns:
        all test module names

      • getModuleCount

        public static int getModuleCount()
        Get the number of modules.
        Returns:
        the module count.

      • getTestsForModule

        public static GWTTestCase.TestModuleInfo getTestsForModule​(java.lang.String syntheticModuleName)
        Get the set of all JUnitHost.TestInfo for the specified module.
        Parameters:
        syntheticModuleName - the synthetic module name
        Returns:
        all tests for the module

      • catchExceptions

        public boolean catchExceptions()
        Determines whether or not exceptions will be caught by the test fixture. Override this method and return false to let exceptions escape to the browser. This will break the normal JUnit reporting functionality, but can be useful in Production Mode with a JavaScript debugger to pin down where exceptions are originating.
        Returns:
        true for normal JUnit behavior, or false to disable normal JUnit exception reporting

      • getModuleName

        public abstract java.lang.String getModuleName()
        Specifies a module to use when running this test case. Subclasses must return the name of a module that will cause the source for that subclass to be included.
        Returns:
        the fully qualified name of a module, or null to run as a pure Java (non-GWT) test case (same effect as passing true to setForcePureJava(boolean))
        See Also:
        isPureJava()

      • getStrategy

        public com.google.gwt.junit.JUnitShell.Strategy getStrategy()
        Get the JUnitShell.Strategy to use when compiling and running this test.
        Returns:
        the test JUnitShell.Strategy

      • getSyntheticModuleName

        public final java.lang.String getSyntheticModuleName()
        Get the synthetic module name, which includes the synthetic extension defined by the JUnitShell.Strategy.
        Returns:
        the synthetic module name, or null if this test case is run in pure Java mode (non-GWT)
        See Also:
        isPureJava()

      • isPureJava

        public boolean isPureJava()
        Returns whether this test case should be run in pure Java mode (non-GWT). Returns true if and only if getModuleName() returns null, or setForcePureJava(boolean) was last invoked with true.

      • run

        public final void run​(junit.framework.TestResult result)
        Stashes result so that it can be accessed during runTest().
        Specified by:
        run in interface junit.framework.Test
        Overrides:
        run in class junit.framework.TestCase

      • setForcePureJava

        public void setForcePureJava​(boolean forcePureJava)
        Specifies whether this test case should be always run in pure Java mode (non-GWT). Passing true has the same effect as returning null in getModuleName(). The setting is false by default.
        Parameters:
        forcePureJava - true to always run this test case in pure Java mode (non-GWT); false to run this test case in GWT mode if getModuleName() does not return null
        See Also:
        isPureJava()

      • setName

        public void setName​(java.lang.String name)
        Overrides:
        setName in class junit.framework.TestCase

      • delayTestFinish

        protected final void delayTestFinish​(int timeoutMillis)
        Put the current test in asynchronous mode. If the test method completes normally, this test will not immediately succeed. Instead, a delay period begins. During the delay period, the test system will wait for one of three things to happen:
        1. If finishTest() is called before the delay period expires, the test will succeed.
        2. If any exception escapes from an event handler during the delay period, the test will error with the thrown exception.
        3. If the delay period expires and neither of the above has happened, the test will error with a TimeoutException.

        This method is typically used to test event driven functionality.

        Example: 

        public void testTimer() {

  // Set a delay period significantly longer than the
  // event is expected to take.
  delayTestFinish(500);

  // Setup an asynchronous event handler.
  Timer timer = new Timer() {
    @Override
    public void run() {
      // do some validation logic

      // tell the test system the test is now done
      finishTest();
    }
  };

  // Schedule the event and return control to the test system.
  timer.schedule(100);
}

        Parameters:
        timeoutMillis - how long to wait before the current test will time out
        Throws:
        java.lang.UnsupportedOperationException - if #supportsAsync() is false
        See Also:
        finishTest()
        Tip:
        Subsequent calls to this method reset the timeout.

      • finishTest

        protected final void finishTest()
        Cause this test to succeed during asynchronous mode. After calling delayTestFinish(int), call this method during the delay period to cause this test to succeed. This method is typically called from an event handler some time after the test method returns control to the caller.

        Calling this method before the test method completes, will undo the effect of having called delayTestFinish(). The test will revert to normal, non-asynchronous mode.

        Example: 

        public void testTimer() {

  // Set a delay period significantly longer than the
  // event is expected to take.
  delayTestFinish(500);

  // Setup an asynchronous event handler.
  Timer timer = new Timer() {
    @Override
    public void run() {
      // do some validation logic

      // tell the test system the test is now done
      finishTest();
    }
  };

  // Schedule the event and return control to the test system.
  timer.schedule(100);
}

        Throws:
        java.lang.IllegalStateException - if this test is not in asynchronous mode
        java.lang.UnsupportedOperationException - if #supportsAsync() is false
        See Also:
        delayTestFinish(int)

      • reportUncaughtException

        protected void reportUncaughtException​(java.lang.Throwable ex)
        Reports an exception that might have escaped to the browser.

        This method is called by the test framework to report uncaught exceptions. The default implementation causes the test case to be reported as 'failed'. However in some rare situations where an uncaught exception is expected, a test case may choose to alter the behavior by overriding it: 

         class SomeTestCase extends GWTTestCase {

   class ExpectedTestException extends Exception {}

   @Override
   protected void reportUncaughtException(Throwable t) {
     // Ignore exceptions that are expected to be thrown by our test cases:
     if (t instanceof ExpectedTestException) {
       return;
     }
     super.reportUncaughtException(t);
   }
   ...
 }
        Note that this method will not cause the test case to fail immediately if the main test body is still executing. In that case, test will fail after the main body returns with the reported exception. If the test has already finished (fail or success) before this method is called, the reported exception is currently ignored, but this may result in an error in a future version of GWT.
        See Also:
        GWT.reportUncaughtException(java.lang.Throwable)

      • gwtSetUp

        protected void gwtSetUp()
                 throws java.lang.Exception
        A replacement for JUnit's setUp() method. This method runs once per test method in your subclass, just before your each test method runs and can be used to perform initialization. Override this method instead of setUp(). This method is run even in pure Java mode (non-GWT).
        Throws:
        java.lang.Exception
        See Also:
        setForcePureJava(boolean)

      • gwtTearDown

        protected void gwtTearDown()
                    throws java.lang.Exception
        A replacement for JUnit's tearDown() method. This method runs once per test method in your subclass, just after your each test method runs and can be used to perform cleanup. Override this method instead of tearDown(). This method is run even in pure Java mode (non-GWT).
        Throws:
        java.lang.Exception
        See Also:
        setForcePureJava(boolean)

      • runTest

        protected void runTest()
                throws java.lang.Throwable
        Runs the test via the JUnitShell environment. Do not override or call this method.
        Overrides:
        runTest in class junit.framework.TestCase
        Throws:
        java.lang.Throwable

      • setUp

        protected final void setUp()
                    throws java.lang.Exception
        This method has been made final to prevent you from accidentally running client code outside of the GWT environment. Please override gwtSetUp() instead.
        Overrides:
        setUp in class junit.framework.TestCase
        Throws:
        java.lang.Exception

      • tearDown

        protected final void tearDown()
                       throws java.lang.Exception
        This method has been made final to prevent you from accidentally running client code outside of the GWT environment. Please override gwtTearDown() instead.
        Overrides:
        tearDown in class junit.framework.TestCase
        Throws:
        java.lang.Exception