# Desired capabilities

> Common desired capabilities for Chrome, Firefox, Edge, Safari, Cloud machines, Android, and iOS, with the key, data type, and value for each.

A **desired capability** is a setting passed to the browser, device, or Cloud machine when a session starts, such as accepting an expired certificate or granting an app's permissions at install. Common ones are listed here by browser and platform, with the key, data type, and value to enter for each. Add one to a run configuration, an app, or a Copilot session.

## Where capabilities apply

You add a capability as a **KEY**, a **DATA TYPE**, and a **VALUE**. Where you add it decides which sessions get it:

- **Run configuration**: under **Custom Desired Capabilities**. Applies to every run that uses the configuration. Data types are **String**, **Integer**, **Boolean**, and **Array**. See [Run configurations](https://testsigma.com/docs/arcus/v2/run-tests/run-configurations/#custom-desired-capabilities).
- **App**: under **Capabilities** on the app page. Applies to every run of the app. Keys must start with `appium:` or `ts:`. See [Apps](https://testsigma.com/docs/arcus/v2/run-tests/apps/#set-app-capabilities).
- **Copilot session**: under **Custom Desired Capabilities** in the Copilot configuration. Applies to that session's run and device, and Arcus doesn't keep it for the next session. See [Copilot configuration](https://testsigma.com/docs/arcus/v2/copilot/configuration/#custom-desired-capabilities).

When an app and a run configuration both set a capability, the run configuration's value wins.

In a Copilot session on Cloud, the lab keeps only the browser capabilities it allows and drops the rest.

## Chrome

| To do this | Key | Data type | Value |
|---|---|---|---|
| Accept insecure or expired certificates | `acceptInsecureCerts` | **Boolean** | `true` |
| Change the user agent | `goog:chromeOptions` | **String** | `{"args":["--user-agent="]}` |
| Add one extension | `goog:chromeOptions` | **String** | `{"extensions":["path/to/extension.crx"]}` |
| Add several extensions | `goog:chromeOptions` | **String** | `{"extensions":["path/to/extension1.crx","path/to/extension2.crx"]}` |
| Load an unpacked extension from a folder | `goog:chromeOptions` | **String** | `{"args":["--disable-features=DisableLoadExtensionCommandLineSwitch","--load-extension=/path/to/extension"]}` |
| Emulate a mobile device | `goog:chromeOptions` | **String** | `{"mobileEmulation":{"deviceName":"iPhone X"}}` |
| Emulate a screen size Chrome doesn't list | `goog:chromeOptions` | **String** | `{"mobileEmulation":{"deviceMetrics":{"width":560,"height":600,"pixelRatio":3.0}}}` |
| Turn off browser and alert notifications | `goog:chromeOptions` | **String** | `{"args":["--disable-notifications"]}` |
| Use a custom browser profile | `goog:chromeOptions` | **String** | `{"args":["user-data-dir=/path/to/profile"]}` |
| Bypass download protection | `goog:chromeOptions` | **String** | `{"prefs":{"safebrowsing.enabled":"true"}}` |
| Stop the password leak pop-up | `goog:chromeOptions` | **String** | `{"prefs":{"profile.password_manager_leak_detection":false}}` |
| Use a fake UI for media streams | `goog:chromeOptions` | **String** | `{"args":["--use-fake-ui-for-media-stream"]}` |
| Use a fake device for media streams | `goog:chromeOptions` | **String** | `{"args":["--use-fake-device-for-media-stream"]}` |
| Capture the entire screen | `goog:chromeOptions` | **String** | `{"args":["--auto-select-desktop-capture-source=Entire screen"]}` |
| Stop waiting for a page to finish loading | `pageLoadStrategy` | **String** | `none` |

Use `pageLoadStrategy` for a page that keeps scripts running and never fires its load event, such as a 3D Secure payment page. Without it, the driver waits for a load that never comes and stops responding after the navigation.

For a custom browser profile, name the folder with `user-data-dir`. The `--profile-directory` argument doesn't work in Chrome. To use a profile such as `Profile 1`, copy its contents into a folder named `Default` and pass the folder that holds it. For a run on **Local Agent**, open `chrome://version` in Chrome on that machine to see the current profile path.

### Set a geolocation in Chrome

A geolocation takes two capabilities. The first allows location access, and the second sets the latitude, longitude, and accuracy in meters.

| Key | Data type | Value |
|---|---|---|
| `goog:chromeOptions` | **String** | `{"profile.default_content_setting_values.geolocation":1}` |
| `geolocation` | **String** | `51.50735, -0.12776, 100` |

## Firefox

| To do this | Key | Data type | Value |
|---|---|---|---|
| Accept insecure or expired certificates | `accept_untrusted_certs` | **Boolean** | `true` |
| Set a geolocation | `firefoxprofile` | **String** | The profile object below |

The geolocation profile allows location access and sets a fixed position:

```json
{
  "geo.prompt.testing": true,
  "geo.prompt.testing.allow": true,
  "geo.enabled": true,
  "geo.wifi.uri": "data:application/json,{\"location\": {\"lat\": 34.052235, \"lng\": -118.243683}, \"accuracy\": 100.0}"
}
```

## Microsoft Edge

| To do this | Key | Data type | Value |
|---|---|---|---|
| Accept insecure or expired certificates | `acceptInsecureCerts` | **Boolean** | `true` |
| Run in private browsing | `MsOptions` | **String** | `{"args":["--inprivate"]}` |
| Allow clipboard access | `MsOptions` | **String** | `{"prefs":{"profile.default_content_setting_values.clipboard":1}}` |
| Stop waiting for a page to finish loading | `pageLoadStrategy` | **String** | `none` |
| Open the app in Internet Explorer mode | `ts.ieMode` | **Boolean** | `true` |

Internet Explorer mode runs a legacy app that needs Internet Explorer 11 inside Edge. It needs a Windows machine with Internet Explorer 11 installed. Protected Mode must also be the same in all 4 Windows security zones, or the session hangs.

## Safari

| To do this | Key | Data type | Value |
|---|---|---|---|
| Accept insecure or expired certificates | `capabilityType.ACCEPT_SSL_CERTS` | **Boolean** | `true` |
| Sign in to a site that uses basic authentication | `testsigma.customHeaders` | **String** | `{"Authorization":"Basic "}` |

Safari blocks a username and password passed in the URL, so basic authentication needs the header instead. The token is your username and password, joined by a colon and encoded in Base64.

The same `capabilityType.ACCEPT_SSL_CERTS` key accepts insecure certificates in Internet Explorer.

## Site permissions

These settings decide what the browser does when a page asks for the microphone, camera, location, or notifications. In each value, `0` asks every time, `1` allows, and `2` blocks.

| Permission | Firefox, with `firefoxprofile` | Chrome, with `goog:chromeOptions` |
|---|---|---|
| Microphone | `{"permissions.default.microphone":1}` | `{"prefs":{"profile.default_content_setting_values.media_stream_mic":1}}` |
| Camera | `{"permissions.default.camera":1}` | `{"prefs":{"profile.default_content_setting_values.media_stream_camera":1}}` |
| Location | `{"permissions.default.geo":1}` | `{"prefs":{"profile.default_content_setting_values.geolocation":1}}` |
| Notifications | `{"permissions.default.desktop-notification":1}` | `{"prefs":{"profile.default_content_setting_values.notifications":1}}` |

Both keys take the data type **String**. To set several permissions, put them in one object, separated by commas.

## Private browsing

| To do this | Key | Data type | Value |
|---|---|---|---|
| Open the browser in incognito or private mode | `testsigma.privateBrowsing` | **Boolean** | `true` |

Leaving the key out, or setting it to `false`, opens the browser normally. Private browsing works in Chrome, Firefox, and Edge.

## Cloud

These capabilities control the Cloud machine itself, so they apply only to runs on Cloud.

| To do this | Key | Data type | Value |
|---|---|---|---|
| Limit how long the browser waits for the next command | `idleTimeout` | **Integer** | Seconds. Default 90, minimum 0, maximum 1000 |
| Limit the total length of a test | `maxDuration` | **Integer** | Seconds. Default 3600, minimum 0, maximum 10800 |
| Set the machine's time zone | `timeZone` | **String** | A city name, such as `Madrid` |
| Capture the console log for each URL | `extendedDebugging` | **Boolean** | `true` |
| Run from a location, for localization testing | `geoLocation` | **String** | A 2-letter location code, such as `DE` |

Both limits stop a test that has gone wrong from running indefinitely.

For `timeZone`, take the city from the [list of tz database time zones on Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Leave out the continent and replace underscores with spaces, so `America/New_York` becomes `New York`.

### Locations for localization testing

`geoLocation` takes one of these 48 codes:

| Location | Code | Location | Code |
|---|---|---|---|
| Argentina | `AR` | Italy | `IT` |
| Australia | `AU` | Japan | `JP` |
| Austria | `AT` | Jordan | `JO` |
| Belgium | `BE` | Malaysia | `MY` |
| Brazil | `BR` | Mexico | `MX` |
| Bulgaria | `BG` | Netherlands | `NL` |
| Canada | `CA` | New Zealand | `NZ` |
| Chile | `CL` | Norway | `NO` |
| China | `CN` | Philippines | `PH` |
| Croatia | `HR` | Poland | `PL` |
| Czech Republic | `CZ` | Portugal | `PT` |
| Denmark | `DK` | Russia | `RU` |
| Egypt | `EG` | Singapore | `SG` |
| Finland | `FI` | South Africa | `ZA` |
| France | `FR` | South Korea | `KR` |
| Germany | `DE` | Spain | `ES` |
| Greece | `GR` | Sweden | `SE` |
| Hong Kong | `HK` | Switzerland | `CH` |
| Hungary | `HU` | Taiwan | `TW` |
| Iceland | `IS` | Thailand | `TH` |
| India | `IN` | Turkey | `TR` |
| Indonesia | `ID` | Ukraine | `UA` |
| Ireland | `IE` | United Kingdom | `GB` |
| Israel | `IL` | United States | `US` |

## Android

On an app's **Capabilities**, a key must start with `appium:`, so add it to a key that doesn't have it, for example `appium:autoGrantPermissions`. An app doesn't accept `noReset`, so set it in a run configuration.

| To do this | Key | Data type | Value |
|---|---|---|---|
| Keep the app's data between sessions | `noReset` | **Boolean** | `true` |
| Grant the permissions in the app manifest at install | `autoGrantPermissions` | **Boolean** | `true` |
| Speed up taps and typing in a slow app | `appium:waitForIdleTimeout` | **String** | `1000L` |
| Test a Flutter app with the Flutter integration driver | `automationName` | **String** | `FlutterIntegration` |

`appium:waitForIdleTimeout` helps most with apps built in React Native or Flutter, which can be slow to record and run.

## iOS

| To do this | Key | Data type | Value |
|---|---|---|---|
| Accept every permission pop-up, including location, contacts, and photos | `autoAcceptAlerts` | **Boolean** | `true` |
| Dismiss every permission pop-up | `autoDismissAlerts` | **Boolean** | `true` |
| Test a Flutter app with the Flutter integration driver | `automationName` | **String** | `FlutterIntegration` |

Re-signing isn't a capability in Arcus. To keep an iOS build as it is, select **Skip re-signing** when you upload it. Use this only for a build already signed for the target devices. See [Upload a build](https://testsigma.com/docs/arcus/v2/run-tests/apps/#upload-a-build).

## Mobile apps on Cloud

Camera image injection and network logs aren't capabilities in Arcus. They're the **Fixed Capabilities** toggles in a mobile run configuration, and they're off unless you turn them on. See [Mobile configurations](https://testsigma.com/docs/arcus/v2/run-tests/run-configurations/#mobile-configurations).

An app with security controls against camera or network spoofing can stop responding after it launches. If that happens, turn **Camera image injection** and **Network logs** off for the run. With camera image injection off, steps that inject an image through the camera don't work.

| To do this | Key | Data type | Value |
|---|---|---|---|
| Simulate Touch ID or fingerprint input on Android and iOS | `testsigma.allowTouchIdEnroll` | **Boolean** | `true` |
