= NAME =
test_snapshot

= SYNOPSIS =
 * test_snapshot

= DESCRIPTION =
This function can be defined in the base test script for a test (fuego_test.sh), and executes commands to gather snapshot data from
the host or board, to put into the machine-snapshot.txt file.

This function is called from [[function_snapshot|snapshot]], which implements
the 'snapshot' phase of test processing.  This is done right before
the 'run' phase, and is intended to be used to capture information about
the state of the machine that might help diagnose any errors found during
a test.

If a test does not have have a test_snapshot function, then a default set
of data is collected from the board (by calling the ov_rootfs_state
function).  If desired, [[function_ov_rootfs_state|ov_rootfs_state]] (the default
status-gathering function) may be called to get the default
information, and then additional commands may be executed (usually using
the [[function_cmd|cmd]] function, to retrieve additional snapshot data
from the target.

== method of saving snapshot data ==
The variable $SNAPSHOT_FILENAME has the filename of the snapshot log file,
and this log file has been created before entry into this function.

This function can perform any operations on the host or board that are
desired, to gather state information that might be relevant to the test.
Each operation should append it's output to the file named by $SNAPSHOT_FILENAME.

== location of results ==
The snapshot data will reside in the log directory for this run, in a file
called ``machine-snapshot.txt``


= EXAMPLES =
Some sample contents are:
{{{#!YellowBox
function test_snapshot {
    echo "============================================================" >>$SNAPSHOT_FILENAME
    echo "Board state information (custom snapshot):" >>$SNAPSHOT_FILENAME
    ov_rootfs_state >>$SNAPSHOT_FILENAME
    echo "network devices status:" >>$SNAPSHOT_FILENANME
    cmd "cat /proc/net/dev" >>$SNAPSHOT_FILENAME
    return 0
}
}}}


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

$SNAPSHOT_FILENAME has the name of the snapshot file.

There are no arguments to this function.


= RETURN =
returns non-zero for error.  However, this routine should not return
an error.

= SOURCE =
Located in the base script (fuego_test.sh) for each test.  The base test scripts are located in /fuego-core/engine/tests/<test_name>.

An example path would be: ''/fuego-core/engine/tests/Functional.hello_world/fuego_test.sh'' (inside the Docker container)

= SEE ALSO =
 * [[function_cmd|cmd]], [[function_snapshot|snapshot]]