From 1cb9d0d549b19c3c9f474dc7852343afbddef22d Mon Sep 17 00:00:00 2001 From: tiffany-kobiton Date: Fri, 13 Mar 2026 12:20:22 -0400 Subject: [PATCH] Add empty device tag warning to capabilities page --- .../capabilities/available-capabilities.adoc | 374 +++++++++--------- 1 file changed, 187 insertions(+), 187 deletions(-) diff --git a/docs/modules/automation-testing/pages/capabilities/available-capabilities.adoc b/docs/modules/automation-testing/pages/capabilities/available-capabilities.adoc index 623cda79..ac5afa25 100644 --- a/docs/modules/automation-testing/pages/capabilities/available-capabilities.adoc +++ b/docs/modules/automation-testing/pages/capabilities/available-capabilities.adoc @@ -2,351 +2,351 @@ :page-aliases: automation-testing:capabilities:add-visualvalidation.adoc :navtitle: Available capabilities -These are the capabilities you can use during an automation session. +This page lists the capabilities that can be used when creating an automation session in Kobiton. -[NOTE] -You can also xref:automation-testing:capabilities/auto-generate-capabilities.adoc[auto-generate your capabilities]. +Capabilities control how a session starts, including device selection, application configuration, and session metadata. -[NOTE] -The `kobiton:visualValidation` capability is deprecated. +Kobiton supports both standard Appium capabilities and additional Kobiton-specific capabilities. -== Kobiton Capabilities +* *Kobiton capabilities* extend Appium functionality and must include the `kobiton:` vendor prefix when used with Appium 2. +* *Appium capabilities* follow standard Appium conventions but may have additional behavior when used with Kobiton devices. -These capabilities are unique to Kobiton. +Examples in this reference use the Appium Java client syntax. [NOTE] ==== -* To use Kobiton capabilities in Basic Appium 2 script, use the `'kobiton:'` vendor prefix, i.e. `'kobiton:sessionName'`. - -* Capabilities with `'kobiton:'` in the name cannot be used without the prefix. +The `kobiton:visualValidation` capability is deprecated. ==== -[IMPORTANT] -Not all Kobiton capabilities can be used in Basic Appium 2 scripts. - -=== `app` +== Kobiton Capabilities -The app to use during the test session. If the app is not already installed on the device, the value of the second parameter will be used to download and install the app. *Only available for app testing*. +Kobiton provides additional capabilities that extend standard Appium functionality. +These capabilities must include the `kobiton:` vendor prefix when used with Appium 2. -* *Type:* `string` -* *Required capabilities:* None -* *Optional capabilities:* None +Example: -.Example [source,java] ---- -capabilities.setCapability("app", "kobiton-store:000111"); // Install the app using the Kobiton app repository. -capabilities.setCapability("app", "https://kobiton.docsapp.net/apps/app_id"); // Install the app using a direct download link. +capabilities.setCapability("kobiton:sessionName", "Login test"); ---- -[#_baselineSessionId] -=== `kobiton:baselineSessionId` +Capabilities with the `kobiton:` prefix cannot be used without the prefix. -Select a baseline session to use for xref:_flexCorrect[] or xref:_visualValidation[]. +.Kobiton capability index +* <> +* <> +* <> +* <> +* <> -* *Type:* `string` -* *Required capabilities:* xref:_flexCorrect[] _or_ xref:_visualValidation[] -* *Optional capabilities:* None +[#kobiton-baselinesessionid] +=== kobiton:baselineSessionId + +Select a baseline session to use for `kobiton:flexCorrect` or visual validation. + +*Type:* string + +*Required capabilities:* `kobiton:flexCorrect` or `kobiton:visualValidation` + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("kobiton:baselineSessionId", 0000011); // Select baseline session for flexCorrect or visualValidation by assigning a kobitonSessionId. +capabilities.setCapability("kobiton:baselineSessionId", 0000011); ---- -[NOTE] -This capability cannot be used in Basic Appium 2 sessions. +NOTE: This capability cannot be used in Basic Appium 2 sessions. -=== `captureScreenshots` +[#kobiton-devicetags] +=== kobiton:deviceTags -Screenshots will be captured after each test step automatically. They'll be available in the xref:session-explorer:manage-sessions.adoc[session overview] after the test session. +Select devices for the automation session using device tags. -* *Type:* `boolean` -* *Required capabilities:* None -* *Optional capabilities:* None +When this capability is used, Kobiton searches for devices that have the specified tag or tags assigned. The session runs on a device that matches the provided tags and any additional capability filters. + +*Type:* array of strings + +*Required capabilities:* None + +*Optional capabilities:* `deviceName`, `udid`, `platformName` .Example [source,java] ---- -capabilities.setCapability("captureScreenshots", true); // Take a screenshot after each test step. +capabilities.setCapability("kobiton:deviceTags", ["android-regression"]); +capabilities.setCapability("kobiton:deviceTags", ["smoke-tests", "pixel-devices"]); ---- -[NOTE] -This is not available for native and hybrid apps, as well as devices on Android 6.0 and earlier. +WARNING: Do not provide an empty value for `kobiton:deviceTags`. An empty value may cause session creation to fail. + +NOTE: If no device selection capability is provided (such as `deviceName`, `udid`, or `kobiton:deviceTags`), Kobiton may not be able to determine a target device for the session. -=== `deviceGroup` +[#kobiton-flexcorrect] +=== kobiton:flexCorrect -The device group within the test session metadata. +Automatically correct element selection when running a script on different devices. -* *Type:* `string` -* *Required capabilities:* None -* *Optional capabilities:* None +*Type:* boolean + +*Required capabilities:* `kobiton:baselineSessionId` + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("deviceGroup", "ORGANIZATION"); // Assign to the device team. +capabilities.setCapability("kobiton:flexCorrect", true); ---- -=== `deviceName` +NOTE: This capability cannot be used in Basic Appium 2 sessions. -The device name. Assign multiple platform versions using wildcards (`*`). +[#kobiton-tags] +=== kobiton:tags -* *Type:* `string` -* *Required capabilities:* None -* *Optional capabilities:* None +Categorize and organize sessions by assigning custom tags at the time of session creation. + +*Type:* array of strings + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("deviceName", "iPhone 11 Pro"); // Use iPhone 11 Pro as the device name. -capabilities.setCapability("deviceName", "*Pro"); // Use any device name ending with 'Pro'. -capabilities.setCapability("deviceName", "iPhone 11*"); // Use any device name starting with 'iPhone 11'. +capabilities.setCapability("kobiton:tags", ["nightly-run", "login-flow", "regression"]); ---- -[#_ensureWebviewsHavePages] -=== `ensureWebviewsHavePages` +[#kobiton-workapp] +=== kobiton:workApp + +Launch a Work Profile app using the name shown in the app drawer (case-sensitive). -Ensures that all WebView elements in the application have loaded their content. +Before using this capability, the Work Profile app must be installed and configured. -* *Type:* `boolean` -* *Required capabilities:* None -* *Optional capabilities:* xref:_visualValidation[] +*Type:* string + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("ensureWebviewsHavePages", true); // Set to true. +capabilities.setCapability("kobiton:workApp", "Firefox"); ---- -[#_flexCorrect] -=== `kobiton:flexCorrect` +NOTE: This capability cannot be used in Basic Appium 2 sessions. -When a script is run on different devices, element selection is autocorrected. For more information, see xref:automation-testing:capabilities/add-flexcorrect.adoc[] +When `kobiton:workApp` is used, the following capabilities are ignored: -* *Type:* `boolean` -* *Required capabilities:* xref:_baselineSessionId[] -* *Optional capabilities:* None +* `app` +* `appium:appPackage` +* `appium:appActivity` -.Example -[source,java] ----- -capabilities.setCapability("kobiton:flexCorrect", true); // Enable flexCorrect by setting capability to true. ----- +== Appium Capabilities -[NOTE] -This capability cannot be used in Basic Appium 2 sessions. +Kobiton supports most standard Appium capabilities. The capabilities listed below are commonly used when running automation sessions on Kobiton devices. -=== `groupId` +.Appium capability index +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> -The group ID within the test session metadata. +[#accesskey] +=== accessKey -* *Type:* `string` -* *Required capabilities:* None -* *Optional capabilities:* None +The Kobiton API key used to authenticate the automation session. + +*Type:* string + +*Required capabilities:* `appium:username` + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("groupId", "0011"); // Assign to the Docs Team. +capabilities.setCapability("appium:accessKey", "ac9****8b-5*fc-4485-82eb-c5b****baed"); ---- -=== `sessionDescription` +[#app] +=== app -The description of the test session, typically between 50-72 characters, but can be set to any length. +The application used during the test session. If the app is not already installed on the device, Kobiton downloads and installs it using the provided value. -* *Type:* `string` -* *Required capabilities:* None -* *Optional capabilities:* None +*Type:* string + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("sessionDescription", "This tests the login feature with biometric authentication."); // Provide the test session description. +capabilities.setCapability("app", "kobiton-store:000111"); +capabilities.setCapability("app", "https://kobiton.docsapp.net/apps/app_id"); ---- -=== `sessionName` +[#autowebview] +=== autoWebview -The name of the test session. +Automatically switch to the WebView context when it becomes available. -* *Type:* `string` -* *Required capabilities:* None -* *Optional capabilities:* None +*Type:* boolean + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("sessionName", "Automation test session"); // Specify the test session name. +capabilities.setCapability("appium:autoWebview", true); ---- -=== `kobiton:tags` +[#browsername] +=== browserName + +The browser used during the test session. -Categorize and organize sessions by assigning a custom tag at the time of session creation. +This capability is only used for web testing. -* *Type:* `string` -* *Required capabilities:* None -* *Optional capabilities:* None +*Type:* string + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("kobiton:tags", ["nightly-run", "login-flow", "regression"]); +capabilities.setCapability("browserName", "safari"); +capabilities.setCapability("browserName", "chrome"); ---- -=== `useConfiguration` +[#deviceorientation] +=== deviceOrientation -The device configuration to use during the test session. *Only available for web testing*. +The starting orientation of the device screen. -* *Type:* `string` -* *Required capabilities:* None -* *Optional capabilities:* None +*Type:* string + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("useConfiguration", "kobiton"); // Use this pre-defined configuration for the test session. +capabilities.setCapability("appium:deviceOrientation", "portrait"); +capabilities.setCapability("appium:deviceOrientation", "landscape"); ---- -[#_work_app] -=== `kobiton:workApp` - -[IMPORTANT] -Before using this capability, you must xref:scripting/launch-work-profile-app-android.adoc#_install_and_prepare_the_work_profile_app[install and prepare the Work Profile app,window=read-later]. - -include::partial$work-profile-capability.adoc[] - -== Appium Capabilities - -Kobiton supports most Appium capabilities. The capabilities listed below are typically required or have specific use cases unique to Kobiton. - -[NOTE] -For Basic Appium 2 sessions, follow the https://appium.io/docs/en/2.0/guides/migrating-1-to-2/#capabilities[Appium 2 guidelines] for vendor prefix. +[#devicename] +=== deviceName -[#_accessKey] -=== `accessKey` +The device name used when selecting a device for the session. -The Kobiton xref:profile:manage-your-api-credentials.adoc#_get_an_api_key[API key,window=read-later] for authentication. Only required for Appium `java-client` 9.2.2 or above. +Wildcards (`*`) can be used to match multiple devices. -* *Type:* `string` -* *Required capabilities:* `'appium:username'` -* *Optional capabilities:* None +*Type:* string + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("appium:accessKey", "ac9****8b-5*fc-4485-82eb-c5b****baed"); // The API key to authenticate with. +capabilities.setCapability("deviceName", "iPhone 11 Pro"); +capabilities.setCapability("deviceName", "*Pro"); +capabilities.setCapability("deviceName", "iPhone 11*"); ---- -=== `autoWebview` +[#ensurewebviewshavepages] +=== ensureWebviewsHavePages -The webview context to use during the test session. *Only available for web testing*. +Ensures that all WebView elements in the application have loaded content before interaction. -* *Type:* `boolean` -* *Required capabilities:* None -* *Optional capabilities:* None +*Type:* boolean + +*Required capabilities:* None + +*Optional capabilities:* `kobiton:visualValidation` .Example [source,java] ---- -capabilities.setCapability("appium:autoWebview", true); // Automatically select the webview context. +capabilities.setCapability("ensureWebviewsHavePages", true); ---- -=== `browserName` +[#fullreset] +=== fullReset + +Remove all apps installed during the test session. -The web browser to use during the test session. *Only available for web testing*. +To keep the apps and only remove their data, use `noReset`. -* *Type:* `string` -* *Required capabilities:* None -* *Optional capabilities:* None +*Type:* boolean + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("browserName", "safari"); // Use Safari for web testing on iOS. -capabilities.setCapability("browserName", "chrome"); // Use Chrome for web testing on Android. +capabilities.setCapability("appium:fullReset", true); ---- -=== `deviceOrientation` - -The starting orientation for the device screen. +NOTE: This capability is only available for private and local devices. -* *Type:* `integer` -* *Required capabilities:* None -* *Optional capabilities:* None +[#noreset] +=== noReset -.Example -[source,java] ----- -capabilities.setCapability("appium:deviceOrientation", "portrait"); // Set the device's starting orientation to portrait. -capabilities.setCapability("appium:deviceOrientation", "landscape"); // Set the device's starting orientation to landscape. ----- - -=== `fullReset` +Remove application data but keep the installed app. -Remove all apps installed during the test session. To keep the apps and only remove their app data, use xref:_noreset[] instead. +To completely remove the app, use `fullReset`. -* *Type:* `boolean` -* *Required capabilities:* None -* *Optional capabilities:* None +*Type:* boolean + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("appium:fullReset", true); // Delete the app and the related data. +capabilities.setCapability("appium:noReset", false); ---- -[NOTE] -This is only available for private and local devices. +NOTE: This capability is only available for private and local devices. -=== `noReset` +[#platformname] +=== platformName -Remove all app data from apps installed during the test session. To remove the full app, use xref:_fullreset[] instead. +The platform used for the automation session. -* *Type:* `string` -* *Required capabilities:* None -* *Optional capabilities:* None +*Type:* string + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("appium:noReset", false); // Delete just the app data. +capabilities.setCapability("platformName", "Android"); +capabilities.setCapability("platformName", "iOS"); ---- -[NOTE] -This is only available for private and local devices. - -=== 'platformName' - -The type of platform, i.e Android or iOS. +[#udid] +=== udid -* *Type:* `boolean` -* *Required capabilities:* None -* *Optional capabilities:* None +The unique device identifier (UDID) of the device used for the session. -=== `udid` - -The device Unique Device Identifier (UDID). - -* *Type:* `string` -* *Required capabilities:* None +*Type:* string + +*Required capabilities:* None + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("appium:udid", "01234567-89ab-cdef-0123-456789abcdef"); // Use the device with this UDID. +capabilities.setCapability("appium:udid", "01234567-89ab-cdef-0123-456789abcdef"); ---- -[#_username] -=== `username` +[#username] +=== username -The Kobiton xref:profile:manage-your-profile.adoc[username,window=read-later] for authentication. Only required for Appium `java-client` 9.2.2 or above. +The Kobiton username used for authentication. -* *Type:* `string` -* *Required capabilities:* `'appium:username'` -* *Optional capabilities:* None +*Type:* string + +*Required capabilities:* `appium:accessKey` + +*Optional capabilities:* None .Example [source,java] ---- -capabilities.setCapability("appium:username", "johndoe"); // The username to authenticate with. ----- +capabilities.setCapability("appium:username", "johndoe"); +---- \ No newline at end of file