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.

enter_cmd_slow

enter_cmd_slow($cmd);

Enter a command with SLOW_TYPING_SPEED to avoid losing keys.

enter_cmd_very_slow

enter_cmd_very_slow($cmd);

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

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

parse_zypper_table

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.

zypper_search($search_params);

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

zypper_repos

zypper_repos($params);

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

zypper_patches

zypper_patches($params);

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

zypper_install_available(@packages);

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_zypper_lock_timeout

set_zypper_lock_timeout($timeout);

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

unlock_bootloader();

Unlock bootloader if boot partition is encrypted.

is_boot_encrypted

is_boot_encrypted();

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

need_unlock_after_bootloader

need_unlock_after_bootloader();

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

is_bridged_networking

is_bridged_networking();

returns BRIDGED_NETWORKING.

set_bridged_networking

set_bridged_networking();

Sets BRIDGED_NETWORKING to 1 if applicable.

print_ip_info();

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

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.

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

quit_packagekit

quit_packagekit();

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

wait_for_purge_kernels

wait_for_purge_kernels();

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

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 SDDM 0.20 uses the first free VT (usually tty2) for the greeter as well as the session.

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.

_handle_firewall

_handle_firewall();

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.

show_oom_info

show_oom_info

Show logs about an out of memory process kill.

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.

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

Example:

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

script_output_retry

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.

Example:

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

validate_script_output_retry

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.

Example:

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

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.

download_script

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

create_btrfs_subvolume();

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

create_raid_loop_device

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)

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.

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.

remount_tmp_if_ro

remount_tmp_if_ro();

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

detect_bsc_1063638

detect_bsc_1063638();

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

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:

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

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

script_finish_io

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

write_sut_file($path, $contents)

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

is_ipxe_boot

Returns true if the current instance is in IPXE boot mode

is_uefi_boot

Returns true if the current instance is in UEFI boot mode