Skip to content
This repository was archived by the owner on Feb 2, 2022. It is now read-only.

Commit 4b8a2bb

Browse files
mgreisenmgreisen
authored
Update docs for raft_local (#191)
Fix a small bug in raft_local during init command.
1 parent 0cddd40 commit 4b8a2bb

File tree

5 files changed

+114
-18
lines changed

5 files changed

+114
-18
lines changed

‎cli/Readme.md‎

Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,6 @@
11
# RAFT CLI
2-
`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)
2+
`raft.py` is Rest API Fuzz Testing service CLI that is used for deployment of the
3+
service to Azure, job creation, deletion, etc. See full documentation [RAFT CLI reference](../docs/cli-reference.md)
34

4-
`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.
5-
6-
This script only support **job create** command. See `raft_local.py --help` for details.
7-
`raft_local.py` expects the following folder structure (You can run `raft_local.py local init` to auto-create required directories)
8-
9-
```Text
10-
CLI //root folder where you downloaded the CLI
11-
|- raft_local.py // raft_local.py script
12-
|- local // folder named local located at the same level as raft_local.py
13-
|- secrets // folder named secrets located inside of local folder
14-
|- storage // folder names storage located inside of local folder
15-
```
16-
17-
`storage` folder will contain all of the data produced by RAFT job runs.
18-
`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.
5+
`raft_local.py` is a script that does not require Azure to run RAFT job configurations.
6+
See documentation on how to use [RAFT on your development machine](../docs/how-to-use-raft-local.md)

‎cli/raft_local.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,9 @@ def init_tools(tools_path):
7575
return tools, tool_paths
7676

7777
def init_local(work_directory):
78+
if not os.path.exists(work_directory):
79+
os.mkdir(work_directory)
80+
7881
secrets_path = os.path.join(work_directory, 'secrets')
7982
if not os.path.exists(secrets_path):
8083
os.mkdir(secrets_path)
@@ -574,9 +577,10 @@ def ArgumentRequired(name):
574577

575578
work_dir = os.path.join(script_dir, 'local')
576579
if local_action == 'init':
577-
storage, secrets = init_local(work_dir)
580+
storage, secrets, event_sink = init_local(work_dir)
578581
print(f'Created results storage folder: {storage}')
579582
print(f'Created secrets folder: {secrets}')
583+
print(f'Created events_sink folder: {event_sink}')
580584

581585
if job_action == 'create':
582586
cli = RaftLocalCLI(work_dir)

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

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# How to run RAFT on your local machine
2+
3+
There are times where you might want to test your service on your development machine before
4+
committing the changes to run in a CI/CD pipeline with your Azure deployment of RAFT. The
5+
`raft_local.py` script is your way to do that.
6+
7+
Because RAFT uses containers for the testing tools, this script will pull down the tools needed
8+
and run them using docker on your local machine.
9+
10+
### Requirements
11+
12+
This script has been tested with these versions of these tools.
13+
* Python (3.8)
14+
* Docker (20.10)
15+
16+
### Limitations
17+
18+
This script only supports the **job create** command. See `raft_local.py --help` for details.
19+
20+
### Getting Started
21+
22+
Run `raft_local.py local init` to auto-create required directories.
23+
24+
These are the directories that will be created and are expected by the script.
25+
```Text
26+
CLI //root folder where you downloaded the CLI
27+
|- raft_local.py // raft_local.py script
28+
|- local // folder named local located at the same level as raft_local.py
29+
|- secrets // folder named secrets located inside of local folder
30+
|- storage // folder names storage located inside of local folder
31+
|- events_sink // folder used to synchronize test tool events
32+
```
33+
34+
35+
* The `storage` folder will contain all of the data produced by RAFT job runs.
36+
* The `secrets` folder is a user maintained folder. </br>
37+
The files in this folder are the names of the secret used in the job definition file.
38+
These files should not have an extension.
39+
40+
For example if my RAFT job configuration requires a text token.
41+
I can store the token in file `MyToken` under `CLI/local/secrets/MyToken` and use `MyToken`
42+
as the secret name in RAFT job configuration.
43+
44+
```
45+
"authenticationMethod": {
46+
"TxtToken": "MyToken"
47+
}
48+
```
49+
50+
### Running raft_local.py
51+
52+
Once you have completed the getting started portion you can use `raft_local.py` to
53+
run a job on your local machine.
54+
55+
Here is an example job definition that runs RESTler and ZAP on a
56+
deployed instance of [PetStore](https://petstore3.swagger.io) that can be launched with
57+
`raft_local.py`
58+
59+
60+
```text
61+
{
62+
"testTasks": {
63+
"targetConfiguration": {
64+
"apiSpecifications": [ "https://petstore3.swagger.io/api/v3/openapi.json" ],
65+
"endpoint": "https://petstore3.swagger.io"
66+
},
67+
"tasks": [
68+
{
69+
"toolName": "RESTler",
70+
"outputFolder": "restler-logs",
71+
"toolConfiguration": {
72+
"tasks": [
73+
{
74+
"task": "compile"
75+
},
76+
{
77+
"task": "Fuzz",
78+
"runConfiguration": {
79+
"Duration": "00:10:00"
80+
}
81+
}
82+
]
83+
}
84+
},
85+
{
86+
"toolName": "ZAP",
87+
"outputFolder": "zap-logs"
88+
}
89+
]
90+
}
91+
}
92+
```
93+
94+
Example command line to create a local job:</br>
95+
`python raft_local.py job create --file <jobdefinitionfile>`

‎docs/samples.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,13 @@ you might want to [onboard](how-to-onboard-a-tool.md).
1010
The samples are located in the **cli/samples** folder under the root of
1111
the RAFT repo, and are organized into three folders: **Zap**, **RESTler**, **Dredd**,
1212
and **multiple-tools**, the latter of which shows how to execute more than
13-
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.
13+
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.
14+
15+
**IMPORTANT NOTE:**</br>
16+
The sample python scripts have been written to take advantage of your Azure deployment of RAFT.
17+
In most sample directories there is a python script that runs the sample and is an example of how to use
18+
our python SDK to run jobs. In many of the sample job definition files there are substitutions that are
19+
made via the python script.
20+
21+
Because of this, the files typically will not run without modification with the `raft_local.py` script.
22+
See [here](how-to-use-raft-local.md) for more information about running RAFT on your desktop with `raft_local.py`.

‎docs/index.md‎ renamed to ‎docs/start-here.md‎

File renamed without changes.

0 commit comments

Comments
 (0)