1.  Test Suite Organization and Procedures

This readme presents an overview of the organization of the
OSF/Motif Test Suite and the procedures for building and
running the tests.  The testing procedures have changed 
somewhat since the 1.1 release of Motif.  We think you
will find the new procedures more intuitive and easier to
use, but please familiarize yourself with them by reading
this guide before you run the new tests.

These test suites were used for testing Motif 1.2. You may find
them useful for any or all of the following:

   * To examine our testing procedures

   * To test your implementation of OSF/Motif

   * To see examples of new Motif functionality in use

   * To check for bugs in the Motif source that may be caus-
     ing problems in your code

1.1  Identifying the Tests

The OSF/Motif Test Suite consists of five main sets of
tests:

   * Resource Manager (Mrm) Tests

   * Toolkit (Xm) Tests

   * XmString Tests

   * Window Manager (mwm) Tests

   * User Interface Language (uil) Tests

   * Drag and Drop tests (new in 1.2)

   * Performance tests (new in 1.2)

   * Memory tests (new in 1.2)


1.2  Locating the Tests

The Motif 1.2 release software is shipped with the tests
located one level below the top directory. You can only
build the tests in this area of the Motif tree.

Throughout this document, we use the path ./tests to specify
the path to the Test Suite.  The ./ indicates the testing
tree root and is not an actual path designation.  For exam-
ple, you might install the release software at a location
called /source/Motif.  In that case, the path ./tests
translates to /source/Motif/tests.

The Test Suite consists of a hierarchy of directories and
files; each directory has subordinate directories and files
relevant to that content area.

The different test sets are located in the Mrm, Toolkit,
XmString, mwm, and uil subdirectories of ./tests.

1.3  Building the Tests

The OSF/Motif Release Notes specify how to build the
OSF/Motif software.  If you follow this process, the tests
can be built along with other snapshot components.

However, be aware that the test suites are very large and
can use large amounts of disk space when compiled on some
machines.  Consequently, you may prefer to build them indi-
vidually prior to running the tests.

If you build this directory separate from the rest of Motif,
make sure you do a make wml before you doing a make depend
in this directory.  There are dependencies between files
created by the make wml process and the test files.

Also note that the directory ./tests/uil/matrix contains a
Build script.  Building is an important part of the test
process for this particular test.  It will not be built
automatically.

1.4  Running the Tests

1.4.1 Manual suite

The test suite shipped with the Motif 1.2 tape is a manual test
suite. You must build the library in ./tests/Manual/lib, which
will be linked with all test cases. Optionally, you can define
the flag -DREGRESSION when when build this library. If you do,
the Instruction message boxes will contain two buttons, PASS and
FAIL, instead of the normal one CONTINUE button. The number of
PASSES and FAILS will be tracked and printed to a summary file
in the test directory. We hope this new feature will enhance your
use of the test suite.

1.4.2 Automated suite

If you have purchased VTS 1.1, you will receive the Quality Assurance
Test Suite (QATS), which contains libraries, scripts, and output
files to support running the test suite automatically.

Full documentation is not yet available for test automation. This
document will be available in July, 1992 and can be obtained by
contacting Motif Support at (617) 621-8990.

Briefly, in order to use the automated suite you must compile all
the libraries under ./tests/Auto/lib, then compile tests for
automation, first building the Makefile for Automation:

	% make IMAKE_DEFINES="-DAUTOMATION" Makefile

Note that the suite is not yet fully automated. ./tests/General contains
a file dirsAuto, which lists the directories currently automated by
OSF. If you automate additional directories, add them to this file.
The RUN_template in ./tests/General must be in place in order to make
the RUN scripts. Always use the RUN scripts when running automated
directories. You will, however, need to modify the RUN.custom files
in each automated directory to specify the path to the test output,
which is used for comparison.

The man pages for the scripting command language can be found in
./tests/docs. There are a number of scripts provided with the
test suite that can serve as examples.

To get more information on ordering the QATS, call OSF Direct at
(617) 621-7300 or email direct@osf.org.

1.5 Other Features

Supplied with this release is a "dirty malloc" package, which writes
an identifiable pattern into uninitialized and freed memory. This library
can be used to test correctness of memory usage and also memory leaks
and string handling. See the README in ./tests/General/lib/Malloc for
full instructions on how to use this package.
