Update the documentation on push/pull file helpers (#906)

Author: Mykola Mokhnach

src/main/java/io/appium/java_client/InteractsWithFiles.java

@@ -29,11 +29,21 @@ public interface InteractsWithFiles extends ExecutesMethod {
 
     /**
      * Pull a file from the simulator/device.
+     * On iOS the server should have ifuse
+     * libraries installed and configured properly for this feature to work
+     * on real devices.
+     * On Android the application under test should be
+     * built with debuggable flag enabled in order to get access to its container
+     * on the internal file system.
      *
-     * @param remotePath On Android and iOS, this is either the path to the file
-     *                   (relative to the root of the app's file system). On iOS only,
-     *                   if path starts with /AppName.app, which will be replaced with
-     *                   the application's .app directory
+     * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page6</a>
+     * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
+     * @see <a href="https://developer.android.com/studio/debug/">'Debug Your App' developer article</a>
+     *
+     * @param remotePath If the path starts with <em>@applicationId/</em>/ prefix, then the file
+     *                   will be pulled from the root of the corresponding application container.
+     *                   Otherwise the root folder is considered as / on Android and
+     *                   on iOS it is a media folder root (real devices only).
      * @return A byte array of Base64 encoded data.
      */
     default byte[] pullFile(String remotePath) {
@@ -44,15 +54,23 @@ default byte[] pullFile(String remotePath) {
     }
 
     /**
-     * Pull a folder from the simulator/device. Does not work on iOS Real
-     * Devices, but works on simulators
+     * Pull a folder content from the simulator/device.
+     * On iOS the server should have ifuse
+     * libraries installed and configured properly for this feature to work
+     * on real devices.
+     * On Android the application under test should be
+     * built with debuggable flag enabled in order to get access to its container
+     * on the internal file system.
+     *
+     * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page6</a>
+     * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
+     * @see <a href="https://developer.android.com/studio/debug/">'Debug Your App' developer article</a>
      *
-     * @param remotePath On Android and iOS, this is either the path to the file
-     *                   (relative to the root of the app's file system). On iOS only,
-     *                   if path starts with /AppName.app, which will be replaced with
-     *                   the application's .app directory
-     * @return A byte array of Base64 encoded data, representing a ZIP ARCHIVE
-     *         of the contents of the requested folder.
+     * @param remotePath If the path starts with <em>@applicationId/</em> prefix, then the folder
+     *                   will be pulled from the root of the corresponding application container.
+     *                   Otherwise the root folder is considered as / on Android and
+     *                   on iOS it is a media folder root (real devices only).
+     * @return A byte array of Base64 encoded zip archive data.
      */
     default byte[] pullFolder(String remotePath) {
         Response response = execute(PULL_FOLDER, ImmutableMap.of("path", remotePath));

src/main/java/io/appium/java_client/android/PushesFiles.java

@@ -32,18 +32,32 @@ public interface PushesFiles extends InteractsWithFiles, ExecutesMethod {
 
     /**
      * Saves base64 encoded data as a file on the remote mobile device.
+     * The application under test should be
+     * built with debuggable flag enabled in order to get access to its container
+     * on the internal file system.
+     *
+     * @see <a href="https://developer.android.com/studio/debug/">'Debug Your App' developer article</a>
      *
      * @param remotePath Path to file to write data to on remote device
+     *                   If the path starts with <em>@applicationId/</em> prefix, then the file
+     *                   will be pushed to the root of the corresponding application container.
      * @param base64Data Base64 encoded byte array of data to write to remote device
      */
     default void pushFile(String remotePath, byte[] base64Data) {
         CommandExecutionHelper.execute(this, pushFileCommand(remotePath, base64Data));
     }
 
     /**
-     * Saves given file as a file on the remote mobile device.
+     * Saves the given file to the remote mobile device.
+     * The application under test should be
+     * built with debugMode flag enabled in order to get access to its container
+     * on the internal file system.
      *
-     * @param remotePath Path to file to write data to on remote device
+     * @see <a href="https://developer.android.com/studio/debug/">'Debug Your App' developer article</a>
+     *
+     * @param remotePath Path to file to write data to on remote device.
+     *                   If the path starts with <em>@applicationId/</em> prefix, then the file
+     *                   will be pushed to the root of the corresponding application container.
      * @param file is a file to write to remote device
      * @throws IOException when there are problems with a file or current file system
      */

src/main/java/io/appium/java_client/ios/PushesFiles.java

@@ -31,14 +31,21 @@ public interface PushesFiles extends ExecutesMethod {
 
     /**
      * Saves base64 encoded data as a media file on the remote mobile device.
-     * This method is only supported on Simulator running Xcode SDK 8.1+.
+     * The server should have ifuse
+     * libraries installed and configured properly for this feature to work
+     * on real devices.
+     *
+     * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page</a>
+     * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
      *
      * @param remotePath Path to file to write data to on remote device
-     *                   Only the filename part matters there, so the remote end
+     *                   Only the filename part matters there on Simulator, so the remote end
      *                   can figure out which type of media data it is and save
      *                   it into a proper folder on the target device. Check
      *                   'xcrun simctl addmedia' output to get more details on
-     *                   supported media types
+     *                   supported media types.
+     *                   If the path starts with <em>@applicationId/</em> prefix, then the file
+     *                   will be pushed to the root of the corresponding application container.
      * @param base64Data Base64 encoded byte array of media file data to write to remote device
      */
     default void pushFile(String remotePath, byte[] base64Data) {
@@ -47,7 +54,12 @@ default void pushFile(String remotePath, byte[] base64Data) {
 
     /**
      * Saves base64 encoded data as a media file on the remote mobile device.
-     * This method is only supported on Simulator running Xcode SDK 8.1+.
+     * The server should have ifuse
+     * libraries installed and configured properly for this feature to work
+     * on real devices.
+     *
+     * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page</a>
+     * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
      *
      * @param remotePath See the documentation on {@link #pushFile(String, byte[])}
      * @param file Is an existing local file to be written to the remote device