driver.push_file(destination_path, source_path) feature (appium#270)

* used base64 library for conversion

* remove unnecessary library use

* changed text in test file

* * Using context when reading file
* changed docstring format
* Catch error thrown if file not present and present user with a better message

* fixed incorrect file path in test

* removed change in pul_file that broke backwards compat and updated docstring description for `destination_path`

Author: JavonDavis

.gitignore

@@ -19,3 +19,6 @@ dist
 __pycache__
 .idea
 .pytest_cache
+
+# Virtual Environments
+venv*

appium/webdriver/webdriver.py

@@ -18,20 +18,17 @@
 import copy
 
 from selenium import webdriver
-
-from selenium.webdriver.common.by import By
-from selenium.webdriver.support.ui import WebDriverWait
 from selenium.common.exceptions import TimeoutException, InvalidArgumentException
-
+from selenium.webdriver.common.by import By
 from selenium.webdriver.remote.command import Command as RemoteCommand
+from selenium.webdriver.support.ui import WebDriverWait
 
 from appium.webdriver.clipboard_content_type import ClipboardContentType
 from appium.webdriver.common.mobileby import MobileBy
-from appium.webdriver.common.touch_action import TouchAction
 from appium.webdriver.common.multi_action import MultiAction
-
-from .mobilecommand import MobileCommand as Command
+from appium.webdriver.common.touch_action import TouchAction
 from .errorhandler import MobileErrorHandler
+from .mobilecommand import MobileCommand as Command
 from .switch_to import MobileSwitchTo
 from .webelement import WebElement as MobileWebElement
 
@@ -776,8 +773,7 @@ def set_value(self, element, value):
         return self
 
     def pull_file(self, path):
-        """Retrieves the file at `path`. Returns the file's content encoded as
-        Base64.
+        """Retrieves the file at `path`. Returns the file's contents as base64.
 
         :Args:
          - path - the path to the file on the device
@@ -799,15 +795,29 @@ def pull_folder(self, path):
         }
         return self.execute(Command.PULL_FOLDER, data)['value']
 
-    def push_file(self, path, base64data):
-        """Puts the data, encoded as Base64, in the file specified as `path`.
+    def push_file(self, destination_path, base64data=None, source_path=None):
+        """Puts the data from the file at `source_path`, encoded as Base64, in the file specified as `path`.
 
-        :Args:
-         - path - the path on the device
-         - base64data - data, encoded as Base64, to be written to the file
+        Specify either `base64data` or `source_path`, if both specified default to `source_path`
+        :param destination_path: the location on the device/simulator where the local file contents should be saved
+        :param base64data: file contents, encoded as Base64, to be written to the file on the device/simulator
+        :param source_path: local file path for the file to be loaded on device
+        :return: WebDriver instance
         """
+        if source_path is None and base64data is None:
+            raise InvalidArgumentException('Must either pass base64 data or a local file path')
+
+        if source_path is not None:
+            try:
+                with open(source_path, 'rb') as file:
+                    data = file.read()
+            except FileNotFoundError:
+                message = 'source_path {} could not be found. Are you sure the file exists?'.format(source_path)
+                raise InvalidArgumentException(message)
+            base64data = base64.b64encode(data).decode('utf-8')
+
         data = {
-            'path': path,
+            'path': destination_path,
             'data': base64data,
         }
         self.execute(Command.PUSH_FILE, data)

test/functional/android/desired_capabilities.py

@@ -27,7 +27,8 @@ def get_desired_capabilities(app):
         'platformName': 'Android',
         'deviceName': 'Android Emulator',
         'app': PATH('../../apps/' + app),
-        'newCommandTimeout': 240
+        'newCommandTimeout': 240,
+        'automationName': 'UIAutomator2'
     }
 
     return desired_caps

test/functional/android/push_file_tests.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import unittest
+
+import desired_capabilities
+
+from appium import webdriver
+
+
+class PushFileTests(unittest.TestCase):
+    def setUp(self):
+        desired_caps = desired_capabilities.get_desired_capabilities('ApiDemos-debug.apk')
+        self.driver = webdriver.Remote('http://localhost:4723/wd/hub', desired_caps)
+
+    def tearDown(self):
+        self.driver.quit()
+
+    def test_push_file(self):
+        test_files = ['test_image.jpg', 'test_file.txt']
+        for file_name in test_files:
+            source_path = os.path.dirname(os.path.abspath(__file__)) + '//' + file_name
+            destination_path = '/data/local/tmp/'+file_name
+
+            original_data = open(source_path, 'rb').read()
+
+            self.driver.push_file(destination_path, source_path=source_path)
+            new_data = self.driver.pull_file(destination_path)
+            self.assertEqual(original_data, new_data)
+
+
+if __name__ == "__main__":
+    suite = unittest.TestLoader().loadTestsFromTestCase(PushFileTests)
+    unittest.TextTestRunner(verbosity=2).run(suite)

test/functional/android/test_file.txt

@@ -0,0 +1 @@
+HEllo

test/functional/android/test_image.jpg

@@ -28,7 +28,7 @@ def get_desired_capabilities(app):
     desired_caps = {
         'deviceName': iphone_device_name(),
         'platformName': 'iOS',
-        'platformVersion': '11.4',
+        'platformVersion': '12.1',
         'app': PATH('../../apps/' + app),
         'automationName': 'XCUITest',
         'allowTouchIdEnroll': True,

test/functional/ios/desired_capabilities.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import unittest
+
+import desired_capabilities
+
+from appium import webdriver
+
+
+class PushFileTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(self):
+        desired_caps = desired_capabilities.get_desired_capabilities('UICatalog.app.zip')
+        self.driver = webdriver.Remote('http://localhost:4723/wd/hub', desired_caps)
+
+    @classmethod
+    def tearDownClass(self):
+        self.driver.quit()
+
+    def test_push_file(self):
+        file_name = 'test_image.jpg'
+        source_path = os.path.dirname(os.path.abspath(__file__)) + '/' + file_name
+        destination_path = file_name
+
+        self.driver.push_file(destination_path, source_path=source_path)
+
+
+if __name__ == "__main__":
+    suite = unittest.TestLoader().loadTestsFromTestCase(PushFileTests)
+    unittest.TextTestRunner(verbosity=2).run(suite)

test/functional/ios/push_file_tests.py

@@ -0,0 +1 @@
+"We have to stop optimizing for programmers and start optimizing for users." - Jeff Atwood