# etest_http
etest\_http is a supplementary library for [etest](https://github.com/wooga/etest)
that makes it easy to test http APIs by providing useful assertions and helper
methods.
## Example Test Case
```erlang
-module (my_api_test).
-compile (export_all).
% etest macros
-include_lib ("etest/include/etest.hrl").
% etest_http macros
-include_lib ("etest_http/include/etest_http.hrl").
test_hello_world() ->
Response = ?perform_get("http://localhost:3000/hello/world"),
?assert_status(200, Response),
?assert_body_contains("Hello", Response),
?assert_body("Hello World", Response).
```
## Installation
Install etest\_http by adding it as a [rebar](https://github.com/basho/rebar)
dependency:
```erlang
% rebar.config:
{deps, [
{etest_http, "", {git, "git://github.com/wooga/etest_http.git"}},
% ...
]}.
```
Then run `rebar get-deps` to synchronize your dependencies.
## Usage
There are two kinds of macros which etest_http provides:
The [request macros](https://github.com/wooga/etest_http#request-macros) provide
a simple API to perform HTTP request. They return a response record on which
subsequent assertions are performed.
The [assertion macros](https://github.com/wooga/etest_http#assertion-macros)
provide useful http API related assertions.
### Request Macros
#### perform_get
Perform a `GET` request, returns a response record.
```erlang
Res = ?perform_get(Url).
Res = ?perform_get(Url, Headers).
Res = ?perform_get(Url, Headers, Queries).
% Url = string()
% header() :: {string() | binary() | atom(), string() | binary()}
% Headers = [header()]
% query() :: [{string(), string()}]
% Queries = [query()]
```
****
#### perform_post
Perform a `POST` request, returns a response record.
```erlang
Res = ?perform_post(Url).
Res = ?perform_post(Url, Headers).
Res = ?perform_post(Url, Headers, Body).
Res = ?perform_post(Url, Headers, Body, Queries).
% Url = string()
% header() :: {string() | binary() | atom(), string() | binary()}
% Headers = [header()]
% query() :: [{string(), string()}]
% Queries = [query()]
% Body = binary()
```
### Assertion Macros
#### assert_contains
Assert that the `Haystack` contains the `Needle`, fail with `assert_contains`
otherwise.
```erlang
% Test Macro.
?assert_contains(Needle, Haystack).
% Test Generator Macro.
?assert_contains(Needle, Haystack).
% Needle = string()
% Haystack = string()
```
****
#### assert_body_contains
Assert that the body received with the response `Res` contains the string
`Needle`, fail with `assert_contains` otherwise too.
```erlang
% Test Macro.
?assert_body_contains(Needle, Res).
% Test Generator Macro.
?assert_body_contains(Needle, Res).
% Needle = string()
```
****
#### assert_body
Assert that the body received with the response `Res` is exactly `Body`, fail
with `assert_equal` otherwise.
```erlang
?assert_body(Body, Res).
% Test Generator Macro.
?assert_body(Body, Res).
% Body = binary()
```
**Planned for future versions:**
* Support for regular expressions
****
#### assert_header
Assert that the presence of a header `HeaderName` in the headers received with
the response `Res`, fail with `assert_header` otherwise.
```erlang
% Test Macro.
?assert_header(HeaderName, Res).
% Test Generator Macro.
?assert_header(HeaderName, Res).
% HeaderName = string()
% Examples:
?assert_header_val("X-Signature", Res).
```
****
#### assert_header_value
Assert that the headers received with the response `Res` has a header
`HeaderName` with value `HeaderValue`, fail with `assert_header_value` otherwise.
```erlang
% Test Macro.
?assert_header_val(HeaderName, HeaderValue, Res).
% Test Generator Macro.
?assert_header_val(HeaderName, HeaderValue, Res).
% HeaderName = string()
% HeaderVal = string()
% Examples:
?assert_header_val(
"X-Signature", "42UVoTWYp9I-wdWJsQYUyEXRoCI1wCXmOVPqwdV8LU0=", Res).
```
****
#### assert_status
Assert that the response's HTTP status code is `StatusCode`, fail with
`assert_status` otherwise.
```erlang
% Test Macro.
?assert_status(StatusCode, Res).
% Test Generator Macro.
?assert_status(StatusCode, Res).
% StatusCode = integer()
% Example:
?assert_status(200, Res).
```
****
#### assert_json
Assert that the body received with the response `Res` contains a JSON structure
equal to `JsonStruct`, fail with `assert_equal` otherwise.
```erlang
% Test Macro.
?assert_json(JsonStruct, Res).
% Test Generator Macro.
?assert_json(JsonStruct, Res).
% JsonStruct = orddict()
% Example:
?assert_json([{message, "Hello World"}], Res).
```
****
#### assert_json_key
Assert that the body received with the response `Res` contains a JSON object,
which has a key `Key` with arbitrary contents, fail with `assert_json_key`
otherwise.
```erlang
% Test Macro.
?assert_json_key(Key, Res).
% Test Generator Macro.
?assert_json_key(Key, Res).
% Key = binary() | [binary()]
% Examples:
?assert_json_key(<<"message">>, Res).
?assert_json_key([<<"messages">>, <<"en">>], Res).
```
****
#### assert_json_value
Assert that the body received with the response `Res` contains a JSON object, which under the key `Key` contains exactly `Val`, fail with `assert_json_value` otherwise.
```erlang
% Test Macro.
?assert_json_value(Key, Val, Res).
% Test Generator Macro.
?assert_json_value(Key, Val, Res).
% Key = binary() | [binary()]
% Val = atom() | binary() | list() | integer() | float() | {list()}
% Examples:
?assert_json_value(<<"message">>, <<"Hello World">>, Res).
?assert_json_value(<<"should_reload">>, true, Res).
?assert_json_value([<<"messages">>, <<"de">>], <<"Hallo Welt">>, Res).
```