feat: add skipDocumentsContainerCheck settings to apply #2541 change

docs/guides/file-transfer.md

@@ -27,10 +27,11 @@ possible formats this path can take:
 * `<container-type>` is the container type
     * On simulators, common values are `app`, `data`, `groups`, but a custom one can also be provided
     * On real devices, the only accepted value is `documents`. All others are treated as Format 2
-        * In `xcuitest-driver` versions prior to version `v8.3.0` the following limitation applies:
-        This value can only be specified for apps that have the `UIFileSharingEnabled` flag set to
+        * This value can only be specified for apps that have the `UIFileSharingEnabled` flag set to
           `true`. You can use the [`mobile: listApps`](../reference/execute-methods.md#mobile-listapps)
           extension to identify such apps.
+        * By assigning the `skipDocumentsContainerCheck` [Settings API](https://appium.io/docs/en/latest/guides/settings/) to `true`, you may skip the above limitation for certain apps.
+
 * `<path-to-file-or-folder>` is the target file or folder
     * On real devices, if `<container-type>` is set to `documents`, this path will be mapped to
       `On My iPhone/<app name>` in the _Files_ app

docs/reference/settings.md

@@ -43,3 +43,4 @@ Along with the common settings, the following driver-specific settings are avail
 | `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.|

lib/commands/file-movement.js

@@ -72,14 +72,26 @@ function verifyIsSubPath(originalPath, root) {
  *
  * @param {string} udid
  * @param {string} [bundleId]
+ * @param {string} [containerType]
  * @returns {Promise<any>}
  */
-async function createAfcClient(udid, bundleId) {
+async function createAfcClient(udid, bundleId, containerType) {
   if (!bundleId) {
     return await services.startAfcService(udid);
   }
   const service = await services.startHouseArrestService(udid);
-  return await service.vendContainer(bundleId);
+
+  const {
+    skipDocumentsContainerCheck = false,
+  } = await this.settings.getSettings();
+
+  if (skipDocumentsContainerCheck) {
+    return service.vendContainer(bundleId);
+  }
+
+  return isDocumentsContainer(containerType)
+    ? await service.vendDocuments(bundleId)
+    : await service.vendContainer(bundleId);
 }
 
 /**
@@ -100,7 +112,7 @@ function isDocumentsContainer(containerType) {
 async function createService(remotePath) {
   if (CONTAINER_PATH_PATTERN.test(remotePath)) {
     const {bundleId, pathInContainer, containerType} = await parseContainerPath.bind(this)(remotePath);
-    const service = await createAfcClient(this.device.udid, bundleId);
+    const service = await createAfcClient(this.device.udid, bundleId, containerType);
     const relativePath = isDocumentsContainer(containerType)
       ? path.join(CONTAINER_DOCUMENTS_PATH, pathInContainer)
       : pathInContainer;