001: /*
002: * Copyright 2007 Google Inc.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy of
006: * the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations under
014: * the License.
015: */
016: package com.google.gwt.junit.client;
017:
018: import com.google.gwt.junit.JUnitShell;
019:
020: import junit.framework.TestCase;
021: import junit.framework.TestResult;
022:
023: /**
024: * Acts as a bridge between the JUnit environment and the GWT environment. We
025: * hook the run method and stash the TestResult object for later communication
026: * between the test runner and the unit test shell that drives the test case
027: * inside a hosted browser.
028: *
029: * <p>
030: * There are two versions of this class. This version is the binary version that
031: * derives from JUnit's {@link TestCase} and handles all the work of starting up
032: * the GWT environment. The other version is a translatable class that is used
033: * within the browser. See the <code>translatable</code> subpackage for the
034: * translatable implementation.
035: * </p>
036: */
037: public abstract class GWTTestCase extends TestCase {
038:
039: /*
040: * Object that collects the results of this test case execution.
041: */
042: private TestResult testResult = null;
043:
044: /**
045: * Add a checkpoint message to the current test. If this test fails, all
046: * checkpoint messages will be appended to the getException description. This can
047: * be useful in web mode for determining how far test execution progressed
048: * before a failure occurs.
049: *
050: * @param msg the checkpoint message to add
051: * @deprecated This method will be removed when web mode supports stack
052: * traces. It can be useful for debugging web mode failures, but
053: * production code should not depend on it.
054: */
055: public final void addCheckpoint(String msg) {
056: // implemented in the translatable version of this class
057: }
058:
059: /**
060: * Determines whether or not exceptions will be caught by the test fixture.
061: * Override this method and return <code>false</code> to let exceptions
062: * escape to the browser. This will break the normal JUnit reporting
063: * functionality, but can be useful in web mode with a JavaScript debugger to
064: * pin down where exceptions are originating.
065: *
066: * @return <code>true</code> for normal JUnit behavior, or
067: * <code>false</code> to disable normal JUnit getException reporting
068: */
069: public boolean catchExceptions() {
070: return true;
071: }
072:
073: /**
074: * Clears the accumulated list of checkpoint messages.
075: *
076: * @see #addCheckpoint(String)
077: * @deprecated This method will be removed when web mode supports stack
078: * traces. It can be useful for debugging web mode failures, but
079: * production code should not depend on it.
080: */
081: public final void clearCheckpoints() {
082: // implemented in the translatable version of this class
083: }
084:
085: /**
086: * Returns the current set of checkpoint messages.
087: *
088: * @return a non-<code>null</code> array of checkpoint messages
089: * @see #addCheckpoint(String)
090: * @deprecated This method will be removed when web mode supports stack
091: * traces. It can be useful for debugging web mode failures, but
092: * production code should not depend on it.
093: */
094: public final String[] getCheckpoints() {
095: // implemented in the translatable version of this class
096: return null;
097: }
098:
099: /**
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 getModuleName();
107:
108: /**
109: * Stashes <code>result</code> so that it can be accessed during
110: * {@link #runTest()}.
111: */
112: @Override
113: public final void run(TestResult result) {
114: testResult = result;
115: super .run(result);
116: }
117:
118: /**
119: * Put the current test in asynchronous mode. If the test method completes
120: * normally, this test will not immediately succeed. Instead, a <i>delay
121: * period</i> begins. During the delay period, the test system will wait for
122: * one of three things to happen:
123: *
124: * <ol>
125: * <li> If {@link #finishTest()} is called before the delay period expires,
126: * the test will succeed.</li>
127: * <li> If any getException escapes from an event handler during the delay
128: * period, the test will error with the thrown getException.</li>
129: * <li> If the delay period expires and neither of the above has happened, the
130: * test will error with a {@link TimeoutException}. </li>
131: * </ol>
132: *
133: * <p>
134: * This method is typically used to test event driven functionality.
135: * </p>
136: *
137: * <p>
138: * <b>Example:</b>
139: * {@example com.google.gwt.examples.AsyncJUnitExample#testTimer()}
140: * </p>
141: *
142: * @param timeoutMillis how long to wait before the current test will time out
143: * @tip Subsequent calls to this method reset the timeout.
144: * @see #finishTest()
145: *
146: * @throws UnsupportedOperationException if this test case is a
147: * {@link Benchmark}
148: */
149: protected final void delayTestFinish(int timeoutMillis) {
150: // implemented in the translatable version of this class
151: }
152:
153: /**
154: * Cause this test to succeed during asynchronous mode. After calling
155: * {@link #delayTestFinish(int)}, call this method during the delay period to
156: * cause this test to succeed. This method is typically called from an event
157: * handler some time after the test method returns control to the caller.
158: *
159: * <p>
160: * Calling this method before the test method completes, will undo the effect
161: * of having called <code>delayTestFinish()</code>. The test will revert to
162: * normal, non-asynchronous mode.
163: * </p>
164: *
165: * <p>
166: * <b>Example:</b>
167: * {@example com.google.gwt.examples.AsyncJUnitExample#testTimer()}
168: * </p>
169: *
170: * @throws IllegalStateException if this test is not in asynchronous mode.
171: * @throws UnsupportedOperationException if this test case is a
172: * {@link Benchmark}
173: *
174: * @see #delayTestFinish(int)
175: */
176: protected final void finishTest() {
177: // implemented in the translatable version of this class
178: }
179:
180: /**
181: * Returns the overall test results for this unit test.
182: *
183: * These TestResults are more comprehensive than JUnit's default test results,
184: * and are automatically collected by GWT's testing infrastructure.
185: */
186: protected final TestResults getTestResults() {
187: // implemented in the translatable version of this class
188: return null;
189: }
190:
191: /**
192: * Runs the test via the {@link JUnitShell} environment.
193: */
194: @Override
195: protected final void runTest() throws Throwable {
196: JUnitShell.runTest(getModuleName(), this, testResult);
197: }
198: }
|