Guidance on using capabilities in Perfecto

Use this guidance to help you apply capabilities effectively when working with Perfecto. Whether you're selecting devices, configuring test environments, or setting up reporting and video options, the following examples and tips are designed to support real-world testing needs. Refer to this content when you're deciding which capabilities to use and how to combine them for different scenarios.

Example: Selecting a mobile device for testing

You define the capabilities to select a device in the Perfecto Lab according to device attributes (instead of a specific device ID) and define the Perfecto security token. To learn more, see Capabilities for selecting a mobile device.

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

Following are examples for supported minimal combinations:

• Mobile web session: 

  securityToken + automationName + deviceName/udid/any other device selection criteria + browserName

• Android session:

  securityToken + automationName + deviceName/udid/any other device selection criteria + app

• iOS session:

  securityToken + automationName + deviceName/udid/any other device selection criteria + bundleId

The following code snippet demonstrates how to initiate a mobile web test on an Android device using Appium 2 and Perfecto. It configures the test to run Chrome on any available Android device (using a regular expression for device selection) and includes Perfecto-specific capabilities for authentication. This setup is ideal for executing cross-device browser tests in the Perfecto cloud.

import io.appium.java_client.android.AndroidDriver;
import io.appium.java_client.android.options.UiAutomator2Options;
import org.openqa.selenium.WebDriver;

import java.net.URL;

public class PerfectoChromeTestAppium2 {
    public static void main(String[] args) throws Exception {
        UiAutomator2Options options = new UiAutomator2Options();
        options.setPlatformName("Android");
        options.setPlatformVersion("14");
        options.setBrowserName("Chrome");
        options.setDeviceName(".*"); // regex for any device

        // Perfecto-specific capabilities — must use perfecto: prefix
        options.setCapability("perfecto:user", "myUser");
        options.setCapability("perfecto:securityToken", "myToken");

        String host = "mymobilecloud.perfectomobile.com";
        URL url = new URL("https://" + host + "/nexperience/perfectomobile/wd/hub");

        WebDriver driver = new AndroidDriver(url, options);

        driver.get("https://example.com");
        System.out.println("Page Title: " + driver.getTitle());

        driver.quit();
    }
}

Additional concepts for device selection

To help you fine-tune your device selection in Perfecto, there are a few advanced techniques worth knowing. Whether you're looking to match devices using patterns or prefer to let Perfecto automatically choose the most suitable option, these concepts can make your test setup more flexible and efficient.

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:

1. If model or manufacturer are selected, but no platformVersion is selected, Perfecto sets the platformVersion to latest.
2. 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.
3. 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.
4. 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.
5. 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

  options.setCapability("perfecto:model", "leading");

• Set the platformVersion capability to Latest to make sure the script tests the latest OS version. For example:

  Copy

  options.setCapability("appium:platformVersion", "latest");

The following table lists examples.

Use of regular expressions

Perfecto supports the use of regular expressions in capability values, allowing for flexible and dynamic device selection. This is especially useful when targeting devices by partial matches or excluding specific attributes. Note that all regular expression values are case-sensitive.

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 S23, Galaxy S24, Galaxy Tab S8 Ultra}.

Example: Using web machine configuration capabilities

The following Java code demonstrates how to run a Selenium WebDriver test on a remote desktop Chrome browser using Perfecto. It sets up a RemoteWebDriver session with specific capabilities for the Windows platform and Chrome browser, including both Appium-standard and Perfecto-specific configurations. The test navigates to https://example.com, prints the page title, and then closes the browser session. This setup is useful for executing automated cross-browser tests in a cloud environment without relying on local infrastructure.

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.RemoteWebDriver;
import org.openqa.selenium.MutableCapabilities;

import java.net.URL;
import java.util.List;

public class PerfectoDesktopChromeTest {
    public static void main(String[] args) throws Exception {
        MutableCapabilities options = new MutableCapabilities();

        options.setCapability("platformName", "Windows");
        options.setCapability("browserName", "Chrome");

        // Appium-standard capabilities (with proper prefix)
        options.setCapability("appium:platformVersion", "11");
        options.setCapability("appium:browserVersion", "latest");

        // Perfecto-specific capabilities (must use perfecto: prefix)
        options.setCapability("perfecto:resolution", "1366x768");
        options.setCapability("perfecto:location", "US East");
        options.setCapability("perfecto:installCertificates", List.of("c1.pem", "c2.crt"));
        options.setCapability("perfecto:user", "myUser");
        options.setCapability("perfecto:securityToken", "myToken");

        String host = "mymobilecloud.perfectomobile.com";
        URL url = new URL("https://" + host + "/wd/hub");

        WebDriver driver = new RemoteWebDriver(url, options);

        driver.get("https://example.com");
        System.out.println("Page Title: " + driver.getTitle());

        driver.quit();
    }
}

In addition to setting browser and platform capabilities, Perfecto also allows you to customize the virtual machine's network configuration. One useful feature is the ability to add custom host entries to the VM’s hosts file using the perfecto:addHostsRecord capability. This is particularly helpful when testing against internal environments or redirecting domain names to specific IP addresses during test execution. The following example demonstrates how to define and apply these host records in Java and JavaScript.

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

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

capabilities.setCapability("perfecto:addHostsRecord", hostsRecords);

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

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

Example: Using web application capabilities

The following code snippet demonstrates how to configure screenshot-related capabilities for a Perfecto web test session. The appium:takesScreenshot capability enables general screenshot functionality, while perfecto:screenshotOnError controls whether a screenshot should be automatically captured when a test error occurs. These settings help manage visual debugging and reporting behavior during test execution.

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

Example: Using Smart Reporting capabilities

The following code snippet illustrates how to configure Perfecto Smart Reporting capabilities within a Selenium test. It sets metadata such as project name, version, job details, tags, and custom fields to enrich test reports generated by Perfecto. These capabilities help organize and filter test results in the Perfecto reporting dashboard. Note that while tags and customFields are merged with SDK-provided values (with SDK values taking precedence), project and job settings will be fully overridden by the SDK if also defined there.

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.

import io.appium.java_client.remote.options.AppiumOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;

AppiumOptions options = new AppiumOptions();
options.setPlatformName("Android"); // or "iOS"
options.setCapability("browserName", "mobileOS");
options.setCapability("perfecto:securityToken", myToken);

// Reporting capabilities
options.setCapability("perfecto:report.projectName", "test_fail_to_open");
options.setCapability("perfecto:report.projectVersion", "2.0");
options.setCapability("perfecto:report.tags", "spring,forward,tag1");
options.setCapability("perfecto:report.jobName", "myTestJob");
options.setCapability("perfecto:report.jobNumber", 8);
options.setCapability("perfecto:report.jobBranch", "master");
options.setCapability("perfecto:report.customFields", "cc=custom,mm=fewer");

// Initialize driver
RemoteWebDriver driver = new RemoteWebDriver(new URL(perfectoLabURL), options);

Example: Using video capabilities

This following code snippet demonstrates how to control video recording behavior in a Perfecto test session. By setting the perfecto:outputVideo capability to false, video capture is disabled for the test run. This can be useful for optimizing performance or conserving storage when video logs are not required.

capabilities.setCapability("perfecto:outputVideo", false);