KATT (Klarna* API Testing Tool) is an HTTP-based API testing tool for Erlang.
* Albeit the "Klarna" mention, this repository is not affiliated with Klarna AB. KATT was born at Klarna, and Klarna maintains copyright for parts of the code, but it is now being maintained outside the company, by its authors and new contributors.
An example is worth a 1000 words.
Use for shooting HTTP requests in a sequential order and verifying the response. Any relevant difference between expected and actual responses will cause a failure.
The builtin validator supports basic text validation and more advanced validation of HTTP headers and JSON structures.
The validator makes use of a few tags with special meaning:
"{{_}}"
Match anything (i.e. no real validation, only check existence).
"{{unexpected}}"
Match nothing (i.e. no real validation, only check lack of existence)
"{{>key}}"
Store value of the whole string (key must be unique within testcase)
"{{<key}}"
Recall stored value.
The "{{_}}"
tag can also be used as a JSON object's property in order to
validate any other additional properties.
By default, the builtin validator will allow additional properties in an object
structure, or additional items in an array structure. To counteract that
default, one can do {..., "{{_}}": "{{unexpected}}"}
or
[..., "{{unexpected}}"]
, effectively making a rule that no properties/items
are expected beyond the ones defined.
A simple example that will make requests to a third party server:
ERL_LIBS=deps erl -pa ebin -noshell -eval '
application:ensure_all_started(katt),
BlueprintFile = "./doc/example-httpbin.apib",
Params = [{hostname, "httpbin.org"}, {my_name, "Joe"}, {your_name, "Mike"}],
io:format("~p~n", [katt:run(BlueprintFile, Params)]).
' -s init stop
... or run the code passed to -eval from the Erlang shell (assuming that you
have started the Erlang shell from the repo's root directory with ERL_LIBS=deps erl -pa ebin
).
You can also fire up katt
from the CLI, with
katt ./doc/example-httpbin.apib hostname=httpbin.org my_name=Joe your_name=Mike
If you want non-string params, use :=
as a separator e.g. my_int:=123
.
You can also output the result in JSON format, with --json
, and beautify it e.g. with python
katt --json ./doc/example-httpbin.apib hostname=httpbin.org my_name=Joe your_name=Mike | python -m json.tool
katt:run
to be called withfilename
params
(optional)protocol
hostname
port
request_timeout
scenario_timeout
callbacks
(optional)ext
to be called withscope
(recall_body, parse, validate_body, validate_type)recall
to be called withsyntax
,text
,params
,callbacks
parse
to be called withheaders
,body
,params
,callbacks
request
to be called withrequest
,params
,callbacks
validate
to be called withexpected
,actual
,params
,callbacks
progress
to be called withtransaction_result
A request can also be configured via HTTP request headers:
x-katt-description
would take precedence over the transaction's descriptionx-katt-request-timeout
would take precedence over therequest_timeout
paramx-katt-request-sleep
would delay the request for a specific amount of milliseconds
OnlyText = fun(_Scope) -> [] end,
katt:run("text_only_scenario.apib", [], [{ext, OnlyText}]).
XmlJson =
fun(recall_body) ->
[ fun katt_callbacks_json:recall_body/4
, fun custom_callbacks_xml:recall_body/4
];
fun(parse) ->
[ fun katt_callbacks_json:parse/5
, fun custom_callbacks_xml:parse/5
];
fun(validate_body) ->
[ fun katt_callbacks_json:validate_body/3
, fun custom_callbacks_xml:validate_body/3
],
fun(validate_type) ->
[ fun katt_callbacks_json:validate_type/7
, fun custom_callbacks_xml:validate_type/7
],
katt:run("xml_and_json_scenario.apib", [], [{ext, XmlJson}]).
See src/katt_callbacks_json.erl to see how your
custom_callbacks_xml
module should be implemented.
A pull-request is most welcome. Please make sure that the following criteria are fulfilled before making your pull-request:
- Include a description regarding what has been changed and why.
- Make sure that the changed or added functionality (if you modify code) is covered by unit tests.
- Make sure that all unit tests pass.