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 Machine declaration
Vitual machine declaration starts with a machine
keyword. The declaration itself has the following syntax:
machine <name> {
<attr1 [attr1_name]: <value1>
<attr2 [attr2_name]: <value2>
<attr3 [attr3_name]: <value3>
...
}
The declaration itself does not mean the actual creation of the virtual machine. The actual creation happens when the first test mentioning this virtual machine is run.
Virtual machines can also be defined inside macros. See here for more information.
Basically, a virtual machine declaration is a set of configuratoin attributes, some of which are mandatory. Attributes must be separated by newlines. At the end of the declaration another newline has to be placed.
For each virtual machine a <name>
must be specified in the form of an identifier or a string. If a string is used, the value inside the string must be convertible to an identifier. Inside the string param referencing is available. The virtual machine's name must be unique for all the virtual resoruces' names (e.g. virtual machines, virtual flash drives and virtual networks).
An attribute consists of an attribute's name, instance's name (only for several attributes) and a value (mandatory). Attribute names and instances' names are identifiers. At the moment, the only attributes requiring names for the instances, are the nic
and disk
attributes. Values' types depend on the attribute and can be one of:
- Positive integer.
- Memory size literal.
- String.
- Boolean literal.
- Attribute block.
For a virtual machine there is a set of mandatory attributes:
cpus
- Type: positive number or string. Number of cores for a virtual processor. If a string is used, the value inside the string must be convertible to positive integer. Inside the string param referencing is available.ram
- Type: memory size literal or string. The amount of RAM for the virtual machine. If a string is used, the value inside the string must be convertible to a memory size literal. Inside the string param referencing is available.- at least one
disk
attribute - Type: attribute block. Requires an instance's name. A disk drive coniguration.
Optional attributes:
iso
- Type: string. Path to the iso-image to be plugged into the DVD-drive after the virtual machine creation. Could be unplugged afterwards with anunplug dvd
action. Inside the string param referencing is available.- One or more
nic
- Type: attribute block. NIC configuration. Requires an instance's name. A NIC configuration. - Exactly one
video
attribute - Type: attribute block. Requires an instance's name. Video device configuration. Unavailable for Hyper-V. loader
- Type: string. Path to a custom loader blob file. Inside the string param referencing is available. Unavailable for Hyper-V.qemu_enable_usb3
- Type: boolean. Enables USB 3 controller for the virtual machine. When the value isfalse
, USB 2 controller is enabled instead. Default value:true
. Unavailable for Hyper-V.
Disks configuration
Virtual machine disks configuration is done with the disk
attributes. For each disk in a virtual machines a disk
attribute is required. To distiguish multiple disks between themselves, every disk
attribute must have a unique (inside the virtual machine) name. The value must be a block of inner attributes. The exact attribute choice depend on what mode you want to configure the disk into.
You can specify several disks for a virtual machine. Just remember to choose unique names for each disk.
Blank disk creation mode
In this mode a new blank disk is created for the virtual machine. To activate this mode you have to specify the size
attribute in the inner block of the disk
attribute. The size
attribute must be a memory size literal or a string. If a string is used, the value inside the string must be convertible to a memory size literal. Inside the string param referencing is available.
Impoting an existing disk image
In this mode a copy of some existing disk image will be created for the virtual machine. With this mode you can manually prepare a virtual machine and then import your setups in the test scripts. To activate this mode you have to specifiy the source
attribute in the inner block of the disk
attribute. The source
attribute must be a string. The source attribute must contain a path to the disk image you want to import.
At the moment only
qcow2
disk images for QEMU andvhdx
disk images for Hyper-V are supported.
The original disk image will stay intact. When importing a disk image a copy is created.
If the original disk image belong to a virtual machine, this machine must be powered off when test scripts run.
Attributes
size
andsource
are mutually exclusive. When one is used the other becomes disabled automatically.
IMPORTANT NOTE! Please, do NOT install testo-guest-additions manually while preparing a virtual machine template! It could lead to unexpected results. Please, istall testo-guest-additions INSIDE test scripts only!
NICs configuration
Network Interface Cards (NICs) configuration is done with the nic
attributes. For each NIC for a virtual machine a nic
attribute is required. To distinguish multiple NICs between themselves every nic
attribute must have a unique (inside the virtual machine) name. The value must be a block of attributes:
Mandatory nic
attributes:
attached_to
- Type: string. Network name to attach the NIC to. The network must be previously declared with thenetwork
directive.
Optional nic
attributes:
adapter_type
- Type: string. A model for the NIC. Different NIC models are run by different drivers. Possible values:ne2k_pci
,i82551
,i82557b
,i82559er
,rtl8139
,e1000
,pcnet
,virtio
,sungem
. If not specified, the hypervisor-default model will be selected. For QEMU the default value isrtl8139
. Inside the string param referencing is available. Unavailable for Hyper-V.mac
- Type: string. MAC-address for the NIC. The value must be a valid MAC address (like00:11:22:33:44:55
). If not specified, a random MAC-address will be generated for the NIC. Inside the string param referencing is available.
Virtual machines are created with all the NICs attached and the links plugged into them. You can detach the NIC with the
unplug nic
action and unplug the virtual link from the NIC with theunplug link
action.
Video device configuration
Unavailable for Hyper-V.
Virtual machines are always created with exactly one video device. By default, the model for this devies is picked based on the current hypervisor capabilities. In the most cases, the vmvga
model is picked. If, foir some reason, you want to choose some other model, you can specify it explicitly.
To do so you sohuld use the video
attribute instance of the virtual machine configuration. The attribute's instance must have a name.
At the moment it is possible to use only one instance of the
video
attribute.
The
video
attribute is optional, there is no need to specify it all the time. If the attribute is absent, the default video device is created.
video
attribute takes a block of inner attributes as a value. There is only one inner attribute available at the moment:
qemu_mode
- Type: string. Video device model. Possible values:vmvga
,qxl
,cirrus
,virtio
. Inside the string param referencing is available.
Bootloader configuration
Unavailable for Hyper-V.
By default, virtual machines use the SeaBIOS bootloader. If you want to use some custom bootloader (for example, UEFI-compatible), you should specify the path to this custom loader in the loader
attribute.
For example, you can enable UEFI in a virtual machine with following steps:
- Download OVMF.
- Specify the path to the
OVMF_CODE.fd
in theloader
attribute (see example below).
Complete example
This example is valid only for QEMU. For other hypervisors some attributes from the example below are unavailable.
Below you can see a complete example of a virtual machine configuration. Here are some main features:
- When the virtual machine is created, the Ubuntu Server 16.04 iso-image is loaded into the virtual DVD-drive.
- Two disks are created for the virtual machine: the
main
is copied (imported) from the existing disk image (from the manually created and prepared virtual machinemy_hand_mand_vm
) and thesecondary
is created empty, with the size specified in thesize_amount
param. - The virtual machine has 3 NICs: the
nat
will be used to connect the VM with the Internet and theWAN
and theLAN
will be used for isolated local area networks (net1
andnet2
), presumably connecting the VM with other VMs.
Take notice that the iso
, disk main's source
and disk secondary's size
attributes' values are calculated based on the ISO_DIR
, VM_DISK_POOL_DIR
and size_amount
params respectively. If any of these params is not defined (it is assumed that these params are to be passed as --param
command line arguments) an error will be generated. For the size
attribute an additional rule takes place: size_amount
param value must be convertable to a memory size literal (for example, "2Gb"). Otherwise an errow will be generated.
machine example_machine {
cpus: 1
ram: 1024Mb
iso: "${ISO_DIR}/ubuntu-16.04.6-server-amd64.iso"
disk main: {
source: "${VM_DISK_POOL_DIR}/my_hand_made_vm.qcow2"
}
disk secondary: {
size: "${size_amount}"
}
nic nat: {
attached_to: "nat"
adapter_type: "e1000"
}
nic WAN: {
attached_to: "net2"
mac: "52:54:00:00:00:00"
adapter_type: "e1000"
}
nic LAN: {
attached_to: "net1"
mac: "52:54:00:00:00:11"
adapter_type: "e1000"
}
video main: {
qemu_mode: "qxl"
}
loader: "/usr/share/OVMF/OVMF_CODE.fd"
qemu_enable_usb3: false
}
Virtual machines caching
There is a cachine mechanism for virtual machines in the Testo Framework. This helps to check the integrity of vms' configurations. If a configuration has changed since the last Testo run (and therefore the cache is lost), then the virtual machine must be re-created, and all the tests involving this virtual machine must be re-run. This is one of the checks performed when evaluating the cache integrity.
The complete virtual machines cache consistency checklist is this:
- Has any attribute changed since the last successful test run?
- Has the iso-image from the
iso
attribute changed since the last successful test run? - Has the disk-image from the
source
attribute for the imported disks changed since the last successful test run? - Has any
network
mentioned inattached_to
innic
sections changed? - Has the
loader
file changed?
If the answer to any of these questions is "yes", then the cache is lost and the virtual machine must be re-created.
There are two ways to check the files' cache consistency for the
iso
andsource
attributes. If the file's size is less then 1 MB (which is basically impossible) then the file's integrity is evaluated based on its contents. Othwervise the evaluation is based on the Last modified timestamp of the file. You can adust the threshold of changing the evaluating mode with thecontent_cksum_maxsize
command line argument.
Manual virtual machine setup
The main Testo concept is to document every action happening with virtual machines right from the bare scratch - starting with the virtual machine clean and empty state (just what you get when you manually create a new virtual machine without importing pre-setup disks). This approach allows Testo to deploy required Test Benches with only .testo
script files (which are easy to store and manage) and a few extra iso-files for the OS installation. This way all the Test Bench setup is placed right in front of your eyes (in the form of test scripts) and you can easily understand and change all that is done with the Test Bench.
However, this approach, of course, has a downside: scripting all the actions from the very beginning could be tedious and uneccessary in some cases. So to save you some labor, Testo-lang has a way to import a manually prepared virtual machine's disk into your Testo Test Bench. To import an existing virtual machine you should stick to the following algorithm:
- Manually create a virtual machine to your liking. When manually creating the VM, you can choose any convenient configuration, but keep in mind the eventual Testo virtual machine configuration.
- Manually set up the virtual machine to your liking (install OS, 3rd party software, change all the required settings and so on).
- Turn off your VM.
- Declare a new virtual machine in a
.testo
file and import the disk image from your manually created VM into it with thesource
attribute of a disk attribute.
Now your Testo-declared machine has a "clone disk" of your manually created VM and you can start the test scripts right from where you ended setting up your original VM.
Of course you could import any suitable disk image into a VM, not neccessary from another virtual machines. You could also combine various types of disks (newly created or imported) in the same virtual machine.
The original VM disk's integrity is a part of cache consistency checks for Testo virtual machines. And therefore if you want to change the initial state of your imported VM you need just to power on your original VM, make some changes, power off the original VM and re-run the tests. The imported virtual machine's cache will be lost and all the according tests will be run again.
You should consider the disk import as exactly the disk only import, not the whole machine import. There's no guarantee that Testo-created machine will have exactly the same hardware configuration as the original manually created virtual machine. In particular, the OS in the Testo-created machine may have other NICs naming order, than the OS in the original machine. Therefore it is strongly not recommended to setup the NICs (IP-addresses and so on) manually, because after the disk import the network settings may turn up lost. Instead, you should consider setting up the network in the test scripts.