Faq (#177)

* docs(installation): update installation page * docs(installation): update installation page * docs(tests): fix debug and built-in functions documentary * docs(tests): added faq page * docs(): code review comments
Zooz · Aug 1, 2019 · 5c8c809 · 5c8c809
1 parent a286f21
commit 5c8c809
Show file tree

Hide file tree

Showing 4 changed files with 83 additions and 20 deletions.
diff --git a/docs/devguide/docs/faq.md b/docs/devguide/docs/faq.md
@@ -0,0 +1,48 @@
+# Frequently Asked Questions
+
+## Installation
+
+### <b>Predator is running, how do I access the UI?</b>
+
+The UI is accessible at http://$MACHINE_IP/ui where `$MACHINE_IP` is your local network address you used to install Predator.
+
+## Tests
+
+### <b>I run a test successfully but no report is created for the test</b>
+
+The Predator-Runner docker that is reporting the test results back to Predator isn't able to connect to it, 
+which is why the test runs but no report is generated. When installing Predator in Docker, the following command is used:
+```
+docker run -d -e JOB_PLATFORM=DOCKER -e INTERNAL_ADDRESS=http://$MACHINE_IP:80/v1 \
+-p 80:80 --name predator -v /var/run/docker.sock:/var/run/docker.sock zooz/predator
+```
+
+The `INTERNAL_ADDRESS=http://$MACHINE_IP:80/v1` is what the Predator-Runner uses to communicate with Predator, 
+and `$MACHINE_IP` needs to be your local network address (an IP address). You can get it by running the command: 
+```
+ifconfig en0 | grep 'inet ' | cut -d' ' -f2
+```
+
+For more information regarding correct installation of Predator using Docker visit the [Installation](installation.md#docker) section.
+
+It is important to note this is an issue and solution only in Docker installations. 
+In Kubernetes and DC/OS installations the `INTERNAL_ADDRESS` is built in.
+
+### <b>What is the http engine Predator uses to run the load?</b>
+
+Predator uses [Artillery](https://github.com/artilleryio/artillery) as its HTTP load engine. 
+Therefore, all `basic` type tests are written in Artillery syntax and all of the features Artillery supports, Predator supports.
+
+To read more about Artillery and its features visit their well written documentary: 
+- [Artillery Documentation](https://artillery.io/docs/)
+- [Artillery Basic Concepts Documentation](https://artillery.io/docs/basic-concepts/)
+- [Artillery Test Structure Documentation](https://artillery.io/docs/script-reference/)
+- [Artillery HTTP Engine Documentation](https://artillery.io/docs/http-reference/)
+
+## Configuration
+
+### <b>I ran Predator with SQLITE and would like to migrate now to a different database. How do I do this?</b>
+
+Migration between different databases is not possible. 
+In order to run Predator with a different supported database, 
+you must restart Predator with the new configuration.
diff --git a/docs/devguide/docs/installation.md b/docs/devguide/docs/installation.md
@@ -16,32 +16,36 @@ For examples and more info check [Universe Catalog](https://universe.dcos.io/#/p
 
 ## Docker
 
-Predator runs in a docker and it triggers other dockers which actually create the load (predator-runner).
-In order to avoid dind side affects, Predator will start its runners as siblings.
+Predator runs in a docker and when installing it using ```Docker```, Predator creates and runs other dockers which actually create the load (predator-runner).
+In order to avoid DIND, Predator will start its runners as siblings using the docker daemon socket.
 
-So this means two things
+<b>Command:</b>
 
-1. When starting Predator in a docker we will mount the docker socket to the container. This will allow Predator start the siblings dockers (predator-runner) 
+```docker run -d -e JOB_PLATFORM=DOCKER -e INTERNAL_ADDRESS=http://$MACHINE_IP:80/v1 -p 80:80 --name predator -v /var/run/docker.sock:/var/run/docker.sock zooz/predator```
+
+
+Explanations:
+
+1. When starting Predator in a docker we will mount the docker socket to the container. This will allow Predator to start the siblings dockers (Predator-Runner). This is done as so:
 <br>
 ```-v /var/run/docker.sock:/var/run/docker.sock``` 
-2. Predator runners will have to reach the main Predator to report test results. Predator has to know it's own accessible address and pass it to the predator-runners.
+
+2. When running tests, the Predator-Runners will have to reach the main Predator to report test results through their internal API. Therefore, Predator has to know it's own accessible address and pass it to the Predator-Runners for them to access Predator's API. This is done by setting the enviornment variable ```INTERNAL_ADDRESS``` as so:
 <br> 
  ```-e INTERNAL_ADDRESS=http://$MACHINE_IP:80/v1```
-   where `$MACHINE_IP` is the local ip address of your machine (not localhost, but actual ip address).
-   In unix or mac this command should give you the ip address:
-   </br>
+   where `$MACHINE_IP` is the local ip address of your machine (not localhost, but actual ip address - it is your local network address).
+   <br>In unix or mac this command should give you the ip address and set it to the MACHINE_IP variable:
    ```export MACHINE_IP=$(ipconfig getifaddr en0 || ifconfig eth0|grep 'inet addr:'|cut -d':' -f2|awk '{ print $1}')```
 
-```docker run -d -e JOB_PLATFORM=DOCKER -e INTERNAL_ADDRESS=http://$MACHINE_IP:80/v1 -p 80:80 --name predator -v /var/run/docker.sock:/var/run/docker.sock zooz/predator```
-
+3. The environment variable ```JOB_PLATFORM``` is set to ```DOCKER``` so that Predator deploys the Predator-Runners as dockers on the machine it is running.
 
 After successfully starting the Predator docker image, access Predator by typing the following URL in your browser:
 
 ```http://{$MACHINE_IP}/ui```
 
 !!! note "If you don't see test reports"
 
-    This usually means that the predator-runner couldn't reach the main Predator and report about test progress;
+    This usually means that the predator-runner couldn't reach the main Predator's API and update it about test progress;
     <br>
     ```docker logs $(docker ps -a -f name=predator -n 1 --format='{{ .ID }}')```
     <br>

diff --git a/docs/devguide/docs/tests.md b/docs/devguide/docs/tests.md
@@ -43,12 +43,14 @@ will randomly store `45697038-...-ed7a4a20e014` or `f02392e8-...-8a9a1ae5c47a` i
 
 ## Built-in Functions
 
-Predator supports some generic functions out of the box and they can be used to generate random data
+Predator supports some generic functions out of the box and they can be used to generate random data.
 
-* `randomNumber(min, max)` will generate random number within the provided range.
-* `$randomString(length)` will generate random string with the specified length.
+* `$randomNumber(min, max)` will generate a random number within the provided range.
+* `$randomString(length)` will generate a random string with the specified length.
 * `$uuid()` will generate v4 UUID.
-* `dateNow()` will generate Number of ms since epoch.
+* `$dateNow()` will generate a number of ms since epoch.
+
+<b>Currently these functions all return values as a `string`. An issue is open regarding this: [#178](https://github.com/Zooz/predator/issues/178)</b>
 
 Usage example:
 
@@ -57,7 +59,7 @@ Usage example:
 	"id": "{{ $uuid() }}",
 	"name": "{{ $randomString(6) }}",
 	"age": "{{ $randomNumber(0,15) }}",
-	"created": "{{$dateNow()}}",
+	"created": "{{ $dateNow() }}"
 }
 
 ```
@@ -237,8 +239,16 @@ In the example above, we created a test with 2 Javascript functions:
 
 * `generateRandomDataGlobal()` is a global function that creates global variables. Those variables can be used in the scope of the test by using the `{{ }}` syntax.
 
-## Debugging Requests/Responses
+## Debugging Test Requests/Responses
+
+It is possible to view all of the requests and responses that the predator-runner sends and receives while running load on the API. 
+This is very useful when your test does not behave the way you expected it to and need the request/response to further investigate.
+The predator-runner will log this data to the log files which can be downloaded.
+
+For the test to run in `debug` mode:
+
+##### 1. UI
+-  Turn on the <b>Debug</b> flag when running a test
 
-For viewing all the requests and responses (Very useful when your test not behaves like you expected)
-It's possible to run tests with the Debug flag (can be send via jobs api or toggled in the run test form)
-The predator-runner will log this data to the log files which can be downloaded and investigated.
+##### 2. API
+- Add `"debug": "*"` to the body of the `POST /jobs` request
diff --git a/docs/devguide/mkdocs.yml b/docs/devguide/mkdocs.yml
@@ -13,6 +13,7 @@ nav:
   - Advanced Test Setup: tests.md
   - Schedules and Reports: schedulesandreports.md
   - Configuration: configuration.md
+  - FAQ: faq.md
   - Contributing: contributing.md
   - API Reference: apireference.md