com.purplehillsbooks.testframe

Class TestRecorderText

java.lang.Object

com.purplehillsbooks.testframe.TestRecorderText

All Implemented Interfaces:

TestRecorder

public class TestRecorderText
extends java.lang.Object
implements TestRecorder

TestRecorderText implements the TestRecorder interface so that:

1. (1) Configuration information is read from a text file called 'test.conf'. This file has one name-value pair per line as parameter_name=parameter_value
2. (2) Test results are written to a text file, typically 'FinalLog.log'.

See Also:

TestSet, Author: Keith Swenson

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.Hashtable<java.lang.String,int[]>	records
static java.util.ArrayList<TestResultRecord>	resultSet

Constructor Summary

Constructors

Constructor and Description
TestRecorderText(java.io.Writer forLog, boolean newVerbose, java.lang.String[] args, java.util.Properties configProps)
TestRecorderText(java.io.Writer forLog, boolean newVerbose, java.lang.String[] args, java.lang.String configDir) Deprecated. constructor, use the one below instead
TestRecorderText(java.io.Writer forLog, boolean newVerbose, java.lang.String[] args, java.lang.String configDir, java.util.Properties configProps) The test driver initializes this class and gives it to each test case.

Method Summary

Modifier and Type	Method and Description
static void	clearResultSet()
int	failedCount()
int	fatalCount()
java.lang.String[]	getCommandLineArgs() The command line arguments to the main routine are stored in the TestRecorder.
java.lang.String	getProperty(java.lang.String name, java.lang.String defaultVal) Read a property from the global properties file.
java.util.Properties	getProps() Tests generally should not use this method but rather should use the convenient routines getProperty and getRequiredProperty,
java.lang.String	getRequiredProperty(java.lang.String name) Read a property from the global properties file.
static java.util.ArrayList<TestResultRecord>	getResults()
java.lang.String	getTestDir() getTestDir returns the path to the folder that contains all the test files.
boolean	isVerbose() Returns the value of the 'verbose' configuration parameter.
void	log(java.lang.String s) Writes the specified string to the log file, only when verbose == true.
void	markFailed(java.lang.String id, java.lang.String details) When a simple test fails, for example a simple calculation performed, and the result does not matched the expected result, then this is called to indicate that the test failed.
void	markFatalError(java.lang.Exception e) A "fatal error" is an error that is so bad that subsequent tests were skipped.
void	markPassed(java.lang.String id) When a simple test passes, for example a simple calculation performed, and the result matched the expected result, then this is called to indicate that the test has succeeded.
static void	parseArgsRunTests(java.lang.String[] args, TestSet ts)
int	passedCount()
void	recordResults(java.lang.String testName, int prevPass, int prevFail) This records results of a single test int eh records hashtable.
void	setCommandLineArgs(java.lang.String[] args) The TestDriver may call this method if it needs to add/modify the command line arguments.
void	setProps(java.util.Properties props) setProps should not be used except in extreme situations where particular properties need to be added or modified for a particular test.
void	testInt(java.lang.String id, int value, int expected)

Methods inherited from class java.lang.Object

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

Field Detail

records

public static java.util.Hashtable<java.lang.String,int[]> records

resultSet

public static java.util.ArrayList<TestResultRecord> resultSet

Constructor Detail

TestRecorderText

public TestRecorderText(java.io.Writer forLog,
                        boolean newVerbose,
                        java.lang.String[] args,
                        java.util.Properties configProps)
                 throws java.lang.Exception

Throws:

java.lang.Exception

TestRecorderText

public TestRecorderText(java.io.Writer forLog,
                        boolean newVerbose,
                        java.lang.String[] args,
                        java.lang.String configDir)
                 throws java.lang.Exception

Deprecated. constructor, use the one below instead

Throws:

java.lang.Exception

TestRecorderText

public TestRecorderText(java.io.Writer forLog,
                        boolean newVerbose,
                        java.lang.String[] args,
                        java.lang.String configDir,
                        java.util.Properties configProps)
                 throws java.lang.Exception

The test driver initializes this class and gives it to each test case. For a run of the tests, only one recorder is constructed, so that it can collect the results of all the tests.

A test class should never be creating a TestRecorder, only the TestDriver should do so. This allows the tests themselves to be reusable in any situation. You can write your own test driver which calls all your tests, or you can use the generic TestDriver class that reads what it needs from input files in order to call the tests.

Throws:

java.lang.Exception

Method Detail

getProperty

public java.lang.String getProperty(java.lang.String name,
                                    java.lang.String defaultVal)

Read a property from the global properties file. If property does not exist, then default is returned.

Specified by:

getProperty in interface TestRecorder

getRequiredProperty

public java.lang.String getRequiredProperty(java.lang.String name)
                                     throws java.lang.Exception

Read a property from the global properties file. The specified property MUST exist in the properties file. Throws a nice exception if the property is missing. Use this for properties like "serverName" where there is no way to provide a reaonsable default. If you need a particular configuration value, then if it is not configured, then this is a configuration problem that must be addressed before running the tests. Throwing an exception will cause termination of the testing due to a fatal error, and it will display the reason for the fatal, which will encourage the tester to set the configuration up correctly.

Specified by:

getRequiredProperty in interface TestRecorder

Throws:

java.lang.Exception

markPassed

public void markPassed(java.lang.String id)

When a simple test passes, for example a simple calculation performed, and the result matched the expected result, then this is called to indicate that the test has succeeded.

This will record the fact the that test succeeded and report it in the final results. The id is a simple name or description that can be used to uniquely identify this test. It might consist of the test number in a particular test set.

When verbose=false (normal situations) this will not produce any output to the log. The logic is that normally we will have hundreds of tests, and they all pass so we don't really need to know about those.

When verbose=true, it will record this pass to the log, which allows you to get a listing of all the tests that were run if you wish.

Specified by:

markPassed in interface TestRecorder

markFailed

public void markFailed(java.lang.String id,
                       java.lang.String details)

When a simple test fails, for example a simple calculation performed, and the result does not matched the expected result, then this is called to indicate that the test failed.

A log entry is printed to record the fact with the details regarless of whether verbose==true or verbose==false. The rationale is that you always want to know about failures. Not only is the id and details written out, but also a line that include the parameters that were passed to the test, as well as any log messages that were saved up since the last result message.

Specified by:

markFailed in interface TestRecorder

Parameters:

id - follows the same rules as above (and it goes without saying that the same id should be used when indicating success as when indicating failure for a particular test.)

details - is additional information explaining what was expected and what was wrong about it. For example to explain what was being done, what was unique about this test case, which might give a clue to why the program failed.

testInt

public void testInt(java.lang.String id,
                    int value,
                    int expected)

Specified by:

testInt in interface TestRecorder

markFatalError

public void markFatalError(java.lang.Exception e)

A "fatal error" is an error that is so bad that subsequent tests were skipped. For example, a particular routine is expecting test 5 consistency constraints on the contents of a file, but it finds that the file does not exist. There are two choices: call markFailed 5 times (so that all failures are recorded) or record a single markFatalError to indicate that something is so wrong it is not even worth continuing testing.

Recording a fatal error means tests has been skipped in this run, and the resulting statistics are meaningless. We don't have a complete record of all the tests that might have failed. The presence of a single fatal test should tell you that something is terribly broken in the tests, and the results are not valid.

Normally, a test case will indicate a fatal error by throwing an exception. The Test Framework will catch the exception, and use this method to record that a test failed to the extent that further testing had to be skipped. Throw a meaningful exception instead of calling this routine.

Specified by:

markFatalError in interface TestRecorder

log

public void log(java.lang.String s)

Writes the specified string to the log file, only when verbose == true. This is used typically for debugging, and calls to this should be removed when the test case is ready for prime time.

Do not use the log method to write out whether a test passes or fails! It is remarkable how many time programmers write tests that require a person to read the log a determine whether the test succeeded or not. In normal testing situation, nobody reads the logs! In the case of automated builds, the automated run of a test produces a log, but if no error is indicated using markFailure, then nobody ever looks at the log files. So use it only for debug information while developing the test.

Note: there is a special capability to reduce clutter and still get meaningful results. When the log method is called, and verbose==false the line is not written to output, but is is saved up in a collection. If the next test result is "pass" then those lines are thrown away. But if the next result is "fail" then those saved up log items are output just before the failure message. So if you are outputting information using log statements before reporting the results of a test, those statements will be seen even with verbose==false if the test fails.

Specified by:

log in interface TestRecorder

passedCount

public int passedCount()

failedCount

public int failedCount()

fatalCount

public int fatalCount()

isVerbose

public boolean isVerbose()

Description copied from interface: TestRecorder

Returns the value of the 'verbose' configuration parameter. Tests will ususally not need to call this method.

Specified by:

isVerbose in interface TestRecorder

getProps

public java.util.Properties getProps()

Description copied from interface: TestRecorder

Tests generally should not use this method but rather should use the convenient routines getProperty and getRequiredProperty,

Specified by:

getProps in interface TestRecorder

setProps

public void setProps(java.util.Properties props)

Description copied from interface: TestRecorder

setProps should not be used except in extreme situations where particular properties need to be added or modified for a particular test.

Specified by:

setProps in interface TestRecorder

getCommandLineArgs

public java.lang.String[] getCommandLineArgs()

Description copied from interface: TestRecorder

The command line arguments to the main routine are stored in the TestRecorder. Individual tests can have access to them using this method, and can use them for any purpose necessary. If the command line pointed to a text file with a list of tests, each line of that file contains the name of a class file, along with parameters, and those parameters will appear in the returned string array.

Specified by:

getCommandLineArgs in interface TestRecorder

setCommandLineArgs

public void setCommandLineArgs(java.lang.String[] args)

Description copied from interface: TestRecorder

The TestDriver may call this method if it needs to add/modify the command line arguments. Tests should not call this method.

Specified by:

setCommandLineArgs in interface TestRecorder

getTestDir

public java.lang.String getTestDir()

Description copied from interface: TestRecorder

getTestDir returns the path to the folder that contains all the test files. If a test needs to read such a file, get this path and append the name of the file on to it. You should assume this directory is "read only"

Specified by:

getTestDir in interface TestRecorder

recordResults

public void recordResults(java.lang.String testName,
                          int prevPass,
                          int prevFail)

This records results of a single test int eh records hashtable. But...the test recorder will be keeping a cumulative total of all tests, so pass in the previous values so they can be discounted. This is not the most straightforward way to do this. Perhaps a better way is to have a command to start a new test, which PUSHes a new results structure on a stack, and a command to complete a test which records the result, and add the results of that test to the global results. I have implemented such a mechanism in the past, but it has been deemed overkill. So this simpler approach will work for now, until we need something better.

clearResultSet

public static void clearResultSet()

getResults

public static java.util.ArrayList<TestResultRecord> getResults()

parseArgsRunTests

public static void parseArgsRunTests(java.lang.String[] args,
                                     TestSet ts)