spec.helpers

Collection of utilities to help testing Kong features and plugins.

Info:

http_client

admin_client () returns a pre-configured http_client for the Kong admin port.
http_client (host, port, timeout) Creates a http client.
http_client:send (opts) Send a http request.
proxy_client () returns a pre-configured http_client for the Kong proxy port.
proxy_ssl_client () returns a pre-configured http_client for the Kong SSL proxy port.

TCP/UDP server helpers

http_server (port) Starts a HTTP server.
tcp_server (port) Starts a TCP server.
udp_server (port) Starts a UDP server.

Custom assertions

contains (expected, array, pattern) Assertion to check whether a value lives in an array.
fail (...) Generic fail assertion.
formparam (name) Adds an assertion to look for a urlencoded form parameter in a mockbin request.
header (name) Adds an assertion to look for a named header in a headers subtable.
jsonbody () Checks and returns a json body of an http response/request.
queryparam (name) An assertion to look for a query parameter in a queryString subtable.
request (response) Generic modifier "request".
response (response) Generic modifier "response".
status (expected, response) Assertion to check the statuscode of a http response.

Shell helpers

clean_prefix (prefix) Cleans the Kong environment.
execute (...) Execute a command.
kong_exec (cmd, env) Execute a Kong command.
prepare_prefix (prefix) Prepare the Kong environment.
wait_for_invalidation (key, timeout) Waits for invalidation of a cached key by polling the mgt-api and waiting for a 404 response.

http_client

An http-client class to perform requests.

admin_client

returns a pre-configured http_client for the Kong admin port.

http_client

Creates a http client. Based on https://github.com/pintsized/lua-resty-http
Parameters:
  • host hostname to connect to
  • port port to connect to
  • timeout in seconds
Returns:
  • http client
See also:

http_client:send

Send a http request. Based on https://github.com/pintsized/lua-resty-http. If opts.body is a table and "Content-Type" header contains application/json, www-form-urlencoded, or multipart/form-data, then it will automatically encode the body according to the content type. If opts.query is a table, a query string will be constructed from it and appended to the request path (assuming none is already present).
Parameters:
  • opts table with options. See https://github.com/pintsized/lua-resty-http

proxy_client

returns a pre-configured http_client for the Kong proxy port.

proxy_ssl_client

returns a pre-configured http_client for the Kong SSL proxy port.

TCP/UDP server helpers


http_server

Starts a HTTP server. Accepts a single connection and then closes. Sends a 200 ok, 'Connection: close' response. If the request received has path /delay then the response will be delayed by 2 seconds.
Parameters:
  • port ` The port where the server will be listening to
Returns:
  • thread A thread object

tcp_server

Starts a TCP server. Accepts a single connection and then closes, echoing what was received (single read).
Parameters:
  • port ` The port where the server will be listening to
Returns:
  • thread A thread object

udp_server

Starts a UDP server. Accepts a single connection, reading once and then closes
Parameters:
  • port ` The port where the server will be listening to
Returns:
  • thread A thread object

Custom assertions


contains

Assertion to check whether a value lives in an array. pattern
Parameters:
  • expected The value to search for
  • array The array to search for the value
  • pattern (optional) If thruthy, then expected is matched as a string
Returns:
  • the index at which the value was found
Usage:
  • local arr = { "one", "three" }
    local i = assert.contains("one", arr)        --> passes; i == 1
    local i = assert.contains("two", arr)        --> fails
    local i = assert.contains("ee$", arr, true)  --> passes; i == 2

fail

Generic fail assertion. A convenience function for debugging tests, always fails. It will output the values it was called with as a table, with an n field to indicate the number of arguments received.
Parameters:
  • ... any set of parameters to be displayed with the failure
Usage:
  • assert.fail(some, value)

formparam

Adds an assertion to look for a urlencoded form parameter in a mockbin request. Parameter name comparison is done case-insensitive. Use the request modifier to set the request to operate on.
Parameters:
  • name name of the form parameter to look up (case insensitive)
Returns:
  • value of the parameter

header

Adds an assertion to look for a named header in a headers subtable. Header name comparison is done case-insensitive.
Parameters:
  • name header name to look for (case insensitive).
Returns:
  • value of the header
See also:

jsonbody

Checks and returns a json body of an http response/request. Only checks validity of the json, does not check appropriate headers. Setting the target to check can be done through request or response (requests are only supported with mockbin.com).
Returns:
  • the decoded json as a table
Usage:
  • local res = assert(client:send { .. your request params here .. })
    local json_table = assert.response(res).has.jsonbody()

queryparam

An assertion to look for a query parameter in a queryString subtable. Parameter name comparison is done case-insensitive.
Parameters:
  • name name of the query parameter to look up (case insensitive)
Returns:
  • value of the parameter

request

Generic modifier "request". Will set a "request" value in the assertion state, so following assertions will operate on the value set. The request must be inside a 'response' from mockbin.org or httpbin.org be extracted from the response.
Parameters:
Usage:
  • local res = assert(client:send { .. your request parameters here ..})
    local length = assert.request(res).has.header("Content-Length")

response

Generic modifier "response". Will set a "response" value in the assertion state, so following assertions will operate on the value set.
Parameters:
Usage:
  • local res = assert(client:send { .. your request parameters here ..})
    local length = assert.response(res).has.header("Content-Length")

status

Assertion to check the statuscode of a http response. alternatively use response.
Parameters:
  • expected the expected status code
  • response (optional) results from http_client:send function,
Returns:
  • the response body as a string
Usage:
  • local res = assert(client:send { .. your request params here .. })
    local body = assert.has.status(200, res)             -- or alternatively
    local body = assert.response(res).has.status(200)    -- does the same

Shell helpers


clean_prefix

Cleans the Kong environment. Deletes the working directory if it exists. configuration will be used
Parameters:
  • prefix (optional) path to the working directory, if omitted the test

execute

Execute a command. Modified version of pl.utils.executeex() so the output can directly be used on an assertion.
Parameters:
  • ... see penlight documentation
Returns:
  • ok, stderr, stdout; stdout is only included when the result was ok

kong_exec

Execute a Kong command. variables, overriding the test config (each key will automatically be prefixed with KONG_ and be converted to uppercase)
Parameters:
  • cmd Kong command to execute, eg. start, stop, etc.
  • env (optional) table with kong parameters to set as environment
Returns:
  • same output as exec

prepare_prefix

Prepare the Kong environment. creates the workdirectory and deletes any existing one. configuration will be used
Parameters:
  • prefix (optional) path to the working directory, if omitted the test

wait_for_invalidation

Waits for invalidation of a cached key by polling the mgt-api and waiting for a 404 response.
Parameters:
  • key the cache-key to check
  • timeout (optional) in seconds, defaults to 10.