KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > gwt > junit > client > GWTTestCase


1 /*
2  * Copyright 2007 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5  * use this file except in compliance with the License. You may obtain a copy of
6  * the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13  * License for the specific language governing permissions and limitations under
14  * the License.
15  */
16 package com.google.gwt.junit.client;
17
18 import com.google.gwt.junit.JUnitShell;
19
20 import junit.framework.TestCase;
21 import junit.framework.TestResult;
22
23 /**
24  * Acts as a bridge between the JUnit environment and the GWT environment. We
25  * hook the run method and stash the TestResult object for later communication
26  * between the test runner and the unit test shell that drives the test case
27  * inside a hosted browser.
28  *
29  * <p>
30  * There are two versions of this class. This version is the binary version that
31  * derives from JUnit's {@link TestCase} and handles all the work of starting up
32  * the GWT environment. The other version is a translatable class that is used
33  * within the browser. See the <code>translatable</code> subpackage for the
34  * translatable implementation.
35  * </p>
36  */
37 public abstract class GWTTestCase extends TestCase {
38
39   /*
40    * Object that collects the results of this test case execution.
41    */
42   private TestResult testResult = null;
43
44   /**
45    * Add a checkpoint message to the current test. If this test fails, all
46    * checkpoint messages will be appended to the getException description. This can
47    * be useful in web mode for determining how far test execution progressed
48    * before a failure occurs.
49    *
50    * @param msg the checkpoint message to add
51    * @deprecated This method will be removed when web mode supports stack
52    * traces. It can be useful for debugging web mode failures, but
53    * production code should not depend on it.
54    */
55   public final void addCheckpoint(String JavaDoc msg) {
56     // implemented in the translatable version of this class
57 }
58
59   /**
60    * Determines whether or not exceptions will be caught by the test fixture.
61    * Override this method and return <code>false</code> to let exceptions
62    * escape to the browser. This will break the normal JUnit reporting
63    * functionality, but can be useful in web mode with a JavaScript debugger to
64    * pin down where exceptions are originating.
65    *
66    * @return <code>true</code> for normal JUnit behavior, or
67    * <code>false</code> to disable normal JUnit getException reporting
68    */
69   public boolean catchExceptions() {
70     return true;
71   }
72
73   /**
74    * Clears the accumulated list of checkpoint messages.
75    *
76    * @see #addCheckpoint(String)
77    * @deprecated This method will be removed when web mode supports stack
78    * traces. It can be useful for debugging web mode failures, but
79    * production code should not depend on it.
80    */
81   public final void clearCheckpoints() {
82     // implemented in the translatable version of this class
83 }
84
85   /**
86    * Returns the current set of checkpoint messages.
87    *
88    * @return a non-<code>null</code> array of checkpoint messages
89    * @see #addCheckpoint(String)
90    * @deprecated This method will be removed when web mode supports stack
91    * traces. It can be useful for debugging web mode failures, but
92    * production code should not depend on it.
93    */
94   public final String JavaDoc[] getCheckpoints() {
95     // implemented in the translatable version of this class
96 return null;
97   }
98
99   /**
100    * Specifies a module to use when running this test case. Subclasses must
101    * return the name of a module that will cause the source for that subclass to
102    * be included.
103    *
104    * @return the fully qualified name of a module
105    */
106   public abstract String JavaDoc getModuleName();
107
108   /**
109    * Stashes <code>result</code> so that it can be accessed during
110    * {@link #runTest()}.
111    */
112   public final void run(TestResult result) {
113     testResult = result;
114     super.run(result);
115   }
116
117   /**
118    * Put the current test in asynchronous mode. If the test method completes
119    * normally, this test will not immediately succeed. Instead, a <i>delay
120    * period</i> begins. During the delay period, the test system will wait for
121    * one of three things to happen:
122    *
123    * <ol>
124    * <li> If {@link #finishTest()} is called before the delay period expires,
125    * the test will succeed.</li>
126    * <li> If any getException escapes from an event handler during the delay
127    * period, the test will error with the thrown getException.</li>
128    * <li> If the delay period expires and neither of the above has happened, the
129    * test will error with a {@link TimeoutException}. </li>
130    * </ol>
131    *
132    * <p>
133    * This method is typically used to test event driven functionality.
134    * </p>
135    *
136    * <p>
137    * <b>Example:</b>
138    * {@example com.google.gwt.examples.AsyncJUnitExample#testTimer()}
139    * </p>
140    *
141    * @param timeoutMillis how long to wait before the current test will time out
142    * @tip Subsequent calls to this method reset the timeout.
143    * @see #finishTest()
144    *
145    * @throws UnsupportedOperationException if this test case is a
146    * {@link Benchmark}
147    */
148   protected final void delayTestFinish(int timeoutMillis) {
149     // implemented in the translatable version of this class
150 }
151
152   /**
153    * Cause this test to succeed during asynchronous mode. After calling
154    * {@link #delayTestFinish(int)}, call this method during the delay period to
155    * cause this test to succeed. This method is typically called from an event
156    * handler some time after the test method returns control to the caller.
157    *
158    * <p>
159    * Calling this method before the test method completes, will undo the effect
160    * of having called <code>delayTestFinish()</code>. The test will revert to
161    * normal, non-asynchronous mode.
162    * </p>
163    *
164    * <p>
165    * <b>Example:</b>
166    * {@example com.google.gwt.examples.AsyncJUnitExample#testTimer()}
167    * </p>
168    *
169    * @throws IllegalStateException if this test is not in asynchronous mode.
170    * @throws UnsupportedOperationException if this test case is a
171    * {@link Benchmark}
172    *
173    * @see #delayTestFinish(int)
174    */
175   protected final void finishTest() {
176     // implemented in the translatable version of this class
177 }
178
179   /**
180    * Returns the overall test results for this unit test.
181    *
182    * These TestResults are more comprehensive than JUnit's default test results,
183    * and are automatically collected by GWT's testing infrastructure.
184    */
185   protected final TestResults getTestResults() {
186     // implemented in the translatable version of this class
187 return null;
188   }
189
190   /**
191    * Runs the test via the {@link JUnitShell} environment.
192    */
193   protected final void runTest() throws Throwable JavaDoc {
194     JUnitShell.runTest(getModuleName(), this, testResult);
195   }
196 }
197
Popular Tags