@@ -146,6 +146,103 @@ proc testid_matches_globs {testid globs} {
#---------- test script handling ----------
+# spwan-ts IFFAIL TESTID SCRIPT-ARGS...
+#
+# Spawns the test script as a test step, and leaves it running.
+# Returns token to pass to reap-ts.
+#
+# reap-ts TOKEN [WANTSTATUS]
+#
+# Waits for the test script to finish.
+#
+# The step status is set to "pass" (if the script exits zero) or
+# IFFAIL (otherwise). (But it is not set if the script,
+# or something else, already set it to "aborted" or "broken".)
+#
+# Return value is true if that step status matches the glob
+# WANTSTATUS (which defaults to "pass"). Test failures do not
+# become Tcl exceptions and do not affect other test execution.
+#
+# run-ts IFFAIL TESTID SCRIPT-ARGS...
+#
+# Runs the test script, waiting for it to finish.
+# The step status is set as for reap-ts.
+#
+# If that step status is not "pass", throws a Tcl exception.
+#
+# Normally (eg, within the recipe), an exception causes the job
+# to be stopped as a failure (and proceed to log collection).
+# Specifically:
+# "ok" is set to "0" (which prevents most other
+# general steps from running)
+# The job status is set to IFFAIL.
+#
+# per-host-ts IFFAIL TESTID SCRIPT-ARGS...
+#
+# Runs the script (as a separate step) for each test host ident.
+# The host ident is appended to SCRIPT-ARGS. (SCRIPT-ARGS
+# should contain an even number of + items for proper testid
+# generation.)
+#
+# The scripts are run in parallel for all host idents.
+#
+# If any of the step statuses is not "pass", sets the job
+# status to IFFAIL and stops the job as a failure (as above).
+#
+# per-host-ts does nothing if the job is no longer $ok
+# (subject to IFFAIL starting with !, see below)
+#
+# IFFAIL can be
+#
+# [-][!].
+# [-][!]STATUS
+#
+# where STATUS is the job/step status to be used if the step
+# status is not as expected, and the special meanings are:
+#
+# - Only for run-ts; suprresses exception on failure.
+# ! Run this even if the job is being truncated.
+# (for per-host-ts, even if the job is no longer $ok)
+# . Shorthand for "fail"
+#
+# TESTID specifies the unique ID for this test step.
+#
+# The testid must be unique within the job; but for steps which
+# actual tests (ie, which might be subject to regression
+# analsysis, or bisection) must be stable - ie, it must not
+# change due to races nor due to future osstest changes.
+# Normally this is acheived by computing it from the
+# SCRIPT-ARGS by specifying something involving "=" or "/@".
+#
+# TESTID is processed with some substitutions (in this order):
+#
+# = at the start is replaced with "SCRIPTBASIS/@"
+# where SCRIPTBASIS is the first entry in SCRIPT-ARGS
+# with ts- removed.
+#
+# * as the whole TESTID is replaced with "SCRIPTBASIS/@(*)"
+#
+# /@ anywhere is replaced with "/ARG/ARG..."
+# (ie, "/ARG" for each ARG in SCRIPT-ARGS after the
+# script name, but see note about "+" in SCRIPT-ARGS,
+# below.)
+#
+# (*) at the end is replaced by (STEPNO)
+# where STEPNO is the step number within the job (which
+# is unique within the job, but not stable).
+#
+# SCRIPT-ARGS is the script name and its arguments, but is also
+# subject to some special processing:
+#
+# The script name should not include the ./ which is necessary
+# to find the script in the current directory. This will be
+# added implicitly.
+#
+# An argument which is precisely "+" toggles whether the
+# subsequent items in SCRIPT-ARGS are added to the expansion of
+# /@ in TESTID. (The "+" itself is not added to the arguments
+# or the testid.)
+
proc run-ts {iffail args} {
set wantstatus pass
if {[regsub {^-} $iffail {} iffail]} { set wantstatus * }
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com> --- v2: More accurate explanation of ! in IFFAIL; and mention $ok. --- sg-run-job | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+)