satin.testing
Class TestLogInternal

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

All Implemented Interfaces:

TestLog

public final class TestLogInternal
extends java.lang.Object
implements TestLog

This is the internal class for a test results log file. It it intended for use only by other classes in the satin.testing package, in particular Test, TestScript, TestGroup and Testcase. Writers of specific tests (test scripts and testcases) should use only the TestLog interface.

Every test log created by the TestScript class is an object of class TestLogInternal, and is cached as such by the TestScript and Testcase objects so that it can access all of the TestLogInternal methods. The script writer only sees the TestLog interface.

File Format

Indentation is used to represent block nesting, one tab character per nesting level. Tabs are not permitted except at the beginnings of lines.
When long lines are wrapped, the continuation lines are indented with three perods, following the tabs.

Author:

Ed Stauff

See Also:

TestScript, Testcase

Inner Class Summary

class

TestLogInternal.PatchPoint Defines a spot for back-patching.

Field Summary

boolean	autoFlush When true, output is flushed to disk after each write operation.
protected TestLogBlock	currentBlock The current log block.
boolean	echoToConsole When true, output is echoed to the console (System.out).
protected TestLogBlock	outermostBlock The outermost log block that encloses the entire test log.

Constructor Summary

TestLogInternal(java.lang.String fileName)
Creates a new test log file.

TestLogInternal(java.lang.String fileName, boolean append)
Creates a new test log file.

Method Summary

TestLogBlock	beginBlock(int type, java.lang.String title) Begins a new nested block in the log file.
TestLogBlock	beginBlock(java.lang.String title) Begins a new nested block in the log file.
TestLogBlock	beginError(java.lang.String str) Writes an error message to the log file, increments the error count, and opens a block that will contain additional error information.
TestLogBlock	beginTestcase(java.lang.String description, RestrictorList testPoint) Begins a testcase block.
TestLogBlock	beginTestGroup(java.lang.String description) Begins a test group block.
TestLogBlock	beginWarning(java.lang.String str) Writes a warning message to the log file, increments the warning count, and opens a block that will contain additional warning information.
void	debug(java.lang.String str) Logs a debugging statement as a separate line, prefixed with "# ".
void	endBlock() Ends the current block.
void	endBlock(TestLogBlock block) Ends the current block, which must be given.
void	endError(TestLogBlock errBlock) Ends an error block that was begun by a call to beginError.
void	endTestcase(TestLogBlock blk, TestStatus status) Ends a testcase block.
void	endTestGroup(TestLogBlock blk) Ends a test group block.
void	endWarning(TestLogBlock errBlock) Ends an warning block that was begun by a call to beginWarning.
java.io.Writer	getAROlog(java.lang.String serverDesc) Returns a stream to be used by an AROremoteServer object for logging ARO events in this test log.
TestLogBlock	getBlock() Returns the current block.
java.lang.String	getPath() Returns the full path of the log file.
java.io.Writer	getUIlog(java.lang.String appDesc) Returns a stream to be used for logging UI activity in this test log.
void	log(java.lang.String str) Writes a string to the log file.
void	logDateTime() Writes the current date & time to the log file in a standard format.
void	logDateTime(java.util.Date d) Writes a date & time to the log file in the following standard format:
void	logError(java.lang.String str) Writes an error message to the log file and increments the error count.
void	logException(java.lang.Throwable x) Writes an exception message to the log file and increments the error count.
void	logFile(java.lang.String name, java.lang.String descr) Writes the name of an associated file.
void	logLine(java.lang.String str) Writes a string to the log file as a separate line.
void	logStackTrace(java.lang.Throwable x) Logs the stack trace for the given exception.
void	logSummary() Writes summary information about the current block.
void	logSummary(java.lang.String descr) Writes summary information about the current block.
void	logTestcaseSummary() Writes testcase summary information about the current block.
void	logWarning(java.lang.String str) Writes a warning message to the log file and increments the warning count.
void	patch(TestLogInternal.PatchPoint pp, java.lang.String newString) Patches a previously written portion of the file.
TestLogInternal.PatchPoint	preparePatch(java.lang.String placeHolder) Prepares a spot for back-patching.
void	restoreBlock(TestLogBlock block) Restores the block context.
void	setLineBreakChars(java.lang.String before, java.lang.String after) Sets line break characters for wrapping long lines for the current block.
int	setMaxWidth(int chars) Sets the maximum physical line width in characters.
void	setTabs(int[] tabs) Sets tab stops for the current block.
void	setTabs(int count, int spacing) Sets equal tab stops for the current block.
protected void	startLine() Outputs a newline if we're not already at the beginning of a line.

Methods inherited from class java.lang.Object

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

Field Detail

echoToConsole

public boolean echoToConsole

When true, output is echoed to the console (System.out).

autoFlush

public boolean autoFlush

When true, output is flushed to disk after each write operation. This is false by default; you should normally leave it false to increase test execution speed. Set it to true only if your script is crashing and you need to figure out exactly where. This variable is set by the -autoflush command line parameter defined by the TestProgram class.

currentBlock

protected TestLogBlock currentBlock

The current log block.

outermostBlock

protected TestLogBlock outermostBlock

The outermost log block that encloses the entire test log.

Constructor Detail

TestLogInternal

public TestLogInternal(java.lang.String fileName)
                throws java.io.IOException

Creates a new test log file. The file is replaced if it already exists.

Parameters:

fileName

the name of the log file.

TestLogInternal

public TestLogInternal(java.lang.String fileName,
                       boolean append)
                throws java.io.IOException

Creates a new test log file.

Parameters:

fileName

the name of the log file.

append

what to do if the file already exists: true = append, false = replace. If the file does not exist, it is created.

Method Detail

log

public void log(java.lang.String str)
         throws java.io.IOException

Writes a string to the log file. Each carriage return, linefeed, or adjacent pair of carriage return plus linefeed, is translated to a standard end-of-line marker, to ensure that line endings are always treated consistently. Tabs are expanded to spaces so that tab characters are reserved for initial indentation. All log output goes through this method.

Specified by:

log in interface TestLog

Parameters:

str

the string to be written.

startLine

protected void startLine()
                  throws java.io.IOException

Outputs a newline if we're not already at the beginning of a line.

logLine

public void logLine(java.lang.String str)
             throws java.io.IOException

Writes a string to the log file as a separate line. A leading end-of-line character is written if necessary, and a final end-of-line character is written always.

Specified by:

logLine in interface TestLog

Parameters:

str

the string to be written.

logDateTime

public void logDateTime(java.util.Date d)
                 throws java.io.IOException

Description copied from interface: TestLog

Writes a date & time to the log file in the following standard format:

YYYY-MM-DD HH:MM:SS

Always use this method to write dates & times, so that they can be read from the log by post-processing programs.

Specified by:

logDateTime in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

d

the date & time.

logDateTime

public void logDateTime()
                 throws java.io.IOException

Description copied from interface: TestLog

Writes the current date & time to the log file in a standard format.

Specified by:

logDateTime in interface TestLog

logFile

public void logFile(java.lang.String name,
                    java.lang.String descr)
             throws java.io.IOException

Description copied from interface: TestLog

Writes the name of an associated file. Use this method to log the names of any auxiliary results or data file that are associated with your test. The name of the file will be placed in the log (not the contents of the file). If the file does not exist, an exception will be thrown.

Specified by:

logFile in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

name

the name of the file. If necessary, it will be expanded to a fully qualified path name before writing it to the log.

descr

a brief description of the file.

debug

public void debug(java.lang.String str)
           throws java.io.IOException

Description copied from interface: TestLog

Logs a debugging statement as a separate line, prefixed with "# ".

Specified by:

debug in interface TestLog

preparePatch

public TestLogInternal.PatchPoint preparePatch(java.lang.String placeHolder)
                                        throws java.io.IOException

Prepares a spot for back-patching. Use with patch to alter parts of the log after they have been written, such as summary info. Do not use tabs or newlines in the place holder string.

Parameters:

placeHolder

the string to write to the file initially (now).

Returns:

a PatchPoint for use with patch.

patch

public void patch(TestLogInternal.PatchPoint pp,
                  java.lang.String newString)
           throws java.io.IOException

Patches a previously written portion of the file. Use with preparePatch to alter parts of the log after they have been written, such as summary info. Do not use tabs or newlines in the new string. Do not write more characters than there were in the place holder.

Parameters:

pp

the PatchPoint obtained from preparePatch.

newString

the new string to write.

logError

public void logError(java.lang.String str)
              throws java.io.IOException

Description copied from interface: TestLog

Writes an error message to the log file and increments the error count. The error message is preceded by a standard prefix by which all errors are identified. Therefore, do not begin the string with asterisks or a word like "error". If you need to associate additional information with the error, use beginError and endError instead of logError.

Specified by:

logError in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

str

the error message to be written.

beginError

public TestLogBlock beginError(java.lang.String str)
                        throws java.io.IOException

Description copied from interface: TestLog

Writes an error message to the log file, increments the error count, and opens a block that will contain additional error information. The error message is preceded by a standard prefix by which all errors are identified. Therefore, do not begin the string with asterisks or a word like "error". You must complete the error block by calling endError. If you have no additional data to associate with this error, use logError instead.

Specified by:

beginError in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

str

the error message to be written.

Returns:

the error block, which must be passed to endError.

endError

public void endError(TestLogBlock errBlock)
              throws java.io.IOException

Description copied from interface: TestLog

Ends an error block that was begun by a call to beginError.

Specified by:

endError in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

errBlock

the log block that was returned by beginError.

logWarning

public void logWarning(java.lang.String str)
                throws java.io.IOException

Description copied from interface: TestLog

Writes a warning message to the log file and increments the warning count. The warning message is preceded by a standard prefix by which all warnings are identified. Therefore, do not begin the string with asterisks or a word like "warning".

Specified by:

logWarning in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

str

the warning message to be written.

beginWarning

public TestLogBlock beginWarning(java.lang.String str)
                          throws java.io.IOException

Description copied from interface: TestLog

Writes a warning message to the log file, increments the warning count, and opens a block that will contain additional warning information. The warning message is preceded by a standard prefix by which all warnings are identified. Therefore, do not begin the string with asterisks or a word like "warning". You must complete the warning block by calling endWarning. If you have no additional data to associate with this warning, use logWarning instead.

Specified by:

beginWarning in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

str

the warning message to be written.

Returns:

the warning block, which must be passed to endWarning.

endWarning

public void endWarning(TestLogBlock errBlock)
                throws java.io.IOException

Description copied from interface: TestLog

Ends an warning block that was begun by a call to beginWarning.

Specified by:

endWarning in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

warningBlock

the log block that was returned by beginWarning.

logException

public void logException(java.lang.Throwable x)
                  throws java.io.IOException

Description copied from interface: TestLog

Writes an exception message to the log file and increments the error count. The exception message is preceded by a standard prefix by which all exceptions are identified. Therefore, do not begin the string with asterisks or a word like "exception". A stack trace is included in the output.

Scripts should normally not need to log exceptions; exceptions should normally be left for the testing infrastructure to catch and report.

Specified by:

logException in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

x

the exception to be logged.

logStackTrace

public void logStackTrace(java.lang.Throwable x)
                   throws java.io.IOException

Logs the stack trace for the given exception.

beginBlock

public TestLogBlock beginBlock(java.lang.String title)
                        throws java.io.IOException

Begins a new nested block in the log file. Use blocks to group logically related sections of the log. Blocks can be nested; you must explicitly end a block with a call to endBlock.

Specified by:

beginBlock in interface TestLog

Parameters:

the

title of the new block.

Returns:

the new block.

beginBlock

public TestLogBlock beginBlock(int type,
                               java.lang.String title)
                        throws java.io.IOException

Begins a new nested block in the log file. Use blocks to group logically related sections of the log. Blocks can be nested; you must explicitly end a block with a call to endBlock.

Parameters:

the

type of the new block.

the

title of the new block.

Returns:

the new block.

endBlock

public void endBlock(TestLogBlock block)
              throws java.io.IOException

Ends the current block, which must be given. The given block must match the current block, or an assertion is thrown.

Specified by:

endBlock in interface TestLog

Parameters:

block

the block to be ended (the current block).

endBlock

public void endBlock()
              throws java.io.IOException

Ends the current block.

restoreBlock

public void restoreBlock(TestLogBlock block)

Restores the block context. Throws an assertion if the given block is not found on the block nesting stack.

Specified by:

restoreBlock in interface TestLog

Parameters:

block

the block to be restored.

getBlock

public TestLogBlock getBlock()

Returns the current block.

beginTestcase

public TestLogBlock beginTestcase(java.lang.String description,
                                  RestrictorList testPoint)
                           throws java.io.IOException

Begins a testcase block. This method is intended for use only by the Testcase class.

endTestcase

public void endTestcase(TestLogBlock blk,
                        TestStatus status)
                 throws java.io.IOException

Ends a testcase block. This method is intended for use only by the Testcase class.

beginTestGroup

public TestLogBlock beginTestGroup(java.lang.String description)
                            throws java.io.IOException

Begins a test group block. This method is intended for use only by the TestGroup class.

endTestGroup

public void endTestGroup(TestLogBlock blk)
                  throws java.io.IOException

Ends a test group block. This method is intended for use only by the TestGroup class.

logSummary

public void logSummary(java.lang.String descr)
                throws java.io.IOException

Writes summary information about the current block. The information includes error count, warning count, and elapsed time.

Parameters:

descr

a description of the summary.

logTestcaseSummary

public void logTestcaseSummary()
                        throws java.io.IOException

Writes testcase summary information about the current block. The information includes testcase counts for each test status.

logSummary

public void logSummary()
                throws java.io.IOException

Writes summary information about the current block. The information includes error count, warning count, and elapsed time.

getPath

public java.lang.String getPath()
                         throws java.io.IOException

Returns the full path of the log file.

setMaxWidth

public int setMaxWidth(int chars)

Sets the maximum physical line width in characters. Lines longer than this will be wrapped.

Specified by:

setMaxWidth in interface TestLog

Following copied from interface: satin.testing.TestLog

Returns:

the previous line width.

setLineBreakChars

public void setLineBreakChars(java.lang.String before,
                              java.lang.String after)

Description copied from interface: TestLog

Sets line break characters for wrapping long lines for the current block. If the block does not have line break characters explicitly set, it inherits them from its parent block.

Specified by:

setLineBreakChars in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

before

characters to break before.

after

characters to break after.

setTabs

public void setTabs(int[] tabs)

Description copied from interface: TestLog

Sets tab stops for the current block. Each tab stop is measured in characters from the left margin of the block; that is, after any indentation. Each tab stop must be greater than the preceding one, or an assertion is thrown. This method discards any previously set tabs stops for this block. If a block does not have tab stops explicitly set, it inherits its tab stops from its parent block.

Specified by:

setTabs in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

tabs

the tab stops.

setTabs

public void setTabs(int count,
                    int spacing)

Description copied from interface: TestLog

Sets equal tab stops for the current block. This method discards any previously set tabs stops for the block. If a block does not have tab stops explicitly set, it inherits its tab stops from its parent block.

Specified by:

setTabs in interface TestLog

Following copied from interface: satin.testing.TestLog

Parameters:

count

the number of tab stops to set.

spacing

the spacing between tab stops, in characters.

getAROlog

public java.io.Writer getAROlog(java.lang.String serverDesc)

Returns a stream to be used by an AROremoteServer object for logging ARO events in this test log. Assign the return value of this method to the aroLog field of the AROremoteServer.

Parameters:

serverDesc

description of the server; will be included in each ARO log line (so keep it short).

getUIlog

public java.io.Writer getUIlog(java.lang.String appDesc)

Returns a stream to be used for logging UI activity in this test log. Assign the return value of this method to the aroLog field of an AROremoteServer object.

Parameters:

appDesc

description of the application; will be included in each log line (so keep it short).

Revision History

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

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

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

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

3/16/01 Ed Stauff - replaced SimpleOutputStream with Writer.

3/13/01 Ed Stauff - doc published for initial review.