satin.testing
Interface TestLog

All Known Implementing Classes:

TestLogInternal

public interface TestLog

This is the public interface for test log files. If used properly, this interface ensures that the contents of the results file conforms to applicable standards so that it can be read by other programs.

Use logLine to write a single complete line of output. Use log to write part of a line.

Test logs are block-structured; they consist of a number of nested blocks that divide the log file into logical sections such as testcases. Most of these blocks are maintained automatically by other testing classes, but you can explicitly create your own blocks using beginBlock and endBlock.

Report simple errors (that are not exceptions) by calling logError. If you want to include additional information about an error, you can create an error block by calling beginError and endError.

Log files support custom tab stops; tab characters are expanded to spaces that pad to the next tab stop. Tab stops are normally every 4 columns; you can set whatever tab stops you want by calling setTabs.

Long lines are automatically wrapped. You can set the maximum line width by calling setMaxWidth. You can set the line break characters by calling setLineBreakChars.

Author:

Ed Stauff

See Also:

TestScript, Testcase

Method Summary

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	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(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	endWarning(TestLogBlock warningBlock) Ends an warning block that was begun by a call to beginWarning.
void	log(java.lang.String str) Writes a string to the log file, without any implicit line endings.
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	logWarning(java.lang.String str) Writes a warning message to the log file and increments the warning count.
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.

Method Detail

log

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

Writes a string to the log file, without any implicit line endings.

Parameters:

str

the string to be written.

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.

Parameters:

str

the string to be written.

logDateTime

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

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.

Parameters:

d

the date & time.

logDateTime

public void logDateTime()
                 throws java.io.IOException

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

logFile

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

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.

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

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

logError

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

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.

Parameters:

str

the error message to be written.

beginError

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

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.

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

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

Parameters:

errBlock

the log block that was returned by beginError.

logWarning

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

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".

Parameters:

str

the warning message to be written.

beginWarning

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

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.

Parameters:

str

the warning message to be written.

Returns:

the warning block, which must be passed to endWarning.

endWarning

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

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

Parameters:

warningBlock

the log block that was returned by beginWarning.

logException

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

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.

Parameters:

x

the exception to be logged.

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.

Parameters:

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.

Parameters:

block

the block to be ended (the current block).

restoreBlock

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

Restores the block context. Throws an assertion if the given block is not found on the block nesting stack. Use this method if you catch and handle an exception to restore the correct block context. For example:

 TestLogBlock blk = log.beginBlock("some stuff");

 try
 {
     // ... do some stuff ...
 }
 catch (whatever)
 {
     log.restoreBlock(blk);
     // ... handle the exception ...
 }

 log.endBlock(blk); 

If an exception is thrown inside the try block after some other log block is begun (nested within the "some block" block), but before that other log block has been ended, then without the call to restoreBlock, the final call to endBlock will fail an assertion because the block it is trying to end is not the current block.

Parameters:

block

the block to be restored.

setTabs

public void setTabs(int[] tabs)

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.

Parameters:

tabs

the tab stops.

setTabs

public void setTabs(int count,
                    int spacing)

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.

Parameters:

count

the number of tab stops to set.

spacing

the spacing between tab stops, in characters.

setMaxWidth

public int setMaxWidth(int chars)

Sets the maximum physical line width in characters. Lines longer than this will be wrapped. If your script nests blocks very deeply, beware of setting the line width too small, since block nesting may be represented by indentation. If block indentation exceeds the maximum width, an assertion will fail.

Returns:

the previous line width.

setLineBreakChars

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

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.

Parameters:

before

characters to break before.

after

characters to break after.

Revision History

7/31/01 Ed Stauff - code review.

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

4/6/01 Ed Stauff - made changes per API review.

3/22/01 Ed Stauff - initial API review by Satin team.