Update docs for raft_local (#191)

Fix a small bug in raft_local during init command.

cli/Readme.md

@@ -1,18 +1,6 @@
 # RAFT CLI
-`raft.py` is Rest API Fuzz Testing service CLI that is used for deployment of the service to Azure, job creation, deletion, etc. See full documentation [RAFT CLI reference](../docs/cli-reference.md)
+`raft.py` is Rest API Fuzz Testing service CLI that is used for deployment of the
+service to Azure, job creation, deletion, etc. See full documentation [RAFT CLI reference](../docs/cli-reference.md)
 
-`raft_local.py` is a script that does not require Azure to run RAFT job configurations. This script requires installation of Python and Docker to run RAFT job configurations.
-
-This script only support **job create** command. See `raft_local.py --help` for details.
-`raft_local.py` expects the following folder structure (You can run `raft_local.py local init` to auto-create required directories)
-
-```Text
-CLI //root folder where you downloaded the CLI
-|- raft_local.py // raft_local.py script 
-|- local         // folder named local located at the same level as raft_local.py
-      |- secrets // folder named secrets located inside of local folder
-      |- storage // folder names storage located inside of local folder
-```
-
-`storage` folder will contain all of the data produced by RAFT job runs. 
-`secrets` folder is a user maintained folder. It uses files without an extension to store data needed for authentication with services under test. For example if my RAFT job configuration requires a text token. I can store the token in file `MyToken` under `CLI/local/secrets/MyToken` and use `MyToken` string name in RAFT job configuration as `TxtToken` authentication method.
+`raft_local.py` is a script that does not require Azure to run RAFT job configurations. 
+See documentation on how to use [RAFT on your development machine](../docs/how-to-use-raft-local.md)

cli/raft_local.py

@@ -75,6 +75,9 @@ def init_tools(tools_path):
     return tools, tool_paths
 
 def init_local(work_directory):
+    if not os.path.exists(work_directory):
+        os.mkdir(work_directory)
+
     secrets_path = os.path.join(work_directory, 'secrets')
     if not os.path.exists(secrets_path):
         os.mkdir(secrets_path)
@@ -574,9 +577,10 @@ def run(args):
 
     work_dir = os.path.join(script_dir, 'local')
     if local_action == 'init':
-        storage, secrets = init_local(work_dir)
+        storage, secrets, event_sink = init_local(work_dir)
         print(f'Created results storage folder: {storage}')
         print(f'Created secrets folder: {secrets}')
+        print(f'Created events_sink folder: {event_sink}')
 
     if job_action == 'create':
         cli = RaftLocalCLI(work_dir)

docs/how-to-use-raft-local.md

@@ -0,0 +1,95 @@
+# How to run RAFT on your local machine
+
+There are times where you might want to test your service on your development machine before
+committing the changes to run in a CI/CD pipeline with your Azure deployment of RAFT. The
+`raft_local.py` script is your way to do that. 
+
+Because RAFT uses containers for the testing tools, this script will pull down the tools needed
+and run them using docker on your local machine. 
+
+### Requirements
+
+This script has been tested with these versions of these tools.
+* Python (3.8) 
+* Docker (20.10)
+
+### Limitations
+
+This script only supports the **job create** command. See `raft_local.py --help` for details.
+
+### Getting Started
+
+Run `raft_local.py local init` to auto-create required directories.
+
+These are the directories that will be created and are expected by the script.
+```Text
+CLI //root folder where you downloaded the CLI
+|- raft_local.py // raft_local.py script 
+|- local         // folder named local located at the same level as raft_local.py
+      |- secrets     // folder named secrets located inside of local folder
+      |- storage     // folder names storage located inside of local folder
+      |- events_sink // folder used to synchronize test tool events
+```
+
+
+* The `storage` folder will contain all of the data produced by RAFT job runs. 
+* The `secrets` folder is a user maintained folder. </br>
+  The files in this folder are the names of the secret used in the job definition file.
+  These files should not have an extension.
+
+  For example if my RAFT job configuration requires a text token. 
+  I can store the token in file `MyToken` under `CLI/local/secrets/MyToken` and use `MyToken` 
+  as the secret name in RAFT job configuration. 
+
+  ```
+      "authenticationMethod": {
+        "TxtToken": "MyToken"
+      }
+  ```
+
+### Running raft_local.py
+
+Once you have completed the getting started portion you can use `raft_local.py` to 
+run a job on your local machine.
+
+Here is an example job definition that runs RESTler and ZAP on a
+deployed instance of [PetStore](https://petstore3.swagger.io) that can be launched with
+`raft_local.py`
+
+
+```text
+{
+  "testTasks": {
+    "targetConfiguration": {
+      "apiSpecifications": [ "https://petstore3.swagger.io/api/v3/openapi.json" ],
+      "endpoint": "https://petstore3.swagger.io"
+    },
+    "tasks": [
+      {
+        "toolName": "RESTler",
+        "outputFolder": "restler-logs",
+        "toolConfiguration": {
+          "tasks": [
+            {
+              "task": "compile"
+            },
+            {
+              "task": "Fuzz",
+              "runConfiguration": {
+                "Duration": "00:10:00"
+              }
+            }
+          ]
+        }
+      },
+      {
+        "toolName": "ZAP",
+        "outputFolder": "zap-logs"
+      }
+    ]
+  }
+}
+```
+
+Example command line to create a local job:</br>
+`python raft_local.py job create --file <jobdefinitionfile>`

docs/samples.md

@@ -11,3 +11,12 @@ The samples are located in the **cli/samples** folder under the root of
 the RAFT repo, and are organized into three folders:  **Zap**, **RESTler**, **Dredd**,
 and **multiple-tools**, the latter of which shows how to execute more than
 one tool in a single job. Each sample folder includes it's own `readme.md` file explaining what the sample is about and how to run it.
+
+**IMPORTANT NOTE:**</br>
+The sample python scripts have been written to take advantage of your Azure deployment of RAFT.
+In most sample directories there is a python script that runs the sample and is an example of how to use
+our python SDK to run jobs. In many of the sample job definition files there are substitutions that are 
+made via the python script. 
+
+Because of this, the files typically will not run without modification with the `raft_local.py` script.
+See [here](how-to-use-raft-local.md) for more information about running RAFT on your desktop with `raft_local.py`.