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