X-Git-Url: https://feistymeow.org/gitweb/?a=blobdiff_plain;f=testkit%2Fdoc%2Ftestkit_reference.html;fp=testkit%2Fdoc%2Ftestkit_reference.html;h=ea9e92272776e952f0678a6c973cbff26b8ace42;hb=d46483c93ecc9a4ef7d80656d23bd0891ddf5ac6;hp=0000000000000000000000000000000000000000;hpb=4e15bc3b03c452086296b0b2e8dab709f34b5957;p=feisty_meow.git diff --git a/testkit/doc/testkit_reference.html b/testkit/doc/testkit_reference.html new file mode 100644 index 00000000..ea9e9227 --- /dev/null +++ b/testkit/doc/testkit_reference.html @@ -0,0 +1,268 @@ + +
+ +The TestKit is a collection of scripts that leverages the ShUnit unit + testing environment. TestKit provides a pattern for creating test + suites using a simple configuration file approach. Full reporting on + test runs is provided in a convenient tabular format.
+Generally, writing a test script using the TestKit is a matter of + minutes. A blank test is provided as a template, and that can be + expanded with whatever test steps are needed.
+TestKit (and ShUnit) are implemented in the GNU Bash script language, but
+ a TestKit test script can invoke external applications, written in
+ whatever programming language or scripting tool is desired, using the
+ standard POSIX interfaces.
+
Follow these steps to download and install the Feisty Meow TestKit:
+
sudo
+ mkdir /opt/feistymeow.org
+ sudo chown -R $USER /opt/feistymeow.org
+ cd /opt/feistymeow.org
+ git clone git://feistymeow.org/feisty_meow
Linux is the easiest environment for running the TestKit, given that the + tests were built using the bash shell within a Linux environment. If + some of the packages used in the tests are missing (such as expect and gnu + awk), these may need to be installed from the appropriate repository for + your Linux distribution. Most distributions include these packages + automatically however.
+The test suite runs well on modern Macs with Intel CPUs. Due to
+ some differences in the versions of a few applications on the Mac, some
+ GNU tools may need to be installed to run the TestKit. These are
+ available via the Brew installer tool.
+
The Cygwin Unix emulation system is required to run the TestKit on + Windows. This package is available at: http://cygwin.com/install.html
+The default packages selected by Cygwin are the starting point of the + install. In addition to those packages, the following packages are + also required (see list below). Rather than using the cygwin setup + program for this task, the next section describes how to install Cygwin + with the apt-cyg tool. Apt-cyg is the preferred method, since it + involves less interaction with the somewhat clunky Cygwin installer. + If necessary, it is possible to install all the packages without apt-cyg + just by using the Cygwin setup program. To find each of these + packages more easily, try switching the âViewâ button on the Cygwin setup + program to âFullâ to get an alphabetized list.
+bc
+ crypt
+ cygutils
+ emacs
+ email
+ expect
+ gcc-g++
+ git
+ gitk
+ gvim
+ inetutils
+ less
+ make
+ mutt
+ ncftp
+ openssh
+ perl
+ procps
+ python
+ sharutils
+ shutdown
+ subversion
+ time
+ unzip
+ util-linux
+ vim
+ wget
+ xinit
+ xterm
+ zip
+
The apt-cyg program brings the convenience of the Debian and Ubuntu + installer application (apt-get) to Cygwin. This program does require + a couple of additional setup steps. This material is drawn from the + apt-cyg home page: https://github.com/transcode-open/apt-cyg
+1. + Install the basic Cygwin packages with setup.exe (rather than the long + list above), but add these two packages which are not selected by default:
+2. + Download and install the apt-cyg program from within a Cygwin bash prompt:
+lynx -source
+ rawgit.com/transcode-open/apt-cyg/master/apt-cyg > apt-cyg
+ install apt-cyg /bin
3. + Install the packages required for the TestKit:
+apt-cyg install bc
+ crypt cygutils emacs email expect gcc-g++ git gitk gvim \
+ inetutils less make mutt ncftp openssh perl procps python
+ sharutils \
+ shutdown time unzip util-linux vim xinit xterm zip
4. + The installation will run for a while but then should conclude with all + required packages installed.
+Tunning tests in TestKit uses a configuration file called + âtestkit.configâ to define the environment and, optionally, which test + scripts to run. This file is the main switchboard that defines where + the tests will find users, home directories, queues, containers, and so + forth. The configuration file can be specified via the environment + variable âTESTKIT_CFG_FILEâ. This variable can be set to any + location, enabling the configuration file to reside in a directory other + than the toolkit folder. If the variable is not defined, then the + testing config file defaults to â$TESTKIT_ROOT/testkit.configâ.
+ The TESTKIT_ROOT variable is frequently referred to in command + examples. It is set up automatically by the prepare_tools script (see + below). +Once the TestKit configuration file has been established, running a whole
+ test suite can be accomplished with this command:
+
bash {TESTKIT_FOLDER}/test_driver.sh +
Where the {TESTKIT_FOLDER} should be replaced with whatever path + the TestKit is stored in.
+Alternatively, if the TESTKIT_ROOT folder is already established, the + tests can be run with:
+bash "$TESTKIT_ROOT/test_driver.sh"
+The test_driver.sh script will output a few informative lines of text + before printing a table of the tests that it intends to run.
+After the test plan is shown, all of the tests listed will be executed in + the order they are listed in, and they will each produce output. + Each individual test (usually a separate bash script) produces a summary + at the end of its run with a count of tests and a report of the tests + success or failure.
+At the end of all the tests in the suite, the table of tests is printed + again with the results for each test. For example, this is a test + run that had no errors in any test (that's good, since it is our super + simple example test):
+The above shows the "summary" view, which does not allow + the individual tests to output to the console. If the "summary" flag + is not passed, then the output from all the test runs is also shown.
+Even when the summary view is used, all output files can + be examined after the run. For example, in the above, the mentioned + output file "test_log.vKf7J3" can be checked to see exactly what happened + during the test.
+A test with a failure in it will have âFAILâ next to the + test that failed, and the final output line will start with + âFAILUREâ. For example:
+01: FAIL â
+ AckPfft_Tests/Gorp_Tests/deslagToaster.sh
+ 02: OKAY â AckPfft_Tests/Gorp_Tests/spumeMerchantry.sh
+ 03: OKAY â AckPfft_Tests/Gorp_Tests/octopusLauncher.sh
+ â¦
+ 22: OKAY -- Snargle_Tests/scramTests/scramForPetunias.sh
FAILURE: 1 Tests Failed out of 22 Tests.
+A failed test will also return a non-zero value from the test execution, + enabling the run of a test suite to be tested for success when launched + externally, such as from a continuous integration system.
+If one wishes to run individual tests within the test suite, rather than + the entire suite, this is done by loading the TestKit variables into the + current shell environment, like so:
+cd {TESTKIT_FOLDER} # replace
+ with actual location of TestKit.
+ source prepare_tools.sh prepare_tools.sh
+ source $TESTKIT_ROOT/library/process_configuration.sh
+ define_and_export_variables
After loading the TestKit environment, one can execute a specific test + and see its results, for example:
+cd examples
+ bash blank_test.sh
The test will run and output its results to the console (that is, output + is sent to standard out and standard error, to be more precise).
+
+