Writing Your First Test As JSON

Setup and Writing the Actions.json File

Hedra offers a multitude of configuration options, but local setup and running is relatively simple, involving only a few configuration files. Begin by creating a fresh folder in your projects directory:

mkdir <PATH_TO_YOUR_PROJECTS_FOLDER>/performance-testing

Change to this directory and then create the following, empty files:

cd <PATH_TO_YOUR_PROJECTS_FOLDER>/performance-testing \
&& touch actions.json \
&& touch config.json \
&& ulimit -n 250000

The actions.json file we just created will contain all the HTTP request data the performance testing framework will consume, while the reporter.json file will specify how (or more so where) we want our testing results processed and stored.

Let’s configure the actions.json file. Simply copy and paste the below to your actions.json file, and then continue reading for explanation:

{
    "https://httpbin.org": [
        {
          "endpoint": "/get",
          "method": "GET",
          "name": "dev_httpbin_get",
          "weight": 1
        }
    ]
  }

For a simple actions.json file like above, The outermost keys specify the hosts the framework will make request against, while the array of objects paired to that key contains the specific endpoints the framework will target. Each endpoint object contains all the data required to make a valid request, including:

• method

• headers

• auth

• data

• params

as well as a required unique name field where you must specify a unique (string) name. This name will be used to group requests results to that endpoint for results calculation, so it’s important to choose a clear name for then endpoint object. A required weight field must also be specified (for this example), which the framework uses to determine and adjust the distribution/chance of executing any given request against any of the specified endpoints.

---

Setting Up Reporting

Now we can likewise configure our reporting facilities via the config.json file. Copy and paste the below to your config.json file and then continue reading for explanation:

{
    "reporter_config": {
        "reporter_type": "statstream",
        "reporter_config": {
            "save_to_file": true
        }
    }
}

The config.json file can contain execution config, distributed config, and reporting config. Above, we specify we wish to use the StatStream Reporter and save our results to JSON file.

---

Running the Test

Finally, we are set to run our performance testing framework. Examine the command below:

hedra --actions-filepath actions.json \
 --total-time 00:01:00 \
  --batch-size 5000 \
  --batch-time 3 \
      --embedded-stats

The following arguments are specified:

• --actions-filepath (required) - The filepath to the actions.json file.

• --total-time - The total time for the test. This can be specified as either a string (HH:MM:SS) or integer number of seconds.

• --batch-size - Hedra “batches” actions, inserting a (by default) one second pause in between batches. This is helpful in preventing the framework from completely overwhelming a target with traffic, and allows you to stagger requests in a more realistic fashion.

• --batch-time - The maximum amount of time Hedra will wait for any single batch of actions to complete.

• --embedded-stats - Tells Hedra to run an embedded statserve server in an independent thread prior to initializing, particularly handy for local tests.

Copy and run this command, and watch as Hedra executs your first test! Initialy, you’ll see the following:

When Hedra begins, it’ll first start then specified embedded Statserve instance. After a few moments, Hedra will run the Setup stage, parsing our specified actions and configuring test execution. Hedra will then begin test execution:

As Hedra executes tests, it will display the time elapsed:

Once testing has completed, Hedra will begin calculating results:

Once calculated, Hedra will output that it has finished execution.

Open the folder you ran Hedra in, you should now see a new results.json. Open this file to examine your results.

---

Simplifying Execution via the Config.json File

To simplify execution, Hedra can consume most all CLI arguments as key/value pairs within the config.json file (--embedded-stats is one exception). Open the config.json file from earlier and add the following:

{
    "executor_config": {
        "total_time": "00:01:00",
        "batch_size": 5000,
        "batch_time": 3
    },
    "reporter_config": {
        "reporter_type": "datadog",
        "reporter_config": {
            "datadog_app_key": "<datadog_app_key>",
            "datadog_api_key": "<datadog_api_key>"
        }
    }
}

Note that we have updated our config to use the Datadog Reporter, passing the app key and api key as required. Now run:

hedra --actions-filepath actions.json \
 --config-filepath config.json \
      --embedded-stats

The framework executes exactly as before! However, we can simplify this further. The --config-filepath argument, telling Hedra where to look for the config.json is entirely optional so long as the config.json file occupies the same directory hedra is run in. run the command below:

hedra --actions-filepath actions.json --embedded-stats

Again, the framework completes the run exactly as if we had specified the original CLI arguments!