AACE Test Harness Installation Instructions
===========================================

Required components
===================

The AACE Test Harness requires the installation of:
   - python 2.6.1 or higher
   - mysql (we tested it on distribution 5.5.9)
   - mysql-DB python module 1.2.3
   - sqlalchemy (a python database tookit - see sqlalchemy.org) 0.6.7
   - mako (a python template library - see makotemplates.org) 0.4.1
   - argparse (a python module - may be within the Python standard
       library - see pypi.python.org/pypi/argparse/1.2.1)

1) install python 2.6.1 or higher on your system.  If you are installing 
   python using your system's package manager, be sure to also install 
   the python header files. These may be located in a seperate package 
   labeled '-dev'.

2) install the C version of mysql-connector. See the web page
   www.mysql.com/products/connector for more information. When this
   connector package is unpacked, note the location of the lib and
   include directories that are chosen for installation. If nonstandard
   directories are chosen (such as directories other than /lib or /usr/lib
   that are already on standard paths) you must set LD_LIBRARY_PATH to
   the connector lib directory. Also these locations are needed in 
   step four of the Installation Instructions below.
   
3) install the python setuptools. For more information, see:
   pypi.python.org/pypi/setuptools
   In particular, the command "easy_install" should be a part of
   the setuptools

4) install MySQL on your database server (does not have to be the same
   system that python was installed on - but must have shared directories). 
   At a minimum, you need to know the database host: "server", the database 
   name: "db_name", a database "user", and that user's "password".

The installation of the mysql-DB python module, sqlalchemy and mako 
should be automatic during the next setup process. Most likely you will 
need to do nothing regarding the argparse module. See the above-referenced 
site if necessary.  If you install these packages using your system's package
manager, you can prevent them from being installed again by passing the
'--no-deps' flag to easy_install in step 5 of the Installation Instructions.

AACE Test Harness Installation Instructions 
===========================================
On the system  with python installed as above, perform these steps:

1) Choose a directory, <UNPACK>, to install the harness package

2) Unzip and unpack the tar file in directory <UNPACK>:
      gunzip aace_harness-1.0.tar.gz
      tar xpf aace_harness-1.0.tar

3) cd to aace_harness. This directory, <UNPACK>/aace_harness, is now
   known as the <ROOT> directory for all documentation and instructions
   within the AACE test harness installation directory.

4) To correctly perform the next step set the CFLAGS environment variable
   to the lib and include directories from the sql connector installation
   from above. For example, in bash use:

     export CFLAGS="-I<connector-directory>/include -L<connector-directory>/lib"

5) Install the web component in the <ROOT> directory:
      easy_install web-1.0dev-py2.7.egg

6) Create the web configuration file in the <ROOT> directory:      
      paster make-config web production.ini

7) Edit production.ini for the port to use and the SQLAlchemy database URL
   entry: 
     -- The default port value is 5000, but may be changed if needed
     -- A typical entry for the URL is:
        sqlalchemy.url = mysql://<user>:<password>@<server>/<db_name>

8) Create the actual database tables to be used by the test harness. In
   the <ROOT> directory type:

      paster setup-app production.ini

   The database should now have all needed tables created

9) In <ROOT> make the config.xml file by following the directions in
   <ROOT>/docs/config_file

Populate the database
=====================
On the database server, go to the <ROOT> directory to prepopulate the database
tables:

mysql -u <user> --password=<password> -h <server> <db_name> < aace_blackjack.sql

Running a test
==============
On the system with python installed (System), first make sure that 
<ROOT>/bin is in your path.

Next, add System to the database table hosts. You can either edit the 
preinstalled row in the hosts table by changing the name "host_machine" to
"System", or you could use the utility host_insert.py found within the
<ROOT>/utils directory (follow the directions at the top of this utils
file).

The AACE Test Harness should now be set up to run a first test. Making sure
that the homeqa variable in the config.xml file is set to <ROOT> (alternately,
you can just add "-homeqa <ROOT>" to the runtest command below), execute the
following command on the System machine:

   runtest -suite c_correct -test a1 -echo -nosave

You should see that test a1 ran successfully. Now execute the following 
command to run the same test but save the result to the database (and to
see less output without the -echo flag):

   runtest -suite c_correct -test a1 

For more details on running tests, see the <ROOT>/docs/runtest_info and
<ROOT>/docs/test_info files.

Viewing output on a web page
============================
On the System server machine, in the <ROOT> directory execute this command;

   paster serve production.ini &

To examine the web page, bring up a browser and type in the url:

   http://System:port#

where port# by default is 5000 in the production.ini file.

You should now see the Test Harness webpage, with the default View of
"AACE Test". Try navigating on this page, and clicking various entries to
see details about the test run.

Note that this first example was just a single test from the c_correct
suite. The entire suite can be run by leaving the "-test a1" option off
of the runtest command line.

The paster job that is started must stay running while viewing the web page.
More details on the web page can be found in the <ROOT>/docs/web_info
file.
