Creating a Test Run¶

Necessary data

To create a test run via API methods, you need a token.

To create a test run via the web interface, you need a Wallarm account.

You can get detailed information about token here.

The token_Qwe12345 value is used as an example token in this document.

When a test run is being created, a new test record is created as well.

This way of test run creation is to be used if it is required to test a target application along with recording of baseline requests.

Creating a Test Run via API¶

To create a test run, send the POST request to the URL https://us1.api.wallarm.com/v1/test_run:

API call:	`POST /v1/test_run`
Authorization:	Required	With the token
HTTP header with the token:	`X-WallarmAPI-Token`	Serves to pass the token’s value to the API server
Parameters:	`name` (required)	Name of the test run
	`test_record_name`	The test record name. All baseline requests will be placed in this test record. Default value: the test run's name.
	`desc`	Detailed description of the test run. Default value: empty string
	`file_extensions_to_exclude`	This parameter allows specifying certain file types that need to be excluded from the evaluation process during testing. These file types are specified by the regular expression. For example, if you set the `ico` file extension to be excluded, then the `GET /favicon.ico` baseline request will not be checked by FAST and will be skipped. The regular expression has the following format: - `.`: any number (zero or more) of any character - `x*`: any number (zero or more) of the `x` character - `x?`: the single `x` character (or none) - any single file extension (e.g., `jpg`) - several extensions delimited by the vertical bar (e.g., `jpg` \| `png`) Default value: empty string (FAST will check baseline requests with any file extension).
	`policy_id`	The identifier of the test policy. If the parameter is missing, then the default policy takes action
	`stop_on_first_fail`	The parameter specifies FAST’s behavior when a vulnerability has been detected: `true`: stop the execution of the test run on the first detected vulnerability. `false`: process all the baseline requests no matter if any vulnerability is detected or not. Default value: `false`
	`skip_duplicated_baselines`	The parameter specifies FAST’s behavior when a duplicated baseline request has been encountered: `true`: skip duplicated baseline requests (if there are a few identical baseline requests, then the test requests are generated for the first baseline request only). `false`: the test requests are generated for each incoming baseline request. Default value: `true`
	`rps_per_baseline`	The parameter specifies a limit on the number of test requests (RPS, requests per second) to be sent to the target application (e.g. there might be 100 test requests derived from a single baseline request). The limit is set per baseline request (no more than `N` test requests per second will be sent for an individual baseline request) in the test run. Minimum value: `1`. Maximum value: `500`. Default value: `null` (RPS is unlimited)
	`rps`	The parameter is similar to the one described above, except that it limits the RPS globally, per test run, not just a single baseline request. In other words, the whole number of test requests per second should not exceed the specified value no matter how many baseline requests were recorded during the test run. Minimum value: `1`. Maximum value: `1000`. Default value: `null` (RPS is unlimited)
	`inactivity_timeout`	The parameter specifies the time interval in seconds during which the FAST node waits for a new baseline request to arrive. This behavior is described here in detail. The timeout has no influence on the processes of creation and execution of security tests for baseline requests that has been recorded. Minimum value: `300` (300 seconds or 5 minutes). Maximum value: `86400` (86400 seconds or 1 day). Default value: `1800` (1800 seconds or 30 minutes)

Example of a request:

curl --request POST \
  --url https://us1.api.wallarm.com/v1/test_run \
  --header 'Content-Type: application/json' \
  --header 'Host: us1.api.wallarm.com' \
  --header 'X-WallarmAPI-Token: token_Qwe12345' \
  --data '{
    "name":"demo-testrun"
}'

Example of a response:

{
  "status": 200,
  "body": {
    "id": tr_1234,
    "name": "demo-testrun",
    ...
    "state": "running",
    ...
}

If the request to the API server is successful, you are presented with the server’s response. The response provides useful information, including:

id: the identifier of a newly created test run (e.g., tr_1234).

You will need the id parameter value to perform the following actions, required to integrate FAST into CI/CD:
1. Checking for the FAST node to start the recording process.
2. Stopping the baseline requests recording process.
3. Waiting for the FAST security tests to finish.
state: the state of the test run.

A newly created test run is in the running state.
A comprehensive description of all the values of the state parameter can be found here.
test_record_id: the identifier of a newly created test record (e.g., rec_0001). All baseline requests will be placed into this test record.

Creating a Test Run via Web Interface¶

To create a test run via your Wallarm account interface, follow the steps below:

Go to your Wallarm account > Test runs by this link for the EU cloud or by this link for the US cloud.
Click the Create test run button.
Enter the name of your test run.
Select the test policy from the Test policy drop-down list. To create a new test policy, please follow this instructions. Also, you can use the default policy.
Select FAST node from the Node drop-down list. To create FAST node, please follow this instruction.
Add Advanced settings if required. This block of settings includes the following points:
- The “Stop on first fail” checkbox defines whether the test run should be stopped after the first vulnerability was found.
- The “Skip duplicated baselines” checkbox defines whether the duplicates of the baseline requests received earlier should be ignored. If the FAST node receives the same baseline request as the one received in this test run previously, then no test requests are created on its basis, and the FAST node console prints the following message: [info] The baseline #8921 is duplicated and already was processed.
- The “Skip following files extensions” checkbox defines whether certain file types are excluded from the evaluation process during testing. These file types are specified by the regular expression.
  
  For example, if you set the ico file extension to be excluded, then the GET /favicon.ico baseline request will not be checked by FAST and will be skipped.
  
  The regular expression can contain one of the following mutually excluding expressions:
  - .: any number of any character
  - x*: any number of the x character
  - x?: the single x character (or no character x at all)
  - any single file extension (e.g., jpg)
  - several extensions delimited by either “|” or “,” character (e.g., jpg | png or jpg, png)
  If a regular expression is not specified, then FAST will check baseline requests with any file extension.
- The “RPS per test run” slider defines the request per second limit for the test run. This setting can take values from 1 to 1000. The default value is 1000.
- The “RPS per baseline” slider defines the request per second limit for one baseline request. This setting can take values from 1 to 500. The default value is 500.
- The “Stop baseline recording after” slider defines the test run time limit. This setting can take values from 5 min (5 minutes) to 1 day (24 hours). The default value is 30 min (30 minutes).
Click the Create and run button.

Reusing test record¶

When the requests are sent from a requests source to the target application, and the recording process is stopped, it is possible to reuse the test record with other test runs.