diff --git a/docs/modules/automation-testing/images/appium-inspector-capabilities.png b/docs/modules/automation-testing/images/appium-inspector-capabilities.png new file mode 100644 index 000000000..9631f23be Binary files /dev/null and b/docs/modules/automation-testing/images/appium-inspector-capabilities.png differ diff --git a/docs/modules/automation-testing/nav.adoc b/docs/modules/automation-testing/nav.adoc index 3691eda70..3a04fc395 100644 --- a/docs/modules/automation-testing/nav.adoc +++ b/docs/modules/automation-testing/nav.adoc @@ -1,4 +1,8 @@ .xref:index.adoc[] + +* Appium Tools + +** xref:appium-tools/connect-appium-inspector-to-kobiton.adoc[] * xref:automation-testing:supported-client-libraries.adoc[Supported client libraries] * Capabilities @@ -20,7 +24,7 @@ ** xref:get-a-session-id/using-the-kobiton-portal.adoc[] ** xref:get-a-session-id/using-the-kobiton-api.adoc[] -* Run an automation test +* Run an automation test in CI/CD ** xref:automation-testing:run-an-automation-test/using-azure-devops.adoc[Using Azure DevOps] ** xref:automation-testing:run-an-automation-test/using-bitrise.adoc[Using Bitrise] ** xref:automation-testing:run-an-automation-test/using-buildkite.adoc[Using BuildKite] diff --git a/docs/modules/automation-testing/pages/appium-tools/connect-appium-inspector-to-kobiton.adoc b/docs/modules/automation-testing/pages/appium-tools/connect-appium-inspector-to-kobiton.adoc new file mode 100644 index 000000000..3030f0976 --- /dev/null +++ b/docs/modules/automation-testing/pages/appium-tools/connect-appium-inspector-to-kobiton.adoc @@ -0,0 +1,129 @@ += Connecting Appium Inspector to Kobiton +:navtitle: Use Appium Inspector + +While Kobiton has a built-in Inspector in Manual sessions and Session Explorer, it is possible to use https://github.com/appium/appium-inspector[Appium Inspector,window=read-later] with Kobiton. + +== Download and install Appium Inspector + +Download https://github.com/appium/appium-inspector/releases[Appium Inspector,window=read-later] for your OS. + +Follow the https://appium.github.io/appium-inspector/latest/quickstart/installation[official installation guide,window=read-later] to install Appium Inspector. + +== Obtain your Kobiton credentials + +You will need: + +* **Kobiton Username**: Find this in your Kobiton profile. +* **Kobiton Access Key**: Generate or view this by following the guide at xref:profile:manage-your-api-credentials.adoc[Manage your API credentials]. + +== Configure connection to Kobiton + +Open *Appium Inspector*. + +Specify the Appium server you want to connect to: + +* For Cloud/Hybrid customers: + +** Choose *Select Cloud Providers*. + +** Select *Kobiton*, then choose *Done*. + +** Select the *Kobiton* tab. + +** Fill the Kobiton username and access key (API key). + +* For Standalone/On-prem customers: + +** Choose the *Appium Server* tab. + +** Fill in the following information: + +*** *Remote host*: fill in the address of the Portal server. You can find this information from the **kobitonServerUrl **value in Automation Settings. Example: `192.168.50.85` or `www.kobiton.local`. + +*** *Remote port*: input `3000`. + +*** *Remote path*: input `/wd/hub`. + +** Check the *SSL* box if the On-Prem Kobiton Portal has SSL enabled. If not, keep it unchecked. + +== Configure Appium capabilities + +Under *Capability Builder*, use the JSON format to enter the required capabilities for launching the device. Keep the following information in mind: + +* To authenticate with the Kobiton Portal, provide the required capabilities below. Note: skip these capabilities for Cloud/Hybrid customers. + +**`"appium:username"`: the Kobiton account’s username. + +** `"appium:accessKey`: the Kobiton account’s API key. + +* If you want to start a basic Appium 2 session, provide the below capability: + +** `“kobiton:runtime"`:"appium". + +** `"appium:automationName"`: must have one of the below values: + +*** `"XCUITest"` for iOS devices. + +*** `"UIAutomator2"` for Android devices. + +See below for examples: + +* Xium session (Xium is Kobiton’s high-speed reimplementation of Appium Server and is the default method to execute Appium tests): + + +[source,json] +---- +{ +"appium:bundleId": "com.example.ToDoApp", +"kobiton:sessionName": "Automation iOS Hybrid App", +"kobiton:sessionDescription": "Automation session", +"kobiton:app": "kobiton-store:v10", +"appium:deviceName": "iPhone 14", +"appium:udid": "aa2ace81ea5b7e6164965b97c5bf432432", +"platformName": "iOS" +} +---- + +* Basic Appium 2 session: + +[source,json] +---- +{ +"kobiton:runtime": "appium", +"appium:automationName": "XCUITest", +"appium:bundleId": "com.example.ToDoApp", +"kobiton:sessionName": "Automation iOS Hybrid App", +"kobiton:sessionDescription": "Automation session", +"kobiton:app": "kobiton-store:v10", +"appium:deviceName": "iPhone 14", +"appium:udid": "aa2ace81ea5b7e6164965b97c5bf432432", +"platformName": "iOS" +} +---- + +For a full list and explanation of each capability, see the Required Capabilities table in xref:basic-appium-server/launch-a-basic-appium-2-session.adoc[Launch a basic Appium 2 session (Beta)]. + +== Start your session + +When all required capabilities are filled in, select *Start Session* to launch a session and inspect with Appium Inspector. + +== Troubleshooting + +* Make sure your credentials are correct and have not expired. +* Ensure the device UDID and group ID match a device available to your account. +* To use the context selector dropdown in the https://appium.github.io/appium-inspector/2023.12/session-inspector/header/#context-switcher[context switcher,window=read-later], you must launch a Basic Appium 2 session. +* In Xium session, the context switcher is not available. Under the https://appium.github.io/appium-inspector/2023.12/session-inspector/commands/[Commands tab,window=read-later], use *Context → getContexts* to get the actual name of the web context, then use *switchContext* to switch to the web view. + +[NOTE] +For more details, see xref:devices:manage-devices.adoc#_automation_settings[Manage devices - Automation settings]. + +== Workarounds for issues with Appium Inspector and Basic Appium 2 server + +[NOTE] +https://github.com/appium/appium-inspector[Appium Inspector,window=read-later] and https://github.com/appium/appium[Basic Appium 2 server,window=read-later] are community-driven projects and are not managed by Kobiton. Below are common workarounds and troubleshooting steps for known issues with these platforms. + +*Android*: + +* When `"browserName"` is set to `"chrome"` for Basic Appium 2 sessions, the actual web context name is `CHROMIUM` instead of `WEBVIEW_`, and cannot be selected from the context dropdown in web/hybrid app mode after switching to native context and back. As a workaround, use *Context → getContexts* under the https://appium.github.io/appium-inspector/2023.12/session-inspector/commands/[Commands tab,window=read-later] to get the actual name of the web context (`CHROMIUM`), then *switchContext* to switch to the web view. + +* __Tap/swipe by coordinates__ actions do not work in web context with Basic Appium 2 session. Switch to native context to perform these actions. \ No newline at end of file diff --git a/docs/modules/automation-testing/pages/basic-appium-server/launch-a-basic-appium-2-session.adoc b/docs/modules/automation-testing/pages/basic-appium-server/launch-a-basic-appium-2-session.adoc index 277778384..8532cec7c 100644 --- a/docs/modules/automation-testing/pages/basic-appium-server/launch-a-basic-appium-2-session.adoc +++ b/docs/modules/automation-testing/pages/basic-appium-server/launch-a-basic-appium-2-session.adoc @@ -7,9 +7,12 @@ The default mobile automation method is Xium. Follow this guide to switch to bas Note that basic Appium 2 support is a beta release, so it currently has several limitations that will be considered for future releases. -== Prerequisites +== Obtain your Kobiton credentials -A basic Appium 2 session can only be launched on devices hosted by Kobiton v4.9 or above. +You will need: + +* **Your Kobiton Username**: You can find this in your profile +* **Your Kobiton Access Key**: You can generate this by following the guide at xref:profile:manage-your-api-credentials.adoc[Manage your API credentials] == Modify the capabilities in your Appium script diff --git a/docs/modules/manual-testing/pages/device-information/inspector.adoc b/docs/modules/manual-testing/pages/device-information/inspector.adoc index 1bd57b85b..945ac1aa6 100644 --- a/docs/modules/manual-testing/pages/device-information/inspector.adoc +++ b/docs/modules/manual-testing/pages/device-information/inspector.adoc @@ -1,49 +1,73 @@ = Inspector :navtitle: Inspector -During a manual session, select *Inspector* to copy specific xpath values, inspect UI elements, and download your device inventory. +The Inspector tool provides powerful capabilities for analyzing and interacting with UI elements during manual testing sessions. Access it by selecting the *Inspector* tab in your Manual session interface to copy specific `xpath` values, inspect UI elements, and download your device inventory for further analysis. -image:manual-testing:inspector-context.png[width=, alt="A manual session displaying a device and the device inspector."] +image:manual-testing:inspector-context.png[width=1000, alt="A manual session displaying a device and the device inspector with XML hierarchy panel visible"] == Refresh inventory -Display the XML hierarchy of the current device screen. Select a specific element from the hierarchy to highlight it on the device. +The *Refresh inventory* button captures the current state of the device screen and displays its complete XML hierarchy in a tree structure. -image:manual-testing:refresh-inventory-closeup.png[width=, alt="The XML hierarchy of the current device screen"] +This feature allows you to see all UI elements currently visible on the device, organized in their parent-child relationships. When you select any element from this hierarchy, it will be highlighted on the actual device screen, making it easy to identify and locate specific UI components. + +image:manual-testing:refresh-inventory-closeup.png[width=1000, alt="The XML hierarchy of the current device screen showing nested UI elements in a tree structure"] [NOTE] -*Refresh inventory* resets all filters and searches. +==== +Clicking *Refresh inventory* will reset all active filters and searches, returning the hierarchy to its unfiltered state. This ensures you're working with the most current screen data. +==== == Inspect elements -Hover over on-screen elements to highlight the elements in the XML hierarchy. +The *Inspect elements* feature enables real-time element inspection by allowing you to hover over any element on the device screen. + +When you hover over an element, it will be automatically highlighted in the XML hierarchy panel, creating a direct visual connection between the physical element on screen and its representation in the code structure. This interactive approach makes it much easier to understand the relationship between what you see and the underlying UI structure. -image:manual-testing:inspect-elements-closeup.png[width=, alt="The icon to inspect elements"] +image:manual-testing:inspect-elements-closeup.png[width=1000, alt="The inspect elements icon showing the crosshair cursor for element selection"] == Download inventory -Download the current XML hierarchy as an `.xml` file. +Use the *Download inventory* function to export the current XML hierarchy as an `.xml` file to your local machine. + +This is particularly useful for offline analysis, sharing with team members, or archiving the UI structure for future reference. The downloaded file contains the complete hierarchical structure of all UI elements currently visible on the device screen. -image:manual-testing:download-inventory-closeup.png[width=, alt="The icon to download the XML heirarchy"] +image:manual-testing:download-inventory-closeup.png[width=1000, alt="The download icon for exporting the XML hierarchy as a file"] + +[NOTE] +==== +The downloaded file will include all WebViews mixed into one file, not just the WebView currently selected in the dropdown. This provides a complete view of all application contexts in a single export. +==== == WebView -Filter the XML hierarchy by the selected WebView. The default WebView is `NATIVE_APP`. +The WebView dropdown allows you to filter the XML hierarchy based on different application contexts. -image:manual-testing:inspector-dropdown-closeup.png[width=, alt="The WebView filter"] +By default, it shows `NATIVE_APP`, which displays native application elements. You can switch to other WebView contexts (such as web content within hybrid apps) to focus on specific types of UI elements. This filtering capability is essential when testing applications that contain both native and web-based components. + +image:manual-testing:inspector-dropdown-closeup.png[width=1000, alt="The WebView filter dropdown showing available context options"] + +[NOTE] +==== +Selecting a different WebView will not change the hierarchy tree to show only that WebView. Instead, it will highlight the selected WebView elements within a box while keeping all other elements visible in the hierarchy. +==== == Search bar -Filter the XML hierarchy by a specific element. +The search functionality enables you to quickly locate specific elements within the XML hierarchy. -image:manual-testing:inspector-search-closeup.png[width=, alt="Search an element to filter that specific element"] +Simply type the name, ID, or any attribute value of the element you're looking for, and the hierarchy will be filtered to show only matching elements. This powerful filtering capability saves time when working with complex UI structures containing many elements. + +image:manual-testing:inspector-search-closeup.png[width=1000, alt="Search bar for filtering elements in the XML hierarchy"] == Attributes -Display an element's attributes. +The *Attributes* section displays detailed information about the currently selected UI element, including its properties, values, and metadata. + +This comprehensive view shows all available attributes such as element IDs, class names, accessibility labels, and custom properties that are essential for automation scripting and element identification. -image:manual-testing:hierarchy-closeup.png[width=, alt="The button to display attributes"] +image:manual-testing:hierarchy-closeup.png[width=1000, alt="The attributes panel showing detailed element properties and values"] -Hover over a specific attribute and to copy it to your clipboard. +To copy any specific attribute value to your clipboard, simply hover over the desired attribute in the attributes panel. This feature streamlines the process of extracting element identifiers and properties for use in automation scripts or documentation. -image:manual-testing:attributes-closeup.png[width=, alt="The icon to copy the attribute"] +image:manual-testing:attributes-closeup.png[width=1000, alt="Hover functionality for copying attribute values to clipboard"] diff --git a/docs/modules/session-explorer/images/appium-inspector-context.png b/docs/modules/session-explorer/images/appium-inspector-context.png index e5fe1507e..308f11a10 100644 Binary files a/docs/modules/session-explorer/images/appium-inspector-context.png and b/docs/modules/session-explorer/images/appium-inspector-context.png differ diff --git a/docs/modules/session-explorer/images/appium-inspector-select-element.png b/docs/modules/session-explorer/images/appium-inspector-select-element.png index d83687439..69bac42e5 100644 Binary files a/docs/modules/session-explorer/images/appium-inspector-select-element.png and b/docs/modules/session-explorer/images/appium-inspector-select-element.png differ diff --git a/docs/modules/session-explorer/images/attributes-context-one.png b/docs/modules/session-explorer/images/attributes-context-one.png new file mode 100644 index 000000000..b11fb0eab Binary files /dev/null and b/docs/modules/session-explorer/images/attributes-context-one.png differ diff --git a/docs/modules/session-explorer/images/attributes-context-two.png b/docs/modules/session-explorer/images/attributes-context-two.png new file mode 100644 index 000000000..4476230e4 Binary files /dev/null and b/docs/modules/session-explorer/images/attributes-context-two.png differ diff --git a/docs/modules/session-explorer/images/attributes-context.png b/docs/modules/session-explorer/images/attributes-context.png deleted file mode 100644 index e2eef34c9..000000000 Binary files a/docs/modules/session-explorer/images/attributes-context.png and /dev/null differ diff --git a/docs/modules/session-explorer/images/download-inventory-context.png b/docs/modules/session-explorer/images/download-inventory-context.png index fb5c68978..16f30844a 100644 Binary files a/docs/modules/session-explorer/images/download-inventory-context.png and b/docs/modules/session-explorer/images/download-inventory-context.png differ diff --git a/docs/modules/session-explorer/images/hover-attribute-closeup.png b/docs/modules/session-explorer/images/hover-attribute-closeup.png index 1b0f4cf0f..a5d225cc8 100644 Binary files a/docs/modules/session-explorer/images/hover-attribute-closeup.png and b/docs/modules/session-explorer/images/hover-attribute-closeup.png differ diff --git a/docs/modules/session-explorer/images/inspect-elements-context.png b/docs/modules/session-explorer/images/inspect-elements-context.png index da3550dd5..9f472df34 100644 Binary files a/docs/modules/session-explorer/images/inspect-elements-context.png and b/docs/modules/session-explorer/images/inspect-elements-context.png differ diff --git a/docs/modules/session-explorer/images/refresh-inventory-closeup.png b/docs/modules/session-explorer/images/refresh-inventory-closeup.png index e973eb66b..21e08cb5f 100644 Binary files a/docs/modules/session-explorer/images/refresh-inventory-closeup.png and b/docs/modules/session-explorer/images/refresh-inventory-closeup.png differ diff --git a/docs/modules/session-explorer/images/search-bar-closeup.png b/docs/modules/session-explorer/images/search-bar-closeup.png index f422c0463..9752c2bd1 100644 Binary files a/docs/modules/session-explorer/images/search-bar-closeup.png and b/docs/modules/session-explorer/images/search-bar-closeup.png differ diff --git a/docs/modules/session-explorer/images/search-session-id-closeup.png b/docs/modules/session-explorer/images/search-session-id-closeup.png index 7ae73b76d..fde4fad1c 100644 Binary files a/docs/modules/session-explorer/images/search-session-id-closeup.png and b/docs/modules/session-explorer/images/search-session-id-closeup.png differ diff --git a/docs/modules/session-explorer/images/select-explorer-context.png b/docs/modules/session-explorer/images/select-explorer-context.png index 9730c6770..1a7121bef 100644 Binary files a/docs/modules/session-explorer/images/select-explorer-context.png and b/docs/modules/session-explorer/images/select-explorer-context.png differ diff --git a/docs/modules/session-explorer/images/select-sessions-closeup.png b/docs/modules/session-explorer/images/select-sessions-closeup.png index 8586692f9..f7c396a6c 100644 Binary files a/docs/modules/session-explorer/images/select-sessions-closeup.png and b/docs/modules/session-explorer/images/select-sessions-closeup.png differ diff --git a/docs/modules/session-explorer/images/session-overview-context copy.png b/docs/modules/session-explorer/images/session-overview-context copy.png deleted file mode 100644 index b9971c8ee..000000000 Binary files a/docs/modules/session-explorer/images/session-overview-context copy.png and /dev/null differ diff --git a/docs/modules/session-explorer/images/session-overview-context.png b/docs/modules/session-explorer/images/session-overview-context.png index 98953c82c..b9971c8ee 100644 Binary files a/docs/modules/session-explorer/images/session-overview-context.png and b/docs/modules/session-explorer/images/session-overview-context.png differ diff --git a/docs/modules/session-explorer/images/webview-closeup.png b/docs/modules/session-explorer/images/webview-closeup.png index 5a8cb13c7..231b958fd 100644 Binary files a/docs/modules/session-explorer/images/webview-closeup.png and b/docs/modules/session-explorer/images/webview-closeup.png differ diff --git a/docs/modules/session-explorer/pages/analytics/reinspect-appium-elements.adoc b/docs/modules/session-explorer/pages/analytics/reinspect-appium-elements.adoc index 214694bda..fdcaf88b1 100644 --- a/docs/modules/session-explorer/pages/analytics/reinspect-appium-elements.adoc +++ b/docs/modules/session-explorer/pages/analytics/reinspect-appium-elements.adoc @@ -17,7 +17,7 @@ image:session-explorer:appium-inspector-context.png[width=1000,alt="A context to To generate the XML hierarchy using the selected test step, select *Refresh Inventory*. -image:session-explorer:refresh-inventory-closeup.png[width=500,alt="A closeup to see Refresh Inventory"] +image:session-explorer:refresh-inventory-closeup.png[width=1000,alt="A closeup to see Refresh Inventory"] [NOTE] *Refresh Inventory* will reset all your active filters and searches. @@ -26,11 +26,11 @@ image:session-explorer:refresh-inventory-closeup.png[width=500,alt="A closeup to By default, WebView is set to `NATIVE_APP`. To filter the XML hierarchy by a different WebView, select the dropdown and choose a different option. -image:session-explorer:webview-closeup.png[width=500,alt="A closeup to webview with default is NATIVE_APP"] +image:session-explorer:webview-closeup.png[width=1000,alt="A closeup to webview with default is NATIVE_APP"] To filter the XML hierarchy by a label, xPath, or xPath attribute, enter your string into the search bar. -image:session-explorer:search-bar-closeup.png[width=500,alt="A closeup to search bar in the Appium Inspector"] +image:session-explorer:search-bar-closeup.png[width=1000,alt="A closeup to search bar in the Appium Inspector"] === Inspect an element @@ -46,11 +46,12 @@ image:session-explorer:appium-inspector-select-element.png[width=1000, alt="Sele To get an element's XML attributes, select an element in the XML hierarchy, then select *Show Attributes*. -image:session-explorer:attributes-context.png[width=1000,alt="A context to Attributes of Appium Inspector"] +image:session-explorer:attributes-context-one.png[width=1000,alt="A context to Attributes of Appium Inspector"] +image:session-explorer:attributes-context-two.png[width=1000,alt="A context to Attributes of Appium Inspector"] To copy a specific attribute to your clipboard, place your mouse of the attribute and select the *Copy* icon. -image:session-explorer:hover-attribute-closeup.png[width=500,alt="Hover over a specific attribute and to copy it to your clipboard"] +image:session-explorer:hover-attribute-closeup.png[width=1000,alt="Hover over a specific attribute and to copy it to your clipboard"] === Download all XML data diff --git a/docs/modules/session-explorer/pages/manage-sessions.adoc b/docs/modules/session-explorer/pages/manage-sessions.adoc index eee89b74b..bf52e84b4 100644 --- a/docs/modules/session-explorer/pages/manage-sessions.adoc +++ b/docs/modules/session-explorer/pages/manage-sessions.adoc @@ -15,7 +15,7 @@ image:search-session-id-closeup.png[width=1000,alt="Search for a session ID"] From the Session Overview window, users can view below mentioned information. -image:session-overview-context copy.png[width=1000,alt="A context to Session Overview"] +image:session-overview-context.png[width=1000,alt="A context to Session Overview"] == Manage the session