/* $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.