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.  Test files
  16 tend to live in :file:`tests` directories under :file:`wizard`.
  17
  18 Doctests
  19 --------
  20
  21 Certain pure functions contain doctests for their functionality.  You
  22 can run them using ``sphinx-build -b doctest doc doc/_build`` in
  23 the Wizard root directory.  These should run and pass on all platforms.
  24 These are found inside of docstrings and are noted by a ``>>>`` marker.
  25 They should be written for simple, self-contained functions that would
  26 benefit from an example code usage.
  27
  28 Acceptance tests
  29 ----------------
  30
  31 These are the most useful metrics of whether or not Wizard is working:
  32 they run Wizard commands and try to see if any of the commands return
  33 a non-zero exit code (future development may allow for pre-conditions and
  34 post-conditions to be checked).  The test scripts are located in the
  35 :file:`tests` directory, and are identifiably by their suffix
  36 ``-test.sh``.  They should run out of the box on
  37 scripts servers, so long as the Wizard source tree is inside of your
  38 :file:`web_scripts` directory, and require some configuration if you
  39 plan on running them locally.
  40
  41 These test scripts are the key to ensuring that Wizard is functioning
  42 properly, and exercise most of the common code paths (and a few, though
  43 not all, of the uncommon ones).  They're organized by application name
  44 and then test name.  Every application should have a :file:`appname-install-test.sh`
  45 which can be run without any parameters; you can also specify a version
  46 number to test installing a particular version installation.  There is
  47 also :file:`appname-upgrade-test.sh`, which requires specifying a version
  48 number and tests upgrading from that version to the latest version in
  49 the repository.
  50
  51 .. note::
  52
  53     There are substantially more MediaWiki test scripts than for other applications,
  54     a mixture of MediaWiki-specific tests and more general tests of functionality.
  55     There may be some possible restructuring to reduce duplication for the
  56     general tests.
  57
  58 There are also utility scripts :file:`all.sh`, which takes a application
  59 name and a version number as parameters, and runs all of the corresponding
  60 test scripts, as well as :file:`clean.sh` which removes all test directories.
  61
  62 Custom configuration can be specified in the :file:`config` file (located at
  63 :file:`tests/config`).  This is actually a Bash script to be sourced by the
  64 real test script (:file:`tests/setup`), which exports various environment
  65 variables that Wizard will use during installation.  You should only need to
  66 set these variables if you're attempting to run these tests off of a
  67 non-scripts server.
  68
  69 Here is a sample :file:`config` file::
  70
  71     MYSQL_ARGS="-uroot -ppassword"
  72
  73     export WIZARD_WEB_HOST="localhost"
  74     export WIZARD_WEB_PATH="/wizard/tests/$TESTDIR"
  75     export WIZARD_DSN="mysql://root:password@localhost/wizard_test_$TESTID"
  76     export WIZARD_EMAIL="bob@example.com"
  77
  78 You will need to specify all of the environment variables in the
  79 :file:`config`.  Those prefixed with ``WIZARD`` are directly used by Wizard,
  80 while the ``MYSQL`` environment variables are used if a test script wants to
  81 interactive directly with a MYSQL database.  We don't quite have a good story
  82 for alternative databases in test scripts.
  83
  84 * :envvar:`WIZARD_WEB_HOST` and :envvar:`WIZARD_WEB_PATH`  indicate Wizard's
  85   configuration with respect to your web server.
  86   ``http://$WIZARD_WEB_HOST/$WIZARD_WEB_PATH`` will be the location that a newly
  87   installed application will be accessible.  You will notice that we used
  88   :envvar:`TESTDIR`; this is the directory that will be created in :file:`tests`
  89   for the application.
  90 * :envvar:`WIZARD_DSN` is the database source name, which
  91   should be used to access a MySQL database (as Wizard does not contain support
  92   for any other database system yet.) You can use :envvar:`TESTID` to uniquely
  93   identify any particular test.
  94 * :envvar:`WIZARD_EMAIL` is any email address you
  95   own that will be configured as an administrative email.