/* $XConsortium: README,v 5.4 94/04/17 20:46:06 hersh Exp $ */ /***************************************************************** Copyright (c) 1989, 1990, 1991 X Consortium Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of the X Consortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium. Copyright (c) 1989, 1990, 1991 by Sun Microsystems, Inc. All Rights Reserved Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Sun Microsystems not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ******************************************************************/ InsPEX, the PEX test suite -------------------------- InsPEX is an automated test suite for testing PEX, through the PHIGS/PHIGS+ C language binding. It performs operations through PHIGS functions, and tests for the expected results using the PHIGS binding itself, and Xlib. Many tests use an interpreter for faster execution time and more efficient test development. Tests requiring verification of pixels use Xlib to retrieve pixel and color map information; the resulting images are either verified automatically, or compared against saved images. An X-based tool, Inspector, is supplied for comparing images against saved reference images, and saving the new images as acceptable images if desired. YOU MUST HAVE A VALID X3D-PEX SERVER RUNNING BEFORE YOU START THE InsPEX TEST SUITE. IT WILL NOT START A SERVER FOR YOU!!! This file contains: * Some comments on porting. * A brief list of other sources for information about InsPEX. The PEX-SI User Guide, in particular, should be referred to for a more complete description of the test suite. * Some comments on this release of InsPEX. PORTING ISSUES -------------- Portability Goals and Non-Goals ------------------------------- InsPEX is intended to work with 8-bit pseudocolor framebuffers. We assume Unix, and have the goal of working under both System V and BSD systems. We also intend InsPEX to work on any 32-bit machine architecture. We do not have the goal of working on non-Unix systems or different frame buffer depths. While support for other frame buffer depths is not built into InsPEX, some provisions were made for porting to other depths. In the definition of the file format for saved images, found in the comment for i_save_image() in tools/pexint/pixutils.c, the first byte is intended to identify the type of file. The only supported type is PSEUDOCOLOR, but other types could be defined and added. Their structure after the description string, width, and height fields would be different, and this first byte would be used to differentiate how the files were created and should be handled. Porting Tests and the Interpreter --------------------------------- Some portable data types are declared in portable.h in INSPEXHOME/tools/pexint, for use in the interpreter and other tests. We have tried to use system calls that are common to both System V and BSD Unix. Some SysV incompatibities reported by an alert sponsor have been fixed, though they require a "SYSV" to be defined during compilation (see the description of I_CFLAGS in the Release Notes or inspex.sh, for a method to set this if it isn't set by the compiler). Porting the Inspector --------------------- The chief portability issue for the Inspector is the choice of Graphical User Interface toolkit. The current implementation uses the XView toolkit, which is available from the X Consortium and from Sun Microsystems. To facilitate porting, however, all toolkit-specific code is isolated into two files, toolkit.c and toolkit.h. Through typedefs and function definitions, these files create a separate interface layer on top of the toolkit being used. While this interface looks like a toolkit itself, it has no pretense of being a general-purpose toolkit -- it was designed strictly to make this particular application easily portable. The interface types and functions should be implementable using any toolkit. An incomplete and non-working port to Athena Widgets is included; if someone can finish this and get it going, please share it with the PEX community. Notification, or call-back, procedures are attached to the buttons of the control panel; since we can't be sure of of what arguments a given toolkit wants to supply to these functions, they are expected to be defined without any arguments. The negative side to this solution is that it forces greater use of global variables. The scrolling list could be implemented as a menu or other control item. Selecting the file name in the list could be used to control loading of files, rather than the current method of selecting and then hitting "load". OTHER DOCUMENTS --------------- PEX-SI User Guide - the section on InsPEX is the most detailed document for the test suite available. PEX-SI Release Notes - this is not likely to contain any information that's not also to be found in this README. A man page for the NewT interpreter builder is in $INSPEXHOME/tools/newt/newt.man. This describes the process of building an interpreter, the files required, and also the language understood by the resulting interpreters. The header comment of the main script, inspex.sh, has a description of the various option switches and environment variables used by the test suite. The file test_descrip in this directory contains an automatically-extracted description of all the supplied tests. Every C-based and interpreter-based test contains a brief description of what the test does, in a comment marked with "##". These comments can be automatically extracted by searching for this sequence, with a script such as this one: #!/bin/csh # extract_doc.csh - given a set of file names, extract the documentation # lines in them and print them in a nicely separated fashion. # Documentation lines are marked by a "##". foreach file ($*) echo $file ----- # extract comment lines, remove '##' and indent slightly. grep "##" $file | sed -e "s/##//" | sed -e "s/^/ /" echo "" end # end of extract_doc.csh. Here's the command used to create test_descrip in this directory: csh% cd $INSPEXHOME csh% extract_doc.csh testcases/*/*.{c,pi} > test_descrip Notes for the final release of the PEX-SI: ----------------------------------------- This information can also be found in the Release Notes. This release of InsPEX has greatly increased test coverage, and some new features. The areas covered include all the PHIGS-PLUS graphics primitives, such as fill area sets with data, quadrilateral meshes, triangle strips, and NURBS. PHIGS-PLUS attributes such as direct color specification, depth cuing, and lighting are also exercised. The testing of input is somewhat limited by the problem of simulating mouse and keyboard input in a reliable and portable fashion. For the pick, locator, and stroke devices, simulating the mouse events is straightforward, but since the string, valuator, and choice devices are built upon a toolkit (Athena Widgets in the PEX-SI's case), getting window ID's for the appropriate windows and sending mouse clicks to the right place on those windows is more difficult, and probably impossible to do in a way that could be quickly ported to another toolkit along with these input devices. The technology for automatic testing of software using a graphical user interface under X has not progressed to the point where we could test this functionality in a way that would be useful to all the potential users of InsPEX. For nearly all of the tests that use image comparison to verify graphical output, we have supplied reference images generated here using the PEX-SI code. Due to outstanding bugs in the code, however, some tests are shipped without reference images. Also, since back-facing attributes are not implemented, the images saved for these tests are actually incorrect. We decided to ship them, however, because they still can be helpful to someone porting the PEX-SI. It should be expected that when backfacing attributes are implemented, these tests will fail and image comparison will be required. Along with the README in the main InsPEX directory, there is a sample log file, sample.log, and an automatically-generated summary of all the current tests, test_descrip. See the README for a description of how that file was generated. Running the InsPEX Test Suite ----------------------------------------- 1) MAKE SURE YOU HAVE AN X3D-PEX SERVER RUNNING 2) Go to INSPEXHOME. Set the DISPLAY environment variable and the PEXAPIDIR environment variable to the proper values. It is also helpful to set MAXFAIL to some reasonable value, otherwise InsPEX will stop after test failures. Also use the VERBOSITY variable to get more clues. See the Using InsPEX section of the PEX-SI User Guide. 3) Type run_InsPEX. If you have not changed the relative locations of the X and PEX directories wrt to the root tree as it appeared on your tape then InsPEX will go off on its merry way (hopefully) performing a make or two, executing interpreted test scripts, compiling and executing some c language test programs and reporting the results. If you have moved things around you can use these shell scripts: run_InsPEX inspex.sh startpex as a guide to making versions that will work on your system. Remeber to try to finesse all environment variables to absolute pathnames as relative pathnames will make your life hell. Don't curse me I didn't write these scripts Good Luck. ----------------------------------------- Unix is a trademark of AT&T.