= NAME =
report

= SYNOPSIS =
 * report <test-command> [<log-filename>]

= DESCRIPTION =
This function performs the indicated command on the target device, and
records it's output to the test log.  This is commonly called
by a test's [[function_test_run|test_run]] function, to actually execute
the test on the target.

See [[Log files]] for a description of the test log on the target.

Note that the exit code from the command is preserved across the 'tee' used
to capture the output from the command, and used with the 'exit' statement
to have this be the return code from the 'report' operation.

To record the output of a command run on the Fuego host, use [[function_log_this|log_this]].

= EXAMPLES =
Here are some sample invocations:
{{{#!YellowBox
    report "hello-world.sh $HELLO_WORLD_ARG"
}}}

= ENVIRONMENT and ARGUMENTS =
The arguments to this function are:
 * $1 - the command to execute on the target
 * $2 - (optional) the filename of the test log, on the target.  If this is not specified, the value $BOARD_TESTDIR/fuego.$TESTDIR/$TESTDIR.log is used.

The following variables are used:
 * FUEGO_HOME
 * TESTDIR

These are used to construct the default test log filename on the target, if a
log filename is not specified in the positional arguments.


= RETURN =
Returns non-zero on error.

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

= SEE ALSO =
 * [[function_test_run|test_run]], [[function_report_append|report_append]], [[function_safe_cmd|safe_cmd]], [[function_log_this|log_this]]