lib/utils.pm

SYNOPSIS

Main file for all kind of functions

save_svirt_pty

 save_svirt_pty();

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

 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_zvm_disk

 unlock_zvm_disk($console);

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

handle_grub_zvm

 handle_grub_zvm($console);

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

TODO: Add support for GRUB_BOOT_NONDEFAULT, GRUB_SELECT_FIRST_MENU, GRUB_SELECT_SECOND_MENU, see boot_grub_item()

handle_untrusted_gpg_key

 handle_untrusted_gpg_key();

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.

integration_services_check_ip

 integration_services_check_ip();

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

integration_services_check

 integration_services_check();

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

unlock_if_encrypted

 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.

clear_console

 clear_console();

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

 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_console_font

 check_console_font();

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.

type_string_slow_extended

 type_string_slow_extended($string);

Enable additional arguments for nested calls of wait_still_screen.

type_string_slow

 type_string_slow($string);

Typing a string with SLOW_TYPING_SPEED to avoid losing keys.

type_string_very_slow

 type_string_very_slow($string);

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.

get_netboot_mirror

 get_netboot_mirror();

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

zypper_call

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

zypper_enable_install_dvd

 zypper_enable_install_dvd();

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

zypper_ar

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

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

Options:

$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

Examples:

 zypper_ar('http://dist.nue.suse.com/ibs/QA:/Head/SLE-15-SP1', name => 'qa-head);
 zypper_ar('https://download.opensuse.org/repositories/devel:/kubic/openSUSE_Tumbleweed/devel:kubic.repo', no_gpg_check => 1, priority => 90);

fully_patch_system

 fully_patch_system();

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

ssh_fully_patch_system

 ssh_fully_patch_system($host);

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

 minimal_patch_system([version_variable => $version_variable]);

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

 zypper_search($search_params);

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

workaround_type_encrypted_passphrase

 workaround_type_encrypted_passphrase();

Record soft-failure for unresolved feature fsc#320901 which we think is important and then unlock encrypted boot partitions if we expect it to be encrypted. This condition is met on 'storage-ng' which by default puts the boot partition within the encrypted LVM same as in test scenarios where we explicitly create an LVM including boot (FULL_LVM_ENCRYPT). ppc64le was already doing the same by default also in the case of pre-storage-ng but not anymore for storage-ng.

is_boot_encrypted

 is_boot_encrypted();

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

is_bridged_networking

 is_bridged_networking();

returns BRIDGED_NETWORKING.

set_bridged_networking

 set_bridged_networking();

Sets BRIDGED_NETWORKING to 1 if applicable.

set_hostname

 set_hostname($hostname);

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

 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.

handle_livecd_reboot_failure

 handle_livecd_reboot_failure();

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

 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.

Example:

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

pkcon_quit

 pkcon_quit();

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

addon_decline_license

 addon_decline_license();

TODO someone should document this

addon_license

 addon_license($addon);

TODO someone should document this

addon_products_is_applicable

 addon_products_is_applicable();

Return 1 if ADDONURL is set and LIVECD is unset.

noupdatestep_is_applicable

 noupdatestep_is_applicable();

Return 1 if neither UPGRADE nor LIVE_UPGRADE is set.

installwithaddonrepos_is_applicable

 installwithaddonrepos_is_applicable();

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

random_string

 random_string($length);

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

handle_emergency

 handle_emergency();

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

service_action

 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.

Example:

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

get_root_console_tty

 get_root_console_tty();

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

get_x11_console_tty

 get_x11_console_tty();

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

arrays_differ

 arrays_differ(\@array1, \@array2);

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

arrays_subset

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

ensure_serialdev_permissions

 ensure_serialdev_permissions();

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.

disable_serial_getty

 disable_serial_getty();

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.

exec_and_insert_password

 exec_and_insert_password($cmd);

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

2. Detects password prompt

3. Insert password and hits enter

shorten_url

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

Shorten url via schort(s.qa.suse.de) 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.

_handle_login_not_found

 _handle_login_not_found($str);

Internal helper function used by reconnect_mgmt_console.

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.

show_tasks_in_blocked_state

 show_tasks_in_blocked_state();

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

See https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/sysrq.rst.

svirt_host_basedir

 svirt_host_basedir();

Return VIRSH_OPENQA_BASEDIR or fall back to /var/lib.

script_retry

 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.

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.

Example:

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

script_run_interactive

 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.

create_btrfs_subvolume

 create_btrfs_subvolume();

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

file_content_replace

 file_content_replace("filename",
       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.