testkit/doc/testkit_reference.html

   1 <html>
   2   <head>
   3     <meta http-equiv="content-type" content="text/html; charset=utf-8">
   4     <title>TestKit Reference Manual</title>
   5   </head>
   6   <body vlink="purple" link="blue" lang="EN-US">
   7     <h1 style=" text-align:center">Feisty Meow® TestKit Reference Manual</h1>
   8       <h3 style=" text-align:center">Author: Chris Koeritz</h3>
   9     <address style=" text-align:center">
  10       Version 1.0 ― Updated August 14 2020</address>
  11     <h1>The Feisty Meow® TestKit</h1>
  12     <p>The TestKit is a collection of scripts that leverages the ShUnit unit
  13       testing environment.&nbsp; TestKit provides a pattern for creating test
  14       suites using a simple configuration file approach.&nbsp; Full reporting on
  15       test runs is provided in a convenient tabular format.</p>
  16     <p>Generally, writing a test script using the TestKit is a matter of
  17       minutes.&nbsp; A blank test is provided as a template, and that can be
  18       expanded with whatever test steps are needed.</p>
  19     <p>TestKit (and ShUnit) are implemented in the GNU Bash script language, but
  20       a TestKit test script can invoke external applications, written in
  21       whatever programming language or scripting tool is desired, using the
  22       standard POSIX interfaces.<br>
  23     </p>
  24     <h2> Getting the TestKit</h2>
  25     <p>Follow these steps to download and install a new "vanilla" version of the
  26       TestKit:<br>
  27     </p>
  28     <div style="border:solid windowtext 1.0pt;padding:1.0pt 4.0pt 1.0pt 4.0pt;
  29 background:#DDD9C3;margin-left:.1in;margin-right:.1in">
  30       <p class="Code-Box" style="margin-top:6.0pt;margin-right:0in;margin-bottom:6.0pt;
  31 margin-left:0in;background:#DDD9C3"><span style="font-family: monospace;">sudo
  32           mkdir /opt/feistymeow.org<br>
  33           sudo chown -R $USER /opt/feistymeow.org<br>
  34           cd /opt/feistymeow.org<br>
  35           git clone git://feistymeow.org/feisty_meow</span></p>
  36     </div>
  37     <p>This is the code used to create the Feisty Meow® version of the TestKit.</p>
  38     <p>It is possible to check out the TestKit within one's own code base, and
  39       then it is possible to retrieve an updated Feisty Meow® TestKit by running
  40       "git pull" on the "testkit" folder.&nbsp; This will get the latest version
  41       from the Feisty Meow® Codebase without disturbing whatever project's
  42       revision control repository contains the TestKit for testing.</p>
  43     <h3>Preparing the TestKit on Linux</h3>
  44     <p>Linux is the easiest environment for running the TestKit, given that the
  45       tests were built using the bash shell within a Linux environment.&nbsp; If
  46       some of the packages used in the tests are missing (such as expect and gnu
  47       awk), these may need to be installed from the appropriate repository for
  48       your Linux distribution.&nbsp; Most distributions include these packages
  49       automatically however.</p>
  50     <h3> Preparing the TestKit on Mac OS X</h3>
  51     <p>The test suite runs well on modern Macs with Intel CPUs.&nbsp; Due to
  52       some differences in the versions of a few applications on the Mac, some
  53       GNU tools may need to be installed to run the TestKit.&nbsp; These are
  54       available via the Brew installer tool. <br>
  55     </p>
  56     <h3> </h3>
  57     <h3> Preparing the TestKit on MS-Windows</h3>
  58     <p>The Cygwin Unix emulation system is required to run the TestKit on
  59       Windows.&nbsp; This package is available at: <a href="http://cygwin.com/install.html">http://cygwin.com/install.html</a></p>
  60     <p>The default packages selected by Cygwin are the starting point of the
  61       install.&nbsp; In addition to those packages, the following packages are
  62       also required (see list below).&nbsp; Rather than using the cygwin setup
  63       program for this task, the next section describes how to install Cygwin
  64       with the apt-cyg tool.&nbsp; Apt-cyg is the preferred method, since it
  65       involves less interaction with the somewhat clunky Cygwin installer.&nbsp;
  66       If necessary, it is possible to install all the packages without apt-cyg
  67       just by using the Cygwin setup program.&nbsp; To find each of these
  68       packages more easily, try switching the “View” button on the Cygwin setup
  69       program to “Full” to get an alphabetized list.</p>
  70     <div style="border:solid windowtext 1.0pt;padding:1.0pt 4.0pt 1.0pt 4.0pt;
  71 background:#DDD9C3;margin-left:.1in;margin-right:.1in">
  72       <p class="Code-Box" style="margin-top:6.0pt;margin-right:0in;margin-bottom:0in;
  73 margin-left:0in;margin-bottom:.0001pt;background:#DDD9C3">bc <br>
  74         crypt <br>
  75         cygutils <br>
  76         emacs <br>
  77         email <br>
  78         expect <br>
  79         gcc-g++<br>
  80         git <br>
  81         gitk <br>
  82         gvim <br>
  83         inetutils <br>
  84         less <br>
  85         make <br>
  86         mutt <br>
  87         ncftp <br>
  88         openssh <br>
  89         perl <br>
  90         procps<br>
  91         python <br>
  92         sharutils <br>
  93         shutdown <br>
  94         subversion <br>
  95         time <br>
  96         unzip <br>
  97         util-linux <br>
  98         vim<br>
  99         wget<br>
 100         xinit <br>
 101         xterm <br>
 102         zip </p>
 103     </div>
 104     <p>&nbsp;</p>
 105     <h3>Apt-cyg Installation Process</h3>
 106     <p>The apt-cyg program brings the convenience of the Debian and Ubuntu
 107       installer application (apt-get) to Cygwin.&nbsp; This program does require
 108       a couple of additional setup steps.&nbsp; This material is drawn from the
 109       apt-cyg home page: <a href="https://github.com/transcode-open/apt-cyg">https://github.com/transcode-open/apt-cyg</a></p>
 110     <p class="MsoListParagraphCxSpFirst" style="text-indent:-.25in">1.&nbsp;
 111       Install the basic Cygwin packages with setup.exe (rather than the long
 112       list above), but add these two packages which are not selected by default:</p>
 113     <ul>
 114       <li>subversion</li>
 115       <li>wget</li>
 116     </ul>
 117     <p class="MsoListParagraphCxSpLast" style="text-indent:-.25in">2.&nbsp;&nbsp;
 118       Download and install the apt-cyg program from within a Cygwin bash prompt:</p>
 119     <div style="border:solid windowtext 1.0pt;padding:1.0pt 4.0pt 1.0pt 4.0pt;
 120 background:#DDD9C3;margin-left:.5in;margin-right:.1in">
 121       <p class="Code-Box" style="margin-top:6.0pt;margin-right:0in;margin-bottom:6.0pt;
 122 margin-left:0in;background:#DDD9C3">lynx -source
 123         rawgit.com/transcode-open/apt-cyg/master/apt-cyg &gt; apt-cyg<br>
 124         install apt-cyg /bin</p>
 125     </div>
 126     <p class="MsoListParagraph" style="text-indent:-.25in">3.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 127       Install the packages required for the TestKit:</p>
 128     <div style="border:solid windowtext 1.0pt;padding:1.0pt 4.0pt 1.0pt 4.0pt;
 129 background:#DDD9C3;margin-left:.5in;margin-right:.1in">
 130       <p class="Code-Box" style="margin-top:6.0pt;margin-right:0in;margin-bottom:0in;
 131 margin-left:0in;margin-bottom:.0001pt;background:#DDD9C3">apt-cyg install bc
 132         crypt cygutils emacs email expect gcc-g++ git gitk gvim \<br>
 133         &nbsp; inetutils less make mutt ncftp openssh perl procps python
 134         sharutils \<br>
 135         &nbsp; shutdown time unzip util-linux vim xinit xterm zip</p>
 136     </div>
 137     <p class="MsoListParagraph" style="text-indent:-.25in">4.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 138       The installation will run for a while but then should conclude with all
 139       required packages installed.</p>
 140     <h2> Setting up a Test Suite</h2>
 141     <p>Tunning tests in TestKit uses a configuration file called
 142       “testkit.config” to define the environment and, optionally, which test
 143       scripts to run.&nbsp; This file is the main switchboard that defines where
 144       the tests will find users, home directories, queues, containers, and so
 145       forth. &nbsp;The configuration file can be specified via the environment
 146       variable “TESTKIT_CFG_FILE”.&nbsp; This variable can be set to any
 147       location, enabling the configuration file to reside in a directory other
 148       than the toolkit folder.&nbsp; If the variable is not defined, then the
 149       testing config file defaults to “$TESTKIT_ROOT/testkit.config”.</p>
 150     The TESTKIT_ROOT variable is frequently referred to in command
 151     examples.&nbsp; It is set up automatically by the prepare_tools script (see
 152     below).
 153     <h2>Running a Test Suite</h2>
 154     <p>Once the TestKit configuration file has been established, running a whole
 155       test suite can be accomplished with this command:<br>
 156     </p>
 157     <div style="border:solid windowtext 1.0pt;padding:1.0pt 4.0pt 1.0pt 4.0pt;
 158 background:#DDD9C3;margin-left:.1in;margin-right:.1in">
 159       <p class="Code-Box" style="margin-top:6.0pt;margin-right:0in;margin-bottom:6.0pt;
 160 margin-left:0in;background:#DDD9C3">&nbsp;bash <i>{TESTKIT_FOLDER}</i>/test_driver.sh
 161         </p> </div>
 162     <p>Where the <i>{TESTKIT_FOLDER}</i> should be replaced with whatever path
 163       the TestKit is stored in.</p>
 164     <p>Alternatively, if the TESTKIT_ROOT folder is already established, the
 165       tests can be run with:</p>
 166     <div style="border:solid windowtext 1.0pt;padding:1.0pt 4.0pt 1.0pt 4.0pt;
 167 background:#DDD9C3;margin-left:.1in;margin-right:.1in">
 168       <p class="Code-Box" style="margin-top:6.0pt;margin-right:0in;margin-bottom:6.0pt;
 169 margin-left:0in;background:#DDD9C3">&nbsp;bash "$TESTKIT_ROOT/test_driver.sh"</p>
 170     </div>
 171     <p></p>
 172     <h3> What to Expect From the Test Run</h3>
 173     <p>The test_driver.sh script will output a few informative lines of text
 174       before printing a table of the tests that it intends to run.</p>
 175     <p>After the test plan is shown, all of the tests listed will be executed in
 176       the order they are listed in, and they will each produce output.&nbsp;
 177       Each individual test (usually a separate bash script) produces a summary
 178       at the end of its run with a count of tests and a report of the tests
 179       success or failure.</p>
 180     <p>At the end of all the tests in the suite, the table of tests is printed
 181       again with the results for each test.&nbsp; For example, this is a test
 182       run that had no errors in any test (that's good, since it is our super
 183       simple example test):</p>
 184     <div style="border:solid windowtext 1.0pt;padding:1.0pt 4.0pt 1.0pt 4.0pt;
 185 background:#DDD9C3;margin-left:.1in;margin-right:.1in">$ cd
 186       $FEISTY_MEOW_APEX/testkit<br>
 187       $ ./test_driver.sh summary<br>
 188       ===========================================================<br>
 189       Testkit environment loaded.<br>
 190       TESTKIT_ROOT=/opt/feistymeow.org/feisty_meow/testkit<br>
 191       TESTKIT_CFG_FILE=/opt/feistymeow.org/feisty_meow/testkit/testkit.config<br>
 192       TMP=/Users/fred/.tmp<br>
 193       TEST_TEMP=/Users/fred/.tmp/testkit_logs_fred<br>
 194       ===========================================================<br>
 195       +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++<br>
 196       TestKit running from: /opt/feistymeow.org/feisty_meow/testkit<br>
 197       TestKit config file:
 198       /opt/feistymeow.org/feisty_meow/testkit/testkit.config<br>
 199       +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++<br>
 200       Full set of tests:<br>
 201       1: /opt/feistymeow.org/feisty_meow/testkit/examples/blank_test.sh<br>
 202       <br>
 203       ======================================================================<br>
 204       Wed Aug 12 14:11:00 EDT 2020: Now running test 1:
 205       /opt/feistymeow.org/feisty_meow/testkit/examples/blank_test.sh<br>
 206       &nbsp; Test output file:
 207       /Users/fred/.tmp/testkit_logs_fred/run_2020_08_12/test_log.vKf7J3<br>
 208       OK: successful test run for test
 209       /opt/feistymeow.org/feisty_meow/testkit/examples/blank_test.sh<br>
 210       <br>
 211       <br>
 212       Results table for this test run:<br>
 213       <br>
 214       01: OKAY -- /opt/feistymeow.org/feisty_meow/testkit/examples/blank_test.sh<br>
 215       <br>
 216       Total testing duration: 00:00 hh:mm (1 seconds total)<br>
 217       OK: All 1 Tests Ran Successfully.<br>
 218     </div>
 219     <p class="Textbody">The above shows the "summary" view, which does not allow
 220       the individual tests to output to the console.&nbsp; If the "summary" flag
 221       is not passed, then the output from all the test runs is also shown.</p>
 222     <p class="Textbody">Even when the summary view is used, all output files can
 223       be examined after the run.&nbsp; For example, in the above, the mentioned
 224       output file "test_log.vKf7J3" can be checked to see exactly what happened
 225       during the test.</p>
 226     <p class="Textbody">A test with a failure in it will have “FAIL” next to the
 227       test that failed, and the final output line will start with
 228       “FAILURE”.&nbsp; For example:</p>
 229     <div style="border:solid windowtext 1.0pt;padding:1.0pt 4.0pt 1.0pt 4.0pt;
 230 background:#DDD9C3;margin-left:.1in;margin-right:.1in">
 231       <p class="Code-Box" style="margin-top:6.0pt;margin-right:0in;margin-bottom:6.0pt;
 232 margin-left:0in;background:#DDD9C3">01: OKAY –
 233         AckPfft_Tests/Gorp_Tests/deslagToaster.sh<br>
 234         02: FAIL – AckPfft_Tests/Gorp_Tests/spumeMerchantry.sh<br>
 235         03: OKAY – AckPfft_Tests/Gorp_Tests/octopusLauncher.sh<br>
 236         …<br>
 237         22: OKAY -- Snargle_Tests/scramTests/scramForPetunias.sh</p>
 238       <p class="Code-Box" style="margin-top:6.0pt;margin-right:0in;margin-bottom:6.0pt;
 239 margin-left:0in;background:#DDD9C3">FAILURE: 1 Tests Failed out of 22 Tests.</p>
 240     </div>
 241     <p>A failed test will also return a non-zero value from the test execution,
 242       enabling the run of a test suite to be tested for success when launched
 243       externally, such as from a continuous integration system.</p>
 244     <h2>Loading the TestKit Environment</h2>
 245     <p>If one wishes to run individual tests within the test suite, rather than
 246       the entire suite, this is done by loading the TestKit variables into the
 247       current shell environment, like so:</p>
 248     <div style="border:solid windowtext 1.0pt;padding:1.0pt 4.0pt 1.0pt 4.0pt;
 249 background:#DDD9C3;margin-left:.1in;margin-right:.1in">
 250       <p class="Code-Box" style="margin-top:6.0pt;margin-right:0in;margin-bottom:6.0pt;
 251 margin-left:0in;background:#DDD9C3">cd <i>{TESTKIT_FOLDER}</i>&nbsp; # replace
 252         with actual location of TestKit.<br>
 253         source prepare_tools.sh prepare_tools.sh<br>
 254         source $TESTKIT_ROOT/library/process_configuration.sh<br>
 255         define_and_export_variables</p>
 256       # Show the important variables.<br>
 257       var $TESTKIT_ROOT $TESTKIT_CFG_FILE</div>
 258     <p>After loading the TestKit environment, one can execute a specific test
 259       and see its results, for example:</p>
 260     <div style="border:solid windowtext 1.0pt;padding:1.0pt 4.0pt 1.0pt 4.0pt;background:#DDD9C3;margin-left:.1in;margin-right:.1in">
 261       <p class="Code-Box" style="margin-top:6.0pt;margin-right:0in;margin-bottom:6.0pt;
 262 margin-left:0in;background:#DDD9C3">cd examples<br>
 263         bash blank_test.sh</p>
 264     </div>
 265     <p>The test will run and output its results to the console (that is, output
 266       is sent to standard out and standard error, to be more precise).</p>
 267     <p><br>
 268     </p>
 269     <h3></h3>
 270   </body>
 271 </html>