/* $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 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 or by using and 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.