DDDR/2 - Display Test Tool

The Display Test Tool (DTT) is a Presentation Manager application that enables the user to select and display one or more display tests. A script interface permits DTT to automatically run predefined test scripts.

Overview
The DTT provides a mechanism for testing video device drivers by exercising them through graphics engine (GRE) API calls. As each test is run, the DTT monitors the return codes from the GRE calls and writes the results in a log file. The current log file can be displayed at any time during manual testing.

DTT Architecture
The DTT is comprised of two major components:
 * A Presentation Manager master program (DTT.EXE) that provides the user interface for test selection and execution
 * Test-case dynamic-link libraries (DLLs) that contain the actual test-case executable code

DTT Master Program
DTT.EXE enables the user to do the following:
 * Select one or more tests from the available test cases
 * Execute the selected test cases on demand
 * Specify a test-case Presentation Manager environment (PS units, PS types, and so forth)
 * Display the DTT test log
 * Set the DTT test-logging level
 * Display the DTT release level
 * Exit DTT

Command-line options enable the user to specify the following:
 * Output log file name
 * Input script file name
 * Level of logging to capture
 * Output test case index file name
 * Input test case index file names
 * Option to search LIBPATH for DLLs
 * Search patterns for DLLs to be preloaded

Test-Case DLLs
Each test-case DLL contains tests for a family of GRE calls. See GRE Function Tests (By Function Name) and GRE Function Tests (By Test-Case Name) for descriptions of the supplied test-case DLLs and GRE functions called.

Operating DTT
DTT can be started from the command line in either an OS/2 window or a full -screen session. DTT also can be started from the OS/2 desktop or any other folder by using the DTT icon. When using the icon, command-line options are specified in the Optional Parameters field of the Settings menu for the icon.

Specifying Command Options
All command-line options are specified with either a hyphen (-) or a slash (/) prefix, followed by an alphabetic character (not case-sensitive), followed immediately by the option value, if any, with no intervening spaces. The hyphen and slash can be used interchangeably. Following are examples of DTT command lines: Load all DLLs in the current directory and set the logging level:

DTT -T*..DLL -L8

Preload the GRELINE DLL; also load a test-case index. Search LIBPATH to locate the DLLs.

DTT /tgreline.dll -ntestindx.ndx -s See DTT Command-Line Options Summary for a summary of DTT command-line options. Executing DTT with the -? command-line option displays a list of the valid command-line options.

Locating, Preloading, and Loading Test-Case DLLs
DTT uses the following sequence to locate test-case DLLs:
 * 1.DLLs specified using the -T command-line option are preloaded during DTT startup. Preloaded DLLs remain resident for the duration of the DTT session.
 * The -T command-line option specifies a search pattern for locating the test -case DLLs to be preloaded. The -T option value can contain global file- name characters (wildcards) in the file name. If the -S option also is specified on the command line, test-case DLL names are located using the same search pattern, but the DLLs found are loaded by searching LIBPATH. Following are examples of how to preload DLLs:

Preload GREBTMP.DLL from LIBPATH.

DTT /tgrebtmp.dll /s

On the currrent drive, preload all DLLs in the DTT\DLL directory.

DTT -T\DTT\DLL\*.DLL
 * The -T command-line option can be specified multiple times.
 * 2.Test-case index files specified using the -N command-line option are loaded. (See for information on creating test-case index files.)
 * A DLL containing a specific test case is loaded only when that test case is executed; the DLL remains resident only until a test case resident in another DLL is executed. If the -S option also is specified on the command line, DTT uses LIBPATH to locate the test-case DLLs specified in a test- case index file. Following are examples of how to load test-case index files:

Load the testndx1.ndx and testndx2.ndx test case index files.

DTT /NE:\DTT\INDEX\testndx1.ndx -nC:\COMMON\testndx2.ndx

Load the testindx.ndx from the current directory.
 * The -N command-line option can be specified multiple times.
 * 3.At this point, if no test cases have been identified to DTT, DTT attempts to load a test-case index file named TESTINDX.NDX from the current directory.
 * 4.Then, if test cases still have not been identified to DTT, DTT attempts to preload any test-case DLLs it locates, using an "*.DLL" search pattern. The search pattern searches the current directory, if the -S command-line option is not specified, or LIBPATH, if the -S option is specified.
 * 5.If DTT fails to locate any test cases, a message to that effect is issued.

The -S command-line option orders DTT to search LIBPATH when attempting to load a test-case DLL. If the -S option is not specified, DTT searches only the specified path (or current directory if no path is specified) to locate test-case DLLs.

The -S command-line option is most useful when using a test-case index file, as shown in the following example:

DTT -Ntestindx.ndx -S

The names of all test cases must be made known to DTT during startup. This can be accomplished in the following ways:
 * Loading test-case index files
 * Preloading test-case DLLs

Loading Test-Case Index Files
A test-case index file associates each test-case name with the DLL that contains it. When a duplicate test case is encountered while loading a test -case index file, only the first instance of a test case is retained. Each test-case DLL passes a list of the test cases it contains to DTT when DTT initializes the DLL.

Creating a Test-Case Index File
A test-case index file enables DTT to start up without having to preload all of the test-case DLLs. To create a test-case index file, use the -K command-line option. When the -K command-line option is specified, DTT starts up normally, loading the specified test-case DLLs and index files. Once startup is complete, DTT writes a test-case index file, for all the loaded test cases, to the file specified in the -K command-line option, then terminates.

If the -S command-line option is specified along with the -K option, the new test-case index file always causes DTT to search LIBPATH when loading the DLLs for the test cases in the index. If the -S command-line option is not used with the -K option, the test-case index file contains the full path to each of the DLLs. A new test-case index file has to be created if the test-case DLLs are moved.

If the -S option is specified when creating a test-case index file, LIBPATH is searched to locate test-case DLLs when using that test-case index file.

DTT Log File
DTT writes information to a log file. The information to be logged is determined by the current logging level, which is hierarchical. At any given logging level, all information at that level and below is logged.

Specifying the DTT Log File Name
A path and file name for the DTT log file can be specified on the DTT command-line using the -F option. If no log file name option is given on the command line, the default file name, DTT_LOG, is used in the current directory.

If a log file does not exist when DTT is started, the log file is created automatically. If the log file does exist, the new log is appended to the existing log file.

Specifying DTT Logging Levels
The DTT logging level can be specified on the DTT command line or changed from the Options pull-down menu after DTT has started. To set the logging level on the command line, specify a -Lx option, where x is the desired logging level, using a number in the range 1 - 9. To change the logging level after DTT has started, select Change logging level from the Options pull-down menu or use Alt+L. The default DTT logging level is 1, L_HDR.

The following table describes the logging levels supported by DTT:

Displaying the DTT Log File
To display the DTT log file for the current session, select Display log window from the Options pull-down menu or use Alt+D.

Operating DTT Automatically
The following provides instructions for specifying a script file, the script file structure, and the script commands DTT supports.

Specifying a Script File
If the name of a DTT script file is provided, DTT executes the supplied script automatically. To specify a script file, use the -I command-line option, as in the following example: DTT -IC:\DTT\SCRIPTS\bittests.scr

Script File Structure
A script file is a list of DTT commands that are executed, one at a time, in the order that the commands appear in the script file. When the end of the script file is reached, DTT terminates. Any DTT script command can appear anywhere in a script file. See Sample DTT Script File for an example of a DTT script file.

Script commands are not case-sensitive, except for the test-case name operand of the CHOOSE script command.

Script Commands

 * Usage Notes :1. Blank lines and comments can appear anywhere in a script file.
 * 2. Comments must be preceded by an asterisk (*) as the

CHOOSE (Test-Case Selection Command)
The operand of the CHOOSE script command specifies the test case to be executed when a DISPLAY script command is encountered. The test-case name operand is case-sensitive and must match the specified test-case name exactly. In script files, test cases are selected by their test-case name only; the test-group name is not used. If the test-case name is not found, the CHOOSE command is ignored.

DCTYPE (Device Context Selection Command)
The operand of the DCTYPE script command identifies the device context to be used for subsequent test cases. Valid operands are:
 * OD_QUEUED :Output is to be queued. (This is the default.)
 * OD_DIRECT :Output is not to be queued.
 * OD_INFO :The device context is to be used only to retrieve information.
 * OD_METAFILE :The device context is to be used to write a metafile.
 * OD_METAFILE_NOQUERY :Same as OD_METAFILE, except querying of the attributes is not permitted.
 * OD_MEMORY :A device context that is used to contain a bit map.

DELAY (Pause Script File Execution Command)
When a DELAY command is encountered in a DTT script file, execution of the script is suspended for five seconds. The DELAY script command has no operand.

DISPLAY (Execute a Test Case Command)
The DISPLAY script command initiates immediate execution of the test case selected by the most recent CHOOSE command.

If the DISPLAY command is not preceded by a CHOOSE command anywhere in the script file, the first test case identified during DTT startup is executed. The DISPLAY script command has no operand.

EXIT (Terminate DTT Command)
When an EXIT command is encountered in a DTT script file, DTT immediately terminates. The EXIT script command has no operand.

PSTYPE (Presentation Space Type Selection Command)
The operand of the PSTYPE script command identifies the presentation space type to be used for subsequent test cases. Valid operands are:
 * GPIT_MICRO :Micro-presentation space.
 * GPIT_NORMAL :Normal presentation space. (This is the default.)

PSUNITS (Presentation Space Units Selection Command)
The operand of the PSUNITS script command identifies the presentation space units to be used for subsequent test cases.

Valid operands are:
 * PU_ARBITRARY :Application-convenient units.
 * PU_PELS :Pel coordinates. (This is the default.)
 * PU_LOMETRIC :Units of 0.1 mm.
 * PU_HIMETRIC :Units of 0.01 mm.
 * PU_LOENGLISH :Units of 0.01 inch.
 * PU_HIENGLISH :Units of 0.001 inch.
 * PU_TWIPS :Units of 1/1440 inch.

Configuring the Device Context and Presentation Space
DTT enables you to specify the device context, presentation-space type, and presentation-space units to use when executing test cases. These parameters can be changed during manual testing or through script commands during automated testing.

To change the configuration manually, select Configurationfrom the Options pull-down menu or use Alt+C. See Operating DTT Automatically for information about changing the configuration using script commands.

Setting the Device Context
To change the device context, select one of the following options from the Device Context section of the DTT Configuration dialog panel:
 * OD_QUEUED :Output is to be queued. (This is the default.)
 * OD_DIRECT :Output is not to be queued.
 * OD_INFO :The device context is to be used only to retrieve information.
 * OD_METAFILE :The device context is to be used to write a metafile.
 * OD_METAFILE_NOQUERY :The same as OD_METAFILE, except the querying of attributes is not permitted.
 * OD_MEMORY :A device context that is used to contain a bit map.

Setting the Presentation-Space Type
To select the presentation-space type to be used when executing test cases, choose one of the following options from the PS Type section of the DTT Configuration dialog panel:
 * GPIT_MICRO :Micro-presentation space.
 * GPIT_NORMAL :Normal presentation space. (This is the default.)

Setting Presentation-Space Units
To set the presentation-page size units for test-case execution, select one of the following from the PS Units section of the DTT Configuration dialog panel:
 * PU_ARBITRARY :Application-convenient units.
 * PU_PELS :Pel coordinates. (This is the default.)
 * PU_LOMETRIC :Units of 0.1 mm.
 * PU_HIMETRIC :Units of 0.01 mm.
 * PU_LOENGLISH :Units of 0.01 inch.
 * PU_HIENGLISH :Units of 0.001 inch.
 * PU_TWIPS :Units of 1/1440 inch.

Selecting and Executing Test Cases
The test cases to be executed are selected from the Test Case Selection dialog panel. Select Testcase from the DTT menu bar or use ALT+T. One or more test cases can be selected for execution during manual operation. Use script commands to select individual test cases during automated operation. See Operating DTT Automatically for information on test-case selection and execution using script commands.

Test Group Selection
There is a 1:1 relationship between test groups and test-case DLLs. Each test group represents a specific DLL. Before a test case can be selected, the test group containing the test case must be selected from the Test Groups section of the DTT Test Case Selection dialog panel. When you select a test group, the list of test cases it contains is added to the Test Cases section of the dialog panel. Deselecting a test group removes the list of test cases it contains from the Test Cases section.

Note: Test groups must be specifically deselected. DTT never automatically deselects a test group.

Test Case Selection
Once the test groups are selected, the individual test cases can be selected from the Test Cases section of the DTT Test Case Selection dialog panel. Test cases can be selected and deselected individually, or groups of test cases can be selected with the match patterns provided using the Add Match and Delete Match push buttons.

Note: Test cases must be specifically deselected. DTT never automatically deselects a test case.

Saving Selected Test Cases
After selecting one or more test cases, use the Save push button or Alt+S to close the Test Case Selection dialog panel.

Executing Test Cases
After selecting and saving one or more test cases, select Display from the DTT menu bar or use Alt+S to begin test-case execution. Each test case selected is executed in the order it appeared in the Test Cases section of the Test Case Selection dialog panel.

During test execution, DISPLAY TEST TOOL: Test Running appears in the DTT window title bar. When the test is complete, the name of the individual test selected reappears in the title bar if a single test was selected. DISPLAY TEST TOOL: Multiple Tests Selected appears if more than one test is selected.

Displaying the DTT Release and Revision Levels
To display the current DTT release and revision levels, select About from the DTT menu bar or use ALT+A.

Exiting DTT
To terminate DTT, select Exit from the DTT menu bar or use ALT+X.