doc/testing.rst

   1 Testing
   2 =======
   3
   4 .. highlight:: sh
   5
   6 As a system administration tool, Wizard employs a variety of testing
   7 mechanisms in order to verify that the code is working and that
   8 there are no regressions.
   9
  10 Unit tests
  11 ----------
  12
  13 Unit tests can be run by running ``nosetests`` in the Wizard root
  14 directory (the directory that contains a :file:`wizard` and :file:`bin`
  15 directory).  These should run and pass on all platforms.
  16
  17 Doctests
  18 --------
  19
  20 Certain pure functions contain doctests for their functionality.  You
  21 can run them using ``sphinx-build -b doctest doc doc/_build`` in
  22 the Wizard root directory.  These should run and pass on all platforms.
  23
  24 Acceptance tests
  25 ----------------
  26
  27 These are the most useful metrics of whether or not Wizard is working:
  28 they run Wizard commands and try to see if any of the commands return
  29 a non-zero exit code (future development may allow for pre-conditions and
  30 post-conditions to be checked).  The test scripts are located in the
  31 :file:`tests` directory, and are identifiably by their prefix ``test-``
  32 and their suffix ``.sh``.  They should run out of the box on
  33 scripts servers, so long as the Wizard source tree is inside of your
  34 :file:`web_scripts` directory, and require some configuration if you
  35 plan on running them locally.
  36
  37 Custom configuration can be specified in the :file:`config` file (located
  38 at :file:`tests/config`.  This is actually a Bash script to be sourced
  39 by the real test script (:file:`tests/setup`), which exports various
  40 environment variables that Wizard will use during installation.
  41
  42 Here is a sample file::
  43
  44     export WIZARD_WEB_HOST="localhost"
  45     export WIZARD_WEB_PATH="/wizard/tests/$TMPNAME"
  46     export WIZARD_MYSQL_HOST="localhost"
  47     export WIZARD_MYSQL_USER="root"
  48     export WIZARD_MYSQL_PASSWORD="password"
  49     export WIZARD_MYSQL_DB="wizard_test_$TMPID"
  50     export WIZARD_EMAIL="bob@example.com"
  51
  52 You will need to specify all of these environment variables.  :envvar:`WIZARD_WEB_HOST`
  53 and :envvar:`WIZARD_WEB_PATH`  indicate Wizard's configuration with respect to
  54 your web server.  ``http://$WIZARD_WEB_HOST/$WIZARD_WEB_PATH`` will be the location
  55 that a newly installed application will be accessible.  You will notice that
  56 we used :envvar:`TMPNAME`; this is the directory that will be created in
  57 :file:`tests` for the application. :envvar:`WIZARD_MYSQL_HOST`,
  58 :envvar:`WIZARD_MYSQL_USER`, :envvar:`WIZARD_MYSQL_PASSWORD` and :envvar:`WIZARD_MYSQL_DB`
  59 are standard configuration variables for accessing a local MySQL database.  You can use
  60 :envvar:`TMPID` to uniquely identify any particular test.  Finally, :envvar:`WIZARD_EMAIL`
  61 is any email address you own that will be configured as an administrative email.
  62
  63 It may be useful to include a little bit of code to handle dropping and creating
  64 databases.  Here is a sample::
  65
  66     MYSQL_ARGS="-uroot -prootpassword"
  67     mysql $MYSQL_ARGS -e "DROP DATABASE \`$WIZARD_MYSQL_DB\`;" || true
  68     mysql $MYSQL_ARGS -e "CREATE DATABASE \`$WIZARD_MYSQL_DB\`;"