From bd11fc58e543cc4182dfaf86de10c985c7d271da Mon Sep 17 00:00:00 2001
From: Rotem M <rotemm@wix.com>
Date: Wed, 27 Jun 2018 18:14:11 +0300
Subject: [PATCH] Updated docs

---
 docs/APIRef.DetoxCLI.md             |  3 ++-
 docs/Guide.Contributing.md          | 33 +++++++++++++++--------------
 docs/Guide.Jest.md                  |  4 ++--
 docs/Introduction.GettingStarted.md |  9 ++++----
 4 files changed, 26 insertions(+), 23 deletions(-)

diff --git a/docs/APIRef.DetoxCLI.md b/docs/APIRef.DetoxCLI.md
index c683163c4f..cb787872ed 100644
--- a/docs/APIRef.DetoxCLI.md
+++ b/docs/APIRef.DetoxCLI.md
@@ -32,7 +32,8 @@ detox [options] [command]
 
 | Options | Description |
 | --- | --- |
-| -h<br>--help | Output usage information |
+| -h, --help | Output usage information |
+
 
 ## Commands
 
diff --git a/docs/Guide.Contributing.md b/docs/Guide.Contributing.md
index 4c02696b9c..dd56199999 100644
--- a/docs/Guide.Contributing.md
+++ b/docs/Guide.Contributing.md
@@ -45,15 +45,20 @@ git submodule update --init --recursive
 lerna bootstrap
 ```
 
-### Building
+### Building & Testing
+##### Automatically
+`scripts/ci.ios.sh` and `scripts/ci.android.sh` are the scripts Detox runs in CI, they will run `lerna bootstrap`, unit tests, and E2E tests. Make sure these scripts pass before submitting a PR, this is exactly what Detox is going to run in CI. 
 
-```sh
-lerna run build
-```
+##### Manually
+Alternativley, you can run it manually
 
-### Testing
+#### 0. Fixing compilation issues in RN sources
+Detox Android test project uses React Native sources instead of the precompiled AAR. The test project uses RN51 and RN53, both have issues with compilation ([Fixed in RN55](https://github.com/facebook/react-native/commit/d8bb990abc226e778e2f32c2de3c6661c0aa64e5#diff-f44163238d434a443b56bd27b3ba0578)). In order to fix this issue, from inside `detox/test` run:
+```sh
+mv node_modules/react-native/ReactAndroid/release.gradle node_modules/react-native/ReactAndroid/release.gradle.bak
+``` 
 
-### 1. Unit tests
+#### 1. Unit tests
 
 ```sh
 lerna run test
@@ -69,7 +74,7 @@ npm run unit
 npm run unit:watch
 ```
 
-#### How to read the coverage report
+##### How to read the coverage report
 After running the tests, jest will create a coverage report.
 
 ```sh
@@ -77,28 +82,24 @@ cd detox
 open coverage/lcov-report/index.html
 ```
 
-### 2. Running Detox e2e coverage tests
+#### 2. Running Detox e2e coverage tests
 Detox has a suite of e2e tests to test its own API while developing (and for regression). The way we do is is by maintaining a special application that is "tested" against Detox's API, but essentially, it's the API that is tested, not the app.
 To run the e2e tests, go to `detox/detox/test`
 
 ```sh
 cd detox/test
-```
-
-
-```sh
 npm run build
 ```
 
 To run the e2e tests, after the application was built.
 
-#### iOS
+##### iOS
 ```sh
 npm run build:ios
 npm run e2e:ios
 ```
 
-#### Android
+##### Android
 ```sh
 npm run build:android
 npm run e2e:android
@@ -120,7 +121,7 @@ launchctl setenv PATH $PATH
 ```
 
 
-### 3. Android Native tests
+#### 3. Android Native tests
 
 0. Install Java and Android SDK 25
 1. In `detox/android` run `./gradlew install` run
@@ -129,7 +130,7 @@ launchctl setenv PATH $PATH
 	./gradlew test
 	```
 
-### 4. Code Generation
+#### 4. Code Generation
 
 We are using a code generator based on `babel` and `objective-c-parser` to generate a Javascript Interface for `EarlGrey` (the testing library we use on iOS).
 This interface allows us to call Objective-C methods through the WebSocket connection directly on the testing device. 
diff --git a/docs/Guide.Jest.md b/docs/Guide.Jest.md
index 38ba958a8f..5debe50e7e 100644
--- a/docs/Guide.Jest.md
+++ b/docs/Guide.Jest.md
@@ -5,7 +5,7 @@ title: Jest
 
 ## Usage
 
-### 0. Use the [Getting Started](Introduction.GettingStarted.md) Guide to set up detox
+### 0. Use the [Getting Started](Introduction.GettingStarted.md) Guide to set up Detox
 
 ### 1. Install Jest
 
@@ -37,7 +37,7 @@ detox init -r jest
 
 There are some things you should notice:
 
-- Don't worry about mocks being used, detox works on the compiled version of your app.
+- Don't worry about mocks being used, Detox works on the compiled version of your app.
 - Detox exposes it's primitives (`expect`, `device`, ...) globally, it will override Jest's global `expect` object.
 
 ## How to run unit test and E2E tests in the same project
diff --git a/docs/Introduction.GettingStarted.md b/docs/Introduction.GettingStarted.md
index ba10ba012f..d56208cc7f 100644
--- a/docs/Introduction.GettingStarted.md
+++ b/docs/Introduction.GettingStarted.md
@@ -87,17 +87,18 @@ npm install detox --save-dev
 
 > TIP: Remember to add the "node_modules" folder to your git ignore.
 
-#### 2. Install test runner
+#### 2. Install a test runner
 
-You can use any JavaScript test runner. At the moment, only two are documented:
+You can use any JavaScript test runner. Detox CLI supports Jest and Mocha out of the box.
 
-- [Jest](Guide.Jest.md)
+- [Jest](http://jestjs.io/)
 
 ```sh
 npm install jest --save-dev
 ```
+Read the [Jest integration guide](Guide.Jest.md) for more details and gotchas.
 
-- [Mocha](https://mochajs.org/) is a good one we recommend:
+- [Mocha](https://mochajs.org/)
 
 ```sh
 npm install mocha --save-dev