From 135d6cb56033aa111cc3c7b72df1cedc75626866 Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Wed, 3 Aug 2011 17:35:48 +0000 Subject: [PATCH] Added more text pieces to releng/README, updated template for new tests --- libisoburn/trunk/releng/README | 178 +++++++++++++++++++++++---- libisoburn/trunk/releng/template_new | 132 +++++++++++++++----- 2 files changed, 258 insertions(+), 52 deletions(-) diff --git a/libisoburn/trunk/releng/README b/libisoburn/trunk/releng/README index ca61b3aa..100410c7 100644 --- a/libisoburn/trunk/releng/README +++ b/libisoburn/trunk/releng/README @@ -9,7 +9,16 @@ Copyright (C) 2011 George Danchev, Thomas Schmitt Provided under GPL version 2 or later. ------------------------------------------------------------------------------ ->>> introduce the test suite, +The impatient tester will build libisoburn and then do + cd ./releng + ./run_all_auto -x ../xorriso/xorriso + +More patient testers will first read the following description. + + + The test suite + ++++ introduce the test suite, Directory ./releng of libisoburn contains a collection of test scripts and auxiliary data. They exercise some typical use cases of building libisoburn @@ -17,7 +26,7 @@ applications and running the ISO 9660 filesystem manipulation and CD/DVD/BD burn program xorriso. ->>> inform about intended audience and resource needs, ++++ inform about resource needs, It is assumed that libburn and libisofs are installed, so that libisoburn can be configured and built. It is not mandatory that libisoburn is already @@ -25,7 +34,7 @@ installed. The tests may use an installed xorriso program as well as a freshly built one. ->>> auto and manual tests ++++ auto and manual tests There are two groups of test scripts: @@ -39,7 +48,10 @@ There are two groups of test scripts: system privileges beyond the reach of a sandbox user, and operate the mechanics of a CD drive. ->>> tell how to run the tests, + ++++ tell how to run the tests, + + Running automated tests The test scripts expect to get run while the working directory is ./releng @@ -60,42 +72,160 @@ or if you want to use an installed xorriso program: ./run_all_auto -x $(type -p xorriso) ++++ General options -x , -k, -f, -c, -h, -- + +There are several options which work with run_all_auto and any single test. + -x absolute or relative path to xorriso binary to be run. + -k keep self-generated data. + -c cleanup temporary data kept from previous run and exit. + -f simulate failure. + -- end of general options, begin of test specific options. +After option "--", there may be given options which are specific to +particular manually executable test scripts. + + + Manually executable tests + >>> list of manual tests -Currently there are the folling tests which should have the attention of -the user or require sysadmin considerations before they get run: +Currently there are the following tests which should have the attention of +the user or require sysadmin considerations before they are run: - ./manual_isojigdo -x ../xorriso/xorriso -Exercises the production of a bootable Debian GNU/Linux image and its Jigdo -files. This test downloads a Debian daily image for i386 of about 70 MB, -extracts its content and composes a new image. -Thus it needs about 250 MB of disk space in releng/releng_generated_data . +./manual_isojigdo -x ../xorriso/xorriso + Exercises the production of a bootable Debian GNU/Linux image and its Jigdo + files. This test downloads a Debian daily image for i386 of about 70 MB, + extracts its content and composes a new image. + Thus it needs about 250 MB of disk space in releng/releng_generated_data . + This test will only work with GNU xorriso or if libjte was installed already + when libisofs was built. libjte is part of package jigit, version >= 1.18, + available at: + http://www.einval.com/~steve/software/JTE/ - ./manual_devices -x ../xorriso/xorriso -Exercises listing of all accessible optical drives and the examination of -a one of these drives. The user needs the permission to operate the CD -drives. This might involve the need for superuser authority. -The media tray of the examined drive will get loaded if it is not already. +./manual_devices -x ../xorriso/xorriso [-- [--dev device_file_to_use]] + Exercises listing of all accessible optical drives and the examination of + a one of these drives. The user needs the permission to operate the CD + drives. This might involve the need for superuser authority. + The media tray of the examined drive will get loaded if it is not already. + If no option --dev is given, then the user gets asked which of the listed + drives to examine more closely. + +>>> ./manual_burn -x ../xorriso/xorriso [-- [--dev device_file_to_use] +>>> [--what ...directory...]] +>>> burns the content of the directory given with --what onto re-usable +>>> media: CD-RW, DVD-RW, DVD-RAM, DVD+RW, BD-RE. +>>> Other media types get refused. +>>> Data, which are possibly present on the media, get overwritten. >>> ./run_all_manual +>>> + Any auto_* script can be run on its own, regardless. +>>> List auto tests + +>>> + All scripts support -h >>> give hints what to do with FAIL results. + +---------------------------------------------------------------------------- + + Creating a new test script + ++++ * DELIVERING A NEW TEST SCRIPT ++++ + Start a new test script over the top of template_new_releng ++++ + Each completed script starts with auto_ or manual_ prefix + +If you want to provide an own test, manual or auto, then first invent a name +for it + test_name="releng/manual_"...some.name... +or + test_name="releng/auto_"...some.name... +Then copy file releng/template_new to $test_name . +Edit $test_name and process any line that begins by "# === TEMPLATE:". +Do what the line prescribes and then remove it from the script. You are +not done as long as such a line remains. + ++++ + Each script' self-generated data are to be stored in ++++ ./releng_generated_data/scriptname/ directory + +Your test must not start if no file ./inc/releng_getopts.inc exists, +i.e. if the current working direcoty is not ./releng. +If your test creates own files on disk, then it must do this underneath +directory ./releng_generated_data/$test_name (resp. $GEN_DATA_DIR, see below). + ++++ + Throw FAIL string to stdout if any failure is detected ++++ + Return exit code 0 on success, non-zero on failure ++++ + Use different exit codes for any failure (range 0-31) + +In case of failure, issue a line to stdout that begins by the word "FAIL", +and make sure that the test script finally returns a non-zero exit value. +This value should be between 1 and 28. Each type of failure should have its +own exit value. +Predefined are: + 31 = Unknown option or unusable argument with known option + 30 = Unexpected state of own directory for self generated files + 29 = Not in ./releng directory or missing essential parts of ./releng + + + General options, variables, and functions + ++++ inc/releng_getopts.inc variables, functions, initializations + +The code piece inc/releng_getopts.inc should get executed inline at the +start of a test script. +It initializes the following variables and sets some of them according +to the general options of the test suite: + SELF basename $0 + GEN_DATA_DIR releng_generated_data/${SELF} + RELENG_XORRISO Path to xorriso binary. "" or "0" means no xorriso. + Default "0". Adjustable by option -x. + SIMULATE_FAILURE 0=normal operation, 1=test script shall simulate a failure. + Default 0. Setable to 1 by option -f. + CLEANUP 0=do not cleanup temporary data, 1=normal operation + Default 1. Setable to 0 by option -k. + SPECIFIC_HELP 0=normal operation, 1=print help text of script and exit 0 + Default 0. Setable to 1 by option -h + +The code piece inc/releng_getopts.inc defines the follwoing functions +for use by the single tests: + + print_help Prints the help text for general options. + + check_for_xorriso [-x] + Will exit with value 31 if no path to a xorriso binary + was defined by option -x of ./run_all_auto or a single + test. + Option -x of check_for_xorriso additionally tests whether + the given path leads to an executable program. + + cleanup Removes the directory tree GEN_DATA_DIR after making + some safety checks. + + boldify Try to set the terminal mode for future output to a more + noticable style of writing. + unboldify Reset terminal mode to normal style of writing. + + + Specific options + ++++ + Keep the newly added script options in sync with other scripts + +Options which are specific to the test should begin with a double dash. +They may have further arguments. +Implement them in the prepared interpreter loop which begins after line + next_is=ignore + +Specific options shall only be interpreted by tests which get run manually. +If you plan to introduce a specific option, look at the description of +existing tests whether one of them would match your needs. In that case, +please re-use the name of that existing option. + + ============================================================================= TODO: -* move auto_isojigdo to manual_isojigdo - because of its resource consumption - -* Remove NOTE|DEBUG|ALL from run_all_auto event class list - * Delete debian-testing-i386-businesscard.iso with ./run_all_auto -c -* manual_isojigdo proposes to run manual checks after it removed the - generated images. - * Have a script ./run_all_manual * derive a GNU xorriso test suite from libisoburn test suite diff --git a/libisoburn/trunk/releng/template_new b/libisoburn/trunk/releng/template_new index 6487b727..65370ade 100755 --- a/libisoburn/trunk/releng/template_new +++ b/libisoburn/trunk/releng/template_new @@ -1,49 +1,125 @@ #!/bin/bash # Copyright 2011 George Danchev +# Copyright 2011 Thomas Schmitt +# === TEMPLATE: Add your own copyright here +# # Licensed under GNU GPL version 2 or later +# === TEMPLATE: Remove this remark before releasing this script. +# +# This is a template for creating a new libisoburn/releng test. +# It is supposed that you have read releng/README before you begin to work +# here. +# +# Step 1: Invent a name for your test +# test_name="manual_"...some.name... +# or +# test_name="auto_"...some.name... +# +# Step 2: Copy releng/template_new to $test_name +# +# Step 3: Edit $test_name and process any line that begins by +# "# === TEMPLATE:". Do what the line prescribes and then remove it +# from the script. You are not done as long as such a line remains. +# +# === TEMPLATE: End of remark to remove + set -e -not_in_releng_exit() { - printf "\nPlease execute the tests from releng directory.\n\n" - exit 1 -} - -print_specific_help() { -cat << HLP -Specific options: - none yet. -Overview: - template. -HLP -} - -# Include common bits -. inc/releng_getopts.inc || not_in_releng_exit - -# -if test "$SPECIFIC_HELP" = 1; then - print_specific_help - exit 0 +getopts_inc=inc/releng_getopts.inc +test -e ./inc/releng_getopts.inc +then + . "$getopts_inc" + + if test "$SPECIFIC_HELP" = 1 + then + print_specific_help + exit 0 + fi +else + echo >&2 + echo "File not found: $getopts_inc" >&2 + echo "Are we in the ./releng directory of a libisoburn SVN checkout ?" >&2 + echo "(Please execute the tests from that ./releng directory.)" >&2 + echo >&2 + exit 29 fi +# Include common bits and interpret standard options +# as listed by function print_help +. inc/releng_getopts.inc + + +# === TEMPLATE: Decide whether the test will have own options, +# === TEMPLATE: apart from those interpreted by inc/releng_getopts.inc +# === TEMPLATE: If not, then remove this interpreter code. +# Set default values for specific option variables. E.g.: +# dev= +# Interpret specific options, they begin after the first --. +next_is=ignore +for i in "$@" +do + if test "$next_is" = "ignore" + then + if test "$i" = "--" + then + next_is="" + fi + +# === TEMPLATE: Implement interpretation of specific options. Like: +# elif test "$next_is" = "dev" +# then +# dev="$i" +# next_is="" +# elif test "$i" = "--dev" +# then +# next_is="dev" + + else + echo >&2 + echo "Unknown test specific option: $i" >&2 + print_help + print_specific_help + exit 31 + fi +done +# === TEMPLATE: End of own option interpreter code. + + # Each test should decide whether or not it needs # a xorriso binary to test, since some do compilations only. -if [ ! -x $RELENG_XORRISO ]; then - print_help - printf "\n${SELF}: -x absolute or relative path to binary to be run.\n\n" - exit 31 -fi +# === TEMPLATE: Decide whether you need a xorriso program. +# === TEMPLATE: If not, then remove this function call +check_for_xorriso -x + # check data dir, if any and after checking -x xorriso +# === TEMPLATE: Decide whether your test will possibly create own files. +# === TEMPLATE: If yes, then make sure to remove this directory if not +# === +# === TEMPLATE: If not, then remove this if ... fi statement. if [ -d "${GEN_DATA_DIR}" ]; then printf "\n${SELF}: directory %s exists!" ${GEN_DATA_DIR} printf "\n${SELF}: use '${SELF} -c' to remove.\n" - exit 8 + exit 30 else mkdir "${GEN_DATA_DIR}" fi + ##################################################################### -exit 1 + + +# === TEMPLATE: Perform your test activities here. + + +# === TEMPLATE: In case of failure, issue a line to stdout that begins by +# === TEMPLATE: the word "FAIL", and make sure that the test script finally +# === TEMPLATE: returns a non-zero exit value. +# === TEMPLATE: 31 = Unknown option or unusable argument with known option +# === TEMPLATE: 30 = Unexpected state of own directory for self generated files +# === TEMPLATE: 29 = Not in ./releng directory or missing essential parts +# === TEMPLATE: 1 to 28 = test specific exit values + +exit 0