Execution environment for tasks¶

rhts-abort¶

rhts-abort -t <type>

Aborts the current recipe, recipe set, or job. A setup task might call this if it detects a failure that will prevent the rest of the recipe from running.

-t <type>¶

Valid values are recipe, recipeset, or job. Abort the recipe, the containing recipe set, or the entire job. This option is required.

rhts-backup¶

rhts-backup <file> [<file> ...]

Copies the given files or directories to a temporary storage area for the duration of the task. The files will be copied back to their original location at the end of the task, using the corresponding rhts-restore program.

For example, a task which needs to modify /etc/hosts could back it up before modifying it:

rhts-backup /etc/hosts
echo "127.0.0.1 testing-bad-values" >/etc/hosts
# test some more things here...

When the task finishes, rhts-restore copies the original version of /etc/hosts back, leaving the system in a clean state for the next task.

rhts-power¶

rhts-power <fqdn> <action>

Sends a power command to another system in the recipe set.

<fqdn>

FQDN of the system to be power-controlled.

<action>

Power command to send. These correspond to the power commands available in Beaker. Valid values are on, off, reboot, and interrupt.

rhts-reboot¶

Saves the harness state, and then reboots the system. Tasks should use this command instead of the conventional reboot command.

The task script should test the REBOOTCOUNT environment variable before rebooting, to avoid infinite loops. For example:

if [ "$REBOOTCOUNT" -eq 0 ] ; then
    # do some setup work here
    rhts-reboot
fi
# do the real work here

rhts-report-result¶

rhts-report-result <testname> <result> <outputfile> [<metric>]

Reports a Pass or Fail result to Beaker. A task can report multiple results (for example, for different phases or cases) but it should report at least one result.

<testname>

Test name for the result being reported. By convention the result of the entire task is reported as $TEST, and any individual phases or cases within the task are reported as a path underneath $TEST (for example, $TEST/setup, $TEST/test-case-5). However Beaker accepts any string for the test name.

<result>

Result to report. Valid values are PASS, WARN, FAIL, or SKIP.

<outputfile>

File name of the captured output or logging relevant to this result. The file will be uploaded to Beaker and made available alongside the reported result in Beaker’s interface.

<metric>

Optional integer “score” or “metric” to be shown alongside this result. Beaker assigns no meaning to this score, the task can use it for any purpose. Some example uses include: the score from a performance test run, the number of test cases executed, or the exit status of a failing command.

rhts-restore¶

Restores files which were previously backed up using rhts-backup. This command is run automatically when a task finishes, there is normally no need to invoke it explicitly in the task.

rhts-run-simple-test¶

rhts-run-simple-test [-u <user>] <testname> <command>

Runs the given command, with output redirected to $OUTPUTFILE, and reports a Pass or Fail result according to the exit status of the command. If you have another program or script which does the real work for the task (for example, a test suite runner), you can use rhts-run-simple-test as a wrapper around it.

-u <user>¶

Run the command as user.

<testname>

Test name to use when reporting the result to Beaker. See rhts-report-result.

<command>

Command to run. Note that shell word splitting is applied to command, so any additional arguments should be passed as a single word.

rhts-submit-log¶

rhts-submit-log -l <file>

Uploads a log file to Beaker. The file will be available in the Beaker results for the current task.

rhts-sync-block¶

rhts-sync-block -s <state> [--timeout <timeout>] [--any] <fqdn> [<fqdn> ...]

Blocks until the given systems in this recipe set have reached a certain state. Use this command, along with rhts-sync-set, to synchronize between systems in a multihost recipe set.

Refer to Multihost tasks for a more detailed guide.

-s <state>¶

Wait for the given state. If this option is repeated, the command will return when any of the states has been reached. This option is required.

--timeout <timeout>¶

Return a non-zero exit status after timeout seconds if the state has not been reached. By default no timeout is enforced and the command will block until either the given state is reached on all specified systems or the recipe is aborted by the local or external watchdog.

--any¶

Return when any of the systems has reached the given state. By default, this command blocks until all systems have reached the state.

<fqdn> [<fqdn> ...]

FQDN of the systems to wait for. At least one FQDN must be given. Use the role environment variables to determine which FQDNs to pass.

rhts-sync-set¶

rhts-sync-set -s <state>

Sets the given state for this system. Other systems in the recipe set can use rhts-sync-block to wait for a state to be set on other systems.

States are scoped to the current task. That is, states set by the current task will have no effect in subsequent tasks. You can use the matching commands rhts-recipe-sync-set and rhts-recipe-sync-block to set and wait for states that are global for the recipe instead.

Internal commands¶

The following commands are used internally by the harness and should not be invoked by tasks directly:

• rhts-db-submit-result
• rhts-extend
• rhts-system-info
• rhts-test-checkin
• rhts-test-update