Updated first test script for Android and iOS according to QSG Python spec (#9)

* Update first test and Readme as per the QSG spec

* Update webdriver remote URL

* Providing access credentials from appium capabilities

* Correcting Selenium dependency version

* Updating readme with dashboard link

* Keeping a single requirements.txt file

* Removing Selenium dependency

* Updated readme

* Updated code changes for Local test

* Setting browserstack.local capability to True

* Updating Github Readme with Local test

* Readme styling changes

* Readme styling changes

* Readme styling changes

* Readme text update

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Changing file names according to QSG

* Updated readme

* updating 'desired_caps' to 'desired_cap' to match with QSG

* BrowserStack access credentials URL in readme.

Author: kn-neeraj

README.md

@@ -1,13 +1,140 @@
 # python-appium-app-browserstack
-App Automate Python Samples
----------------------
 
-This repository contains code for Automated Native App tests. Please feel free to clone the repo and use the example code.
-Refer [Getting Started with App Automate](https://www.browserstack.com/app-automate/appium-python) for more details.
+This repository demonstrates how to run Appium Python tests on BrowserStack App Automate.
+
+## Setup
+
+### Requirements
+
+1. Python 3.6+ or Python 2.7+
+    
+    - For Windows, download latest python version from [here](https://www.python.org/downloads/windows/) and run the installer executable
+    - For Mac and Linux, run `python --version` to see what python version is pre-installed. If you want a different version download from [here](https://www.python.org/downloads/)
+
+2. Package Manager pip
+
+    Note : `pip` comes installed with Python 2.7.9+ and python 3.4+
+
+    - If `pip` is not installed, follow these instructions:
+        - Securely download get-pip.py by following this link: [get-pip.py](https://bootstrap.pypa.io/get-pip.py) or use following cURL command to download it:
+
+        ```sh
+        curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
+        ```
+
+        - After dowloading, run the file :
+
+            - For Python 3
+
+                ```sh
+                python3 get-pip.py
+                ```
+
+            - For Python 2
+
+                ```sh
+                python2 get-pip.py
+                ```
+
+### Install the dependencies
+
+To install the dependencies, run the following command in project's base directory:
+
+- For Python 3
+
+    ```sh
+    pip3 install -r requirements.txt
+    ```
+
+- For Python 2
+
+    ```sh
+    pip2 install -r requirements.txt
+    ```
+
+## Getting Started
+
+Getting Started with Appium tests in Python on BrowserStack couldn't be easier!
+
+### Run your first test :
+
+**1. Upload your Android or iOS App**
+
+Upload your Android app (.apk or .aab file) or iOS app (.ipa file) to BrowserStack servers using our REST API. Here is an example cURL request :
+
+```
+curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
+-X POST "https://api-cloud.browserstack.com/app-automate/upload" \
+-F "file=@/path/to/apk/file"
+```
+
+Ensure that @ symbol is prepended to the file path in the above request. Please note the `app_url` value returned in the API response. We will use this to set the application under test while configuring the test later on.
+
+**Note**: If you do not have an .apk or .ipa file and are looking to simply try App Automate, you can download and test using our [sample Android app](https://www.browserstack.com/app-automate/sample-apps/android/WikipediaSample.apk) or [sample iOS app](https://www.browserstack.com/app-automate/sample-apps/ios/BStackSampleApp.ipa).
+
+
+**2. Configure and run your first test**
+
+Open `browserstack_sample.py` file in `Android` or `iOS` folder :
+
+- Replace `YOUR_USERNAME` & `YOUR_ACCESS_KEY` with your BrowserStack access credentials. Get your BrowserStack access credentials from [here](https://www.browserstack.com/accounts/settings)
+
+- Replace `bs://<app-id>` wkth the URL obtained from app upload step
+
+- Set the device and OS version
+
+- If you have uploaded your own app update the test case
+
+- Run `python browserstack_sample.py`
+
+- You can access the test execution results, and debugging information such as video recording, network logs on [App Automate dashboard](https://app-automate.browserstack.com/dashboard)
+
+---
+
+### **Use Local testing for apps that access resources hosted in development or testing environments :**
+
+**1. Upload your Android or iOS App**
+
+Upload your Android app (.apk or .aab file) or iOS app (.ipa file) that access resources hosted on your internal or test environments to BrowserStack servers using our REST API. Here is an example cURL request :
+
+```
+curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
+-X POST "https://api-cloud.browserstack.com/app-automate/upload" \
+-F "file=@/path/to/apk/file"
+```
+
+Ensure that @ symbol is prepended to the file path in the above request. Please note the `app_url` value returned in the API response. We will use this to set the application under test while configuring the test later on.
+
+**Note**: If you do not have an .apk or .ipa file and are looking to simply try App Automate, you can download and test using our [sample Android Local app](https://www.browserstack.com/app-automate/sample-apps/android/LocalSample.apk) or [sample iOS Local app](https://www.browserstack.com/app-automate/sample-apps/ios/LocalSample.ipa).
+
+
+**2. Configure and run your local test**
+
+Open `browserstack_sample_local` file in `Android` or `iOS` folder :
+
+- Replace `YOUR_USERNAME` & `YOUR_ACCESS_KEY` with your BrowserStack access credentials. Get your BrowserStack access credentials from [here](https://www.browserstack.com/accounts/settings)
+
+- Replace `bs://<app-id>` wkth the URL obtained from app upload step
+
+- Set the device and OS version
+
+- Ensure that `browserstack.local` capability is set to `true`. Within the test script, there is code snippet that automatically establishes Local Testing connection to BrowserStack servers using Python binding for BrowserStack Local. 
+
+- If you have uploaded your own app update the test case
+
+- Run `python browserstack_sample_local.py`
+
+- You can access the test execution results, and debugging information such as video recording, network logs on [App Automate dashboard](https://app-automate.browserstack.com/dashboard)
+
+## Integration with other python frameworks
+
+For other Python frameworks samples, refer to following repositories :
 
-For frameworks integration with BrowserStack, refer to their individual repositories -
-- [Lettuce](https://github.com/browserstack/lettuce-appium-app-browserstack)
 - [Behave](https://github.com/browserstack/behave-appium-app-browserstack)
+- [Lettuce](https://github.com/browserstack/lettuce-appium-app-browserstack)
+
+Note: For other test frameworks supported by App-Automate refer our [Developer documentation](https://www.browserstack.com/docs/)
+
+## Getting Help
 
-For python 2 support refer the branch
-- [python-2-master](https://github.com/browserstack/python-appium-app-browserstack/tree/python-2-master)
+If you are running into any issues or have any queries, please check [Browserstack Support page](https://www.browserstack.com/support/app-automate) or [get in touch with us](https://www.browserstack.com/contact?ref=help).

android/BrowserStackAndroid.py

@@ -0,0 +1,47 @@
+from appium import webdriver
+from appium.webdriver.common.mobileby import MobileBy
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+import time
+
+desired_cap = {
+    # Set your access credentials
+    "browserstack.user" : "YOUR_USERNAME",
+    "browserstack.key" : "YOUR_ACCESS_KEY",
+
+    # Set URL of the application under test
+    "app" : "bs://<app-id>",
+
+    # Specify device and os_version for testing
+    "device" : "Google Pixel 3",
+    "os_version" : "9.0",
+    
+    # Set other BrowserStack capabilities
+    "project" : "First Python project", 
+    "build" : "Python Android",
+    "name" : "first_test"
+}
+
+# Initialize the remote Webdriver using BrowserStack remote URL
+# and desired capabilities defined above
+driver = webdriver.Remote(
+    command_executor="http://hub-cloud.browserstack.com/wd/hub", 
+    desired_capabilities=desired_cap
+)
+
+# Test case for the BrowserStack sample Android app. 
+# If you have uploaded your app, update the test case here. 
+search_element = WebDriverWait(driver, 30).until(
+    EC.element_to_be_clickable((MobileBy.ACCESSIBILITY_ID, "Search Wikipedia"))
+)
+search_element.click()
+search_input = WebDriverWait(driver, 30).until(
+    EC.element_to_be_clickable((MobileBy.ID, "org.wikipedia.alpha:id/search_src_text"))
+)
+search_input.send_keys("BrowserStack")
+time.sleep(5)
+search_results = driver.find_elements_by_class_name("android.widget.TextView")
+assert(len(search_results) > 0)
+
+# Invoke driver.quit() after the test is done to indicate that the test is completed.
+driver.quit()

android/README.md

@@ -5,14 +5,28 @@
 from browserstack.local import Local
 import time
 
-userName = "BROWSERSTACK_USERNAME"
-accessKey = "BROWSERSTACK_ACCESS_KEY"
+# Set your BrowserStack access credentials here
+userName = "YOUR_USERNAME"
+accessKey = "YOUR_ACCESS_KEY"
 
 desired_caps = {
-    "build": "Python 3 Android Local",
-    "device": "Samsung Galaxy S7",
+    "browserstack.user" : userName,
+    "browserstack.key" : accessKey,
+
+    # Set URL of the application under test
+    "app" : "<bs://app-id>",
+
+    # Specify device and os_version for testing
+    "device" : "Google Pixel 3",
+    "os_version" : "9.0",
+
+    #Set BrowserStack Local capability as True
     "browserstack.local": True,
-    "app": "bs://<hashed app-id>"
+
+    # Set other BrowserStack capabilities
+    "project" : "First Python Local project", 
+    "build" : "Python Android Local",
+    "name" : "local_test"
 }
 
 bs_local = None
@@ -27,29 +41,38 @@ def stop_local():
     global bs_local
     bs_local.stop()
 
+# Start BrowserStack local binary
 start_local()
-driver = webdriver.Remote("http://" + userName + ":" + accessKey + "@hub-cloud.browserstack.com/wd/hub", desired_caps)
+
+# Initialize the remote Webdriver using BrowserStack remote URL
+# and desired capabilities defined above
+driver = webdriver.Remote(
+    command_executor="http://hub-cloud.browserstack.com/wd/hub", 
+    desired_capabilities=desired_caps
+)
+
+# Test case for the BrowserStack sample Android app. 
+# If you have uploaded your app, update the test case here. 
 test_button = WebDriverWait(driver, 30).until(
     EC.element_to_be_clickable((MobileBy.ID, "com.example.android.basicnetworking:id/test_action"))
 )
 test_button.click()
 WebDriverWait(driver, 30).until(
     EC.element_to_be_clickable((MobileBy.CLASS_NAME, "android.widget.TextView"))
 )
-
 test_element = None
 search_results = driver.find_elements_by_class_name("android.widget.TextView")
 for result in search_results:
     if result.text.__contains__("The active connection is"):
         test_element = result
-
 if test_element is None:
     raise Exception("Cannot find the needed TextView element from app")
-
 matched_string = test_element.text
 print (matched_string)
 assert(matched_string.__contains__("The active connection is wifi"))
 assert(matched_string.__contains__("Up and running"))
 
+# Invoke driver.quit() after the test is done to indicate that the test is completed.
 driver.quit()
+
 stop_local()