Define capabilities

Familiarize yourself with the capabilities Perfecto supports for automated testing using Selenium and Appium. To learn more, see Supported Appium capabilities.

On this page:

Perfecto authentication

Capability name	Description
`securityToken`^*	Your personal security token

^* Mandatory parameter

Capabilities for selecting a mobile device

Define the capabilities to select a device in the Perfecto Lab according to device attributes (instead of a specific device ID) and define the Lab credentials.

You can still select a specific device using the deviceName capability.

Tip: Use auto-generated capabilities as the basis for selecting either mobile or web devices.

Capability name	Description	Values/examples
`deviceName`	The deviceId	For example: 345304573489573498
`deviceType`	The platform type	Web, Mobile
`description`	The device description
`location`	The device location	For Example: NA-US-BOS
`manufacturer`	manufacturer	For example: Apple, Samsung, HTC, Microsoft
`model`	The device model.	For example: iPhone-5S, Galaxy S III, Xperia Z, 9100, HTC One
`network`	The device network	For example: AT&T, Verizon
`openDeviceTimeout`	The timeout, in minutes, to wait for a specific device in case it is not available at the start of the script (use with caution)	Max: 9 minutes
`platformName`	The device operating system	For example: Android, Windows, iOS
`platformVersion`	The device operating system version	For example: 9.3.1
`resolution`	The resolution of the device screen	For example: 1920x1080
`screenshotFormat`	Type of image	.jpg (default), .png, .bmp
`automationInfrastructure`	Device automation infrastructure of the mobile	For example: XCUITest, UIAutomation (for iOS), UIAutomator1, UIAutomator2 (for Android)
`audioPlayback`	Determine if device playback audio should be added to the video recording of the execution or not	true, false. Default is false

Copy

Example

DesiredCapabilities capabilities = new DesiredCapabilities("mobileChrome", "", Platform.ANY);
String host = "mymobilecloud.perfectomobile.com";
capabilities.setCapability("platformName", "Android");
capabilities.setCapability("platformVersion", "4.4");
capabilities.setCapability("user", "myUser");
capabilities.setCapability("securityToken", "myToken");
URL url = new URL("https://" + host + "/nexperience/perfectomobile/wd/hub");
RemoteWebDriver driver = new RemoteWebDriver(url, capabilities);

Auto-selection of leading devices

The limitation in using a specific device is that sometimes the device may be busy running a different script or may be disabled. The better option for scripts running automatically is to supply the necessary device characteristics and let Perfecto automatically select the device from the available devices. When the test script does not define a specific device, Perfecto selects a leading device for testing. This is the default configuration in public cloud instances. For private clouds, Perfecto Support can configure leading devices upon request.

The leading devices feature ensures that your tests always run again the most relevant, stable, popular devices with the highest possible OS version. If a leading device is not available, Perfecto selects the device with the highest OS version instead. In particular, Perfecto selects devices based on the following guidelines:

If model or manufacturer are selected, but no platformVersion is selected, Perfecto sets the platformVersion to latest.
If model and manufacturer are not selected and the Leading Device feature is enabled, Perfecto selects one of the leading devices with the highest OS version available.
In either case, if the platformVersion is not selected, Perfecto selects the highest available OS version. Prior to this enhancement, the OS selection was random.
If model is set to leading, Perfecto selects a random leading device with the highest OS version available. If a leading device is not available, the allocation fails.
If model is not selected, Perfecto selects a random leading device with the highest OS version available. If a leading device is not available, Perfecto selects a random device with the highest OS version available.

If you are an automation engineer, this means that when you use the Select device command to select a device based on attributes, you can:

Set the model capability to leading to have the script test one of the leading devices. For example:
Copy
```
capabilities.setCapability(”model", ”leading”);
```
Set the platformVersion capability to Latest to make sure the script tests the latest OS version. For example:
Copy
```
capabilities.setCapability("platformVersion", "Latest”);
```

The following table lists examples.

Capabilities specified	Situation	Result
`platformName=Android`	A leading Android device is available.	A random leading Android device is selected.
`platformName=Android`	A leading Android device is not available.	A random Android device is selected.
`platformName=Android, model=leading`g	A leading Android device is available.	A random leading Android device is selected.
`platformName=android, model=leading`	A leading Android device is not available.	Allocation fails.
`model=Samsung Galaxy S10`	Samsung Galaxy S10 is available.	The specific device is allocated.
`model=Samsung Galaxy S10`	Samsung Galaxy S10 is NOT available.	Allocation fails.
`model=Samsung galaxy S10, platformName=iOS`	Samsung Galaxy S10 is available.	Allocation fails.
`model=Samsung galaxy` `S10, platformName=UK`	There is a Samsung Galaxy S10 in Boston, but not in the UK.	Allocation fails.

For the public cloud, the following devices are currently defined as leading devices.

Android	iOS
Galaxy S10	iPhone 8
Galaxy S10+	iPhone 8 Plus
Galaxy S10e	iPhone X
Galaxy S9	iPhone XS
Galaxy S9+	iPhone XS Max
Galaxy S8	iPhone XR
Galaxy S8 Plus
Pixel 3
Pixel 3 XL

Mobile browser

Capability name	Description	Values
`browserName`	Browser application name	chrome, mobileChrome, safari, mobileSafari, mobileOS, mobileDefault
`version`	Browser version	for example: 53, 49
`platform`		Any

Regular expressions

You can use regular expressions including wildcards. The capability values are case sensitive.

OR: For example, "ATaT|T-Mob" for network means either ATaT (for AT&T) or a network beginning with 'T-Mob'.
NOT: For example, "(?!(Amazon|Apple)).*" for manufacturer means neither Amazon nor Apple.
contains: For example, ".*Galaxy.* for model means the model contains the string 'Galaxy' and would match any of {Galaxy S6, Galaxy S9, Galaxy 8+}.

Capabilities for development

Capability name	Description
`eclipseExecutionId`	The Eclipse execution id
`scriptName`	Name used as the Report Name for the Report Library and Live Stream interfaces (see also the *Smart Reporting capabilities* below)

To learn more see, Supported Appium capabilities.

Capabilities for Desktop Web testing

Learn which capabilities you can use to configure the web machine and web application you want to run.

Web machine configuration capabilities

Set the capabilities to define the machine to be used for your Web app testing. Note that Windows machines are VMs.

Important: The system automatically selects a Selenium 4.x Server version depending on whether the request has been submitted in a valid W3C syntax.

Capability name	Description	Values	Comments
`addHostsRecord`	Add custom records to the VM's hosts file. (See Note3 below.)	<key, value> entry, where Key is the IP-address Value is DNS hostname to add to the file
`browserName`	The browser running on VM.	Internet Explorer, Chrome, Firefox, Edge, Safari.
`browserVersion`	The browser version.	See here for supported browser versions.	The browserVersion capability supports the following values in addition to a version number: latest: This will always run the latest supported version for the selected browser. latest-1: This will run the version previous to the latest version supported. latest-2: This will run a version two previous to the latest version supported. beta: This will always run the latest beta-testing version for the selected browser. These values will be translated to the appropriate version number and will be listed in the execution report with the version number. When running a Safari session, you must specify the version number in the `browserVersion` capability. Including `latest` as the version number may result in an error.
`deviceType`	The platform type	Web, Mobile.
`installCertificates`	The list of web certificates to be installed To learn how to install certificates manually and for information on error codes, see Manage Windows web certificates.	File names, separated by comma, with the following file extensions: .crt, .cer, .pem
`location`	Location of Perfecto Web machine facility, when using a virtual web platform. When accessing physical Mac devices use same values as for Mobile selection (See Note2 below)	US East, EU Germany, AP Sydney.	The location capability is optional when platformName capability is Windows but mandatory when platformName is Mac.
`platformName`^*	The VM OS.	Windows, Mac.
`platformVersion`^*	The OS version.	See list of supported versions.
`resolution`	The VM display resolution.	1024x768 (default) See here for complete list of supported resolutions.
`uploadFileFromRepo`	Upload a file from the Perfecto repository to the virtual machine. Perfecto then downloads the file to the following location on the Mac or virtual Windows machine: Windows: `C://Temp//` Mac: `/tmp/` The location of the uploaded file is returned as part of the return capability uploadedFileLocation. This functionality is also available through the Perfecto extension `perfecto:file:upload`.	uploadFromRepo	To use this capability, add it to your test scripts as follows, where `fileLocation` is the location of the file in the Perfecto repository. Tip: For information on retrieving the file location, see Manage the repository > View, copy, or update file information. `capabilities.setCapability(“uploadFileFromRepo”, “PUBLIC:apiDemos2.apk”);`

^* Mandatory parameter

Copy

Example

DesiredCapabilities capabilities = new DesiredCapabilities("mobileChrome", "", Platform.ANY);
String host = "mymobilecloud.perfectomobile.com";
capabilities.setCapability("platformName", "Windows");
capabilities.setCapability("platformVersion", "10");
capabilities.setCapability("browserName", "Chrome");
capabilities.setCapability("browserVersion", "latest");
capabilities.setCapability("resolution", "1366x768");
capabilities.setCapability("location", "US East");
capabilities.setCapability("installCertificates", List.of("c1.pem","c2.crt"));
URL url = new URL("https://" + host + "/nexperience/perfectomobile/wd/hub/fast");
RemoteWebDriver driver = new RemoteWebDriver(url, capabilities);

Before setting the capability value, set up the records to add to the hosts file as a dictionary. The following examples show how to generate the following lines in the VM's hosts file:

...
# localhost name resolution is handled within DNS itself.
#    127.0.0.1       localhost
#    ::1             localhost
ip1   url1
ip2   url2
                                                

Copy

Java example

Map<String, String> hostsRecords = new HashMap<>();
hostsRecords.put("ip1", "url1");
hostsRecords.put("ip2", "url2");

capabilities.setCapability("addHostsRecord", hostsRecords);

Copy

JavaScript example

var hostsRecords={};
hostsRecords ["ip1"]="host1";
hostsRecords ["ip2"]="host2";

...
var capabilities = {
    ...
    'addHostsRecord': hostsRecords,
    ...
}

Web application capabilities

Taking screenshots affects the execution time of the desktop web test. Screenshot capabilities support Selenium commands (not, for example, Visual Analysis or Assert).

Capability name	Description	Possible values	Default value
`takesScreenshot`	System takes screenshots of application at different points during execution and attaches them to the execution report.	true \| false	false
`screenshotOnError`	System takes screenshot of application at point where an error status is reported. Screenshot is attached to the execution report.	true \| false	true

Copy

Example

capabilities.setCapability("takesScreenshot", true);
capabilities.setCapability("screenshotOnError", false);

General capabilities

Capability name Description Value

Capability name	Description	Value
`waitForAvailableLicense`	Adds the option to wait for an available license when all licenses are in use. In this case, Perfecto displays the following error message: `EE-500-0001 - Max number of sessions reached. To add auto wait timeout of up to 15 minutes, use the "'waitForAvailableLicense': true" capability` Copy Usage example `capabilities.setCapability("waitForAvailableLicense", true);`	Boolean (default: `false`)

waitForAvailableLicense

Adds the option to wait for an available license when all licenses are in use. In this case, Perfecto displays the following error message:

EE-500-0001 - Max number of sessions reached. To add auto wait timeout of up to 15 minutes, use the "'waitForAvailableLicense': true" capability

Copy

Usage example

capabilities.setCapability("waitForAvailableLicense", true);

Boolean (default: false)

Smart Reporting capabilities

Test analysis with Smart Reporting uses different test identifying parameters as flags associated with the test reports. These identifying items are used to filter, select, or just to easily identify the test report. These values may be associated to the test using the reporting SDK or alternatively using the following DesiredCapability fields:

Capability name	Description	Values
`report.projectName`	Identifier of the test run project name	String
`report.projectVersion`	Version number associated with the project	String
`report.jobName`	CI Job name for this test	String
`report.jobNumber`	CI Job number for this test	Integer
`report.jobBranch`	Name of test branch, if relevant	String
`report.tags`	Any tags user associated with this test	Strings, separated by a comma (',')
`report.customFields`	Any set of custom parameters to associate with the test run	Strings in the format `key=value,key=value`...

Any values for the project or job information will be overwritten by settings using the SDK. Values provided for the tags and customFields will be merged, with priority given to values set by the SDK. See also the scriptName capability above.

Copy

Example

String browserName = "mobileOS";
DesiredCapabilities capabilities = new DesiredCapabilities(browserName, "", Platform.ANY );
String host = perfectoLabURL;
capabilities.setCapability("securityToken", myToken);
capabilities.setCapability("report.projectName", "test_fail_to_open");
capabilities.setCapability("report.projectVersion", "2.0");
capabilities.setCapability("report.tags", "spring,forward,tag1");
capabilities.setCapability("report.jobName", "myTestJob");
capabilities.setCapability("report.jobNumber", 8);
capabilities.setCapability("report.jobBranch", "master");
capabilities.setCapability("report.customFields", "cc=custom,mm=fewer");

Perfecto and video

Speed up test execution performance by controlling whether a report or video will be created during script execution. Shorter executions times mean that more tests can be run per hour.

Capability name	Description	Values
`outputVideo`	The test execution output video	true \| false

Copy

Example

capabilities.setCapability("outputVideo", false);

Supported Appium capabilities

To learn more, see Supported Appium capabilities.

Define capabilities

Perfecto authentication

Capabilities for selecting a mobile device

Auto-selection of leading devices

Mobile browser

Regular expressions

Capabilities for development

Capabilities for Desktop Web testing

Web machine configuration capabilities

Web application capabilities

General capabilities

Smart Reporting capabilities

Perfecto and video

Supported Appium capabilities

Also in this section