function run test

NAME [edit section]

run_test

SYNOPSIS [edit section]

Run a Fuego test using "ftc run-test"

DESCRIPTION [edit section]

This function can be used by a test to run another "nested" test. It is used primarily by batch tests to execute the sub-tests (child tests) that are part of the batch.

This runs the test on the board defined by $NODE_NAME, which is usually the same board as the parent (ie calling) test.

Usually, the caller will define the variable FUEGO_BATCH_ID, which is used to assign the sub-test to a group of tests. If FUEGO_BATCH_ID is not defined on entry to the function, it will be set to a value using the function allocate_next_batch_id.

It is possible to control the timeout of the test using an 'ftc run-test' argument, or by setting the variable DEFAULT_TIMEOUT.

The result of the test is output and logged to the host-side log for the test. The format of the result line is similar to TAP13, but with a prefix, like so:

[[$FUEGO_BATCH_ID]] (ok|not ok) $TC_NUM $TC_NAME

That is, the line consists of the batch id in double-square brackets, followed by the result string (either 'ok' or 'not ok') followed by the testcase number and testcase name.

You can control both the testcase number and testcase name explicitly using variables TC_NUM and TC_NAME, but if these are not specified the function will define them for you (and increment TC_NUM for you automatically).

EXAMPLES [edit section]

Here are some sample invocations:

Simple invocation:

run_test Functional.hello_world

Invocation with FUEGO_BATCH_ID, and using 'ftc run-test' arguments

FUEGO_BATCH_ID="my-prefix-$(allocate_next_batch_id)"
run_test Functional.hello_world -s hello-random
run_test Functional.LTP -s default --timeout 30m
run_test Functional.stress --reboot true

Any 'ftc run-test' arguments can be used. The example above uses:

-s to specify a spec
--timeout to specify a timeout for the nested test
--reboot to request a reboot prior to the nested test

Invocation showing use of TC_NAME to set the testcase name for each sub-test:

FUEGO_BATCH_ID="my-prefix-$(allocate_next_batch_id)"
TC_NAME="cpu-performance"
run_test Benchmark.Dhrystone
TC_NAME="filesystem-performance"
run_test Benchmark.IOzone -s nopread

Invocation showing use of DEFAULT_TIMEOUT, and explicit timeout:

DEFAULT_TIMEOUT="5m"
run_test Functional.hello_world
run_test Functional.bc
run_test Functional.LTP --timeout 30m

The timeout for tests 'hello_world' and 'bc' would be 5 minutes, while the timeout for Functional.LTP would be 30 minutes.

ENVIRONMENT and ARGUMENTS [edit section]

Positional arguments:

$1 is the name of the test to run
$2.. are arguments to use with 'ftc run-test'

Environment variables:

NODE_NAME is the name of the board to run the test on
FUEGO_BATCH_ID (optional) - is an string used to identify the current batch. If not defined, a string is allocated using allocate_next_batch_id
DEFAULT_TIMEOUT (optional) indicates the timeout for the test. If not defined, a value of "30m" is used. The DEFAULT_TIMEOUT value will be used when none of the positional arguments defines a '--timeout' value for the test.
TC_NUM (optional) is the number of the sub-test. If not defined, a value of '1' is used.
TC_NAME (optional) is the name of the testcase. If not defined, a string consisting of the test name and the positional arguments is constructed and used as the testcase name.

RETURN [edit section]

Returns non-zero on error.

SOURCE [edit section]

Located in scripts/functions.sh