/* $TOG: README /main/8 1999/12/09 14:46:26 jff $ */
5.  OSF/Motif Window Manager Tests

This README describes the OSF/Motif Window Manager tests.
It provides information about the individual tests, and
offers instructions for running and interpreting the tests
and test output.

                            Note

Throughout this README, we use the path ./tests/mwm to
identify the top directory of the Window Manager tests.  The
./ indicates the testing tree root and is not an actual path
designation.  For example, if you installed the Motif 1.1
release software at /source/Motif, then ./tests/mwm
translates to /source/Motif/tests/mwm at your site.

5.1  Overview and Directory Structure

The OSF/Motif Window Manager test directory, ./tests/mwm,
consists of several files and subdirectories:

   * The file Imakefile is used to build Makefile, which in it's turn
	is used to build the PI tests.

   * The subdirectory ./tests/mwm/PI contains tests of the
     OSF/Motif Window Manager programmatic interface.

   * The subdirectory ./tests/mwm/user contains tests of the
     OSF/Motif Window Manager user interface.

5.1.1  The Contents of the PI Test Subdirectory

The PI test subdirectory contains the following tests:

PIColormap    PIMwmHints   PIProtocols
PIHints       PIMwmInfo
PIIconState   PINames

The test subdirectory contains the following files:

   * The file Imakefile is used to build Makefile, which in it's turn
	is used to build the tests.

   * The README file contains information specific to test
     directory's build and run procedure.

   * Files with the suffixes .c, .h, and .uil are the source
     files for the tests.

   * The file PI.Xdefaults contains Xdefaults that are
     installed for use with the PINames test.

   * The file PITests.h contains declarations used by all
     the tests.

   * The file convenience.c contains the source code for
     convenience routines used by all the tests.

   * The files main.c and main.uil contain the source code
     for the main routine used by all the tests.

   * The file summary.c contains the source code for the
     summary routine used by all the tests.

   * The file run_PINames is a script that runs the PINames
     test.

5.1.2  The Contents of the user Test Subdirectory

The tests in this subdirectory are designed to test all the
resources and functions of mwm that can be tested by user-
interface tests.

In this test suite, mwm resources are tested by copying dif-
ferent default files into the user's home directory, res-
tarting X and mwm, and then running the tests.  The tests
are basically manual, although the setup is done by a shell
script.  Note that the startup environment for X varies.
The shell script may need to be modified for your environ-
ment.

The directory contains the following files and subdirec-
tories.

   * The README file contains information specific to the
     test subdirectory's build and run procedure.

   * The Instruct subdirectory contains the instructions for
     each test.  The instructions for a particular test are
     named the same as the test for convenience.  These are
     installed in your home directory with the name
     .instruct, and read during the execution of the tests.

   * The mwmrc subdirectory contains the .mwmrc files for
     each test.  The .mwmrc file for a particular test is
     named the same as the test for convenience.  These are
     installed in your home directory with the name .mwmrc.

   * The x11start subdirectory contains the .x11start files
     for each test.  .x11start files are only used for HP
     machines.  The .x11start file for a particular test is
     named the same as the test for convenience.  These are
     installed in your home directory with the name
     .x11start.

   * The xdefaults subdirectory contains the .Xdefaults
     files for each test.  The .Xdefaults file for a partic-
     ular test is named the same as the test for conveni-
     ence.  These are installed in your home directory with
     the name .Xdefaults.

   * The file setup is a script that saves the .mwmrc,
     .x11start, and .Xdefaults in your home directory, and
     replaces them with the startup files for each test.

   * The file startxterm is a script that initializes the
     window environment for each test on a DEC Pmax.  The
     window environment is initialized by the .x11start when
     the X server is started on HP machines.  For other
     machines, customization may be required.  It is neces-
     sary to restart the session between tests.

5.2  Compiling the Tests

The tests in the PI subdirectory must be compiled before you
can run them.  The default files in the user subdirectory
must be installed and initialized in your home directory
before you can use them.

5.2.1  Compiling the PI Test Subdirectory

   * If you used the global build process after installing
     the software, the tests should already be built.  We do
     not recommend building the tests with global build pro-
     cess because of the size of the test suite.  (This
     assumes that you did not move the test suite files
     prior to invoking the make commands.)

   * If you did not include the test suite files in your
     initial global build process, you can build the tests
     now using the make all command from either the
     ./tests/mwm or ./tests/mwm/PI directory.

The compiled tests use a large amount of disk space.  You
may prefer to build each test separately if disk space is
limited at your site. You can build each test individually
using the make command for each test.  The make command for
each test should include the test name and the name of the
final uid file.  In all cases the final uil file name is the
same as test name with a .uid suffix.  For example, to build
the PIHints enter the command make PIHints PIHints.uid from
the ./tests/mwm/PI test subdirectory.

5.2.2  Installing and Initializing the user Test Subdirec-
       tory

Installing the user tests in your home directory will
overwrite your environment startup files .Xdefaults, .mwmrc,
and .x11start.  (The x11start file is only used on HP
machines.)  You should make copies of these files before you
install the tests so you can recover your system environment
when you are finished running the tests.  You can move the
files yourself or use the setup script to move them.

Entering setup clean from the ./tests/mwm/user directory
will move the environment startup files in your home direc-
tory to the files Xdefaults.tst, mwmrc.tst, and
x11start.tst.  These files can be restored by hand after you
are finished running the user tests.

Take the following steps to install and initialize a Window
Manager test.

  1.  Install the Motif Window Manager that you are going to
      test, usually ./clients/mwm/mwm, into the bin direc-
      tory of your home directory either with a link, copy
      or move command.  For example,

      cp ./clients/mwm/mwm ~/bin
      chmod +x ~/bin/mwm

  2.  Install a test in your home directory using the setup
      script in the user subdirectory.  The syntax follows.

      setup testname

      Where testname is the test you want to install.  This
      copys all of the appropriate test default files to
      your home directory.  This must be done before each
      test.

  3.  Restart the X server and mwm.  On HP machines this is
      done by entering <Shift> <Ctrl> <Break> to exit X,
      changing directories to the test directory, and enter-
      ing x11start to restart X, which will execute the
      .x11start file.  The .x11start file starts up mwm and
      initializes the test with three windows.

      On DEC Pmaxes this is done by logging out and back in
      again, changing directories to ./tests/mwm/users and
      entering startxterm.  Logging out and back in again
      restarts the X server.  startxterm starts up mwm and
      initializes the test with three windows.

      On the Pmaxes, you should iconify the original window
      to avoid confusion during the test.  If the original
      window is obscured at the start of the test, it is
      best to wait until it is not obscured to iconify it so
      as not to disturb the testing procedures.

5.3  Running the Window Manager Tests

All the Window Manager tests are interactive.  The PI tests
include a MessageBox with instructions for running and
interpreting each test.  When the test is completed, a sum-
mary message for the test is displayed in the MessageBox.
The user tests include an extra window on the rightmost side
of the screen that includes instructions for running the
tests.  The instructions are displayed using less and can be
scrolled using <space> or by using <j> and <k> as in vi.

5.3.1  Running the PI Tests

To run any of the tests except PINames individually, simply
enter the name of the compiled test in the ./tests/mwm/PI
directory.  The tests will display a MessageBox with
instructions for the test.  When the test has completed, a
summary of the results is displayed in the MessageBox

The test PINames is run from within the run_PINames script.
The script run_PINames runs the command machine to determine
the type of machine it is running on.  If this command is
not available on your platform, or if your platform is a
version of System V, but not the hp300 machine, modify the
script appropriately.  Also, the run_PINames script prints a
message at the end that says something like the following.

run_PINames: 21326 Killed

This is normal.

5.3.2  Running the user Tests

Once a test is initialized three windows should be displayed
on the screen.  The rightmost window should contain the
instructions for the test.

While running the tests, it is sometimes necessary to give
focus to the instructions window to scroll the instructions.
This can affect the test, so whenever possible, scroll the
instructions so that a whole section is shown in the window
before you start that section.  After running the tests a
few times, it will become obvious which points in the tests
are good times for scrolling the instructions.  It is also
possible to use a printed copy of the instructions and
ignore the instructions window on the screen (except where
the instructions window itself is used in a test).

Additional Test in 1.1.2:

behavior_test tests that mwm does not dump core while handling an
empty clientlist. This test kills the current X session, starts a new
X session using the files behavior.xinit, behavior.Xdefs, and 
behavior.mwmrc. To run this test you have to type 'nohup behavior_test'.

Additional Test in 1.1.4:

Mwm_res.test currently tests PIR 3381 about user being able to resize the
window during placement when interactivePlacement is True and resize on
windows is turned off through clientDecoration and clientFunctions resources.
It turns off these resources and sets interactivePlacement to True through
the resource file Mwm_res.Xdefs.
