7006 / efrisby

A REST API testing framework for erlang

efrisby

A REST API testing framework for erlang inspired by frisby-js

Installation

By adding the following dependency to your rebar.config file :

%% Rebar3 test profiles
{profiles, [
    {test, [
        {deps, [
            {efrisby, {git, "[email protected]:7006/efrisby.git", {tag, "0.5.1"}}}
        ]}
    ]}
]}.

Basic Usage.

You have to start all efrisby dependencies before using any of the functions

To start in the console run:

$ rebar3 shell

And run the following command to start all of the application it depends on:

   > application:ensure_all_started(efrisby).
%% > ok,[idna,mimerl,certifi,hackney,efrisby]}

   > efrisby:get("http://localhost/api/1.0/users/3.json", [
        {status, 200},
        {content_type, "application/json"},
        {json_types, [
            {<<"id">>, integer},
            {<<"is_admin">>, boolean},
            {<<"username">>, bitstring}
        ]},
        {json, [
            {<<"id">>, 3},
            {<<"is_admin">>, false},
            {<<"username">>, <<"johndoe">>}
        ]}
    ]).
%% > {ok, Response}

Write Tests

efrisby tests start with one by calling one of get, post, put, options, delete, or head to generate an HTTP request and assert the response.

efrisby has many built-in test assertions like :

• status to easily test HTTP status codes
• content_type to test content type header
• headers to test expected HTTP headers
• json to test expected JSON keys/values
• json_types to test JSON value types

eq :

{ok, Response} = efrisby:get("https://api.github.com/users/FabioBatSilva", [
    {status, 200},
    {content_type, "application/json; charset=utf-8"},
    {json_types, [
        {<<"id">>, integer},
        {<<"url">>, bitstring},
        {<<"login">>, bitstring}
    ]},
    {json, [
        {<<"id">>, 588172},
        {<<"login">>, <<"FabioBatSilva">>},
        {<<"url">>, <<"https://api.github.com/users/FabioBatSilva">>}
    ]}
]).

> efrisby_resp:json(Response).
[
    {<<"id">>, 588172},
    {<<"login">>, <<"FabioBatSilva">>},
    {<<"url">>, <<"https://api.github.com/users/FabioBatSilva">>}
]

Expectations

Expectation are used to generate assertions on the response. These helpers make testing API response bodies and headers easy with minimal time and effort.

{status, integer()}

Assert that HTTP Status code equals expectation.

efrisby:get("https://api.github.com/users/FabioBatSilva", [
    {status, 200}
]).
%% > {ok, Response}

{headers, list()}

Assert the HTTP response headers.

efrisby:get("https://api.github.com/users/FabioBatSilva", [
    {headers, [
        {<<"content-type">>, <<"application/json; charset=utf-8">>}
    ]}
]).
%% > {ok, Response}

{json, bitstring() | none(), list() | integer() | atom() | bitstring()}

Tests that response JSON body contains the provided keys/values in the response.

efrisby:get("https://api.github.com/users/FabioBatSilva", [
    {json, [
        {<<"id">>, 588172},
        {<<"login">>, <<"FabioBatSilva">>}
    ]}
]).
%% > {ok, Response}

efrisby:get("https://api.github.com/users/FabioBatSilva", [
    {json, ".id", 588172},
    {json, ".login", <<"FabioBatSilva">>}
]).
%% > {ok, Response}

{json_types, bitstring() | none(), list()}

Tests that response JSON body contains the provided keys/values types.

efrisby:get("https://api.github.com/users/FabioBatSilva", [
    {json_types, [
        {<<"id">>, integer},
        {<<"login">>, bitstring}
    ]}
]).
%% > {ok, Response}

Using Paths with json and json_types

Both json and json_types accept a tuple containing a path. The path value can be a nested path separated by periods, like args.foo.mypath, a simple path like .results or . to test the whole JSON value.

efrisby:get("http://httpbin.org/get?foo=bar&bar=baz", [
    {json_types, ".args", [
        {<<"bar">>, bitstring},
        {<<"foo">>, bitstring}
    ]},
    {json, ".args", [
        {<<"foo">>, <<"bar">>},
        {<<"bar">>, <<"baz">>}
    ]}
]).
%% > {ok, Response}

Request Methods

efrisby support your basic HTTP verbs..

• efrisby:get(url(), expectations(), options())
• efrisby:head(url(), expectations(), options())
• efrisby:options(url(), expectations(), options())
• efrisby:put(url(), body(), expectations(), options())
• efrisby:post(url(), body(), expectations(), options())
• efrisby:patch(url(), body(), expectations(), options())
• efrisby:delete(url(), body(), expectations(), options())

Every request method accepts an optional list of parameters as its last argument, Request options control various aspects of a request including, headers, timeout settings and more.

eq :

-define(OPTIONS, [
    {failure_callback, fun erlang:display/1},
    {http_options, [{timeout, 150000}]},
    {base_url, "https://myapi.local"},
    {headers, [
        {"Accept", "application/json"}
    ]}
]).

• http_options Options for hackney http client (see https://github.com/benoitc/hackney)
• failure_callback Assertion failure callback function
• base_url Base request url
• headers Http headers

efrisby:get(url(), expectations(), options())

GET request.

efrisby:get("/users/FabioBatSilva", [
    {status, 200}
], ?OPTIONS).
%% > {ok, Response}

efrisby:post(url(), body(), expectations(), options())

POST request.

Body = [
    {<<"login">>, <<"FabioBatSilva">>},
    {<<"name">>, <<"Fabio B. Silva">>}
],

Expectations = [
    {status, 200},
    {content_type, "application/json"},
    {json_type, [
        {id, integer}
    ]}
],

efrisby:post("/users", Body, Expectations, ?OPTIONS).
%% > {ok, Response}