RATS README.txt $Header: /home/davison/swd/projects/rats/working/lib/RCS/README.txt,v 1.16 2009/08/21 17:34:12 davison Exp davison $ SECTION: Installing RATS SECTION: RATS Quick Start SUBSECTION: RATS Configuration Check SUBSECTION: Run an Example Test Script SECTION: RATS Directory and File Structure SECTION: Installing RATS RATS is packaged in several tarballs, listed and described below: ratsexport.yyyymmdd_hhmm.tgz Java source, etc. for building RATS jars Not needed by script writers or testers. The build procedure is described elsewhere in this document. ratsjars.yyyymmdd_hhmm.tgz RATS jars to be installed in cave/. Needed to make CAVE rats-scriptable. ratslibs.yyyymmdd_hhmm.tgz RATS Perl libraries, utilities. Needed by all RATS users. ratstests.yyyymmdd_hhmm.tgz Sample test packages. 8006.tgz.yyyymmdd_hhmm.tgz Test package for test case 8006. (Not included with the other tests because of its size.) In the following discussion, the environment variables listed below will be used for directory names. To install RATS you must define the environment variables and, in some cases, create the directories. Note that the environment variables starting with RATS_ must be defined when RATS test scripts are run. The other environment variables are needed just for installation. $RDL This is the RATS download directory to which you will download the RATS tarballs. It can be a temporary directory. The RDL environment variable does not have to be defined to run RATS. It is used here as a notational convenience. The installation instructions will assume that the tarballs are in $RDL. $RATS_CAVE This is the CAVE installation directory (~awips/cave, /usr/local/cave, or wherever CAVE is installed). It is the directory containing (among other things): cave, cave.sh, cave.ini, etc. The RATS_CAVE environment variable must be defined for RATS to run. $RATS_LIB This is the directory where the RATS perl libraries and utilities will be installed. The environment variable must be defined to run RATS. $RATS_RUN After installation, this directory will contain the following subdirectories: data, output, scripts, testPackages. You need not create the subdirectories. They will be described later in this document. The RATS_RUN environment variable must be defined in order to run RATS. Begin installation by creating directory $RDL and downloading the ratsjars, ratslibs, and ratstests tarballs to it. You may also want to download the 8006 tarball. RATS is installed by expanding the tarballs above in the proper directories as described below. When you do that, the files from the tarball may overwrite existing files. Most files are RATS-specific, and will only overwrite previously installed RATS versions. If you have made custom versions of any RATS files you will have to save them off and merge the changes into the new versions. When you install ratsjars it will overwrite the SWT GTK jar file: $CAVE/plugins/org.eclipse.swt.gtk.linux.x86_.jar. You may want to save off the original version of that file before installing ratsjars. In general, you can review the contents of a tarball (thus seeing what it will overwrite) by using the table- of-contents option: tar ztf Installing ratsjars cd $RATS_CAVE tar zxf $RDL/ratsjars.yyyymmdd_hhmm.tgz cp cave caveForRats Installing ratslibs mkdir -p $RATS_LIB cd $RATS_LIB tar zxf $RDL/ratslibs.yyyymmdd_hhmm.tgz Staging ratstests mkdir -p $RATS_RUN/testPackages cd $RATS_RUN/testPackages tar zxf $RDL/ratstests.yyyymmdd_hhmm.tgz Staging 8006.tgz cp $RDL/8006.yyyymmdd_hhmm.tgz $RATS_RUN/testPackages Installing RATS tests The test packages are tarballs staged in $RATS_RUN/testPackages (if you have staged them in accordance with the preceding instructions). To install a specific test: cd $RATS_RUN tar zxf testPackages/ SECTION: RATS Quick Start SUBSECTION: RATS Configuration Check Take a few minutes to verify correct setting of environment variables and set CAVE up for scripting... 1) Try to start CAVE as follows: cd $RATS_CAVE ./cave.sh CAVE should start up normally. Try a few CAVE functions, especially data loading, to verify normal, unscripted operation. Resize the main CAVE shell so that it occupies most of the screen, but is above the default location of the AlertViz shell. (RATS does not require any specific CAVE shell size, but problems can occur if it is very small. Also, any script that references a widget that is not visible on the screen will fail.) 2) Verify that the following ls commands all work without error: ls $RATS_CAVE/caveForRats ls $RATS_LIB/Rats.pl ls $RATS_RUN/testPackages/optionsSetTime*.tgz (Those three environment variables must be defined for RATS to run.) 3) Use a RATS utility to start a scriptable version of CAVE: $RATS_LIB/startCave.pl -s CAVE should start up. Try a few CAVE functions, especially data loading, to verify normal operation. SUBSECTION: Run an Example Test Script In this subsection you will install and run an example test script, optionsSetTime.pl. Please note the following: o When the test script starts up it will look for any running instances of CAVE and will try to kill them. Then it will start CAVE. o You must leave the mouse pointer in a screen location that will be occupied by the main CAVE shell. That is, after startup the mouse pointer must be on the CAVE shell. (This is a CAVE thing, not a RATS thing. The CAVE widgets don't get mapped, at least in KDE, until the pointer is on the CAVE shell.) o Don't touch the mouse or keyboard associated with the CAVE display while the test is running. (It's safe to do so while the CAVE splash screen is still visible.) By this time you may have gotten tired of typing the long environment variable names. I did. So for convenience I put the following into my environment setup file: export RL=$RATS_LIB export RR=$RATS_RUN export RRS=$RATS_RUN/scripts export RRO=$RATS_RUN/output If you have not already installed the optionsSetTime test script, do it now: cd $RR tar zxf testPackages/optionsSetTime.*.tgz Run the test: cd $RRS perl -w optionsSetTime.pl After the test completes, inspect the log file: view $RRO/optionsSetTime.*.log You can install and run any of the other sample test packages in $RATS_RUN/testPackages by the same procedure you used above. Please note the following: o A new log file is created in $RATS_RUN/output for each test execution. The log file names are built from the script name and a timestamp. o The CAVE stdout and stderr streams are captured to files in $RATS_RUN/output. Each execution of CAVE generates a new file with a timestamp in its name. o There are various other files in $RATS_RUN/output. Generally speaking, test scripts should only create, modify, or delete files in $RATS_RUN/output or in /tmp, not in any other directory. (Although a script might create its own directory hierarchy under $RATS_RUN/output.) o After running a batch of tests you can delete $RATS_RUN/output. The test scripts will create the directory if it does not exist. SECTION: RATS Directory and File Structure The $RATS_LIB directory contains the major infrastructure files. Two big files of perl subroutines live there: Rats.pl and Cave.pl. You will also see several executable utility scripts. The utility scripts contain header comments describing their purpose and usage. $RATS_LIB also contains the perl XML library hierarchy because those libraries were dropped from RHEL in RHEL 5, and RATS has not yet been refitted with whatever XML library is available in RHEL 5. Those who write and run test scripts should rarely, if ever, have to modify any files in $RATS_LIB. One $RATS_LIB directory can be shared among users on the same machine. Each user should have his or her own $RATS_RUN directory hierarchy. The hierarchy looks like this: $RATS_RUN testPackages Contains the test package tarballs. Each tarball contains at least one test script. Some of them (autotest, for example) contain several. The tarball for a test package will also contain any data files that test requires. The tarballs should be constructed such that if they are expanded in $RATS_RUN the script files will go into the scripts subdirectory and the data files will go into the data subdirectory. scripts This is the directory from which test scripts should be run. Typically test script writers will do their script development work in this directory. data Contains data files needed by scripts. output Contains files created by test scripts.