Main file for all kind of functions



Save the pty device within the svirt shell session so that we can refer to the correct pty pointing to the first tty, e.g. for password entry for encrypted partitions and rewriting the network definition of zKVM instances.

Does not work on Hyper-V.


type_line_svirt($string [, expect => $expect] [, timeout => $timeout] [, fail_message => $fail_message]);

Sends $string to the svirt terminal, waits up to $timeout seconds and expects $expect to be returned on the terminal if $expect is set. If the expected text is not found, it will fail with $fail_message.



Unlock the zvm disk if needed. $console should be set to console('x3270'). $testapi::password will be used as password.



Make sure that grub was started and send four enter keys to boot the system. $console should be set to console('x3270').




This function is used during the installation. Check if a previous needle match included the tag import-known-untrusted-gpg-key. If yes, import the key, otherwise don't.



Check that guest IP address that host and guest see is the same. Die, if this is not the case.



Make sure integration services (e.g. kernel modules, utilities, services) are present and in working condition.


unlock_if_encrypted([check_typed_password => $check_typed_password]);

Check whether the system under test has an encrypted partition and attempts to unlock it. $check_typed_password will default to 0.



ctrl-l does not get queued up in buffer. If this happens to fast, the screen would not be cleared. So this function will simply type clear\n.


assert_gui_app($application [, install => $install] [, exec_param => $exec_param] [, remain => $remain]);

assert_gui_app (optionally installs and) starts an application, checks it started and closes it again. It's the most minimalistic way to test a GUI application

Mandatory parameter: application (the name of the application).

Optional parameters are:

install: boolean
    Does the application have to be installed first? Especially
    on live images where we want to ensure the disks are complete
    the parameter should not be set to true - otherwise we might
    mask the fact that the app is not on the media.

exec_param: string
    When calling the application, pass this parameter on the command line.

remain: boolean
    If set to true, do not close the application when tested it is
    running. This can be used if the application shall be tested further.



Check the console font using a needle.

13.2, Leap 42.1, SLE12 GA&SP1 have problems with setting up the console font, we need to call systemd-vconsole-setup to workaround that.



Enable additional arguments for nested calls of wait_still_screen.



Typing a string with SLOW_TYPING_SPEED to avoid losing keys.



Typing a string even slower with VERY_SLOW_TYPING_SPEED.

The bootloader prompt line is very delicate with typing especially when scrolling. We are typing very slow but this could still pose problems when the worker host is utilized so better wait until the string is displayed before continuing For the special winter grub screen with moving penguins wait_still_screen does not work so we just revert to sleeping a bit instead of waiting for a still screen which is never happening. Sleeping for 3 seconds is less waste of time than waiting for the wait_still_screen to timeout, especially because wait_still_screen is also scaled by TIMEOUT_SCALE which we do not need here.



Enter a command with SLOW_TYPING_SPEED to avoid losing keys.



Enter a command even slower with VERY_SLOW_TYPING_SPEED. Compare to type_string_very_slow.



Return the mirror URL eg from the MIRROR_HTTP var if INSTALL_SOURCE is set to http.


zypper_call($command [, exitcode => $exitcode] [, timeout => $timeout] [, log => $log] [, dumb_term => $dumb_term]);

Function wrapping 'zypper -n' with allowed return code, timeout and logging facility. First parammeter is required command, all others are named and provided as hash for example:

zypper_call("up", exitcode => [0,102,103], log => "zypper.log");

# up        --> zypper -n up --> update system
# exitcode  --> allowed return code values
# log       --> capture log and store it in zypper.log
# dumb_term --> pipes through cat if set to 1 and log is not set. This is a  workaround
#               to get output without any ANSI characters in zypper before 1.14.1. See boo#1055315.

dumb_term will default to is_serial_terminal().



Enables the install DVDs if they were used during the installation.


zypper_ar($url, [ name => NAME ], [ priority => N ]);

Add repository (with zypper ar) unless it's already repo $name already added and refresh repositories.


$name alias for repository, optional When used, additional check if repo not yet exists is done, and adding only if it doesn't exist. Also zypper ref is run only on this repository. NOTE: if not used, $url must be a URI pointing to a .repo file.

$no_gpg_check pass --no-gpgcheck for repos with not valid GPG key, optional

$priority set repo priority, optional

$params other ar subcommand parameters, optional


zypper_ar('', name => 'qa-head);
zypper_ar('', no_gpg_check => 1, priority => 90);



Run zypper patch twice. The first run will update the package manager, the second run will update the system.



Connect to the remote host $host using ssh and update the system by running zypper patch twice. The first run will update the package manager, the second run will update the system.


minimal_patch_system([version_variable => $version_variable]);

zypper doesn't offer --updatestack-only option before 12-SP1, use patch for sp0 to update packager


parse_zypper_table($table, $fields);

Parse ASCII table generated by commands such as zypper search into an array of hashes. Pass the ASCII table in $table as a single string. Pass an array of hash keys in $fields. Keys will be mapped to columns by position.


Run zypper search with given command line arguments and parse the output into an array of hashes.



Run zypper repos with given command line arguments and parse the output into an array of hashes. Only table output is supported.



Run zypper patches with given command line arguments and parse the output into an array of hashes.


Install all available packages from the given list. Packages not found in enabled repositories will be skipped. Package availability is tested by exact name match.



Set how many seconds zypper will wait for other processes to release the system lock. If this function is called without arguments, it'll set timeout to 300 seconds.



Unlock bootloader if boot partition is encrypted.



This will return 1 if the env variables suggest that the boot partition is encrypted.



Whether the disk encryption password(s) need to be entered during system boot (e.g. plymouth or systemd-cryptsetup text prompt).

With newer grub2 (in TW and SLE15-SP6 currently), if root disk is encrypted and contains `/boot`, entering the passphrase in GRUB2 is enough. The key is passed on during boot, so it's not asked for a second time. We need to enter the passphrase again if there are separate partitions encrypted without LVM configuration (cr_swap,cr_home etc).






Sets BRIDGED_NETWORKING to 1 if applicable.


Print the interface addresses, routes and adjacent network nodes (that have been seen). Especially useful for multi-machine test debugging.



Setting hostname according input parameter using hostnamectl. Calling reload-or-restart to make sure that network stack will propogate hostname into DHCP/DNS.

If you change hostname using hostnamectl set-hostname, then hostname -f will fail with hostname: Name or service not known also DHCP/DNS don't know about the changed hostname, you need to send a new DHCP request to update dynamic DNS yast2-network module does NetworkService.ReloadOrRestart if Stage.normal || !Linuxrc.usessh if hostname is changed via yast2 lan.


assert_and_click_until_screen_change($mustmatch [, $wait_change [, $repeat ]]);

This will repeat assert_and_click($mustmatch) up to $repeat times, trying againg if the screen has not changed within $wait_change seconds after the assert_and_click. Returns the number of attempts made. $wait_change defaults to 2 (seconds) and $repeat defaults to 3.

You can check if the screen changed by using an explicit repeat and comparing it to the returned number of attempts. If the value equals repeat the screen didn't change.



Handle a potential failure on a live CD related to boo#993885 that the reboot action from a desktop session does not work and we are stuck on the desktop.


assert_screen_with_soft_timeout($mustmatch, bugref => $bugref [,timeout => $timeout] [,soft_timeout => $soft_timeout] [,soft_failure_reason => $soft_failure_reason]);

Extending assert_screen with a soft timeout. When $soft_timeout is hit, a soft failure is recorded with the message $soft_failure_reason but assert_screen continues until the (hard) timeout $timeout is hit. This makes sense when an assert screen should find a screen within a lower time but still should not fail and continue until the hard timeout, e.g. to discover performance issues.

There MUST be a $bugref set for the softfail. If it is not set this function will die.


assert_screen_with_soft_timeout('registration-found', timeout => 300, soft_timeout => 60, bugref => 'bsc#123456');



Stop and mask packagekit service and wait until it is really dead. This is needed to prevent access conflicts to the RPM database.



Wait until purge-kernels is done Prevent RPM lock e.g. SUSEConnect fail



TODO someone should document this



TODO someone should document this



Return 1 if ADDONURL is set and LIVECD is unset.



Return 1 if neither UPGRADE nor LIVE_UPGRADE is set.



Return 1 if installation should be done with addon repos based on ENV variables.



Returns a random string with length $length (default: 4) containing alphanumerical characters.



Handle emergency shell or (systemd) emergency mode and dump some basic logging information to the serial output.


service_action($service_name [, {type => ['$unit_type', ...] [,action => ['$service_action', ...]]}]);

Control systemd services. type may be set to service, socket, ... and $action to start, stop, ... Default action is to 'stop' $service_name.service unit file.


service_action('dbus', {type => ['socket', 'service'], action => ['unmask', 'start']});



Returns tty number used designed to be used for root-console. When console is not yet initialized, we cannot get it from arguments. Since SLE 15 gdm is running on tty2, so we change behaviour for it and openSUSE distris, except for Xen PV (bsc#1086243).



Returns tty number used designed to be used for X. Since SLE 15 gdm is always running on tty7, currently the main GUI session is running on tty2 by default, except for Xen PV and Hyper-V (bsc#1086243). See also: bsc#1054782 SDDM 0.20 uses the first free VT (usually tty2) for the greeter as well as the session.


arrays_differ(\@array1, \@array2);

Comparing two arrays passed by reference. Return 1 if arrays has symmetric difference and 0 otherwise.


arrays_subset(\@array1, \@array2);

Compares two arrays passed by reference to identify if array1 is a subset of array2.

Returns resulting array containing items of array1 that do not exist in array2. If all the items of array1 exist in array2, returns an empty array (which means array1 is a subset of array2).



Grant user permission to access serial port immediately as well as persisting over reboots. Used to ensure that testapi calls like script_run work for the test user as well as root.



Serial getty service pollutes serial output with login prompt, which interferes with the output, e.g. when calling script_output. Login prompt messages on serial are used on some remote backend to identify that system has been booted, so do not mask on non-qemu backends. This is only necessary for Linux < 4.20.4 so skipped on more recent versions.



1. Execute a command ($cmd) that ask for a password

2. Detects password prompt

3. Insert password and hits enter


shorten_url($url, [wishid => $wishid]);

Shorten url via schort( This is mainly used for autoyast url shorten to avoid limit of x3270 xedit.

$url is the url to short. $wishid is the prefered short url id.



Internal helper function used by reconnect_mgmt_console.



Internal helper function used by reconnect_mgmt_console.


reconnect_mgmt_console([timeout => $timeout]);

After each reboot we have to reconnect to the management console on remote backends. $timeout can be set to some specific time and if during reboot GRUB is shown twice grub_expected_twice can be set to 1.



Dumps tasks that are in uninterruptable (blocked) state and wait for headline of dump.




Show logs about an out of memory process kill.



Return VIRSH_OPENQA_BASEDIR or fall back to /var/lib.


script_retry($cmd, [expect => $expect], [retry => $retry], [delay => $delay], [timeout => $timeout], [die => $die]);

Repeat command until expected result or timeout.

$expect refers to the expected command exit code and defaults to 0.

$retry refers to the number of retries and defaults to 10.

$delay is the time between retries and defaults to 30.

$fail_message is an optional error message in case of failure. Defaults to "Waiting for Godot".

The command must return within $timeout seconds (default: 25).

If the command doesn't return $expect after $retry retries, this function will die, if $die is set.


script_retry('ping -c1 -W1 machine', retry => 5);


script_output_retry($cmd, [retry => $retry], [delay => $delay], [timeout => $timeout], [die => $die]);

Repeat command until expected result or timeout. Return the output of the command on success.

$expect refers to the expected command exit code and defaults to 0.

$retry refers to the number of retries and defaults to 10.

$delay is the time between retries and defaults to 30.

$fail_message is an optional error message in case of failure. Defaults to "Waiting for Godot".

The command must return within $timeout seconds (default: 25).

If the command doesn't return $expect after $retry retries, this function will die, if $die is set.


script_output_retry('ping -c1 -W1 machine', retry => 5);


validate_script_output_retry($cmd, $check, [retry => $retry], [delay => $delay], [timeout => $timeout]);

Repeat command until validate_script_output succeeds or die. Return the output of the command on success.

$retry refers to the number of retries and defaults to 10.

$delay is the time between retries and defaults to 30.

$fail_message is an optional error message in case of failure. Defaults to "Can't validate output after $retry retries".

If the command doesn't succeed after $retry retries, this function will die.


validate_script_output_retry('ping -c1 -W1 machine', m/1 packets transmitted/, retry => 5, delay => 60);


script_run_interactive($cmd, $prompt, $timeout);

For interactive command, input strings or keys according to the prompt message in the run time. Pass arrayref $prompt which contains the prompt message to be matched (regex) and the answer with string or key to be typed. for example:

    prompt => qr/\(A\)llow/m,
    key    => 'a',
    prompt => qr/Enter Password or Pin/m,
    string => "testpasspw\n",

A "EOS~~~" message followed by return value will be printed as a mark for the end of interaction after the command finished running.

If the first argument is undef, only the sencond part will be processed - to match output and react. If the second argument is undef, the first part will be processed - to run the command without interaction with terminal output. This is useful for some situation when you want to do more between inputing command and the following interaction, eg. switch TTYs or detach the screen.


download_script($srcfile, [$destfile]);

Download $srcfile script from worker data directory to the SUT and save it as $destfile, with executable bit set. If $destfile is not set, the default is to save the script file under the same name in the current directory.



Create btrfs subvolume for /boot/grub2/arm64-efi before migration. ref:bsc#1122591


create_raid_loop_device([raid_type => $raid_type], [device_num => $device_num], [file_size => $file_size]);

Create a raid array over loop devices. Raid type is $raid_type, using $device_num number of loop device, with the size of each device being $file_size megabytes.

Example to create a RAID 5 array over 3 loop devices, 200 Mb each: create_raid_loop_device(raid_type => 5, device_num => 3, file_size => 200)


      regex_to_find => text_to_replace,
      '--sed-modifier' => 'g',
      'another^&&*(textToFind' => "replacement")

Generify sed usage as config file modification tool. allow to modify several items in one function call by providing regex_to_find / text_to_replace as hash key/value pairs

Special key --sed-modifier allowing to add modifiers to expression.

Special key --debug allow to output full file content into serial. Disabled by default.

assert_file_content assert_file_content( "path", value );

It could check a file be point to 'path' whether include 'value'.

ensure_ca_certificates_suse_installed ensure_ca_certificates_suse_installed();

This functions checks if ca-certificates-suse is installed and if it is not it adds the repository and installs it.

install_patterns install_patterns();

This functions install extra patterns if var PATTERNS is set.

permit_root_ssh permit_root_ssh();

Due to bsc#1173067, openssh now no longer allows RootLogin using password auth on Tumbleweed, the latest SLE16 and Leap16 will sync with Tumbleweed as well.

permit_root_ssh_in_sol permit_root_ssh_in_sol();

for ipmi backend, PermitRootLogin has to be set in sol console however, assert_script_run and script_run is not stable in sole console enter_cmd or type_string are acceptable

cleanup_disk_space cleanup_disk_space();

In fully_patch_system and minimal_patch_system, we'll create so many snapshots. which will cost large part of the disk space. We need to delete these snapshots before the migration only if the available space is less than DISK_LOW_WATERMARK.

package_upgrade_check package_upgrade_check();

This function is used for checking if the package is upgraded to the required version

Sample config of parameter of the function below: my $pkg_list = {ibmtss => '1.6.0'}; here, 'libmtss' is the package name, and '1.6.0' is target version which needs to be upgrated to

_validate_result _validate_result();

This is a private method which is used by generate_results to convert the results in a string representation. At the moment the status that are supported are {PASS,FAIL}.

The method takes as the only argument the return of a perl statement or subroutine.

generate_results generate_results();

This function is used to construct a hash suitable for representation in junit xml format.

parse_test_results parse_test_results();

Takes test as an argument. test is an array of hashes which contain the test results. They usually are generated by generate_results. Those are parsed and create the junit xml representation.

test_case test_case($name, $description, $result);

test_case can produce a data_structure which parse_test_results can utilize. Using test_case in an OpenQA module you are able to /name/ and describe the whole test as subtasks, in a XUnit format.



Mounts /tmp to shared memory if not possible to write to tmp. For example, save_y2logs creates temporary files there.



Btrfs maintenance jobs lead to the system being unresponsive and affects SUT's performance. Not to waste time during investigation of the failures, we would like to detect if such jobs are running, providing a hint why test timed out. This method will create a softfail if such a problem is detected.


script_start_io($cmd [, %args]);

Start program $cmd in console for interactive input and output. Call script_finish_io() after sending the appropriate exit command to the program. Example usage:

wait_serial(qr/^123/m) or die 'Wrong output';
enter_cmd('int("123", 16)');
wait_serial(qr/^291/m) or die 'Wrong output';
script_finish_io(exitcode => [12]);

Set $quiet to avoid recording serial result for the initial command.


script_finish_io([timeout => $timeout] [, exitcode => undef]);

Finish interactive session started by script_start_io() and return command exit code. If $exitcodes is set, the command exit code must match one of the values in the given array, otherwise the current test will fail. $timeout controls how long to wait for the interactive command to exit. See script_start_io() for example usage.

handle_screen handle_screen($needles, $handler_map [, assert => $assert] [, max_loops => $max_loops] [...]);

Wait for $needles to appear on screen and then execute the appropriate handler function from $handler_map hash. $needles can be any value accepted by assert_screen() or check_screen(). $assert controls whether failed needle match should trigger test failure (when true, default) or just silently return (when false). $max_loops limits how many needle checks and handler calls can be done (default: count of $needles). Negative $max_loops means unlimited loop count. Any additional keyword arguments will be passed to assert_screen() or check_screen().

$handler_map is a hashref in the format {"needle-tag" => $handler}. After a successful needle match, all needle tags in $handler_map will be checked and the matching needle must have exactly one of them. It is an error if the needle does not have exactly one handler in $handler_map.

handle_screen() will return after $max_loops iterations, or if a handler function returns any value that evaluates to true, or if needle match fails when $assert is false. The return value is the last value returned by a handler function, or undefined if needle match failed.

Note that you may need to set timeout keyword argument if you set $assert to false because check_screen() has $timeout=0 by default.

define_secret_variable define_secret_variable($var_name, $var_value); define_secret_variable sets a hidden environment variable without exposing it to openQA. This function is useful to hide secrets from openQA by setting them as an accessible environment variable, but without any traces in the output terminals. e.g. define_secret_variable('SECRET', get_var('_SECRET_VARIABLE')) would store the openQA variable '_SECRET_VARIABLE' into the '$SECRET' environment variable, which can be used afterwards by using $SECRET.

ping_size_check ping_size_check($target, $size); ping_size_check will ping the defined target with different and increasing sizes with disabled packet fragmentation. If a size is specified, it will do single ping check with one size.

Mandatory parameter: target destination of ping target.

Optional parameter: size ping size for single ping test.


write_sut_file($path, $contents)

Write $contents to a file $path on the SUT. The directories in $path must already exist.