Getting Started
IntroductionGetting startedOverviewRunning TestoTests running policyTesto for Hyper-V Guides
Guide 1. The very first testGuide 2. Ubuntu Server InstallationGuide 3. Internet access in virtual machinesTesto for QEMU Guides
Guide 1. The very first testGuide 2. Ubuntu Server InstallationGuide 3. Guest AdditionsGuide 4. ParamsGuide 5. CachingGuide 6. Internet access in virtual machinesGuide 7. Linking up virtual machinesGuide 8. Flash DrivesGuide 9. MacrosGuide 10. If clauseGuide 11. No snapshotsGuide 12. Mouse controlGuide 13. Importing disk imagesGuide 14. JS-selectorsGuide 15. CyclesGuide 16. Macros with declarationsReference
Test scripts general overviewTesto lang basic syntaxVirtual Machine declarationVirtual flash drive declarationVirtual network declarationParamsTests declarationMacrosVirtual Machines ActionsMouse actionsDetecting images on the screenVirtual Flash Drives ActionsConditionsCyclesPossible keyboard key IDsJavascript selectors
Main conceptsBuilt-in global functionsExceptionsClass TextTensorClass ImgTensorClass PointVirtual Machines Actions
start
Starts a virtual machine. The virtual Machine must be stopped at the moment of the call. Starting an already started virtual machine results in an error.
start
Arguments: no
stop
Stops a virtual machine, simulating power failure. The virtual machine must be running at the moment of the call. Trying to stop an already stopped virtual machine results in an error.
stop
Arguments: no
shutdown
Sends the ACPI signal to a virtual machine, launching a "mild" virtual machine stop. The action waits for the virtual machine to get powered off. Waiting timeout depends on the optional argument timeout_time_spec
. Virtual machine OS must support ACPI signal processing to make this action work. The virtual machine must be running at the moment of the action call. Trying to shutdown an already stopped virtual machine results in an error.
shutdown [timeout timeout_time_spec]
Arguments:
timeout_time_spec
- Type: time interval or string. Timeout for the virtual machine to stop. Default value - 1 min. If the string type is used, the value inside the string must be convertible to a time interval. Inside the string param referencing is available.
Examples:
shutdown
shutdown timeout 10m
shutdown timeout "5m"
#works if the value of param shutdown_timeout is convertible to a time interval
shutdown timeout "${shutdown_timeout}"
press
Sends signals to a virtual machine, providing pressings of keyboard keys specified in key_spec
. The press
action also supports sending sequences of key pressings. In this case the key specifications must be divided by commas. You can adjust the sleep time interval between the pressings with the interval_time_spec
interval. The virtual machine must be running.
press <key_spec1>[,key_spec2][,key_spec3]... [interval interval_time_spec]
Arguments:
key_spec
- Key specification to press.interval_time_spec
- Type: time interval or string. Sleep time interval between the key pressings. Default value:30ms
. If the string type is used, the value inside the string must be convertible to a time interval. Inside the string param referencing is available. Default value can be changed with theTESTO_PRESS_DEFAULT_INTERVAL
param. See here for more information.
Key specification
Key specification is a special language clause and looks like this:
<key_id1>[+key_id2][+key_id3]...[*number]
key_id
is an identifier containing the name of a key. See here for a complete list of key values. key_id
is case-insensitive, so for example enter
is treated the same way as Enter
or ENTER
.
Key specification consists of two parts: combination of the keyboard keys pressed simultaneously and the number of times to press this combination. The combination part must contatin at least one key_id
. To press several keys simultaneously you need to add more key_ids
and divide keys with the "+" sign. The number part shows how many times the combination part must be pressed.
The number part (number
) may be either a positive integer or a string. If the string type is used, the value inside the string must be convertible to a positive integer. Inside the string param referencing is available.
Key spec examples:
Down
- press "Down arrow" key one time.LEFTCTRL + alt + Delete
- press keys Ctrl Alt Delete simultaneously one time.LEFTCTRL + alt + Delete * 1
- the same as the previous example.Backspace * "6"
- press the Backspace 6 times.leftalt + F2 * "${number_num}"
- press LeftAlt and F2 keys simultaneously as many times as specified innumber_num
param. Works only if thenumber_num
param can be converted to a positive integer.
press
action examples
#Press "Down" 6 times, then press Enter 1 time
press Down*6, Enter
# send key combination Ctrl Alt Delete, then press Down 2 times, then Enter 3 times
press LeftCTRL + LEFTALT + Delete, Down*2, Enter*3
hold
Hold down keyboard keys specified in key_spec
in a virtual machine. The keys will be held until explicit call of the release
action. The virtual machine must be running.
hold <key_spec>
Arguments:
key_spec
- Key specification to hold down.
Notes
The hold
action has some restrictions:
- You can't hold down keys already being held;
- You can't finish a test with any keys being held. You must call the
release
action before the end of the test; - You can't use keys being held down in
press
actions; - You can't use keys being held down when typing text in
type
actions; - You can't use a number of times in the
key_spec
. It is implied that keys can be held down only one time.
release
Release keyboard keys specified in key_spec
in a virtual machine. The keys to be released must be held down by a previously called hold
action. If no key_spec
is specified, all the held keys are to be released. The virtual machine must be running.
release [key_spec]
Arguments:
key_spec
- Key specification to release.
Notes
The release
action can be used with no arguments. In this case all the keys being held down are to be released. If you need to release only some of the held down keys you have to specify the key_spec
argument.
The release
action has some restrictions:
- You can't release the keys that are not being held down;
- You can't call the
release
action without akey_spec
if there is no keys being held down; - You can't use a number of times in the
key_spec
. It is implied that keys can be released only one time.
Examples
#Hold down left ctrl and left alt
hold LeftCtrl + LeftAlt
press Delete
#Release only left ctrl
release LeftCtrl
#Release all the keys being held down (e.g. left alt)
release
type
Type a text specified in string
using the virtual machine keyboard. The virtual machine must be running. All the newline characters ('\n') in the specified text are transformed to the Enter
key pressings. All the tab characters ('\t') a transformed to the Tab
key pressings.
type <text> [interval interval_time_spec]
Arguments:
text
- Type: string. The text to type. Inside the string param referencing is available.interval_time_spec
- Type: time interval or string. Sleep time interval between the key pressings when typing the text. Default value:30ms
. If the string type is used, the value inside the string must be convertible to a time interval. Inside the string param referencing is available. Default value can be changed with theTESTO_TYPE_DEFAULT_INTERVAL
param. See here for more information.
Examples:
type "Hello world"
type "Hello ${World}"
type """Hello ${World}
Some multiline
string ${World} another multiline
string
"""
type "Hello world" interval 30ms
type "Hello world" interval "1s"
# works if the param value "type_interval" is convertible to a time interval
type "Hello world" interval "${type_interval}"
mouse
Mouse-related actions are documented here.
sleep
Unconditional sleep for specified amount of time.
sleep <timeout timeout_time_spec>
Arguments
timeout_time_spec
- Type: time interval or string. Time period to sleep. If the string type is used, the value inside the string must be convertible to a time interval. Inside the string param referencing is available.
Examples:
sleep 10s
# works if the param value "sleep_timeout" is convertible to a time interval.
sleep "${sleep_timeout}"
wait
Wait for an event to appear on the virtual machine screen. The event is specified in the select_expr
argument. Waiting timeout is specified in the timeout_time_spec
argument. If the expected event does not appear before the timeout, an error is generated. You can adjust the screen check frequency with the interval_time_spec
argument. The virtual machine must be running.
wait <select_expr> [timeout timeout_time_spec] [interval interval_time_spec]
Arguments:
select_expr
- Select expression (an event) to wait.timeout_time_spec
- Type: time interval or string. Timeout for theselect_expr
to appear on the screen. Default value:1m
. If the string type is used, the value inside the string must be convertible to a time interval. Inside the string param referencing is available. Default value can be changed with theTESTO_WAIT_DEFAULT_TIMEOUT
param. See here for more information.interval_time_spec
- Type: time interval or string. Time interval between the screen checks for the expected event to appear. Default value:1s
. If the string type is used, the value inside the string must be convertible to a time interval. Inside the string param referencing is available. Default value can be changed with theTESTO_WAIT_DEFAULT_INTERVAL
param. See here for more information.
Select expressions for the wait
and check
actions
The wait
action and check
expression provide you with not only some basic screen checks (the presense or absense of a text or an image), but also some more coplex checks, as well as whole combinations of checks. There are three types of checks in Testo-lang:
Basic text checks
If you just want (or check) to simply wait for a text to appear on the screen, all you need to do is to perform a wait
action with the following syntax:
wait "Extected string"
Inside the string param referencing is available, like this:
wait "Extected string with a param value ${param}"
The text must be continuous, i.e. there must be no newlines or big gaps between characters. For example, if a text consists of three words, but the third word stays too far from the first two words, then the wait for the whole text will fail.
Basic image checks
If you need wait (or check) for an image to appear on the screen, then you should place the img
specifier after the wait
(or check
), followed by a path to the image template you want to find:
wait img "/path/to/img/to/be/searched"
See more informations about image detection here.
Complex javascript-based checks
For more elaborate screen checks in the wait
(or check
) you can use javascript selections. These selections look like javascript code snippets which must return a bool-value true
or false
.
If the javascript returned true
- then wait
and check
actions are considered complete, and test control goes to the next action. Otherwise wait
and check
processing continues until a true
is returned or a timeout is due. Any other returned value is treated as an error and the test will fail.
wait js "find_text('Hello world').match_color('blue', 'gray').size() == 1"
The example above waits for a text "Hello world" with blue charecters and gray background to appear on the screen. Such a string could represent, for example, a selected menu entry.
For more information about javascript-selections see here.
Using several checks together in the same action
Checks may be combined together into whole select expressions with logical connectives and negations: &&
(AND), ||
(OR) and !
(NOT). Exressions also support nested expressions enclosed in parentheses.
Examples
wait "Hello world" && img "${IMG_DIR}/my_icon.png"
Wait for simultaious presence of the text "Hello world" and the image, which path depends on the value of the IMG_DIR
param.
# works if the param value "wait_timeout" is convertible to a time interval
wait !"Hello world" || js """
find_text("Menu entry")
.match_color("${foreground_colour}", "gray")
.size() == 1
""" timeout 10m interval "${wait_interval}"
Wait for either of two events:
- Absense of the text
Hello world
on the screen. - Presence of the text
Menu entry
on the screen.Menu entry
must have the grey background and the character color determined by theforeground_colour
param value.
Check frequency is determined by the value of the wait_interval
param. Maximum waiting time is 10 minutes.
Macro call
Call the macro_name
macro. The macro must be declared before the calling. The macro must consist of actions (not commands) applicable to virtual machines.
Macro calls are described here.
plug
The plug
action allows you to attach various devices to a virtual machine. All the possible ways to use the plug
actions are listed below.
plug flash
This action is not available for Hyper-V
Insert a virtual flash drive into a virtual machine.
plug flash <flash_name>
Arguments:
flash_name
- Type: identifier or string. The name of the virtual flash drive to insert. The flash drive must be declared and not be inserted in any virtual machine. If the string type is used, the value inside the string must be convertible to an identifier. Inside the string param referencing is available.
Examples:
plug flash my_flash
plug flash "my_flash"
# works if param value "flash_name" is convertible to an identifier
# and if the flash drive with such name is declared
plug flash "${flash_name}"
At the moment it is not allowed to have more than 1 flash drive plugged into a virtual machine at the same time.
All plugged flash drives must be unplugged before the end of the test. It is not allowed to finish a test with plugged flash drives.
Trying to plug an already plugged flash drive will result in an error.
plug nic
Insert a Network Interface Card (NIC) into a virtual machine. The name of the NIC must correspond to a name specified in the nic
attribute of the virtual machine declaration. The virtual machine must be powered off.
plug nic <nic_name>
Arguments:
nic_name
- Type: identifier or string. The name of the NIC to insert. The NIC with this name must be declared in the virtual machine configuration. If the string type is used, the value inside the string must be convertible to an identifier. Inside the string param referencing is available.
plug nic internet_nic
plug nic "internet_nic"
# works if param value "nic_name" is convertible to an identifier
# and if the NIC with the resulting name exists in the virtual machine configuration
plug nic "${nic_name}"
Plugging/Unplugging NICs requires that the virtual machine must be powered off.
Trying to plug an already plugged NIC will result in an error.
plug link
Plug a virtual link to the NIC. The name of the NIC must correspond to a name in the nic
attribute of the virtual machine declaration.
plug link <nic_name>
Arguments:
nic_name
- Type: identifier or string. The name of the NIC to plug the link into. The NIC with this name must be declared in the virtual machine configuration. If the string type is used, the value inside the string must be convertible to an identifier. Inside the string param referencing is available.
Trying to plug an already plugged link will result in an error.
plug dvd
Insert the iso-image of a disk into the virtual DVD drive of a virtual machine.
plug dvd <path_to_iso_file>
Arguments:
path_to_iso_file
- Type: string. The path to the iso-image. The specified iso-image must exist.
Trying to plug an iso into the already occupied DVD-drive will result in an error.
plug hostdev usb
This action is not available for Hyper-V
Attach a Host-plugged USB device to the virtual machine.
plug hostdev usb <usb_device_address>
Arguments:
usb_device_address
- Type: string. The USB address of the device to be plugged. The address must be represented as"Bus_num-Device_num"
, whereBus_num
andDevice_num
are decimal numbers (for instance,"3-1"
). Inside the string param referencing is available.
An attempt to plug an already plugged USB device will result in an error.
An USB device can't be plugged at more than one Virtual Machine at a time.
If the test isn't labeled with the
no_snapshots: true
attribute, then all the plugged USB devices must be unplugged before the end of the test. An attempt to finish the test with a USB device attached to a virtual machine will lead to an error.
You can check the USB address for the device with the
lsusb
utulity (for instance).
MOST IMPORTANT! Testo does not take snapshots and does not provide any guarantee about the integrity of plugged Host USB devices. Testo won't undo all the changes done to the USB device during tests! Use this action at your own risk!
unplug
The unplug
action allows you to detach various devices from a virtual machine. All the possible ways to use the unplug
actions are listed below.
unplug flash
This action is not available for Hyper-V
Remove a virtual flash drive from a virtual machine.
unplug flash <flash_name>
Arguments:
flash_name
- Type: identifier or string. The name of the virtual flash drive to remove. The flash drive must be declared and inserted into current virtual machine. If the string type is used, the value inside the string must be convertible to an identifier. Inside the string param referencing is available.
All plugged flash drives must be unplugged before the end of the test. It is not allowed to finish a test with plugged flash drives.
Trying to unplug an already unplugged flash drive will result in an error.
unplug nic
Remove a Network Interface Card (NIC) from a virtual machine. The name of the NIC must correspond to a name in the nic
attribute of the virtual machine declaration. The virtual machine must be powered off.
unplug nic <nic_name>
Arguments:
nic_name
- Type: identifier or string. The name of the NIC to detach. The NIC with this name must be declared in the virtual machine configuration. If the string type is used, the value inside the string must be convertible to an identifier. Inside the string param referencing is available.
Plugging/Unplugging NICs requires that a virtual machine must be turned off.
Trying to unplug an already unplugged NIC will result in an error.
unplug link
Unplug a virtual link from a NIC. The name of the NIC must correspond to a name in the nic
attribute of the virtual machine declaration.
unplug link <nic_name>
Arguments:
nic_name
- Type: identifier or string. The name of the NIC to unplug the link from. The NIC with this name must be declared in the virtual machine configuration. If the string type is used, the value inside the string must be convertible to an identifier. Inside the string param referencing is available.
Trying to unplug an already unplugged link will result in an error.
unplug dvd
Remove the current iso-image from the DVD-drive of the Virtual Machine.
unplug dvd
Arguments: no
Trying to remove the iso-image from an empty DVD-drive will result in an error.
unplug hostdev usb
This action is not available for Hyper-V
Detach a Host-plugged USB device from the virtual machine.
unplug hostdev usb <usb_device_address>
Arguments:
usb_device_address
- Type: string. The USB address of the device to be unplugged. The address must be represented as"Bus_num-Device_num"
, whereBus_num
andDevice_num
are decimal numbers (for instance,"3-1"
). Inside the string param referencing is available.
An attempt to unplug a not-plugged USB device will result in an error.
exec
Execute the specified in the script
script inside a virtual machine with the interpreter specified in interpreter
. The testo-guest-additions
agent must be installed on the virtual machine before calling this action. If the interpreter failed (exit code is not 0), then the current test fails with an error. Stdout and stderr from the interpreter
are redirected to Testo stdout, therefore you can see the script processing in real time.
exec <interpreter> <script> [timeout timeout_time_spec]
Arguments:
interpreter
- Type: identifier. The name of the interpreter to execute the script. At the moment the next values are allowed:bash
,cmd
,python
,python2
andpython3
. The interpreter must be installed and available inside the virtual machine OS.script
- Type: string. The script to execute.timeout_time_spec
- Type: time interval or string. Timeout for the script to execute. Default value:10m
. If the string type is used, the value inside the string must be convertible to a time interval. Inside the string param referencing is available. Default value can be changed with theTESTO_EXEC_DEFAULT_TIMEOUT
param. See here for more information.
Examples:
exec bash "echo Hello world!"
exec cmd "echo Hello world!" timeout 5m
# works if the param value "python_timeout" is convertible to a time interval
exec python """
print('Hello, world!')
""" timeout "${python_timeout}"
copyto
Copies a file or a directory from the Host to a virtual machine. The testo-guest-additions
agent must be installed on the virtual machine before calling this action.
copyto <from> <to> [nocheck] [timeout timeout_time_spec]
Arguments:
from
- Type: string. Path to the file or directory on the Host. The path must exist.to
- Type: string. Full destination path on the virtual machine.nocheck
- Type: identifier with fixed value. The presence of this specifier disables the semantic checking of the file existence on the host. This way you can run tests withcopyto
actions even if thefrom
file doesn't exist on the host at the moment of running. It is assumed that the file will be there at the actual moment ofcopyto
execution.timeout_time_spec
- Type: time interval or string. Timeout for copying to complete. Default value:10m
. If the string type is used, the value inside the string must be convertible to a time interval. Inside the string param referencing is available. Default value can be changed with theTESTO_COPY_DEFAULT_TIMEOUT
param. See here for more information.
You must specify the full destination path in the
to
argument. For example, if you need to copy the file/home/user/some_file.txt
on the virtual machine destination/path/on/vm/some_file.txt
you should callcopyto
like this:copyto /home/user/some_file.txt /path/on/vm/some_file.txt
. Copying directories falls under the same rules.
Copying links is not allowed.
You should remember that with the
nocheck
specifier thefrom
files' integrity is not included in the test cache. Which means that changing thefrom
files won't lead to the test cache invalidation.
copyfrom
Copies a file or a directory from a virtual machine to the Host. The testo-guest-additions
agent must be installed on the virtual machine before calling this action.
copyfrom <from> <to> [timeout timeout_time_spec]
Arguments:
from
- Type: string. Path to the file or directory on the virtual machine. The path must exist.to
- Type: string. Full destination path on the Host.timeout_time_spec
- Type: time interval or string. Timeout for copying to complete. Default value:10m
. If the string type is used, the value inside the string must be convertible to a time interval. Inside the string param referencing is available. Default value can be changed with theTESTO_COPY_DEFAULT_TIMEOUT
param. See here for more information.
You must specify the full destination path in the
to
argument (seecopyto
action notes).
Copying links is not allowed.
abort
Abort the current test running with an error message. The test is considered failed.
abort <error_message>
Arguments:
error_message
- Type: string. Abort (error) message.
Prints a message to the Testo stdout.
print <message>
Arguments:
message
- Type: string. Message to print.