Update first test script according to QSG spec and added package.json to manage npm dependencies

.gitignore

@@ -0,0 +1 @@
+node_modules/

README.md

@@ -1,9 +1,105 @@
 # node-appium-app-browserstack
-App Automate Node Samples
----------------------
 
-This repository contains code for Automated Native App tests. Please feel free to clone the repo and use the example code.
+This repository demonstrates how to run Appium NodeJS tests on BrowserStack App Automate.
 
-For frameworks integration with BrowserStack, refer to their individual repositories -
+## Setup
+
+### Requirements
+
+1. Node.js
+
+    - If not installed, install Node.js from [here](https://nodejs.org/en/download/)
+
+    - Ensure you have node & npm installed by running `node -v` & `npm -v`
+
+### Install the dependencies
+
+To install the dependencies run the following command in the project's base directory :
+
+```
+npm install
+```
+
+## Getting Started
+
+Getting Started with Appium tests in NodeJS on BrowserStack couldn't be easier!
+
+### Run your first test :
+
+**1. Upoad 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 `BrowserStackSample.js` file in `Android` or in `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 `node BrowserStackSample.js`
+
+- 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 tes**
+
+Open `BrowserStackSampleLocal.js` file in `Android` or in `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 Javascript binding for BrowserStack Local.
+
+- If you have uploaded your own app update the test case
+
+- Run `node BrowserStackSampleLocal.js`
+
+- 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 NodeJS frameworks
+
+For other NodeJS frameworks samples, refer to following repositories :
 
 - [WebdriverIO](https://github.com/browserstack/webdriverio-appium-app-browserstack)
+
+Note: For other test frameworks supported by App-Automate refer our [Developer documentation](https://www.browserstack.com/docs/)
+
+## Getting Help
+
+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/BrowserStackSample.js

@@ -0,0 +1,56 @@
+let wd = require('wd');
+let assert = require('assert');
+let asserters = wd.asserters;
+
+desiredCaps = {
+  // Set your BrowserStack 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 NodeJS project',
+  'build' : 'Node Android',
+  'name': 'first_test'
+};
+
+// Initialize the remote Webdriver using BrowserStack remote URL
+// and desired capabilities defined above
+driver = wd.promiseRemote("http://hub-cloud.browserstack.com/wd/hub");
+
+// Test case for the BrowserStack sample Android app. 
+// If you have uploaded your app, update the test case here. 
+driver.init(desiredCaps)
+  .then(function () {
+    return driver.waitForElementByAccessibilityId(
+      'Search Wikipedia', asserters.isDisplayed 
+      && asserters.isEnabled, 30000);
+  })
+  .then(function (searchElement) {
+    return searchElement.click();
+  })
+  .then(function () {
+    return driver.waitForElementById(
+      'org.wikipedia.alpha:id/search_src_text', asserters.isDisplayed 
+      && asserters.isEnabled, 30000);
+  })
+  .then(function (searchInput) {
+    return searchInput.sendKeys("BrowserStack");
+  })
+  .then(function () {
+    return driver.elementsByClassName('android.widget.TextView');    
+  })
+  .then(function (search_results) {
+    assert(search_results.length > 0);
+  })
+  .fin(function() { 
+    // Invoke driver.quit() after the test is done to indicate that the test is completed.
+    return driver.quit(); 
+  })
+  .done();

android/BrowserStackSampleLocal.js

@@ -0,0 +1,85 @@
+let wd = require('wd');
+let assert = require('assert');
+let asserters = wd.asserters;
+let Q = wd.Q;
+let browserstack = require('browserstack-local');
+
+// Set your BrowserStack access credentials
+let userName = 'YOUR_USERNAME'
+let accessKey = "YOUR_ACCESS_KEY"
+
+desiredCaps = {
+   '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,
+
+  // Set other BrowserStack capabilities
+  'project' : 'First NodeJS project',
+  'build' : 'Node Android Local',
+  'name': 'local_test',
+  'browserstack.debug' : true,
+};
+
+let promise = new Promise(function(resolve, reject) {
+  // Start BrowserStack Local
+  exports.bs_local = new browserstack.Local();
+  exports.bs_local.start({'key':  accessKey}, (error) => {
+    if (error) return reject(error);
+    console.log('BrowserStack Local connected.');
+    resolve();
+  });
+});
+
+promise.then(function() {
+    // Initialize the remote Webdriver using BrowserStack remote URL
+    // and desired capabilities defined above
+    driver = wd.promiseRemote("http://hub-cloud.browserstack.com/wd/hub");
+
+    // Test case for the BrowserStack sample Android Local app. 
+    // If you have uploaded your app, update the test case here. 
+    driver.init(desiredCaps)
+    .then(function () {
+      return driver.waitForElementById('com.example.android.basicnetworking:id/test_action', asserters.isDisplayed && asserters.isEnabled, 30000);
+    })
+    .then(function (testElement) {
+      return testElement.click();
+    })
+    .then(function () {
+      return driver.waitForElementsByClassName('android.widget.TextView', asserters.isDisplayed, 30000);
+    })
+    .then(function (textElements) {
+      return Q().then(function () {
+        return textElements.map(function (textElement) {
+          return textElement.text().then(function(value) {
+            if (value.indexOf('The active connection is') !== -1) {
+              console.log(value);
+              assert(value.indexOf('The active connection is wifi') !== -1);
+              assert(value.indexOf('Up and running') !== -1);
+            }
+          });
+        })
+      }).all()
+    })
+    .fin(function() { 
+      // Invoke driver.quit() after the test is done to indicate that the test is completed.  
+      return driver.quit(); 
+    })
+    .done(function() {
+       // Stop BrowserStack Local
+        exports.bs_local.stop((error) => {
+          if(error) return console.log("Error in stopping BrowserStack Local :"+ error)
+          console.log("Stopped BrowserStack Local")
+        })
+    });  
+}, function(error) { 
+    console.log("Failed to start BrowserStack Local :" + error)
+})