Added more text pieces to releng/README, updated template for new tests
This commit is contained in:
parent
01c193c95b
commit
de36d9b67f
178
releng/README
178
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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user