= NAME =
test_run

= SYNOPSIS =
Performs the actual steps needed to execute the test software on the target.

= DESCRIPTION =
This function is defined in the base test script for a test, and executes those
commands required to build the software.

When this function starts, the test program (if any) has been installed on the
target board.

== Commonly called functions or programs ==
This function can contain calls to just about any command, but there are some
common commands sed for building Linux source
 * assert_define - used to check that required test variables are defined
 * cmd - used to execute commands on the target, e.g. for test preparation
 * report - used to execute the test and save the log output (test stdout) to a file
 * report_append - used to execute another command on the target, and append the log output to the test log

Disk and filesystem tests may use the following routines:
 * hd_test_mount_prepare - mount a filesystem in preparation for a test
 * hd_test_clean_unmount - unmount a filesystem after a test had concluded

= EXAMPLES =
Some sample contents are:
{{{#!YellowBox
function test_run {
    report "cd $FUEGO_HOME/fuego.$TESTDIR; ./hello $FUNCTIONAL_HELLO_WORLD_ARG"
}
}}}

{{{#!YellowBox
function test_run {
    report "cd /tmp/fuego.$TESTDIR/target_bin; ./bin/run-all-posix-option-group-tests.sh"
}
}}}

{{{#!YellowBox
function test_run {
    assert_define BENCHMARK_TIOBENCH_MOUNT_BLOCKDEV
    assert_define BENCHMARK_TIOBENCH_MOUNT_POINT
    assert_define BENCHMARK_TIOBENCH_THREADS
    assert_define BENCHMARK_TIOBENCH_SIZE
    
    hd_test_mount_prepare $BENCHMARK_TIOBENCH_MOUNT_BLOCKDEV $BENCHMARK_TIOBENCH_MOUNT_POINT

    report "cd $FUEGO_HOME/fuego.$TESTDIR; ./tiotest -d $BENCHMARK_TIOBENCH_MOUNT_POINT -t $BENCHMARK_TIOBENCH_THREADS -f $BENCHMARK_TIOBENCH_SIZE –S"  
    report_append "cd $FUEGO_HOME/fuego.$TESTDIR; ./tiotest -d $BENCHMARK_TIOBENCH_MOUNT_POINT -t $BENCHMARK_TIOBENCH_THREADS -f $BENCHMARK_TIOBENCH_SIZE –W"  

    hd_test_clean_umount $BENCHMARK_TIOBENCH_MOUNT_BLOCKDEV $BENCHMARK_TIOBENCH_MOUNT_POINT
}
}}}

= ENVIRONMENT and ARGUMENTS =
A number of environment variables are set (see [[Core interfaces]] and [[Variables]])

However, some variables that are commonly used in this function are:
 * $TESTDIR - name of the test directory
 * $FUEGO_HOME - the directory where materials for the test are located (on the target)
   * This is usually used with $FUEGO_HOME/fuego.$TESTDIR

There are no arguments to this function.

= RETURN =
returns non-zero for error

= SOURCE =
Located in the base script for each test.  The base test scripts are located in /home/jenkins/fuego/engine/tests/<test_name>.

An example path would be: ''/home/jenkins/fuego/engine/tests/Functional.hello_world/hello_world.sh''

= SEE ALSO =
 * [[function_report|report]], [[function_report_append|report_append]], [[function_cmd|cmd]], [[function_hd_test_mount_prepare|hd_test_mount_prepare]], [[function_hd_test_clean_umount|hd_test_clean_umount]]