kobiton · duylam · Jun 8, 2018 · May 30, 2018 · Jun 4, 2018 · Jun 4, 2018
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+.DS_Store
diff --git a/1-triggering-jenkins.md b/1-triggering-jenkins.md
@@ -0,0 +1,96 @@
+# Triggering a Jenkins build from a push to GitHub
+
+This guide will demonstrate how to get Jenkins to build your project everytime your source code is changed and pushed to GitHub. 
+
+### Prerequisites
+
+* Jenkins is installed, let's assume it's at https://ci.awesome-mapp.com
+
+*Follow the steps below to setup Jenkins for GitHub* 
+
+#### 1.1 Install the GitHub integration plugin
+
+* On Jenkins, go to 'Manage Jenkins' and then click on 'Manage Plugins'. 
+
+![manage-jenkins](assets/2-manage-jenkins.png)
+
+* Click on the tab 'Available', search for the GitHub Integration Plugin, and install it.
+
+![github-integration-plugin](assets/2-github-integration-plugin.png)
+
+#### 1.2 Configure GitHub repo to push to Jenkins
+
+* Go to your Github, click on Settings, and then go to 'Integration & services'. Add the Jenkins Github plugin.
+
+![jenkins-git](assets/2-jenkinsgit.png)
+
+* Once you've added the plugin, click on it. For 'Jenkins hook url', enter in the URL of your Jenkins instance, e.g. https://awesome-mapp.com/, followed by /github-webhook/ 
+
+![jenkins-hook](assets/2-jenkins-hook.png)
+
+**SSH Key**
+
+If you do not already have an SSH key, you can generate one with the following command in your terminal. 
+
+```
+ssh-keygen
+```
+Copy the public key. This may vary depending on where the key was generated. 
+```
+cat /var/lib/jenkins/.ssh/id_rsa.pub
+```
+In GitHub, go to 'Settings' and 'Deploy keys'. Click on 'Add deploy key' and paste the SSH key you just created. 
+
+![deploy-key](assets/2-deploykeys.png)
+
+#### 1.3 Allow Jenkins to access GitHub repository
+
+* Upload the app you want to test to a GitHub repo. 
+
+* Go to Jenkins and create a new freestyle project.
+
+* In Jenkins, go to the configuration of your project. Under the tab 'General', check the box that says 'GitHub project' and enter in your project url. 
+
+![githubproject](assets/2-github-project.png)
+
+* Under the Source Code Management, add the repository URL with 'git@github.com:' before your repo. 
+
+![sourcecode-management](assets/2-sourcecode-management.png)
+
+> Troubleshooting
+
+You may see an error from adding your repository URL if your "Credentials" are set to "None".  
+
+![failure-error](assets/2-failure-error.png)
+
+To fix this, we must add a credential. Under the "Source Code Management" section in "Credentials", click on the 'Add' button.
+
+![credential](assets/2-credential.png)
+
+There are several kinds of credentials you may choose.
+
+1. Username with password
+
+Enter in the username that will be used to connect to the git repository. You may leave the ID and Description field empty. 
+
+![user-with-pass](assets/2-username-with-password.png)
+
+2. SSH Username with private key
+
+Enter in the username that will be used to connect to the git repository.
+
+There are three options for the Private Key. If you choose to Enter directly, you may have to retrieve your RSA private key.
+
+Enter in The passphrase for your key. 
+
+You may leave the ID and Description empty. 
+
+Select the Credential you just created in the Credentials dropdown. 
+
+* Under the 'Build Triggers' section, check the box with 'GitHub hook trigger for GITScm polling'. 
+
+![trigger](assets/2-trigger.png)
+
+**Jenkins (GitHub plugin)**
+
+Make a push to your GitHub repository and then check Jenkins to see if a build was done successfully. 
diff --git a/2-running-automation-testing.md b/2-running-automation-testing.md
@@ -0,0 +1,161 @@
+# 2. Running automation test with Kobiton
+
+#### 2.1 Prepare Kobiton configuration for executing automation testing
+
+* #### Username 
+1. Go to https://portal.kobiton.com/
+2. In the upper right hand corner, click on your name and in the drop down menu, click on Profile. 
+
+![profile](assets/2-profile-user.png)
+
+3. You should see the username. 
+
+![username](assets/2-username.png)
+
+* #### API key
+1. Click on your name in the upper righthand corner again and select settings. 
+2. You should be able to find your API key under 'API Keys'. 
+
+![api-key](assets/2-apikey.png)
+
+* #### Desired cap
+1. In the navigation bar at the top of the Kobiton website, select Devices. 
+2. Hover over any device and click on the Automation settings button (the gear symbol). 
+
+![automation](assets/2-automation.png)
+
+3. On the left hand side, you can select your preferred language, as well as any other variables you would like to adjust, such as **App Type**, **Device Group**, and **Orientation**. Adjusting the settings on the left side will affect the desiredCaps, which you can find in the right side of the window. 
+
+![automation-settings](assets/2-automationsettings.png)
+
+## 2.2 Create new Jenkins project to execute the automation test
+
+#### How to setup Jenkins to run automation testing
+
+Jenkins is an open source automation server that provides hundreds of plugins to support building, deploying, and automating any project. 
+
+Download Jenkins from https://jenkins.io/ and make sure you have a Jenkins server available with a public domain. 
+
+**2.2.1 Write the automation test script**
+
+* How to write a simple test
+
+For examples of automation tests, go to https://github.com/kobiton/samples . 
+
+Choose a language for your test script, and decide whether you want to test on Android or iOS, and either do a web test or an app test. Make sure in the code you specify your Kobiton username, API key, and information under desiredCaps. 
+
+**2.2.2 Create Jenkins project**
+
+On the left side on the page, click on New Item to start a new Jenkins project. 
+
+![new-item](assets/2-new-item.png)
+
+Enter in a name for the project and select 'Freestyle project'. Hit 'OK'. 
+
+![project](assets/2-project.png)
+
+Go to Configure in your Jenkins project. Add a build step, execute shell. 
+
+![build-execute-shell](assets/2-build-execute-shell.png)
+
+Enter this in the command. Enter your own Kobiton  username and API key as well as the desired device and platform you wish to test with. The below example will execute the android-web-test script sample from Kobiton. 
+```
+#!/bin/bash
+[ ! -d "samples" ] && git clone https://github.com/kobiton/samples.git || echo "Samples already exist"
+cd samples/javascript
+npm install
+npm run android-web-test
+```
+
+This guide is executing the NodeJS test script from the Kobiton samples, so we will add the NodeJS Plugin on Jenkins to execute NodeJS script as a build step. To do this, go to 'Manage Jenkins' -> 'Manage Plugins' -> Available. Search for NodeJS and install it.
+
+![manage-plugins](assets/2-manageplugins.png)
+
+If you are using a different language, you may try to find a suitable plugin for your project if necessary.
+
+Under build environment, check the box that says 'Provide Node & npm bin/ folder to PATH'.
+
+![build-environment](assets/2-build-environment.png)
+
+**2.2.3 Trigger Jenkins project by pushing on GitHub**
+
+Try Build now and check Kobiton cloud devices to see if a test session was created. 
+
+**2.2.4 Get the automation session data through Kobiton REST API**
+
+
+- Update test result to session (https://api.kobiton.com/docs/#update-session-information)
+
+```
+PUT /sessions/{sessionId}
+``` 
+To make a request:
+
+1. Encode your credential in base64 for HTTP Basic Authentication, you may use below command and note the text result
+
+```
+echo -n <your username>:<your api-key> | base64
+```
+2. Use encoded base64 from above in curl commands, like below
+
+```
+curl -X GET https://api.kobiton.com/v1/sessions \
+  -H 'Authorization: Basic dGVzdHVzZXI6MTIzZWQtMTIzZmFjLTkxMzdkY2E='
+  -H 'Accept: application/json'
+```
+
+Below are necessary Kobiton Rest API endpoints that you may need.
+
+- Get session info
+```
+GET /sessions{sessionId}
+```
+To make a request:
+```
+curl -X GET https://api.kobiton.com/v1/sessions/{sessionId} \
+  -H 'Authorization: Basic dGVzdHVzZXI6MTIzZWQtMTIzZmFjLTkxMzdkY2E='
+  -H 'Accept: application/json'
+```
+
+With this line of code, you can print the session information to the console. 
+```javascript
+console.log(sessionCapabilities)
+```
+
+- Get session commands
+```
+GET /sessions/{sessionId}/commands
+```
+To make a request:
+
+```Shell
+curl -X GET https://api.kobiton.com/v1/sessions/{sessionId}/commands \
+  -H 'Authorization: Basic dGVzdHVzZXI6MTIzZWQtMTIzZmFjLTkxMzdkY2E='
+  -H 'Accept: application/json'
+
+```
+To get to a certain page in your commands, add the page number to the commands URL. For example:
+```javascript
+`https://api-test.kobiton.com/v1/sessions/${sessionId}/commands?page=2`
+```
+
+> For more details on how to retrieve information about your session, go to https://api.kobiton.com/docs/
+
+## Final result
+
+The test is a either a success or failure.
+
+#### Failure case
+
+* Error: "The environment you requested was unavailable." 
+    - This means that the device you selected is already booked. Either select a different device or wait a few moments until your device becomes available
+* Other 
+    - Contact Kobiton for support
+    - Go to portal.kobiton.com
+    - In the navigation bar at the top of the page, click on 'Support'
+
+    ![support](assets/2-support.png)
+
+    - Fill in the information for your request and submit your ticket
+
+    ![submit-ticket](assets/2-submit-ticket.png)
diff --git a/README.md b/README.md
@@ -1,2 +1,17 @@
 # Jenkins-HockeyApp-Appium-ReactNative
 Guidance on integrating Kobiton service into the build pipeline of mobile app development: Jenkins, HockeyApp, Appium and ReactNative
+
+If you are a company with a domain, ex: https://awesome-mapp.com and you use:
+
+- Jenkins to build the app
+- HockeyApp for keeping the daily app build
+- Appium to write the automation test
+- ReactNative to write app
+
+The guidelines in this repo will show you how to trigger a Jenkins build from a push on GitHub (i.e. everytime a change is made to your source code), and how to run automation tests with Kobiton. 
+
+## Contents
+1. First guide will demonstrate [how to trigger a Jenkins build from a push to GitHub](./1-triggering-jenkins.md). 
+
+2. The second guide will demonstrate [how to run automation tests on your app with the Kobiton service](./2-running-automation-testing.md). 
+
diff --git a/assets/2-apikey.png b/assets/2-apikey.png
diff --git a/assets/2-automation.png b/assets/2-automation.png
diff --git a/assets/2-automationsettings.png b/assets/2-automationsettings.png
diff --git a/assets/2-build-environment.png b/assets/2-build-environment.png
diff --git a/assets/2-build-execute-shell.png b/assets/2-build-execute-shell.png
diff --git a/assets/2-credential.png b/assets/2-credential.png
diff --git a/assets/2-deploykeys.png b/assets/2-deploykeys.png
diff --git a/assets/2-failure-error.png b/assets/2-failure-error.png
diff --git a/assets/2-github-integration-plugin.png b/assets/2-github-integration-plugin.png
diff --git a/assets/2-github-project.png b/assets/2-github-project.png
diff --git a/assets/2-jenkins-hook.png b/assets/2-jenkins-hook.png
diff --git a/assets/2-jenkinsgit.png b/assets/2-jenkinsgit.png
diff --git a/assets/2-manage-jenkins.png b/assets/2-manage-jenkins.png
diff --git a/assets/2-manageplugins.png b/assets/2-manageplugins.png
diff --git a/assets/2-new-item.png b/assets/2-new-item.png
diff --git a/assets/2-profile-user.png b/assets/2-profile-user.png
diff --git a/assets/2-project.png b/assets/2-project.png
diff --git a/assets/2-sourcecode-management.png b/assets/2-sourcecode-management.png
diff --git a/assets/2-status.png b/assets/2-status.png
diff --git a/assets/2-submit-ticket.png b/assets/2-submit-ticket.png
diff --git a/assets/2-support.png b/assets/2-support.png
diff --git a/assets/2-trigger.png b/assets/2-trigger.png
diff --git a/assets/2-user.png b/assets/2-user.png
diff --git a/assets/2-username-with-password.png b/assets/2-username-with-password.png
diff --git a/assets/2-username.png b/assets/2-username.png