Nap is a FAST, file-based framework for creating and running integration tests over HTTP.

Installation Options

Using go get

$ go install[email protected]

Building the Source

$ git clone
$ cd nap
$ go install

Getting Started

Follow these steps to get to work.

Starting a New Project

To create a new project, run the new command:

$ nap new my-project
Created a new project called my-project. Run cd my-project to get started.


A request represents a single HTTP request. To generate a request, use the generate command:

$ nap generate request my-request.yml

By default, this creates a YAML file inside the requests folder like the following:

name: my-request
verb: GET
    - Accept: application/json

Note: to customize the default request template, edit request.yml found inside the .templates folder.

Running Requests

To run a specific request, use the run command as follows:

$ nap run request my-request
- my-request.yml: 200 OK


A routine is a file containing instructions for running one or more requests, scripts or assertions in a specific order. To generate a routine, use the generate command:

$ nap generate routine my-routine

By default, this creates a YAML file inside the routines folder like the following:

name: my-routine
    - type: request 
      name: my-request
      expectStatusCode: 200

Note: to customize the default routine template, edit routine.yml found inside the .templates folder.


An expectation defines an attribute to be tested after the request is executed. Nap supports several ways to help determine whether a request meets expectations or not:

Status Code Expectation

expectStatusCode: 2XX

The status code expectation will test against the expected status code. An X will match any digit in the response. For example, to match against all successful response codes, the expectation would be 2XX.

Headers Expectation

  - Content-Type: application/json
  - X-CUSTOM-HEADER: custom-value

The headers expectation tests to ensure the provided headers exist with the expected values. It isn’t a strict comparison against all headers.

Response Content Expectation

expectResponseContent: |

The response content expectation performs a strict match against the string-encoded content of the response.

JSON Expectation

  status: success

The JSON expectation will test specific parts of a JSON-encoded response object. The above example would match against an object literal such as:

    "status": "success",
    "result": [
            "name": "example"


To work with multiple routines, use the subroutine pattern:

    - type: routine
      name: my-routine
    - type: routine
      name: my-other-routine

Subroutines are the fastest way to run many requests. Each subroutine will run within its own goroutine. This allows designing each subroutine as an end-to-end integration test that can run in parallel to other tests.

Running Routines

To run a routine, use the run command as follows:

$ nap run routine my-routine
- my-request.yml: 200 OK

Environment Variables

The env folder contains a default YAML configuration file: default.yml. By default, this file is empty. Values added to the default configuratoin may be substituted within requests or routines. Here is an example of our first request with the base URL stored as a variable:


name: my-request
path: ${baseurl}/facts
verb: GET
type: request
body: ""
    - Accept: application/json



You may create new configurations either by adding a .yml file manually to the env folder or via the generate command:

$ nap generate env my-env

To run a request with a particular environment, use the run command with the --env or -e flag:

$ nap run request my-request -e my-env
- my-request.yml: 200 OK


View Github