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

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 an optional $reason string which is recorded in the log file.

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.

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.

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 NeedleFailed 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 30s.

match_has_tag
match_has_tag($tag);

Returns true if last matched needle has $tag else return undef.

assert_and_click
assert_and_click($mustmatch, [$button], [$timeout], [$click_time], [$dclick]);

Wait for needle with $mustmatch tag to appear on SUT screen. Then click $button in the middle of the last match region as defined in the needle JSON file. 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.

Throws NeedleFailed exception if $timeout timeout is hit. Default timeout is 30s.

assert_and_dclick
assert_and_dclick($mustmatch, $button, [$timeout], [$click_time]);

Alias for assert_and_click with $dclick set.

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

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.

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);

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.

test variable access

get_var
get_var($variable [, $default ])

Returns content of test variable $variable or the $default given as second argument or 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.

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 unselected needles are now taken into account (useful if you change scenarios during the test run)

check_var
check_var($variable, $value);

Returns true if test variable $variable is equal to $value or returns undef.

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/virtio_screen.pm.

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

Wait for $regex or anyone of $regexes to appear on serial output.

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.

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]);

Deprecated mode

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.

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 [, $wait]);

Run $cmd (in the default implementation, by assuming the console prompt and typing the command). If $wait_seconds is greater than 0, wait for that length of time for execution to complete (otherwise, returns undef immediately). See `distri-`script_run> for default timeout.

<Returns> exit code received from $cmd', or undef if $wait_seconds is 0 or execution does not complete within $wait_seconds.

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])

fetches the script through HTTP into the SUT and execs it with bash -xe and directs stdout (not' stderr!) to the serial console and returns the output if' the script exists with 0. Otherwise the test is set to failed.

The default timeout for the script is 30 seconds. If you need more, pass a second parameter

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

Wrapper around script_output, that runs a callback on the output. Use it as

validate_script_output "cat /etc/hosts", sub { m/127.*localhost/ }
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 [, $do_wait]);

Send one $key to SUT keyboard input.

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 not matched or $counter is 0. $tag can be string or ARRAYREF (['tag1', 'tag2']) Default counter is 20 steps, default timeout is 1s

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

type_string
type_string($string [, max_interval => <num> ] [, wait_screen_changes => <num> ] [, wait_still_screen => <num> ] [, secret => 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 for the given seconds after the whole string is typed.

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

type_password
type_password([$password]);

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

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

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 1s

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.

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.

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) 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).

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'

assert_shutdown
assert_shutdown([$timeout]);

Periodically check backend for status until 'shutdown'. Does not' initiate shutdown. Default timeout is 60s

Returns undef on success, throws exception on timeout.

eject_cd
eject_cd;

if backend supports it, eject the CD

save_memory_dump
save_memory_dump(filename => undef, migration_speed => "4096m");

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

The memory dump can be created at any point, but it’s recommended to use it within a post fail hook. Different filenames should be provided if the dump is being used within the test itself.

Currently only qemu backend is supported.'

save_storage_drives
save_storage_drives([$filename]);

Saves all of the SUT drives using $filename as part of the final filename, the default will be the current test’s name. The disk number will be always present.

This method must be called within a post_fail_hook.

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, but only from the post_fail_hook. So that memory and disk dumps can be extracted without any risk of data changing.

Call this method to ensure memory and disk dump refer to the same machine state.

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.

wait_idle
wait_idle([$timeout_sec]);

*Deprecated: * It is recommended to avoid the use of wait_idle. See https://progress.opensuse.org/issues/5830 for details.

This function will basically just sleep some time as this is the only viable option considering all backend implementations. Previously this function tried to wait until a test system becomes idle or timeout which only reliably worked on qemu backend and was just sleeping on other backends. As such it is wasting a lot of time and should be avoided as such.

Default timeout is 19s.

log and data upload and download helpers

diag
diag('important message');

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

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

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.

Returns constructor URL. Can be used inline:

script_run("curl " . autoinst_url . "/data");
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;