appium-mcp 0.0.1 → 1.1.5

package/src/resources/submodules/appium-xcuitest-driver/docs/reference/ios-predicate.md

@@ -0,0 +1,196 @@
+---
+title: Predicate Locator Strategy
+--- 
+
+The XCUITest driver supports searching elements using the _predicate_ and _class chain_
+[locator search strategies](./locator-strategies.md). They are powered by Apple XCTest, provide
+flexibility and are much faster than XPath. Predicates can be used to restrict a set of elements to
+select only those for which some condition evaluates to true.
+
+!!! tip
+
+    In addition to the examples listed here, make sure to check the links in the
+    [More Information](#more-information) section below!
+
+
+### Quick Examples
+
+=== "Predicate String"
+
+    ```java
+    // java
+    driver.findElements(AppiumBy.iOSNsPredicateString("isVisible == 1"));
+    ```
+
+=== "Class Chain"
+
+    ```java
+    // java
+    driver.findElements(AppiumBy.iOSClassChain("**/XCUIElementTypeWindow[`label LIKE '*yolo*'`]"));
+    ```
+
+The predicate string example would select all visible elements on the page, while the class chain
+example would find all elements of type `XCUIElementTypeWindow` whose label contains `yolo`. Class
+chain queries allow to create much more complicated search expressions and may contain multiple
+predicates. Check the [More Information](#more-information) section below for how to build such queries.
+
+### Basic Comparisons
+
+* `=` , `==` - The left-hand expression is equal to the right-hand expression:
+  ```java
+  // java
+  driver.findElements(AppiumBy.iOSNsPredicateString("label == 'Olivia'"));
+
+  // same in Xpath:
+  driver.findElements(AppiumBy.xpath("//*[@label = 'Olivia']"));
+  ```
+
+* `>=` , `=>` - The left-hand expression is greater than or equal to the right-hand expression.
+
+* `<=` , `=<` - The left-hand expression is less than or equal to the right-hand expression.
+
+* `>` - The left-hand expression is greater than the right-hand expression.
+
+* `<` - The left-hand expression is less than the right-hand expression.
+
+* `!=` , `<>` - The left-hand expression is not equal to the right-hand expression.
+
+* `BETWEEN` - The left-hand expression is between, or equal to either of, the values specified in
+  the right-hand side. The right-hand side is a two value array (an array is required to specify
+  order) giving upper and lower bounds. For example, `1 BETWEEN { 0 , 33 }`, or `$INPUT BETWEEN { $LOWER, $UPPER }`.
+  In Objective-C, you could create a `BETWEEN` predicate as shown in the following example:
+
+    ```java
+    driver.findElements(AppiumBy.iOSNsPredicateString("rect.x BETWEEN { 1, 100 }"));
+    ```
+
+    This creates a predicate that matches all elements whole left top coordinate is in range between
+    1 and 100.
+
+### Boolean Value Predicates
+
+* `TRUEPREDICATE` - A predicate that always evaluates to `TRUE` .
+
+* `FALSEPREDICATE` - A predicate that always evaluates to `FALSE`.
+
+### Basic Compound Predicates
+
+* `AND` , `&&` - Logical AND.
+
+* `OR` , `||` - Logical OR.
+
+* `NOT` , `!` - Logical NOT.
+
+### String Comparisons
+
+String comparisons are by default case and diacritic sensitive. You can modify an operator using the
+key characters `c` and `d` within square braces to specify case and diacritic insensitivity
+respectively, for example, `value BEGINSWITH[cd] 'bar'`.
+
+* `BEGINSWITH` - The left-hand expression begins with the right-hand expression.
+
+    ```java
+    driver.findElement(AppiumBy.iOSNsPredicateString("type == 'XCUIElementTypeButton' AND name BEGINSWITH 'results toggle'"));
+
+    // same in Xpath:
+    driver.findElement(AppiumBy.xpath("//XCUIElementTypeButton[starts-with(@name, 'results toggle')]"));
+    ```
+
+* `CONTAINS` - The left-hand expression contains the right-hand expression.
+
+    ```java
+    driver.findElement(AppiumBy.iOSNsPredicateString("type == 'XCUIElementCollectionView' AND name CONTAINS 'opera'"));
+
+    // same in Xpath:
+    driver.findElement(AppiumBy.xpath("//XCUIElementCollectionView[contains(@name, 'opera')]"));
+    ```
+
+* `ENDSWITH` - The left-hand expression ends with the right-hand expression.
+
+* `LIKE` - The left hand expression equals the right-hand expression: `?` and `*` are allowed as
+  wildcard characters, where `?` matches 1 character and `*` matches 0 or more characters. In Mac
+  OS X v10.4, wildcard characters do not match newline characters.
+
+    ```java
+    driver.findElement(AppiumBy.iOSNsPredicateString("name LIKE '*Total: $*'"));
+
+    // XPath1 does not have an alternative to the above expression
+    ```
+
+* `MATCHES` - The left hand expression equals the right hand expression using a regex-style
+  comparison according to ICU v3 (for more details see the ICU User Guide for
+  [Regular Expressions](http://userguide.icu-project.org/strings/regexp)).
+
+    ```java
+    driver.findElement(AppiumBy.iOSNsPredicateString("value MATCHES '.*of [1-9]'"));
+
+    // XPath1 does not have an alternative to the above expression
+    ```
+
+### Aggregate Operations
+
+* `IN` - Equivalent to an SQL IN operation, the left-hand side must appear in the collection
+  specified by the right-hand side. For example, `name IN { 'Ben', 'Melissa', 'Matthew' }`.
+  The collection may be an array, a set, or a dictionary (in the case of a dictionary, its values
+  are used).
+
+### Identifiers
+
+* **C style identifier** - Any C style identifier that is not a reserved word.
+
+* **\#symbol** - Used to escape a reserved word into a user identifier.
+
+* **[\\]{octaldigit}{3}** - Used to escape an octal number ( ```\``` followed by 3 octal digits).
+
+* **[\\][xX]{hexdigit}{2}** - Used to escape a hex number ( ```\x``` or ```\X``` followed by 2 hex digits).
+
+* **[\\][uU]{hexdigit}{4}** - Used to escape a Unicode number ( ```\u``` or ```\U``` followed by 4 hex digits).
+
+### Literals
+
+Single and double quotes produce the same result, but they do not terminate each other. For example,
+`"abc"` and `'abc'` are identical, whereas `"a'b'c"` is equivalent to a space-separated
+concatenation of `a, 'b', c`.
+
+* `FALSE` , `NO` - Logical false.
+
+* `TRUE` , `YES` - Logical true.
+
+* `NULL` , `NIL` - A null value.
+
+* `SELF` - Represents the object being evaluated.
+
+* `"text"` - A character string.
+
+* `'text'` - A character string.
+
+* **Comma-separated literal array** - For example, `{ 'comma', 'separated', 'literal', 'array' }` .
+
+* **Standard integer and fixed-point notations** - For example, `1 , 27 , 2.71828 , 19.75` .
+
+* **Floating-point notation with exponentiation** - For example, `9.2e-5` .
+
+* `0x` - Prefix used to denote a hexadecimal digit sequence.
+
+* `0o` - Prefix used to denote an octal digit sequence.
+
+* `0b` - Prefix used to denote a binary digit sequence.
+
+### Reserved Keywords
+
+The following keywords are reserved:
+
+`AND, OR, IN, NOT, ALL, ANY, SOME, NONE, LIKE, CASEINSENSITIVE, CI, MATCHES, CONTAINS, BEGINSWITH,
+ENDSWITH, BETWEEN, NULL, NIL, SELF, TRUE, YES, FALSE, NO, FIRST, LAST, SIZE, ANYKEY, SUBQUERY,
+CAST, TRUEPREDICATE, FALSEPREDICATE`
+
+### Available Attributes
+
+Check the [Element Attributes](./element-attributes.md) document to know all element attribute
+names and types that are available for usage in predicate locators.
+
+### More Information
+
+* [Apple Developer documentation on Predicates](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Predicates/AdditionalChapters/Introduction.html)
+* [NSPredicate Cheat Sheet](https://academy.realm.io/posts/nspredicate-cheatsheet/)
+* [Class Chain Queries Construction Rules](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules)

package/src/resources/submodules/appium-xcuitest-driver/docs/reference/locator-strategies.md

@@ -0,0 +1,19 @@
+---
+hide:
+  - toc
+
+title: Locator Strategies
+---
+
+The XCUITest driver supports several location strategies in the native context. The following table
+lists them in performance order (the first one is the fastest one):
+
+| <div style="width:14em">Name</div> | Description | Speed Ranking | Example |
+| --- | --- | --- | --- |
+| `className` | Performs search by element's `type` [attribute](element-attributes.md). The full list of supported XCUIElement type names could be found in the official XCTest [documentation on XCUIElementType](https://developer.apple.com/documentation/xctest/xcuielementtype) | ⭐⭐⭐⭐⭐ | `XCUIElementTypeButton` |
+| `id`, `name`, `accessibility id` | All these locator types are synonyms and internally get transformed into search by element's `name` [attribute](element-attributes.md). | ⭐⭐⭐⭐⭐  | `my name` |
+| `-ios predicate string` | This strategy is mapped to the native XCTest predicate locator. Check the [NSPredicate cheat sheet](https://academy.realm.io/posts/nspredicate-cheatsheet/) for more details on how to build effective predicate expressions. All the supported element [attributes](element-attributes.md) could be used in these expressions. | ⭐⭐⭐⭐⭐  | `(name == 'done' OR value == 'done') AND type IN {'XCUIElementTypeButton', 'XCUIElementTypeKey'}` |
+| `-ios class chain` | This strategy is mapped to the native XCTest predicate locator, but with respect to the actual element tree hierarchy. Such locators are basically a supertype of `-ios predicate string`. Read [Class Chain Queries Construction Rules](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules) for more details on how to build such locators. | ⭐⭐⭐⭐ | ```**/XCUIElementTypeCell[$name == 'done' OR value == 'done'$]/XCUIElementTypeButton[-1]``` |
+| `xpath` | For elements lookup using the Xpath strategy the driver uses the same XML tree that is generated by the page source API. This means such locators are the slowest (sometimes up to 10x slower) in comparison to the ones above, which all depend on native XCTest primitives, but are the most flexible. Use Xpath locators only if there is no other way to locate the given element. Only Xpath 1.0 is supported. | ⭐⭐ | `//XCUIElementTypeButton[@value=\"Regular\"]/parent::*` |
+
+Also, consider checking the [How To Achieve The Best Lookup Performance](https://github.com/facebookarchive/WebDriverAgent/wiki/How-To-Achieve-The-Best-Lookup-Performance) article.

package/src/resources/submodules/appium-xcuitest-driver/docs/reference/scripts.md

@@ -0,0 +1,29 @@
+---
+hide:
+  - toc
+
+title: Scripts
+---
+
+Appium drivers can include scripts for executing specific actions. The following table lists the
+scripts bundled with the XCUITest driver. These scripts can be run as follows:
+
+```
+appium driver run xcuitest <script-name>
+```
+
+|Script Name|Description|
+|------------|-----------|
+|`open-wda`|Opens the WebDriverAgent project in Xcode|
+|`build-wda`|Builds the WebDriverAgent project using the first available iPhone simulator and the latest iOS supported by the current Xcode version by default|
+|`build-wda --sdk=17.5 --name="iPhone 15"`|Builds the WebDriverAgent project using the iPhone 15 simulator with iOS 17.5. If `--sdk` and `--name` params are not specified - the latest iOS and the first available iPhone simulator will be used|
+|`tunnel-creation`|Creates tunnels for connected iOS devices, starts CoreDeviceProxy, and sets up a tunnel registry server. Requires sudo access to communicate with iOS devices|
+|`tunnel-creation --udid=<device-udid>` or `-u <device-udid>`|Creates a tunnel for a specific iOS device with the given UDID|
+|`tunnel-creation --packet-stream-base-port=<port>`|Specifies the base port for packet stream servers (default: 50000)|
+|`tunnel-creation --tunnel-registry-port=<port>`|Specifies the port for the tunnel registry server (default: 42314)|
+|`download-wda-sim --outdir=/path/to/dir`|Download corresponding version's prebuilt WDA for iOS matched with the host machine architecture from [GitHub WebDriver release page](https://github.com/appium/WebDriverAgent/releases) into `--outdir` directory. The downloaded package name will be `WebDriverAgentRunner-Runner.app`.|
+|`download-wda-sim --platform=tvos --outdir=/path/to/dir`|Download corresponding version's prebuilt WDA for `--platform` into `--outdir` directory. If `--platform=tvos` is provided, the download module will be for tvOS (`WebDriverAgentRunner_tvOS-Runner.app`), otherwise the command will download iOS.|
+|`image-mounter mount --image <path> --manifest <path> --trustcache <path>`|Mount a Personalized Developer Disk Image on an iOS device. Requires paths to the .dmg image file, BuildManifest.plist, and .trustcache file. Requires the `appium-ios-remotexpc` optional dependency.|
+|`image-mounter mount --image <path> --manifest <path> --trustcache <path> --udid <device-udid>`|Mount a Developer Disk Image on a specific iOS device with the given UDID|
+|`image-mounter unmount`|Unmount a Developer Disk Image from the first available iOS device (default mount path: `/System/Developer`)|
+|`image-mounter unmount --udid <device-udid>`|Unmount a Developer Disk Image from a specific iOS device with the given UDID|

package/src/resources/submodules/appium-xcuitest-driver/docs/reference/security-flags.md

@@ -0,0 +1,22 @@
+---
+hide:
+  - toc
+
+title: Security Feature Flags
+---
+
+Some insecure driver features are disabled by default. They can be enabled upon launching Appium as follows:
+```
+appium --allow-insecure <feature-name>
+```
+or
+```
+appium --relaxed-security
+```
+
+|Feature Name|Description|
+|------------|-----------|
+|`shutdown_other_sims`|Allow any session to use a capability to shutdown any running simulators on the host|
+|`perf_record`|Allow recording the system performance and other metrics of the simulator|
+|`audio_record`|Allow recording of host audio input(s)|
+|`customize_result_bundle_path`|Allow customizing the paths to result bundles, using the `resultBundlePath` capability|

package/src/resources/submodules/appium-xcuitest-driver/docs/reference/server-args.md

@@ -0,0 +1,16 @@
+---
+hide:
+  - toc
+
+title: Appium Server Arguments
+---
+
+Some driver arguments can be set when launching the Appium server. This can be done as follows:
+
+```
+appium --driver-xcuitest-[argName]=[argValue]
+```
+
+|Argument|Description|Default|Example|
+|----|-------|-----------|-------|
+| `webdriveragent-port` | Local port used for communicating with WebDriverAgent | `8100` | `--driver-xcuitest-webdriveragent-port=8200` |

package/src/resources/submodules/appium-xcuitest-driver/docs/reference/settings.md

@@ -0,0 +1,49 @@
+---
+hide:
+  - toc
+
+title: Settings
+---
+
+The XCUITest driver supports Appium's [Settings API](https://appium.io/docs/en/latest/guides/settings/).
+Along with the common settings, the following driver-specific settings are available:
+
+| <div style="width:14em">Name</div> | Type | Description |
+| --- | --- | --- |
+| `elementResponseAttributes` | `string` | Comma-separated list of element attribute names to be included into findElement response. By default only element UUID is present there, but it is also possible to add the following items: `name`, `text`, `rect`, `enabled`, `displayed`, `selected`, `attribute/<element_attribute_name>`. It is required that `shouldUseCompactResponses` setting is set to `false` in order for this one to apply. |
+| `shouldUseCompactResponses` | `boolean` | Used in combination with `elementResponseAttributes` setting. If set to `false` then the findElement response is going to include the items enumerated in `elementResponseAttributes` setting. `true` by default |
+| `screenshotQuality` | `int` | See the description of the corresponding capability. |
+| `mjpegServerFramerate` | `int` | The maximum count of screenshots per second taken by the MJPEG screenshots broadcaster. Must be in range 1..60. `10` by default |
+| `mjpegScalingFactor` | `float` | The percentage value used to apply downscaling on the screenshots generated by the MJPEG screenshots broadcaster. Must be in range 1..100. `100` is by default, which means that screenshots are not downscaled. |
+| `mjpegServerScreenshotQuality` | `int` | The percentage value used to apply lossy JPEG compression on the screenshots generated by the MJPEG screenshots broadcaster. Must be in range 1..100. `25` is by default, which means that screenshots are compressed to the quarter of their original quality. |
+| <s>`customSnapshotTimeout`</s> | `float` | *Removed since XCUITest driver v8.0.0*. Set how much time in float seconds is allowed to resolve a single accessibility snapshot with custom attributes. _Snapshots_ are mainly used for page source generation, XML lookup and custom attributes retrieval (these are visibility and accessibility ones). It might be necessary to increase this value if the actual page source is very large and contains hundreds of UI elements. Defaults to 15 seconds. Since Appium 1.19.1 if this timeout expires and no custom snapshot could be made then WDA tries to calculate the missing attributes using its own algorithms, so setting this value to zero might speed up, for example, page source retrieval, but for the cost of preciseness of some element attributes. |
+| `waitForIdleTimeout` | `float` | Has the same meaning as corresponding capability (see above) |
+| `animationCoolOffTimeout` | `float` | The amount of time in float seconds to wait until the application under test does not have any active animations. This check is usually applied after each automation action that is supposed to change the state of the application under test, like `click` one, and blocks XCTest until the transition of the tested application to a new state completes or the cool off timeout occurs. The default value is `2` (seconds). Setting it to zero disables animation checks completely. |
+| `snapshotMaxDepth` | `int` | Changes the value of maximum depth for traversing elements source tree. It may help to prevent out of memory or timeout errors while getting the elements source tree, but it might restrict the depth of source tree. Please consider restricting this value if you observed an error like _Timed out snapshotting com.apple.testmanagerd..._ message or _Cannot get 'xml' source of the current application_ in your Appium log since they are possibly timeout related. A part of elements source tree might be lost if the value was too small. Defaults to `50` |
+| `useFirstMatch` | `boolean` | Enabling this setting makes single element lookups faster, but there is the known [problem](https://github.com/appium/appium/issues/10101) related to nested elements lookup. Defaults to `false`. |
+| `reduceMotion` | `boolean` | Changes the 'reduce motion' preference of accessibility feature. Defaults to `false` |
+| `defaultActiveApplication` | `string` | Sets the hint for active application selection. This helps WebDriverAgent to select the current application if there are multiple items in the active applications list and the desired one is also one of them. The setting is particularly useful for split-screen apps automation. Defaults to `auto`, which makes WebDriverAgent to select the application whose element is located at `screenPoint` location or a single item from the active apps list if the length of this list is equal to one. |
+| `activeAppDetectionPoint` | `string` | Defines the coordinates of the current screen point. WebDriverAgent uses this point to detect the active application if multiple application are active on the screen. The format of this value is `x,y`, where x and y are float or integer numbers representing valid screen coordinates. Setting this value to a point outside the actual screen coordinates might corrupt WebDriverAgent functionality. By default the screen point coordinates equal to 20% of the minimum screen dimension each, e.g. `MIN(w, h) * 0.2, MIN(w, h) * 0.2` |
+| `includeNonModalElements` | `boolean` | Whether returns all of elements including no modal dialogs on iOS 13+. It fixes [cannot find elements on nested modal presentations](https://github.com/appium/appium/issues/13227), but it might make visibility attributes unreliable. You could also enable `shouldUseTestManagerForVisibilityDetection` setting (defaults to `false`) or `simpleIsVisibleCheck` capability to improve the visibility detection. This issue may happen between iOS 13.0 to 13.2 (Xcode 11.0 to 11.2). The query issued in `includeNonModalElements` returns `nil` with newer iOS/Xcode versions and Appium/WDA return proper elements three without this setting being used. Defaults to `false`. |
+| `acceptAlertButtonSelector` | `string` | Allows to customize accept alert button selector. It helps you to handle an arbitrary element as accept button in `accept alert` command. The selector should be a valid [class chain](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules) expression, where the search root is the alert element itself. The default button location algorithm is used if the provided selector is wrong or does not match any element. Example: ```**/XCUIElementTypeButton[`label CONTAINS[c] 'accept'`]``` |
+| `dismissAlertButtonSelector` | `string` | Allows to customize dismiss alert button selector. It helps you to handle an arbitrary element as dismiss button in `dismiss alert` command. The selector should be a valid [class chain](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules) expression, where the search root is the alert element itself. The default button location algorithm is used if the provided selector is wrong or does not match any element. Example: ```**/XCUIElementTypeButton[`label CONTAINS[c] 'dismiss'`]``` |
+| `screenshotOrientation` | `string` | Adjust screenshot orientation for iOS. Appium tries to return a screenshot and adjust its orientation properly using internal heuristics, but sometimes it does not work, especially in landscape mode. The actual screenshot orientation depends on various factors such as OS versions, model versions and whether this is a real or simulator device. This option allows you to enforce the given image orientation. Acceptable values: `auto` (default), `portrait`, `portraitUpsideDown`, `landscapeRight`, `landscapeLeft`. |
+| `boundElementsByIndex` | `boolean` | Whether to look up elements with [`allElementsBoundByAccessibilityElement`](https://developer.apple.com/documentation/xctest/xcuielementquery/1500816-allelementsboundbyaccessibilitye) (default) or [`allElementsBoundByIndex`](https://developer.apple.com/documentation/xctest/xcuielementquery/1500945-allelementsboundbyindex). [This Stack Overflow topic](https://stackoverflow.com/questions/49307513/meaning-of-allelementsboundbyaccessibilityelement) explains the differences. Defaults to `false`. |
+| `keyboardAutocorrection` | `boolean` | Changes the 'Auto-Correction' preference in _Keyboards_ setting. Defaults to `false`. |
+| `keyboardPrediction` | `boolean` | Changes the 'Predictive' preference in _Keyboards_ setting. Defaults to `false`. |
+| `nativeWebTap` | `boolean` | See the description of the corresponding capability. |
+| `nativeWebTapStrict` | `boolean` | See the description of the corresponding capability. |
+| `nativeWebTapTabBarVisibility` | `enum` | Bypass finding whether the existence of the _**tab bar**_ before tapping on the element. It could make native web tap faster. If it's `visible`, tab bar offset will be added without checking the existence of the tab bar. It's `invisible`, the tab bar offset will be `zero`. If you want to leave Appium to check and measure the tab bar offset, unset or set `detect`. Only applicable if `nativeWebTap` and `nativeWebTapStrict` are enabled. Unset by default. |
+| `nativeWebTapSmartAppBannerVisibility` | `enum` | The same as `nativeWebTapTabBarVisibility`, this keyword will bypass finding whether the existence of the _**smart app banner**_. |
+| `safariTabBarPosition` | `string` | Handle offset of Safari tab bar in `nativeWebTap` enabled interactions. If `platformVersion` was greater than or equal to 15 and iPhone device, the value is `bottom` by default. Otherwise `top`. When the value is `top`, Appium considers offset as the bar length. iOS 15+ environment can customize the bar position in the settings app, so please adjust the offset with this. Acceptable values: `bottom`, `top` |
+| `useJSONSource` | `boolean` | See the description of the corresponding capability. |
+| `pageSourceExcludedAttributes` | `string` | One or more comma-separated attribute names to be excluded from the output. It might be sometimes helpful to exclude, for example, the `visible` attribute, to significantly speed-up page source retrieval. Attributes which can be excluded with `useJSONSource` are frame, enabled, visible, accessible and focused. Defaults to an empty string. Example: `"visible,accessible"` |
+| `maxTypingFrequency` | `int` | Maximum frequency of keystrokes for typing and clear. If your tests are failing because of typing errors, you may want to adjust this. Defaults to `60` keystrokes per minute. |
+| `respectSystemAlerts` | `boolean` | Currently we detect the app under test as active if XCTest returns XCUIApplicationStateRunningForeground state for it. In case the app under test is covered by a system alert from the Springboard app this approach might be confusing as we cannot interact with it unless an alert is properly handled. If this setting is set to true (by default it is false) then it forces WDA to verify the presence of alerts shown by Springboard and return the latter while performing the automated app detection. It affects the performance of active app detection, but might be more convenient for writing test scripts (e.g. eliminates the need of proactive switching between system and custom apps). Also, this behavior emulates the legacy active application detection logic before version 6 of the driver. |
+| `webScreenshotMode` | `native` or `page` or `viewport` | Defines the screenshoting logic if the current context is set to a web one. The default value is `native`, which makes the driver to take screenshots from WDA, e.g. the whole device screen including status bars. The `page` mode tries to retrieve the screenshot of the whole active web page, while the `viewport` one only retrieves a shot of the visible viewport. |
+| `useClearTextShortcut` | `boolean` | Whether to use the fastest operation (using IOHIDEvent) to clear texts. In headless mode, simulator's keyboard won't show up anymore after clearing texts using this approach in some cases (see [this issue](https://github.com/appium/appium/issues/20727) for more details). Defaults to true |
+| `limitXPathContextScope` | `boolean` | Due to historical reasons XCUITest driver limits scopes of element context-based searches to the parent element. This means a request like `findElement(By.xpath, "//XCUIElementTypeButton").findElement(By.xpath, "./..")` would always fail, because the driver only collects descendants of the `XCUIElementTypeButton` element for the destination XML source. The `limitXPathContextScope` setting being set to `false` changes that default behavior, so the collected page source includes the whole page source XML where `XCUIElementTypeButton` node is set as the search context. With that setting disabled the search query above should not fail anymore. Although, you must be careful while building XPath requests for context-based searches with the `limitXPathContextScope` setting being set to `false`. A request like `findElement(By.xpath, "//XCUIElementTypeAlert").findElement(By.xpath, "//XCUIElementTypeButton")` would ignore the current context and search for `XCUIElementTypeButton` through the whole page source. Use `.` notation to correct that behavior and only find `XCUIElementTypeButton` nodes which are descendants of the `XCUIElementTypeAlert` node: `findElement(By.xpath, "//XCUIElementTypeAlert").findElement(By.xpath, ".//XCUIElementTypeButton")`. |
+| `skipDocumentsContainerCheck` | `boolean` | Whether to apply special handling for the `documents` container type in file management such as pushing/pulling to/from real devices (`false`, the default value), or to treat them in the same way as other container types (`true`). For certain applications having this setting enabled helps to workaround documents upload issues if the `UIFileSharingEnabled` flag is not active in the application manifest.|
+| `autoClickAlertSelector` | `string` | Allows providing a custom [class chain](./locator-strategies.md) selector, which is used to automatically locate an element inside an alert hierarchy, and click it as soon as a new alert is detected. If the provided locator string is invalid then an error is thrown. Providing an empty string disables the feature. This setting has priority over `autoAcceptAlerts` or `autoDismissAlerts` capabilities, e.g. if both are enabled then the destination element to tap on would be selected only based on the provided selector value. If an alert is active, but no element matches the provided selector, then no click would be performed. If two or more elements match the provided selector then the very first matched element is clicked. The selector lookup is performed starting from the root element of the matched alert hierarchy (usually XCUIElementTypeAlert). |
+| `includeHittableInPageSource` | `boolean` | Determines whether the [`hittable`](https://developer.apple.com/documentation/xctest/xcuielement/ishittable) attribute should be included in the page source XML tree. This value reflects whether an element is currently interactive from XCTest’s perspective. Disabled by default due to potential performance impact on large UI hierarchies. Defaults to `false`. |
+| `includeMinMaxValueInPageSource` | `boolean` | Determines whether the `minValue` and `maxValue` attributes should be included in the page source. These attributes represent numeric boundaries for controls like sliders and progress indicators. Disabled by default due to potential performance impact when multiple such elements are present. Defaults to `false`. |

package/src/schema.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+
+export const elementUUIDScheme = z
+  .string()
+  .describe('The uuid of the element returned by appium_find_element to click');

package/src/scripts/simple-index-documentation.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Simple Documentation Indexing Script
+ *
+ * This script is a simplified version for indexing Markdown documents into an in-memory vector store
+ * using LangChain's RecursiveCharacterTextSplitter and MemoryVectorStore.
+ *
+ * Usage:
+ * - Index a single Markdown file: npm run simple-index-docs [markdownPath] [chunkSize] [overlap]
+ * - Index all Markdown files in a directory: npm run simple-index-docs [dirPath] [chunkSize] [overlap]
+ *
+ * Examples:
+ * - npm run simple-index-docs ./my-doc.md 1000 200
+ * - npm run simple-index-docs ./src/resources 1000 200
+ *
+ * If no path is provided, it defaults to indexing all Markdown files in the src/resources directory.
+ * If a file path is provided, it will index that specific file.
+ * If a directory path is provided, it will index all Markdown files in that directory.
+ */
+
+import * as path from 'path';
+import * as fs from 'fs';
+import {
+  indexMarkdown,
+  indexAllMarkdownFiles,
+} from '../tools/documentation/simple-pdf-indexer.js';
+
+/**
+ * Main function to handle the documentation indexing process
+ */
+async function main(): Promise<void> {
+  // Parse command line arguments
+  const args = process.argv.slice(2);
+  let markdownPath: string;
+  let chunkSize = 1000; // Default chunk size
+  let chunkOverlap = 200; // Default overlap
+  let indexSingleFile = false;
+
+  if (args.length > 0 && args[0]) {
+    markdownPath = path.resolve(process.cwd(), args[0]);
+
+    if (fs.existsSync(markdownPath) && fs.statSync(markdownPath).isFile()) {
+      indexSingleFile = true;
+      console.log(`Using provided file path: ${markdownPath}`);
+    } else {
+      console.log(`Using provided directory path: ${markdownPath}`);
+    }
+  } else {
+    // Default to submodules directory which contains the git submodules
+    markdownPath = path.resolve(process.cwd(), 'src/resources/submodules');
+    console.log(`Using default submodules directory: ${markdownPath}`);
+  }
+
+  if (args.length > 1 && !isNaN(Number(args[1]))) {
+    chunkSize = Number(args[1]);
+    console.log(`Using chunk size: ${chunkSize}`);
+  }
+
+  if (args.length > 2 && !isNaN(Number(args[2]))) {
+    chunkOverlap = Number(args[2]);
+    console.log(`Using overlap: ${chunkOverlap}`);
+  }
+
+  console.log('Using sentence-transformers embeddings (no API key required)');
+
+  console.log(
+    'Starting simplified documentation indexing process with in-memory vector store...'
+  );
+
+  try {
+    if (indexSingleFile) {
+      console.log(`Indexing single Markdown file: ${markdownPath}`);
+      await indexMarkdown(markdownPath, chunkSize, chunkOverlap);
+      console.log('Documentation indexing completed successfully');
+    } else {
+      console.log(`Indexing all Markdown files in directory: ${markdownPath}`);
+      const indexedFiles = await indexAllMarkdownFiles(
+        markdownPath,
+        chunkSize,
+        chunkOverlap
+      );
+      console.log(
+        `Documentation indexing completed successfully for ${indexedFiles.length} Markdown files`
+      );
+    }
+    process.exit(0);
+  } catch (error: any) {
+    console.error('Documentation indexing failed:', error);
+    process.exit(1);
+  }
+}
+
+main();

package/src/scripts/simple-query-documentation.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Simple Documentation Query Script
+ *
+ * This script is used to test the answerAppiumQuery function
+ * by querying the indexed Markdown documentation in the in-memory vector store.
+ *
+ * Usage: npm run simple-query-docs "your query here"
+ *
+ * Example: npm run simple-query-docs "What is Appium?"
+ */
+
+import { answerAppiumQuery } from '../tools/documentation/index.js';
+
+/**
+ * Main function to handle the documentation query process
+ */
+async function main(): Promise<void> {
+  console.log('Using sentence-transformers embeddings (no API key required)');
+  console.log(
+    'Note: This script will return relevant documentation chunks without generating responses'
+  );
+
+  console.log('process.argv:', process.argv);
+  const args = process.argv.slice(2);
+  console.log('args:', args);
+  let query = '';
+
+  if (args.length > 0) {
+    query = args.join(' ');
+    console.log(`Using provided query: "${query}"`);
+  } else {
+    query = 'What is Appium and how do I get started?';
+    console.log(`No query provided, using default query: "${query}"`);
+  }
+
+  console.log(`Querying in-memory vector store with: "${query}"`);
+
+  try {
+    const result = await answerAppiumQuery({
+      query,
+    });
+
+    console.log('\n--- ANSWER ---\n');
+    console.log(result.answer);
+
+    if (result.sources && result.sources.length > 0) {
+      console.log('\n--- SOURCES ---\n');
+      result.sources.forEach((source: any) => {
+        console.log(`- ${source}`);
+      });
+    }
+
+    process.exit(0);
+  } catch (error: any) {
+    console.error('Query failed:', error);
+    process.exit(1);
+  }
+}
+
+main();

package/src/server.ts

@@ -0,0 +1,40 @@
+import { FastMCP } from 'fastmcp';
+import registerTools from './tools/index.js';
+import registerResources from './resources/index.js';
+import { hasActiveSession, safeDeleteSession } from './tools/session-store.js';
+import log from './locators/logger.js';
+
+const server = new FastMCP({
+  name: 'MCP Appium',
+  version: '1.0.0',
+  instructions:
+    'Intelligent MCP server providing AI assistants with powerful tools and resources for Appium mobile automation',
+});
+
+registerResources(server);
+registerTools(server);
+
+// Handle client connection and disconnection events
+server.on('connect', event => {
+  log.info('Client connected:', event.session);
+});
+
+server.on('disconnect', async event => {
+  log.info('Client disconnected:', event.session);
+  // Only try to clean up if there's an active session
+  if (hasActiveSession()) {
+    try {
+      log.info('Active session detected on disconnect, cleaning up...');
+      const deleted = await safeDeleteSession();
+      if (deleted) {
+        log.info('Session cleaned up successfully on disconnect.');
+      }
+    } catch (error) {
+      log.error('Error cleaning up session on disconnect:', error);
+    }
+  } else {
+    log.info('No active session to clean up on disconnect.');
+  }
+});
+
+export default server;

package/src/tests/README.md

@@ -0,0 +1,83 @@
+# Tests for Mobile Agent
+
+This directory contains unit tests for the Mobile Agent project.
+
+## Running Tests
+
+To run all tests:
+
+```bash
+npm test
+```
+
+To run specific test files:
+
+```bash
+# Run tests for the locator generation functionality
+npm run test:locators
+```
+
+## Test Files
+
+### generate-all-locators.test.ts
+
+This file contains tests for the `generateAllElementLocators` function, which is responsible for generating locators for all elements in a page source XML.
+
+The tests cover:
+
+1. Basic functionality with valid XML
+2. Handling of invalid/empty XML
+3. Various filtering options:
+   - `includeTagNames` - Include only specific element types
+   - `excludeTagNames` - Exclude specific element types
+   - `minAttributeCount` - Filter elements by minimum attribute count
+   - `fetchableOnly` - Include only interactable elements (platform-specific)
+   - `clickableOnly` - Include only clickable elements
+
+## Adding New Tests
+
+When adding new tests:
+
+1. Create a new test file in the `src/tests` directory with the `.test.ts` extension
+2. Import the necessary functions and types from the source files
+3. Use Jest's `describe`, `test`, and `expect` functions to structure your tests
+4. Add a new script to `package.json` for running your specific test file
+
+## Test Structure
+
+Tests should follow this general structure:
+
+```typescript
+import { describe, test, expect } from '@jest/globals';
+import { functionToTest } from '../path/to/function.js';
+
+describe('functionToTest', () => {
+  test('should do something specific', () => {
+    // Arrange - set up test data
+    const input = 'some input';
+    
+    // Act - call the function
+    const result = functionToTest(input);
+    
+    // Assert - verify the result
+    expect(result).toBe('expected output');
+  });
+});
+```
+
+## Mocking
+
+For tests that require mocking dependencies, use Jest's mocking capabilities:
+
+```typescript
+import { jest } from '@jest/globals';
+
+// Mock a module
+jest.mock('../path/to/module.js');
+
+// Create a mock function
+const mockFunction = jest.fn();
+mockFunction.mockReturnValue('mocked value');
+```
+
+Note that when working with ESM modules, you may need to use different mocking approaches than with CommonJS modules.