Page tree
Skip to end of metadata
Go to start of metadata

Last updated: May 05, 2020 15:31

When selecting a desktop web device to use for automation testing of a web application, there is sometimes the need to create the proper environment for the device. This may require that the device has data files in a particular location of the desktop web device's "storage", certificates are installed, or certain additional applications run in the background. This will more closely reflect the working environment of the web application's end user.

Service overview

The Desktop-Web Customization Service (DCS) allows the user to pre-configure the Desktop-Web VM, generated for automation testing, with resources supplied from a repository of artifacts.

The configuration of the VM is performed based on a "playbook" that includes YAML instructions of what configuration operations, for example install certificates, download artifacts, application executions, to perform prior to executing the automation script.

DCS is called as part of the Selenium execution, under the control of the DesiredCapabilities, and executes the playbook instructions on the generated VM accessing files stored on Perfecto's cloud storage. When the playbook instructions are complete, the automation script is activated on the Desktop-Web VM in the proper environment.

On this page:

Use the DCS

This section walks you through using the DCS.

1 | Prepare the playbook

The playbook is a YAML file that follows a syntax similar to the Ansible playbook syntax. This syntax allows the playbook to run commands in a Windows cmd window using the win_shell module. Sample playbook files can be found in the Ansible git repo.

Note: Playbooks for DCS should define the hosts to be all (at start of playbook) - the actual host is dynamically determined by DCS -

- name: Configure Fast Web VM
hosts: all

Perfecto supplies a small set of prepared playbook files:

Playbook NameDescription
pm-self-signed.ymlInstall certificates (previously uploaded to the Perfecto cloud-based repository, as below) onto the Desktop-Web VM
pm-upload-files.ymlUpload files (previously uploaded to the Perfecto cloud-based repository, as below) onto the Desktop-Web VM.
Files will be located at C:\Temp on the VM "disk storage".

These can be customized for the particular customer's use case. Alternatively, a custom-playbook can be prepared for the user.

Note: Customizing the playbook should be prepared and reviewed together with Perfecto support and developers.

2 | Upload files

The playbook execution may access files that need to be transferred to the VM during the DCS processing. The files are stored in a partition for the particular customer in a Perfecto, cloud-based, repository. These files will be uploaded by Perfecto support for the customer.

3 | Specify the DCS in the automation script

The DCS feature introduces the following new Selenium driver Capabilities:

  • customizationScript - identifies the playbook used to configure the Desktop-Web environment. Playbook file should be located in the customer's partition in the Perfecto cloud repository and should be in the format described above.
  • customizationScriptArgs - arguments supplied to the playbook. The arguments should be supplied as a Java Map format. The playbook supports two arguments:
    • timeout - defines the timeout for completion of the customization. Integer value indicates the number of seconds [default value: 90 sec]
    • fileslist - a list of String names of artifacts that playbook accesses.

The following snippet uses the capabilities to identify the playbook, and supply a list of files and a new timeout:

Map<String, Object> resourceArgs = new HashMap<>();
resourceArgs.put("timeout", 120);
myfiles =  new String[]{"arg1", "arg2", "arg3"};
resourceArgs.put("fileslist", myfiles);
capabilities.setCapability("customizationScript", "MyPlaybook.yml");
capabilities.setCapability("customizationScriptArgs", resourceArgs);

For a full sample, see the sample in GitHub that pre-loads a set of certificates to the Desktop-Web machine.

Troubleshooting and limitations

Error messages

DCS may report two error indicators in various situations:

  • Timeout exceeded - if the customization process requires a longer time than the configured timeout (default 90 sec, see above customizationScriptArgs) - the error message will appear in the execution report as:
    WFA-500-0156 – “Customization script timeout exceeded
  • General playbook error - reported in various situations, for example - file not found, YAML syntax error. The error message will appear in the execution report as:
    WFA-500-0157 – <text describing the exact error>


The feature is currently supported only on Windows Fast Web configurations.

Not supported on Mac Desktop-Web devices.