satin.testing
Class Test

java.lang.Object
  |
  +--satin.testing.Test

Direct Known Subclasses:

TestComponent, TestProgram

public abstract class Test
extends java.lang.Object

This is an abstract base class for all tests, including Testcase, TestScript, TestGroup and TestSuite. The fundamental architecture for using a Test object is:

1. Instantiate a Test object, passing it any parameters it may need.
2. Run the Test object at most once by calling the run method (which takes no arguments).

Each test object can be run at most once. If you want to re-run a test, you must instantiate a new one. The fundamental architecture for implementing a test consists of five phases:

1. Construction - the (overridden) constructor takes any parameters that are needed by the test. (TestScript is an exception; it gets it parameters from a parameter file.)
2. Setup - performs any setup that might be needed before actually performing the test.
3. Execute - performs the test.
4. Verify - verified the results of the test.
5. Cleanup - performs any cleanup that might be needed after performing the test.

The run method calls setup, execute verify and cleanup in turn. Separating a test into these phases helps improve error reporting: if a test fails during setup, it means that the actual test itself was never performed; if a test fails during execute or verify, it gives a clearer indication that the feature under test does not work. The Test class takes care of catching all exceptions and logging them to a TestLog.

In practice, most actual test classes will derive from Testcase, TestScript or TestGroup.

Author:

Ed Stauff

Field Summary

protected java.lang.Exception

lastException The most recent exception that was caught by doSetup, doExecute, doVerify, or doCleanup.

Constructor Summary

protected

Test() The constructor.

Method Summary

protected void	cleanup() Override this method to perform test-specific cleanup.
protected boolean	doCleanup() Performs the cleanup phase, catching and reporting any exceptions.
protected boolean	doExecute() Performs the execution phase, catching and reporting any exceptions.
protected boolean	doSetup() Performs the setup phase, catching and reporting any exceptions.
protected boolean	doVerify() Performs the verification phase, catching and reporting any exceptions.
protected abstract void	execute() Override this method to perform the test.
abstract TestLog	getLog() Returns the log file.
final boolean	run() Runs the test.
protected void	setup() Override this method to perform test-specific setup.
protected void	verify() Override this method to verify the results of the test.

Methods inherited from class java.lang.Object

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

Field Detail

lastException

protected java.lang.Exception lastException

The most recent exception that was caught by doSetup, doExecute, doVerify, or doCleanup.

Constructor Detail

Test

protected Test()

The constructor.

Method Detail

run

public final boolean run()
                  throws java.lang.Exception

Runs the test. The setup method is called first. If setup runs without throwing an exception, then the execute method is called. If execute runs without throwing an exception, then the verify method is called. The cleanup method is called last, regardless of whether setup, execute or verify threw an exception. All Exceptions are logged to the test log returned by getLog. Errors, however, are neither caught nor logged, as they indicate programming errors.

Each test object can be run at most once. If you try to run a test more than once, an assertion will fail. If you need to run a test more than once, you must instantiate it once for each run.

You should normally not override this method.

Returns:

true if the test was completely successful, false otherwise.

doSetup

protected boolean doSetup()
                   throws java.io.IOException

Performs the setup phase, catching and reporting any exceptions. Do not override this method; override setup instead. Do not call this method from any method except run.

Returns:

false if setup threw an exception; true otherwise.

doExecute

protected boolean doExecute()
                     throws java.io.IOException

Performs the execution phase, catching and reporting any exceptions. Do not override this method; override execute instead. Do not call this method from any method except run.

Returns:

false if execute threw an exception; true otherwise.

doVerify

protected boolean doVerify()
                    throws java.io.IOException

Performs the verification phase, catching and reporting any exceptions. Do not override this method; override verify instead. Do not call this method from any method except run.

Returns:

false if execute threw an exception; true otherwise.

doCleanup

protected boolean doCleanup()
                     throws java.io.IOException

Performs the cleanup phase, catching and reporting any exceptions. Do not override this method; override cleanup instead. Do not call this method from any method except run.

Returns:

false if cleanup threw an exception; true otherwise.

setup

protected void setup()
              throws java.lang.Exception

Override this method to perform test-specific setup. Any exceptions thrown by this method will be caught and logged, and will prevent the execute method from being called. You can perform the setup for your test in your execute method instead, but putting it here can provide clearer error reporting.

execute

protected abstract void execute()
                         throws java.lang.Exception

Override this method to perform the test. Any exceptions thrown by this method will be caught and logged.

verify

protected void verify()
               throws java.lang.Exception

Override this method to verify the results of the test. It is called only if execute ran without throwing an exception. Any exceptions thrown by this method will be caught and logged. You can perform the verification for your test in your execute method instead, but putting it here can provide clearer error reporting.

cleanup

protected void cleanup()
                throws java.lang.Exception

Override this method to perform test-specific cleanup. It is called regardless of whether setup, execute or verify threw an exception. Any exceptions thrown by this method will be caught and logged.

getLog

public abstract TestLog getLog()

Returns the log file. This method must never return null.

Revision History

7/31/01 Ed Stauff - code review.

6/27/01 Ed Stauff - added lastException field.

5/31/01 Ed Stauff - made run final.

5/15/01 Ed Stauff - changes per 2nd API review.

3/27/01 Ed Stauff - made changes per API review.

3/22/01 - reviewed by Test Automation team.