Diglett  

Command-line tool for automating HTTP requests.

1. Installation
2. Usage
3. Development

Installation

Install from npm

Available soon 🏋️‍♀️

Install from repository

Clone the repository. In the root of the repository, run:

# Install dependencies
$ yarn

# Invoke the CLI
$ ./bin/run --help

# Alternatively, link the executable with `yarn link`:
$ yarn link

# Now `diglett` should be available in your `PATH`
$ diglett --help

Usage

Basic concepts

Working with Diglett involves three concepts: request templates, requests, and request-response pairs.

Request templates are templates for HTTP requests. For example, a request template could specify that a query parameter id needs to be a number.

From request template, diglett can render a request. In the example above, the query parameter would be filled by an actual number, creating a valid HTTP request that can be sent to the target host.

As a final step, diglett can send the HTTP requests and record the corresponding response, creating a request-response pair.

Generating request templates

A RequestsTemplate object looks like this:

defaults: {}
templates:
  - req:
      method: get
      host: petstore.swagger.io
      path: "/v1/pets?limit={{ limit }}"
      pathname: /v1/pets
      protocol: http
      query:
        limit: "{{ limit }}"
    parameters:
      limit:
        required: false
        schema:
          type: integer
          format: int32

For a full example of a templates file, see templates/petstore-templates.yaml.

defaults field specifies defaults that should be used in all requests. templates contains the actual request templates. A request template contains the req and parameters fields. In req object, a parameter is identified by the {{ parameter_name }} syntax. These signal that the values are filled in the rendering phase.

parameters is a dictionary with parameters as keys and JSON schema objects as values. From the JSON schema, values are generated in the rendering phase (see below) using json-schema-faker. Templates are rendered (i.e., parameters filled) using nunjucks.

You can either create templates by hand or from OpenAPI schema.

From OpenAPI

If you have an OpenAPI schema of an API, you can create "request templates" from the schema with generate:templates command.

$ DEBUG=* diglett generate:templates openapi/petstore.yaml

This will create a YAML file containing templates from which requests can be built. See an example in petstore-templates.yaml built from petstore.yaml.

Rendering requests

Once you have created a file containing request templates, you can generate actual requests from them using the render command.

$ DEBUG=* diglett render templates/petstore-templates.yaml

As explained above, requests are rendered using nunjucks and json-schema-faker.

render command outputs requests in JSONL format, where every line is an ISerializedRequest object defined in types.ts. For an example file containing requests, see the example in petstore-requests.jsonl.

Removing duplicates

Skip duplicate requests by adding the -d flag:

diglett render templates/petstore-templates.yaml -d

Rendering multiple requests per template

Render nItems requests per template by adding the -n {N_ITEMS} flag:

diglett render templates/petstore-templates.yaml -n 5  # Create five requests per every template

Sending requests

To send all the rendered HTTP requests from a file, use the send command. Before performing the requests, you should perform a "dry-run" showing what will be done instead of sending any HTTP requests:

# Dry-run by default
$ DEBUG=diglett* diglett send requests/petstore-requests.jsonl

The command outputs request-response pairs to stdout in JSONL format.

If everything looks good, send the requests by adding the -f flag:

# Add "-f" flag to send requests
diglett send requests/petstore-requests.jsonl -f

diglett will send all the requests from the file using RequestQueue with a 500 ms delay between requests.

Adding headers

One can define headers used for all requests with the -H flag:

# Add "-f" flag to send requests
diglett send requests/petstore-requests.jsonl -H 'Authorization: Basic XXX'

This is useful for APIs requiring, for example, authentication.

Development

Install dependencies:

$ yarn

Compile TypeScript:

$ yarn compile

Run tests:

$ yarn test

Execute CLI:

./bin/run --help

Link the executable so it's available as diglett:

yarn link
diglett --help  # Local version