- introduction
- internal
  - _calculate_clickpoint
  - init
  - set_distribution
- video output handling
  - save_screenshot
  - record_soft_failure
  - record_info
  - force_soft_failure
  - assert_screen
  - check_screen
  - match_has_tag
  - assert_and_click
  - click_lastmatch
  - assert_and_dclick
  - wait_screen_change
  - assert_screen_change
  - wait_still_screen
  - assert_still_screen
- test variable access
  - get_var
  - get_required_var
  - set_var
  - check_var
  - get_var_array
  - check_var_array
- script execution helpers
  - is_serial_terminal
  - wait_serial
  - x11_start_program
  - assert_script_run
  - script_run
  - background_script_run
  - assert_script_sudo
  - script_sudo
  - script_output
  - save_tmp_file
  - get_test_data
  - validate_script_output
  - become_root
  - ensure_installed
  - hashed_string
- keyboard support
  - send_key
  - hold_key
  - release_key
  - send_key_until_needlematch
  - type_string
  - type_password
  - enter_cmd
- mouse support
  - mouse_set
  - mouse_click
  - mouse_dclick
  - mouse_tclick
  - mouse_hide
  - mouse_drag mouse_drag([$startpoint, $endpoint, $startx, $starty, $endx, $endy, $button, $timeout]);
- multi console support
  - add_console
  - select_console
  - console
  - reset_consoles
  - current_console
- audio support
  - start_audiocapture
  - assert_recorded_sound
  - check_recorded_sound
- miscellaneous
  - power
  - check_shutdown
  - assert_shutdown
  - eject_cd
  - disconnect_usb
  - switch_network
  - save_memory_dump
  - save_storage
  - freeze_vm
  - resume_vm
  - parse_junit_log
  - parse_extra_log
- log and data upload and download helpers
  - diag
  - host_ip
  - autoinst_url
  - data_url
  - upload_logs
  - upload_asset
  - compat_args
  - show_curl_progress_meter
  - backend_get_wait_still_screen_on_here_doc_input
  - get_username, set_username
  - get_realname, set_realname
  - get_password, set_password
  - get_serialdev, set_serialdev

# introduction

This test API module provides methods exposed by the os-autoinst backend to be used within tests.

Many methods define a timeout parameter which can be scaled by setting the `TIMEOUT_SCALE` variable in the test settings which are read by the isotovideo process. The scale parameter can be used based on performance of workers to prevent false positive timeouts based on differing worker performance.

os-autoinst is used in the openQA project. For more information on how to use openQA, please visit http://open.qa/documentation

# internal

## _calculate_clickpoint

This subroutine is used to by several subroutines dealing with mouse clicks to calculate a clickpoint, when only the needle area is available. It takes the area coordinates and returns the configured clickpoint or else the center of that area. It is meant to be a helper subroutine not available to be used in tests.

## init

Used for internal initialization, do not call from tests.

## set_distribution

    set_distribution($distri);

Set distribution object.

You can use distribution object to implement distribution specific helpers.

# video output handling

## save_screenshot

    save_screenshot;

Saves screenshot of current SUT screen.

## record_soft_failure

    record_soft_failure($reason);

Record a soft failure on the current test modules result. The result will still be counted as a success. Use this to mark where workarounds are applied. Takes a `$reason` string which is recorded in the log file. See `force_soft_failure` to forcefully override a failed test module status from a `post_fail_hook` or `record_info` when the status should not be influenced.

## record_info

    record_info($title [, $output] [, result => $result] [, resultname => $resultname]);

Example:

    record_info('workaround', "we know what we are doing");

Record a generic step result on the current test modules. This is meant for informational purposes to be interpreted by a displaying system. For example openQA can show a info box as part of the job results details. Use this instead of `record_soft_failure` for example when you do not want to mark the job as a softfail. The optional value `$result` can be 'ok' (default), 'fail', 'softfail'. `$resultname` can be specified for the additional name tag on the result file.

## force_soft_failure

    force_soft_failure($reason);

Similar to `record_soft_failure` but can be used to override the test module status to softfail from a `post_fail_hook` if the module would be set to fail otherwise. This can be used for easier tracking of known issues without needing to handle failed tests a lot.

## assert_screen

    assert_screen($mustmatch [, [$timeout] | [timeout => $timeout]] [, no_wait => $no_wait]);

Wait for needle with tag `$mustmatch` to appear on SUT screen. `$mustmatch` can be string or `ARRAYREF` of string (`['tag1', 'tag2']`). The maximum waiting time is defined by `$timeout`. It is recommended to use a value lower than the default timeout only when explicitly needed. `assert_screen` is not very suitable for checking performance expectations. Under the normal circumstance of the screen being shown this does not imply a longer waiting time as the method returns as soon as a successful needle match occurred.

Note when using multiple tags the method returns on the first match and an additional `assert_screen` may be needed for consecutive screens.

Specify `$no_wait` to run the screen check as fast as possible that is possibly more than once per second which is default. Select this to check a screen which can change in a range faster than 1-2 seconds not to miss the screen to check for.

Returns matched needle or throws `FailedNeedle` exception if $timeout timeout is hit. Default timeout is 30s.

## check_screen

    check_screen($mustmatch [, [$timeout] | [timeout => $timeout]] [, no_wait => $no_wait]);

Similar to `assert_screen` but does not throw exceptions. Use this for optional matches. Check `assert_screen` for parameters.

Unlike `assert_screen` it is recommended to use the lowest possible timeout to prevent needless waiting time in case no match is expected behaviour. In general a value of 0s for the timeout should suffice, that is only checking once with no waiting time. In most cases a check_screen with a higher timeout can be replaced by `assert_screen` with multiple tags using an `ARRAYREF` in combination with `match_has_tag` or another synchronization call in before, for example `wait_screen_change` or `wait_still_screen`.

Returns matched needle or `undef` if timeout is hit. Default timeout is 0s.

## match_has_tag

    match_has_tag($tag);

Returns true (1) if last matched needle has `$tag`, false (0) if last matched needle does not have `$tag`, and `undef` if no needle has yet been matched at the time of the call.

## assert_and_click

    assert_and_click($mustmatch [, timeout => $timeout] [, button => $button] [, clicktime => $clicktime ] [, dclick => 1 ] [, mousehide => 1 ] [, point_id => $id ]);

Wait for needle with `$mustmatch` tag to appear on SUT screen. Then click `$button` at the "click_point" position as defined in the needle JSON file, or - if the JSON has not explicit "click_point" - in the middle of the last needle area. If `$dclick` is set, do double click instead. `$mustmatch` can be string or `ARRAYREF` of strings (`['tag1', 'tag2']`). `$button` is by default `'left'`. `'left'` and `'right'` is supported. If `$mousehide` is true then always move mouse to the 'hidden' position after clicking to prevent to hide the area where the user wants to assert/click in the second step. If `$point_id` is specified, the clickpoint used will be the one with a matching ID.

Throws `FailedNeedle` exception if `$timeout` timeout is hit. Default timeout is 30s.

## click_lastmatch

    click_lastmatch([, button => $button] [, clicktime => $clicktime ] [, dclick => 1 ] [, mousehide => 1 ] [, point_id => $id ]);

Click `$button` at the "click_point" position as defined in the needle JSON file of the last matched needle, or - if the JSON has not explicit "click_point" - in the middle of the last match area. If `$dclick` is set, do double click instead. Supported values for `$button` are `'left'` and `'right'`, `'left'` is the default. If `$mousehide` is true then always move mouse to the 'hidden' position after clicking to prevent to disturb the area where the user wants to assert/click in the second step, otherwise move the mouse back to its previous position. If `$mousehide` is -1 then keep mouse in the place where it clicked. If `$point_id` is specified, the clickpoint used will be the one with a matching ID.

## assert_and_dclick

    assert_and_dclick($mustmatch [, timeout => $timeout] [, button => $button] [, clicktime => $clicktime ] [, dclick => 1 ] [, mousehide => 1 ]);

Alias for `assert_and_click` with `$dclick` set.

## wait_screen_change

    wait_screen_change(CODEREF [,$timeout [, similarity_level => 50, no_wait => 0]]);

Wrapper around code that is supposed to change the screen. This is the opposite to `wait_still_screen`. Make sure to put the commands to change the screen within the block to avoid races between the action and the screen change. `wait_screen_change` waits for a screen change after `CODEREF` was executed.

Example:

    wait_screen_change {
       send_key 'esc';
    };

Notice: If you use the second parameter, you could get the following warning

    Useless use of private variable in void context

To avoid it, use parentheses for the function call and the reserved word 'sub' for the callback subroutine block.

    wait_screen_change(sub {
      send_key 'esc';
    }, 15);

To lower the backend's internal update interval while looking for screen changes, use the optional parameter `no_wait => 1`. This makes the test execution faster if the screen change is expected to happen (almost) immediately.

Returns true if screen changed or false on timeout. Default timeout is 10s. Default similarity_level is 50.

## assert_screen_change

    assert_screen_change(CODEREF [,$timeout]);

Run `CODEREF` with `wait_screen_change` but `die` if screen did not change within timeout. Look into `wait_screen_change` for details.

Example:

    assert_screen_change { send_key 'alt-f4' };

## wait_still_screen

    wait_still_screen([$stilltime | [stilltime => $stilltime]] [, $timeout] | [timeout => $timeout]] [, similarity_level => $similarity_level] [, no_wait => $no_wait]);

Wait until the screen stops changing.

See `assert_screen` for `$no_wait`.

Returns true if screen is not changed for given `$stilltime` (in seconds) or undef on timeout. Default timeout is 30s, default stilltime is 7s.

## assert_still_screen

    assert_still_screen([$args...])

Run `wait_still_screen` but `die` if screen changed within timeout. Look into `wait_still_screen` for details.

# test variable access

## get_var

    get_var($variable [, $default ])

Returns the contents of the test variable `$variable` if defined, otherwise the `$default` if specified, otherwise `undef`.

## get_required_var

    get_required_var($variable)

Similar to `get_var` but without default value and throws exception if variable can not be retrieved.

## set_var

    set_var($variable, $value [, reload_needles => 1] );

Set test variable `$variable` to value `$value`.

Variables starting with `_SECRET_`, including `_PASSWORD`, or whose **NAME** (key) matches a custom regular expression in the test variable `_HIDE_SECRETS_REGEX` will not appear in the `vars.json` file. For example, to hide all variables starting with 'SCC_REGCODE', use '^SCC_REGCODE'.

Specify a true value for the `reload_needles` flag to trigger a reloading of needles in the backend and call the cleanup handler with the new variables to make sure that possibly deselected needles are now taken into account (useful if you change scenarios during the test run)

## check_var

    check_var($variable, $value);

Returns whether the test variable `$variable` is equal to `$value`.

## get_var_array

    get_var_array($variable [, $default ]);

Return the given variable as array reference (split variable value by , | or ; )

## check_var_array

    check_var_array($variable, $value);

Boolean function to check if a value list contains a value

# script execution helpers

## is_serial_terminal

    is_serial_terminal;

Determines if communication with the guest is being performed purely over a serial port. When true, the guest should have a tty attached to a serial port and os-autoinst sends commands to it as text. This differs from when a text console is selected in the guest, but VNC is being used to simulate key presses.

When a serial terminal is selected you will not be able to use functions which rely on needles. This sub is not exported by default as most tests will not benefit from changing their behaviour depending on if communication happens over serial or VNC.

For more info see consoles/virtio_console.pm and consoles/serial_screen.pm.

## wait_serial

    wait_serial($regex or ARRAYREF of $regexes, [, timeout => $timeout] [, expect_not_found => $expect_not_found] [, %args]);

Positional mode (not suggested)

    wait_serial($regex or ARRAYREF of $regexes [, $timeout [, $expect_not_found [, @args ]]]);

Wait for `$regex` or anyone of `$regexes` to appear on serial output. A regex object has to be created with the `qr` operator.

Setting `$no_regex` will cause it to do a plain string search.

Set `$quiet`, to avoid recording serial_result.

For serial_terminal there are more options available, like `record_output`, `buffer_size`. See `consoles::serial_screen::read_until` for details.

Returns the string matched or `undef` if `$expect_not_found` is false (default).

Returns `undef` or (after timeout) the string that did _not_ match if `$expect_not_found` is true. The default timeout is 90 seconds.

Examples:

    wait_serial qr/Password:\s*$/i;
    wait_serial 'substring', no_regex => 1, timeout => 30;

## x11_start_program

    x11_start_program($program[, @args]);

Start `$program` in graphical desktop environment.

The implementation is distribution specific and not always available.

## assert_script_run

    assert_script_run($cmd [, timeout => $timeout] [, fail_message => $fail_message] [,quiet => $quiet] [,max_interval => $max_interval]);

Positional mode (not suggested)

    assert_script_run($cmd [, $timeout [, $fail_message]]);

Run `$cmd` via `$distri->script_run` and `die` unless it returns zero (indicating successful completion of `$cmd`). Default timeout is 90 seconds. Use `script_run` instead if `$cmd` may fail.

`$fail_message` is returned in the die message if specified.

`$quiet` and `$max_interval` are passed through to `$distri->script_run`. In the default implementation, `$quiet` is used to avoid recording serial_results. `$max_interval` (1-250) controls typing speed (lower values mean slower typing).

The `script_run` implementation is distribution specific and not always available. For this to work correctly, it must return 0 if and only if `$command` completes successfully. It must NOT return 0 if `$command` times out. The default implementation should work on *nix operating systems with a configured serial device.

## script_run

    script_run($cmd [, timeout => $timeout] [, output => ''] [, quiet => $quiet] [,max_interval => $max_interval]);

Positional mode (not suggested)

    script_run($cmd [, $timeout]);

Run `$cmd` (in the default implementation, by assuming the console prompt and typing the command). If `$timeout` is greater than 0, wait for that length of time for execution to complete.

`$output` can be used as an explanatory text that will be displayed with the execution of the command.

`$quiet` and `$max_interval` are passed through to `$distri->script_run`. In the default implementation, `$quiet` is used to avoid recording serial_results. `$max_interval` (1-250) controls typing speed (lower values mean slower typing).

`script_run` will throw an exception if the timeout has expired.

<Returns> exit code received from $cmd or undef if `$timeout` is 0.

The implementation is distribution specific and not always available.

The default implementation should work on *nix operating systems with a configured serial device so long as the user has permissions to write to the supplied serial device `$serialdev`.

## background_script_run

    background_script_run($cmd [, output => ''] [, quiet => $quiet]);

Run `$cmd` in background without waiting for it to finish. Remember to redirect output, otherwise the PID marker may get corrupted.

`$output` can be used as an explanatory text that will be displayed with the execution of the command.

<Returns> PID of the $cmd process running in the background.

The implementation is distribution specific and not always available.

The default implementation should work on *nix operating systems with a configured serial device so long as the user has permissions to write to the supplied serial device `$serialdev`.

## assert_script_sudo

    assert_script_sudo($command [, $wait]);

Run `$command` via `script_sudo` and then check by `wait_serial` if its exit status is not zero. See `wait_serial` for default timeout.

The implementation is distribution specific and not always available.

Make sure the non-root user has permissions to write to the supplied serial device `$serialdev`.

## script_sudo

    script_sudo($program [, $wait]);

Run `$program` using sudo. Handle the sudo timeout and send password when appropriate. `$wait` defaults to 2 seconds.

The implementation is distribution specific and not always available.

## script_output

    script_output($script [, $wait, type_command => 1, proceed_on_failure => 1] [,quiet => $quiet])

Executing script inside SUT with `bash -eox` (in case of serial console with `bash -eo`) and directs `stdout` (not `stderr`!) to the serial console and returns the output if the script exits with 0. Otherwise the test is set to failed. NOTE: execution result may include extra serial output which was on serial console since command was triggered in case serial console is not dedicated for the script output only.

The script content is based on the variable content of `current_test_script` and is typed or fetched through HTTP depending on various parameters. Typing can be forced by passing `type_command =` 1> for example when the SUT does not provide a usable network connection.

`proceed_on_failure` - allows to proceed with validation when `$script` is failing (return non-zero exit code)

The default timeout for the script is based on the default in `wait_serial` and can be tweaked by setting the `$wait` positional parameter.

## save_tmp_file

    save_tmp_file($relpath, $content)

Saves content to the file in the worker pool directory using hash of the path, including file, so it can be fetched via http later on using `<autoinst_url`/files/#path_to_the_file> > url. Can be used to modify files for specific test needs, e.g. autoinst profiles. Dies if cannot open file for writing.

Returns filename of saved file (filename hashed).

Example: save_tmp_file('autoyast/autoinst.xml', '<profile>Test</profile>') Then the file can be fetched using url: `<autoinst_url`/files/autoyast/autoinst.xml> >

## get_test_data

    get_test_data($relpath)

Returns content of the file located in data directory. This method can be used if one needs to modify files content before accessing it in SUT.

Example: get_test_data('autoyast/autoinst.xml') This will return content of the file located in data/autoyast/autoinst.xml

## validate_script_output

    validate_script_output($script, $code | $regexp [, timeout => $timeout] [, quiet => $quiet] [, title => $title] [, fail_message => $fail_message])

Positional mode (not suggested)

    validate_script_output($script, $code, [$wait])

Wrapper around script_output, that runs a callback on the output, or alternatively matches a regular expression. Use it as

    validate_script_output "cat /etc/hosts", sub { m/127.*localhost/ };
    validate_script_output "cat /etc/hosts", qr/127.*localhost/;
    validate_script_output "cat /etc/hosts", qr/127.*localhost/, title => 'localhost check', fail_message => 'No localhost line in /etc/hosts!';
    validate_script_output "cat /etc/hosts", sub { $_ !~ m/987.*somehost/ };

## become_root

    become_root;

Open a root shell.

The implementation is distribution specific and not always available.

## ensure_installed

    ensure_installed $package;

Helper to install a package to SUT.

The implementation is distribution specific and not always available.

## hashed_string

    hashed_string();

Return a short string representing the given string by passing it through the MD5 algorithm and taking the first characters.

# keyboard support

## send_key

    send_key($key [, wait_screen_change => $wait_screen_change]);

Send one `$key` to SUT keyboard input. Waits for the screen to change when `$wait_screen_change` is true.

Special characters naming:

    'esc', 'down', 'right', 'up', 'left', 'equal', 'spc',  'minus', 'shift', 'ctrl'
    'caps', 'meta', 'alt', 'ret', 'tab', 'backspace', 'end', 'delete', 'home', 'insert'
    'pgup', 'pgdn', 'sysrq', 'super'

## hold_key

    hold_key($key);

Hold one `$key` until release it

## release_key

    release_key($key);

Release one `$key` which is kept holding

## send_key_until_needlematch

    send_key_until_needlematch($tag, $key [, $counter, $timeout]);

Send specific key until needle with `$tag` is matched or `$counter` is 0. `$tag` can be string or `ARRAYREF` (`['tag1', 'tag2']`) Default counter is 20 steps, default timeout is 1s

Throws `FailedNeedle` exception if needle is not matched until `$counter` is 0.

## type_string

    type_string($string [, max_interval => <num> ] [, wait_screen_change => <num> ] [, wait_still_screen => <num> ] [, secret => 1 ]
    [, timeout => <num>] [, similarity_level => <num>] [, lf => 1 ]);

send a string of characters, mapping them to appropriate key names as necessary

you can pass optional parameters with following keys:

`max_interval (1-250)` determines the typing speed, the lower the `max_interval` the slower the typing.

`wait_screen_change` if set, type only this many characters at a time `wait_screen_change` and wait for the screen to change between sets.

`wait_still_screen` if set, `wait_still_screen` returns true if screen is not changed for given `$wait_still_screen` seconds or false if the screen is not still for the given seconds within defined `timeout` after the whole string is typed. Default timeout is 30s, default stilltime is 0s.

`similarity_level` can be passed as argument for wrapped `wait_still_screen` calls.

`secret (bool)` suppresses logging of the actual string typed.

`lf (bool)` finishes the string with an additional line feed, for example to enter a command line.

## type_password

    type_password($password [, max_interval => <num> ] [, wait_screen_change => <num> ] [, wait_still_screen => <num> ] [, timeout => <num>]
    [, similarity_level => <num>] );

A convenience wrapper around `type_string`, which doesn't log the string.

Uses `$testapi::password` if no string is given.

You can pass the same optional parameters as for `type_string` function.

## enter_cmd

    enter_cmd($string [, max_interval => <num> ] [, wait_screen_change => <num> ] [, wait_still_screen => <num> ] [, secret => 1 ]
    [, timeout => <num>] [, similarity_level => <num>] );

A convenience wrapper around `type_string`, that adds a linefeed to execute a command within a command line prompt.

You can pass the same optional parameters as for `type_string` function.

# mouse support

## mouse_set

    mouse_set($x, $y);

Move mouse pointer to given coordinates

## mouse_click

    mouse_click([$button, $hold_time]);

Click mouse `$button`. Can be `'left'` or `'right'`. Set `$hold_time` to hold button for set time in seconds. Default hold time is 0.15s

## mouse_dclick

    mouse_dclick([$button, $hold_time]);

Same as mouse_click only for double click.

## mouse_tclick

    mouse_tclick([$button, $hold_time]);

Same as mouse_click only for triple click.

## mouse_hide

    mouse_hide([$border_offset]);

Hide mouse cursor by moving it out of screen area.

## mouse_drag mouse_drag([$startpoint, $endpoint, $startx, $starty, $endx, $endy, $button, $timeout]);

Click mouse `$button`, `'left'` or `'right'`, at a given location, hold the button and drag the mouse to another location where the button is released. You can set the `$startpoint` and `$endpoint` by passing the name of the needle tag, i.e. the mouse drag happens between the two needle areas. Alternatively, you can set all the coordinates explicitly with `$startx`, `$starty`, `$endx`, and `$endy`. You can also set one point using a needle and another one using coordinates. If both the coordinates and the needle are provided, the coordinates will be used to set up the locations and the needle location will be ignored.

# multi console support

All `testapi` commands that interact with the system under test do that through a console. `send_key`, `type_string` type into a console. `assert_screen` 'looks' at a console, `assert_and_click` looks at and clicks on a console.

Most backends support several consoles in some way. These consoles then have names as defined by the backend.

Consoles can be selected for interaction with the system under test. One of them is 'selected' by default, as defined by the backend.

There are no consoles predefined by default, the distribution has to add them during initial setup and define actions on what should happen when they are selected first by the tests.

E.g. your distribution can give e.g. `tty2` and `tty4` a name for the tests to select

    $self->add_console('root-console',  'tty-console', {tty => 2});
    $self->add_console('user-console',  'tty-console', {tty => 4});

## add_console

    add_console("console", "console type" [, optional console parameters...])

You need to do this in your distribution and not in tests. It will not trigger any action on the system under test, but only store the parameters.

The console parameters are console specific. Parameter `persistent` skips console reset and console is persistent during the test execution.

The implementation is distribution specific and not always available.

## select_console

    select_console($console [, @args]);

Example:

    select_console("root-console");

Select the named console for further `testapi` interaction (send_text, send_key, wait_screen_change, ...)

If this the first time, a test selects this console, the distribution will get a call into activate_console('root-console', $console_obj, @args) to make sure to actually log in root. For the backend it's just a `tty` object (in this example) - so it will ensure the console is active, but to setup the root shell on this console, the distribution needs to run test code.

After the console selection the distribution callback `$distri-`console_selected> is called with `@args`.

## console

    console("testapi_console")->$console_command(@console_command_args)

Some consoles have special commands beyond `type_string`, `assert_screen`

Such commands can be accessed using this API.

`console("bootloader")`, `console("errorlog")`, ... returns a proxy object for the specific console which can then be directly accessed.

This is also useful for typing/interacting 'in the background', without turning the video away from the currently selected console.

Note: `assert_screen()` and friends look at the currently selected console (select_console), no matter which console you send commands to here.

## reset_consoles

    reset_consoles;

will make sure the next select_console will activate the console. This is important if you did something to the system that affects the console (e.g. trigger reboot).

## current_console

Return the currently selected console, a call when no console is selected, will return `undef`.

# audio support

## start_audiocapture

    start_audiocapture;

Tells the backend to record a `.wav` file of the sound card.

Only supported by qemu backend.

## assert_recorded_sound

    assert_recorded_sound('we-will-rock-you');

Tells the backend to record a `.wav` file of the sound card and asserts if it matches expected audio. Comparison is performed after conversion to the image.

Only supported by QEMU backend.

## check_recorded_sound

    check_recorded_sound('we-will-rock-you');

Tells the backend to record a `.wav` file of the sound card and checks if it matches expected audio. Comparison is performed after conversion to the image.

Only supported by QEMU backend.

# miscellaneous

## power

    power($action);

Trigger backend specific power action, can be `'on'`, `'off'`, `'acpi'` or `'reset'`

## check_shutdown

    check_shutdown([$timeout]);

Periodically check backend for status until `'shutdown'`. Does not initiate shutdown.

Returns true on success and false if `$timeout` timeout is hit. Default timeout is 60s.

## assert_shutdown

    assert_shutdown([$timeout]);

Periodically check backend for status until `'shutdown'`. Does not initiate shutdown.

Returns `undef` on success, marks the test as failed and throws exception if `$timeout` timeout is hit. Default timeout is 60s.

## eject_cd

    eject_cd;

if backend supports it, eject the CD

## disconnect_usb

    disconnect_usb;

if backend supports it, disconnect the USB stick (or other device specified by id)

## switch_network

    switch_network network_enabled => $boolean, [network_link_name => $string];

Changes network device's state akin to disconnecting the physical cable, default network is qanet0.

This method is fatal in case the network device doesn't exist.

## save_memory_dump

    save_memory_dump(filename => undef);

Saves the SUT memory state using `$filename` as base for the memory dump filename, the default will be the current test's name.

This method must be called within a post_fail_hook.

Currently only qemu backend is supported.

## save_storage

    save_storage(filename => undef);

Saves all of the SUT volumes using `$filename` as part of the final filename, the default will be the current test's name.

Currently only qemu backend is supported.

## freeze_vm

    freeze_vm;

If the backend supports it, freeze the virtual machine. This will allow the virtual machine to be paused/frozen within the test, it is recommended to call this within a `post_fail_hook` so that memory and disk dumps can be extracted without any risk of data changing, or in rare cases call it before the tests tests have already begun, to avoid unexpected behaviour.

Currently only qemu backend is supported.

## resume_vm

    resume_vm;

If the backend supports it, resume the virtual machine. Call this method to start virtual machine CPU explicitly if DELAYED_START is set.

Currently only qemu backend is supported.

## parse_junit_log

    parse_junit_log("report.xml");

Upload log file from SUT (calls upload_logs internally). The uploaded file is then parsed as jUnit format and extra test results are created from it.

## parse_extra_log

    parse_extra_log(Format => $file [, failok =>1] [, timeout => $timeout]);

Upload log file from SUT (calls upload_logs internally). The uploaded file is then parsed as the format supplied, that can be understood by OpenQA::Parser and extra test results are created from it.

    Formats currently supported are: JUnit, XUnit, LTP, IPA, TAP

# log and data upload and download helpers

## diag

    diag('important message');

Write a diagnostic message to the logfile. In color, if possible.

## host_ip

Return VM's host IP. In a kvm instance you reach the VM's host under default 10.0.2.2

Optional named parameter `inside_sut` in `$args` will force using actual worker IP/hostname even on KVM guests if set to 0.

In case of non-qemu tries to return a sane default if the test variable `WORKER_HOSTNAME` was not specified.

## autoinst_url

    autoinst_url([$path, $query, $args]);

Returns the base URL to contact the local `os-autoinst` service.

Optional `$path` argument is appended after base URL.

Optional HASHREF `$query` is converted to URL query and appended after path.

Optional named parameter `inside_sut` in `$args` will force using actual worker IP/hostname even on KVM guests if set to 0.

Returns a URL that can be used like this:

    script_run("curl " . autoinst_url . "/data");

This function can be used to download ISO, HDD and other assets from the isotovideo working directory into the SUT. Note that the openQA worker does *not* synchronize repository assets there so those assets cannot be downloaded via the autoinst URL when the openQA worker is used.

## data_url

    data_url($name);

returns the URL to download data or asset file Special values REPO_\d and ASSET_\d points to the asset configured in the corresponding variable

## upload_logs

    upload_logs($file [, failok => 0, timeout => 90, log_name => "custom_name.log" ]);

Upload `$file` to OpenQA WebUI as a log file and return the uploaded file name. If failok is not set, a failed upload or timeout will cause the test to die. Failed uploads happen if the file does not exist or is over 20 GiB in size, so failok is useful when you just want to upload the file if it exists but not mind if it doesn't. Default timeout is 90s. `log_name` parameter allow to control resulted job's attachment name.

## upload_asset

    upload_asset $file [,$public[,$nocheck]];

Uploads `$file` as asset to OpenQA WebUI

You can upload private assets only accessible by related jobs:

    upload_asset '/tmp/suse.ps';

Or you can upload public assets that will have a fixed filename replacing previous assets - useful for external users:

    upload_asset '/tmp/suse.ps', 1;

If you just want to upload a file and verify that it was uploaded correctly on your own (e.g. in svirt console we don't have a serial line and can't rely on assert_script_run check), add an optional `$nocheck` parameter:

    upload_asset '/tmp/suse.ps', 1, 1;

## compat_args

Helper function to create backward compatible function arguments when moving from positional arguments to named one.

    compat_args( $hash_ref_defaults, $arrayref_old_fixed, [ $arg1, $arg2, ...])

A typical call would look like:

    my %args = compat_args({timeout => 60, .. }, ['timeout'], @_);

## show_curl_progress_meter

Helper function to alter the curl command to show progress meter. Progress meter is shown only when the server output is redirected. This works only when uploading where the output is not lately used.

    show_curl_progress_meter( $cmd )

A typical call would look like:

    $cmd .= show_curl_progress_meter($cmd);

## backend_get_wait_still_screen_on_here_doc_input

Function to query the backend if it has the known bug from https://progress.opensuse.org/issues/60566 which is that typing too fast into the here-document input can yield invalid script content. This function returns the value to be used by `wait_still_screen` before starting to write the script into the here document.

## get_username, set_username

    my $old = get_username;
    set_username($new);

Wrapper around the exported `$username` variable.

## get_realname, set_realname

    my $old = get_realname;
    set_realname($new);

Wrapper around the exported `$realname` variable.

## get_password, set_password

    my $old = get_password;
    set_password($new);

Wrapper around the exported `$password` variable.

## get_serialdev, set_serialdev

    my $old = get_serialdev;
    set_serialdev($new);

Wrapper around the exported `$serialdev` variable.