Added more text pieces to releng/README, updated template for new tests

This commit is contained in:
Thomas Schmitt 2011-08-03 17:35:48 +00:00
parent 504205de79
commit 135d6cb560
2 changed files with 258 additions and 52 deletions

View File

@ -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

View File

@ -1,49 +1,125 @@
#!/bin/bash
# Copyright 2011 George Danchev <danchev@spnet.net>
# Copyright 2011 Thomas Schmitt <scdbackup@gmx.net>
# === 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