satin.testing
Class Testcase

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

public abstract class Testcase
extends TestComponent

This is an abstract base class for testcases. It supports separation of the test into setup, execution and cleanup phases to make error reporting more accurate. It catches all exceptions and logs them to a TestLog, along with a summary of the testcase.

A derived class must override the execute method, in which the test is performed. The setup and cleanup methods may also be overridden as appropriate.

Each testcase object is intended to be executed at most once. If you need to execute the same test multiple times, then instantiate it once for each execution. If many tests are required that differ only in their data, use one derived class that accepts the data in the constructor, and instantiate it once for each test.

Do not run a testcase from within another testcase. Testcases are intended to represent the smallest useful unit of testing.

Example

This is a rather pointless example that tests the toUpperCase method of the String class.

 class TestToUpper extends Testcase
 {
     String value;
     String expectedResult;
     String actualResult;
 
     public TestToUpper (TestLog log, String value, String expectedResult)
     {
         super(log, "tcToUpper \"" + value + "\"");
         this.value = value;
         this.expectedResult = expectedResult;
     }
 
     protected void execute ()
     {
         this.actualResult = this.value.toUpperCase();
     }
 
     protected void verify ()
     {
         verify(this.expectedResult, this.actualResult);
     }
 }

Author:

Ed Stauff

Field Summary

final java.lang.String	identifier The identification string that was passed to the constructor, or null.
final TestLog	log The log for this test.
protected boolean	needsManualVerification Must the results be manually verified? If your testcase ever sets this to true, you must override logManualVerification.
final RestrictorList	testPoint The restrictor list that was passed to the constructor, or null.

Fields inherited from class satin.testing.Test

lastException

Constructor Summary

Testcase(TestLog log, RestrictorList testPoint)
The preferred constructor.

Testcase(TestLog log, java.lang.String identifier)
An alternate constructor.

Method Summary

protected final boolean	doCleanup() Performs the cleanup phase, catching and reporting any exceptions.
protected final boolean	doExecute() Performs the execute phase, catching and reporting any exceptions.
protected final boolean	doSetup() Performs the setup phase, catching and reporting any exceptions.
protected final boolean	doVerify() Performs the verify phase, catching and reporting any exceptions.
final TestLog	getLog() Returns the log file.
protected void	logManualVerification() Logs instructions on how to manual verify the results of this testcase.
final TestStatus	status() Returns the status of the test.
final void	verify(boolean condition, java.lang.String whatWentWrong) Throws a TestFailure if condition is false.
final void	verify(char expected, char actual) Throws a TestFailure if the two chars are not equal.
final void	verify(double expected, double actual, double tolerance) Throws a TestFailure if the expected differs from actual by more than tolerance.
final void	verify(double expected, double actual, double tolerance, java.lang.String detail) Throws a TestFailure if the expected differs from actual by more than tolerance.
final void	verify(long expected, long actual) Throws a TestFailure if actual != expected.
final void	verify(long expected, long actual, java.lang.String detail) Throws a TestFailure if actual != expected.
final void	verify(java.lang.Object expected, java.lang.Object actual) Throws a TestFailure if actual != expected.
final void	verify(java.lang.Object expected, java.lang.Object actual, java.lang.String detail) Throws a TestFailure if actual != expected.
final void	verify(java.lang.String expected, java.lang.String actual) Throws a TestFailure if the two strings are not equal.
final void	verify(java.lang.String expected, java.lang.String actual, java.lang.String detail) Throws a TestFailure if the two strings are not equal.

Methods inherited from class satin.testing.Test

cleanup, execute, run, setup, verify

Methods inherited from class java.lang.Object

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

Field Detail

log

public final TestLog log

The log for this test. All test output should be directed to this log. You can use this field or the getLog method interchangeably.

identifier

public final java.lang.String identifier

The identification string that was passed to the constructor, or null.

testPoint

public final RestrictorList testPoint

The restrictor list that was passed to the constructor, or null.

needsManualVerification

protected boolean needsManualVerification

Must the results be manually verified? If your testcase ever sets this to true, you must override logManualVerification.

Constructor Detail

Testcase

public Testcase(TestLog log,
                RestrictorList testPoint)

The preferred constructor. All parameters and data required by a test should be passed into the (overridden) constructor.

Parameters:

testPoint

the complete restrictor list that identifies this testcase.

Testcase

public Testcase(TestLog log,
                java.lang.String identifier)

An alternate constructor. Use this constructor only if you cannot identify your testcase with a RestrictorList. Production testcases may not use this constructor.

All parameters and data required by a test should be passed into the (overridden) constructor.

Parameters:

identifier

a string that should uniquely identify the testcase within the log file.

Method Detail

status

public final TestStatus status()

Returns the status of the test.

doSetup

protected final 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.

Overrides:

doSetup in class Test

Returns:

false if setup threw an exception; true otherwise.

doExecute

protected final boolean doExecute()
                           throws java.io.IOException

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

Overrides:

doExecute in class Test

Returns:

false if execute threw an exception; true otherwise.

doVerify

protected final boolean doVerify()
                          throws java.io.IOException

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

Overrides:

doVerify in class Test

Returns:

false if verify threw an exception; true otherwise.

doCleanup

protected final 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.

Overrides:

doCleanup in class Test

Returns:

false if cleanup threw an exception; true otherwise.

logManualVerification

protected void logManualVerification()
                              throws java.io.IOException

Logs instructions on how to manual verify the results of this testcase. If your testcase ever sets needsManualVerification to true, then you must override this method. It should write to the log file a complete but concise description of how to verify the results of the testcase, including where to find the results. Do not begin your instructions with a phrase like "Verification Instructions"; the logging infrastructure will provide a standard title.

getLog

public final TestLog getLog()

Returns the log file. Must not return null. All test output should be directed to this log. You can use this method or the log field interchangeably; this method is provided for use in the base Test class, which does not have access to a log field.

Overrides:

getLog in class Test

verify

public final void verify(boolean condition,
                         java.lang.String whatWentWrong)
                  throws TestFailure

Throws a TestFailure if condition is false.

Parameters:

condition

the condition to test.

whatWentWrong

descriptive information.

verify

public final void verify(java.lang.Object expected,
                         java.lang.Object actual,
                         java.lang.String detail)
                  throws TestFailure

Throws a TestFailure if actual != expected. Compares actual and expected using both the equals operator "==" and the equals method. If both comparisons fail, a TestFailure is thrown.

Parameters:

actual

the object actually encountered during the test.

expected

the object that was expected during the test.

detail

any additional descriptive information.

verify

public final void verify(java.lang.Object expected,
                         java.lang.Object actual)
                  throws TestFailure

Throws a TestFailure if actual != expected. Compares actual and expected using the equals method. If it returns false, a TestFailure is thrown.

Parameters:

actual

the object actually encountered during the test.

expected

the object that was expected during the test.

verify

public final void verify(long expected,
                         long actual,
                         java.lang.String detail)
                  throws TestFailure

Throws a TestFailure if actual != expected.

Parameters:

actual

the value actually encountered during the test.

expected

the value that was expected during the test.

detail

any additional descriptive information.

verify

public final void verify(long expected,
                         long actual)
                  throws TestFailure

Throws a TestFailure if actual != expected.

Parameters:

actual

the value actually encountered during the test.

expected

the value that was expected during the test.

verify

public final void verify(double expected,
                         double actual,
                         double tolerance,
                         java.lang.String detail)
                  throws TestFailure

Throws a TestFailure if the expected differs from actual by more than tolerance. More specifically, the exception is thrown if the absolute value of the difference between actual and expected is greater than expected times tolerance.

Parameters:

actual

the value actually encountered during the test.

expected

the value that was expected during the test.

tolerance

how close the values must be, as a factor (not an absolute difference). Must be >= 0.

detail

any additional descriptive information.

verify

public final void verify(double expected,
                         double actual,
                         double tolerance)
                  throws TestFailure

Throws a TestFailure if the expected differs from actual by more than tolerance. More specifically, the exception is thrown if the absolute value of the difference between actual and expected is greater than expected times tolerance.

Parameters:

actual

the value actually encountered during the test.

expected

the value that was expected during the test.

tolerance

how close the values must be, as a factor (not an absolute difference). Must be >= 0.

verify

public final void verify(char expected,
                         char actual)
                  throws TestFailure

Throws a TestFailure if the two chars are not equal.

Parameters:

actual

the char actually encountered during the test.

expected

the char that was expected during the test.

verify

public final void verify(java.lang.String expected,
                         java.lang.String actual,
                         java.lang.String detail)
                  throws TestFailure

Throws a TestFailure if the two strings are not equal.

Parameters:

actual

the string actually encountered during the test.

expected

the string that was expected during the test.

detail

any additional descriptive information.

verify

public final void verify(java.lang.String expected,
                         java.lang.String actual)
                  throws TestFailure

Throws a TestFailure if the two strings are not equal.

Parameters:

actual

the string actually encountered during the test.

expected

the string that was expected during the test.

Revision History

7/31/01 Ed Stauff - made changes per code review.

6/26/01 Ed Stauff - added more verify methods.

5/31/01 Ed Stauff - removed overridden run method.

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

4/10/01 - added TestComponent class.

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

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