= NAME =
run_test

= SYNOPSIS =
Run a Fuego test using "ftc run-test"

= DESCRIPTION =
This function can be used by a test to run another "nested" test.
It is used primarily by [[Using Batch Tests|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
[[function_allocate_next_batch_id|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 =
Here are some sample invocations:

Simple invocation:
{{{#!YellowBox
run_test Functional.hello_world
}}}

----
Invocation with FUEGO_BATCH_ID, and using 'ftc run-test' arguments 
{{{#!YellowBox
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:
{{{#!YellowBox
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:

{{{#!YellowBox
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 =
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 [[function_allocate_next_batch_id|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 =
Returns non-zero on error.

= SOURCE =
Located in ''scripts/functions.sh''

= SEE ALSO =
 * [[Using Batch Tests]], [[function_allocate_next_batch_id|allocate_next_batch_id]], [[function_test_run|test_run]]