docs: architecture deep dive (wix#132)

docs/Guide.Contributing.md

@@ -1,6 +1,5 @@
 # Contributing to detox
 
-
 ### Clone detox and submodules
 
 ```sh
@@ -26,7 +25,7 @@ npm install -g react-native-cli
 
 For all the internal projects (detox, detox-server, detox-cli, demos, test) `lerna` will create symbolic links in `node_modules` instead of `npm` copying the content of the projects. This way, any change you do on any code is there immediately. There is no need to update node modules or copy files between projects.
 
-### Install `fbsimctl` 
+### Install `fbsimctl`
 
 ```sh
 brew tap facebook/fb
@@ -58,7 +57,7 @@ lerna run test
 
 Detox JS code is 100% test covered and is set to break the build if coverage gets below, so make sure you run unit tests (`lerna run test`) locally before pushing.
 
-Alternatively, to run only the JS tests, run the following from the `detox/detox` directory: 
+Alternatively, to run only the JS tests, run the following from the `detox/detox` directory:
 
 ```sh
 npm run unit
@@ -93,5 +92,3 @@ To run the e2e tests, after the application was built.
 ```sh
 npm run e2e
 ```
-
-**NOTE: The updated flow can always be found in [our CI build script](../scripts/ci.sh)**

docs/Introduction.HowDetoxWorks.md

@@ -28,3 +28,22 @@ Detox eliminates flakiness by automatically synchronizing your tests with the ap
 * Keeping track of the React Native bridge which carries asynchronous messages
 * Keeping track of asynchronous React Native layout and the shadow queue
 * Keeping track of the JavaScript event loop which may contain pending asynchronous actions
+
+
+### Architecture
+The sequence diagram below shows the general communication scheme between the components in Detox.
+![architecture overview](img/action-sequence.mmd.png)
+
+To understand this topic more thoroughly we need to have a look at an example action in detail. The numbers in the listing below correlate with the ones in the diagram.
+
+### Action (`element.tap`)
+
+1. `element.tap()` in your test case is invoked.
+2. `TapAction` in [`expect.js`](https://github.com/wix/detox/blob/master/detox/src/ios/expect.js) gets invoked
+3.  `TapAction` instance gets passed to [`invoke.js`](https://github.com/wix/detox/blob/master/detox/src/invoke.js), where it gets transformed to JSON. The resulting JSON correlates more with the native code than with the JS code for better extensibility.
+4. JSON gets send to detox-server by [`Client.js`](https://github.com/wix/detox/blob/master/detox/src/client/Client.js)
+6. detox-server forwards it to the testee in [`DetoxServer.js`](https://github.com/wix/detox/blob/master/detox-server/src/DetoxServer.js)
+7. [`DetoxManager.m`](https://github.com/wix/detox/blob/master/detox/ios/Detox/DetoxManager.m) invokes the [`TestRunner.m`](https://github.com/wix/detox/blob/master/detox/ios/Detox/TestRunner.m). `TestRunner.m` uses [`MethodInvocation.m`](https://github.com/wix/detox/blob/master/detox/ios/Detox/MethodInvocation.m) to map the JSON representation of the native commands into the actual native command and executes it. *(8)*
+
+
+*NOTE: the images can be updated with [mermaid](http://knsv.github.io/mermaid/#mermaid). The files can be found under `img-src`*

docs/img-src/action-sequence.mmd

@@ -0,0 +1,19 @@
+sequenceDiagram
+  participant Test Runner(1)
+  participant Tester(3)
+  participant Detox Server(5)
+  participant Testee(7)
+  participant Earl Grey(9)
+
+  %% Note over Test Runner(1),Detox Server(5): Runs on your computer
+  %% Note over Testee(7),Earl Grey(9): Runs on the device
+
+  Test Runner(1)->>Tester(3): assertion / action (2)
+  Tester(3)->>Detox Server(5): native code as JSON (4)
+  Detox Server(5)->>Testee(7): Websocket connection (6)
+  Testee(7)-x+Earl Grey(9): native invocation (8)
+  Note left of Earl Grey(9): EarlGrey waits for device to become idle again
+  Earl Grey(9)->>-Testee(7): (10)
+  Testee(7)->>Detox Server(5): (11)
+  Detox Server(5)->>Tester(3): (12)
+  Tester(3)->>Test Runner(1): (13)

docs/img-src/build.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+mermaid -o '../img' *.mmd