Document updated on Dec 11, 2021

Automated End-to-End (E2E) tests

In addition to checking the syntax of your KrakenD configuration and ensuring that the gateway can start, you can run integration tests to guarantee that all the active software components from beginning to end have the expected flow and that the gateway returns what you planned.

The krakend e2e command launches the integration tests.

Creating e2e test files

In essence, all you need to do is create a specs folder and place the test files inside. Then, KrakenD will run all the tests declared in the folder and exit with the proper status code. All tests must be deterministic and reproducible.

The default directory structure for specs is:

/etc/krakend
├── krakend.json
└── specs
    ├── test-foo.json
    ├── test-bar.json
    └── some-other-test.json

Each test file is a very simple .json file, it doesn’t need to have a specific name. It contains an in (the request you want to do to KrakenD) and an out (what you expect as the response). In addition, the following attributes are recognized in each test spec:

• in: The parameters used to build the request to a running KrakenD with your configuration
  • method: The request method
  • url: The full URL to the endpoint you want to test
  • header: An optional map of header to include in the request
• out: The expected response from the gateway
  • status_code (integer): The expected status code
  • body: The expected returned body by the response as a string, or as JSON object.
  • header: Any header included in the response. When the value is empty, you don’t expect that header.

For instance, save your first test under specs/test1.json and run it with any krakend configuration:

{
	"@comment": "Makes sure that the debug endpoint returns a status ok",
    "in": {
        "method": "GET",
        "url": "http://localhost:8080/__debug/something",
        "header": {
            "User-Agent": "krakend e2e tool"
        }
    },
    "out": {
        "status_code": 200,
        "body": {
          "status": "ok"
        },
        "header": {
            "content-type": ["application/json; charset=utf-8"],
            "Cache-Control": [""],
            "X-Krakend-Completed": ["true"]
        }
    }
}

In the example above, the response must contain the content-type and X-Krakend-Completed with the specified values, and the Cache-Control header cannot be present.

Running the e2e tests

The e2e command can run without additional flags if you use the default naming, but has several run options. It looks like this:

$krakend e2e -h

╓▄█                          ▄▄▌                               ╓██████▄µ
▐███  ▄███╨▐███▄██H╗██████▄  ║██▌ ,▄███╨ ▄██████▄  ▓██▌█████▄  ███▀╙╙▀▀███╕
▐███▄███▀  ▐█████▀"╙▀▀"╙▀███ ║███▄███┘  ███▀""▀███ ████▀╙▀███H ███     ╙███
▐██████▌   ▐███⌐  ,▄████████M║██████▄  ║██████████M███▌   ███H ███     ,███
▐███╨▀███µ ▐███   ███▌  ,███M║███╙▀███  ███▄```▄▄` ███▌   ███H ███,,,╓▄███▀
▐███  ╙███▄▐███   ╙█████████M║██▌  ╙███▄`▀███████╨ ███▌   ███H █████████▀
                     ``                     `'`

Version: v2.0

Executes an end to end test for the gateway based on the configuration file and a set of specs.

Usage:
  krakend e2e [flags]

Examples:
krakend e2e -c config.json -s specs

Flags:
  -c, --config string    Path to the krakend configuration file. (default "./krakend.json")
  -d, --delay duration   The delay for the delayed backend endpoint. (default 200ms)
  -e, --envar string     Comma separated list of patterns to use to filter the envars to pass (set to ".*" to pass everything).
  -h, --help             help for e2e
  -r, --no-redirect      Disable redirects at the http client.
  -p, --port int         The port for the mocked backend api. (default 8081)
  -s, --specs string     Path to the specs folder. (default "./specs")

When you run the tests, KrakenD will tell you the failing ones with a [KO] and the working ones with an [OK]. For instance:

$krakend e2e
[OK] test1
1 test(s) completed
Total time: 1.102928274s