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     MYSQL_ARGS="-uroot -ppassword"
  45
  46     export WIZARD_WEB_HOST="localhost"
  47     export WIZARD_WEB_PATH="/wizard/tests/$TESTDIR"
  48     export WIZARD_DSN="mysql://root:password@localhost/wizard_test_$TESTID"
  49     export WIZARD_EMAIL="bob@example.com"
  50
  51 You will need to specify all of these environment variables.  Those prefixed
  52 with ``WIZARD`` are directly used by Wizard, while the ``MYSQL`` environment
  53 variables are used if a test script wants to interactive directly with a
  54 MYSQL database.  We don't quite have a good story for alternative databases
  55 in test scripts.
  56
  57 * :envvar:`WIZARD_WEB_HOST` and :envvar:`WIZARD_WEB_PATH`  indicate Wizard's
  58   configuration with respect to your web server.
  59   ``http://$WIZARD_WEB_HOST/$WIZARD_WEB_PATH`` will be the location that a newly
  60   installed application will be accessible.  You will notice that we used
  61   :envvar:`TESTDIR`; this is the directory that will be created in :file:`tests`
  62   for the application.
  63 * :envvar:`WIZARD_DSN` is the database source name, which
  64   should be used to access a MySQL database (as Wizard does not contain support
  65   for any other database system yet.) You can use :envvar:`TESTID` to uniquely
  66   identify any particular test.
  67 * :envvar:`WIZARD_EMAIL` is any email address you
  68   own that will be configured as an administrative email.
  69