Used for internal initialization, do not call from tests.
set_distribution($distri);
Set distribution object.
You can use distribution object to implement distribution specific helpers.
save_screenshot;
Saves screenshot of current SUT screen.
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.
assert_screen($mustmatch [,$timeout]);
Wait for needle with tag $mustmatch
to appear on SUT screen. $mustmatch
can be string or ARRAYREF
of string (['tag1', 'tag2']
).
Returns matched needle or throws NeedleFailed
exception if $timeout timeout is hit. Default timeout is 30s.
check_screen($mustmatch [,$timeout]);
Similar to assert_screen
but does not throw exceptions. Use this for optional matches. Check assert_screen
for parameters.
Returns matched needle or undef
if timeout is hit. Default timeout is 30s.
match_has_tag($tag);
Returns true if last matched needle has $tag
else return undef
.
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 last matched region. 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($mustmatch, $button, [$timeout], [$click_time]);
Alias for assert_and_click
with $dclick
set.
wait_screen_change { CODEREF [,$timeout] };
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';
};
Returns true if screen changed or undef
on timeout. Default timeout is 10s.
wait_still_screen([$stilltime_sec [, $timeout_sec [, $similarity_level]]]);
Wait until the screen stops changing.
Returns true if screen is not changed for given $stilltime (in seconds) or undef on timeout. Default timeout is 30s, default stilltime is 7s.
get_var($variable [, $default ])
Returns content of test variable $variable
or the $default
given as second argument or undef
get_required_var($variable)
Similar to get_var
but without default value and throws exception if variable can not be retrieved.
set_var($variable, $value);
Set test variable $variable
to value $value
.
check_var($variable, $value);
Returns true if test variable $variable
is equal to $value
or returns undef
.
get_var_array($variable [, $default ]);
Return the given variable as array reference (split variable value by , | or ; )
check_var_array($variable, $value);
Boolean function to check if a value list contains a value
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($program[, $timeout, $options]);
Start $program
in graphical desktop environment.
The implementation is distribution specific and not always available.
script_run($program [, $wait]);
Run $program
(by assuming the console prompt and typing it).
The $wait
parameter will (unless 0) wait for the script to finish by following the script with an echo to serial line and waiting for it. Default timeout is 30s.
Make sure the command does not write to the serial output.
assert_script_run($cmd [, timeout => $timeout] [, fail_message => $fail_message]);
Deprecated mode
assert_script_run($cmd [, $timeout [, $fail_message]]);
Run $cmd
via script_run
and die
if its exit status is not zero. The exit status is checked by magic string on the serial port. See script_run
for default timeout. $fail_message
is returned in the die message if specified.
Make sure the command does not write to the serial output.
script_sudo($program [, $wait]);
Run $program
using sudo. Handle the sudo timeout and send password when appropriate. $wait_seconds
defaults to 2 seconds.
The implementation is distribution specific and not always available.
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.
Make sure the command does not write to the serial output.
The implementation is distribution specific and not always available.
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($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;
Open a root shell.
The implementation is distribution specific and not always available.
ensure_installed $package;
Helper to install a package to SUT.
The implementation is distribution specific and not always available.
power($action);
Trigger backend specific power action, can be 'on'
, 'off'
, 'acpi'
or 'reset'
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;
if backend supports it, eject the CD
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([$timeout_sec]);
Wait until the system becomes idle (as configured by IDLETHRESHOLD) or timeout. This function only works on qemu backend and will sleep on other backends. As such it's wasting a lot of time and should be avoided as such. Take it as last resort if there is nothing else you can assert on. Default timeout is 19s.
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($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($file [, failok => 0 ]);
Upload $file
to OpenQA WebUI as a log file and return the uploaded file name. If failok is not set, a failed upload 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.
upload_asset $file [,$public];
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;
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($key);
Hold one $key
until release it
release_key($key);
Release one $key
which is kept holding
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($string [, max_interval => <num> ] [, wait_screen_changes => <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.
secret (bool)
suppresses logging of the actual string typed.
type_password([$password]);
A convenience wrapper around type_string
, which doesn't log the string.
Uses $testapi::password
if no string is given.
mouse_set($x, $y);
Move mouse pointer to given coordinates
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([$button, $hold_time]);
Same as mouse_click only for double click.
mouse_tclick([$button, $hold_time]);
Same as mouse_click only for triple click.
mouse_hide([$border_offset]);
Hide mouse cursor by moving it out of screen area.
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("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("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.
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;
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).
start_audiocapture;
Tells the backend to record a .wav
file of the sound card.
Only supported by qemu backend.
assert_recorded_sound('we-will-rock-you');
Tells the backend to record a .wav
file of the sound card.
Only supported by QEMU backend.
diag('important message');
Write a diagnostic message to the logfile. In color, if possible.
hashed_string();
Return a short string representing the given string by passing it through the MD5 algorithm and taking the first characters.