annon_api

v0.16.2

annon_api v0.16.2 Annon.ConnCase

This module defines the test case to be used by tests that require setting up a connection.

Credentials

Most of source code is a copy-paste from Phoenix.ConnTest, it’s already contains great tests suite, but we don’t want to depend on Phoenix.

Endpoint testing

Annon.ConnCase typically works against routers. That’s the preferred way to test anything that your router dispatches to.

conn = get build_conn(), "/"
assert conn.resp_body =~ "Welcome!"

conn = post build_conn(), "/login", [username: "john", password: "doe"]
assert conn.resp_body =~ "Logged in!"

As in your application, the connection is also the main abstraction in testing. build_conn() returns a new connection and functions in this module can be used to manipulate the connection before dispatching to the router.

For example, one could set the accepts header for json requests as follows:

build_conn()
|> put_req_header("accept", "application/json")
|> get("/")

The router being tested is accessed via the @router module attribute.

Controller testing

The functions in this module can also be used for controller testing. While router testing is preferred over controller testing as a controller often depends on the pipelines invoked in the router and before, unit testing controllers may be helpful in some situations.

For such cases, just pass an atom representing the action to dispatch:

conn = get build_conn(), :index
assert conn.resp_body =~ "Welcome!"

Link to this section Summary

Functions

assert_error_sent(status_int_or_atom, func)

Asserts an error was wrapped and sent with the given status

build_conn()

Creates a connection to be used in upcoming requests

build_conn(method, path, params_or_body \\ nil)

Creates a connection to be used in upcoming requests with a preset method, path and body

conn()

Deprecated version of conn/0. Use build_conn/0 instead

connect(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current router

delete(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current router

delete_req_cookie(conn, key)

Deletes a request cookie

dispatch(conn, router, method, path_or_action, params_or_body \\ nil)

Dispatches the connection to the given router

get(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current router

head(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current router

html_response(conn, status)

Asserts the given status code, that we have an html response and returns the response body if one was set or sent

json_response(conn, status, opts \\ [])

Asserts the given status code, that we have an json response and returns the decoded JSON response if one was set or sent

options(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current router

patch(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current router

patch_json(conn, path_or_action, params)

Dispatches to the current router with JSON-encoded params

post(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current router

post_json(conn, path_or_action, params)

Dispatches to the current router with JSON-encoded params

put(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current router

put_json(conn, path_or_action, params)

Dispatches to the current router with JSON-encoded params

put_req_cookie(conn, key, value)

Puts a request cookie

recycle(conn)

Recycles the connection

redirected_to(conn, status \\ 302)

Returns the location header from the given redirect response

response(conn, given)

Asserts the given status code and returns the response body if one was set or sent

response_content_type(conn, format)

Returns the content type as long as it matches the given format

text_response(conn, status)

Asserts the given status code, that we have an text response and returns the response body if one was set or sent

trace(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current router

Link to this section Functions

Link to this function assert_error_sent(status_int_or_atom, func) 
assert_error_sent(integer() | atom(), function()) :: {integer(), list(), term()}

Asserts an error was wrapped and sent with the given status.

Useful for testing actions that you expect raise an error and have the response wrapped in an HTTP status, with content usually rendered by your MyApp.ErrorView.

The function accepts a status either as an integer HTTP status or atom, such as 404 or :not_found. If an error is raised, a 3-tuple of the wrapped response is returned matching the status, headers, and body of the response:

{404, [{"content-type", "text/html"} | _], "Page not found"}

Examples 

assert_error_sent :not_found, fn ->
  get build_conn(), "/users/not-found"
end

response = assert_error_sent 404, fn ->
  get build_conn(), "/users/not-found"
end
assert {404, [_h | _t], "Page not found"} = response
Link to this function build_conn() 
build_conn() :: Plug.Conn.t()

Creates a connection to be used in upcoming requests.

Link to this function build_conn(method, path, params_or_body \\ nil) 
build_conn(atom() | binary(), binary(), binary() | list() | map()) ::
  Plug.Conn.t()

Creates a connection to be used in upcoming requests with a preset method, path and body.

This is useful when a specific connection is required for testing a plug or a particular function.

Link to this function conn() 
conn() :: Plug.Conn.t()

Deprecated version of conn/0. Use build_conn/0 instead

Link to this macro connect(conn, path_or_action, params_or_body \\ nil) (macro)

Dispatches to the current router.

See dispatch/5 for more information.

Link to this macro delete(conn, path_or_action, params_or_body \\ nil) (macro)

Dispatches to the current router.

See dispatch/5 for more information.

Link to this function delete_req_cookie(conn, key) 
delete_req_cookie(Plug.Conn.t(), binary()) :: Plug.Conn.t()

Deletes a request cookie.

Link to this function dispatch(conn, router, method, path_or_action, params_or_body \\ nil)

Dispatches the connection to the given router.

When invoked via get/3, post/3 and friends, the router is automatically retrieved from the @router module attribute, otherwise it must be given as an argument.

The connection will be configured with the given method, path_or_action and params_or_body.

If path_or_action is a string, it is considered to be the request path and stored as so in the connection. If an atom, it is assumed to be an action and the connection is dispatched to the given action.

Parameters and body

This function, as well as get/3, post/3 and friends, accepts the request body or parameters as last argument:

  get build_conn(), "/", some: "param"
  get build_conn(), "/", "some=param&url=encoded"

The allowed values are:

  • nil - meaning there is no body

  • a binary - containing a request body. For such cases, :headers must be given as option with a content-type

  • a map or list - containing the parameters which will automatically set the content-type to multipart. The map or list may contain other lists or maps and all entries will be normalized to string keys

  • a struct - unlike other maps, a struct will be passed through as-is without normalizing its entries

Link to this macro get(conn, path_or_action, params_or_body \\ nil) (macro)

Dispatches to the current router.

See dispatch/5 for more information.

Link to this macro head(conn, path_or_action, params_or_body \\ nil) (macro)

Dispatches to the current router.

See dispatch/5 for more information.

Link to this function html_response(conn, status) 
html_response(Plug.Conn.t(), status :: integer() | atom()) ::
  String.t() | no_return()

Asserts the given status code, that we have an html response and returns the response body if one was set or sent.

Examples 

assert html_response(conn, 200) =~ "<html>"
Link to this function json_response(conn, status, opts \\ [])

Asserts the given status code, that we have an json response and returns the decoded JSON response if one was set or sent.

Examples 

body = json_response(conn, 200)
assert "can't be blank" in body["errors"]
Link to this macro options(conn, path_or_action, params_or_body \\ nil) (macro)

Dispatches to the current router.

See dispatch/5 for more information.

Link to this macro patch(conn, path_or_action, params_or_body \\ nil) (macro)

Dispatches to the current router.

See dispatch/5 for more information.

Link to this macro patch_json(conn, path_or_action, params) (macro)

Dispatches to the current router with JSON-encoded params.

See dispatch/5 for more information.

Link to this macro post(conn, path_or_action, params_or_body \\ nil) (macro)

Dispatches to the current router.

See dispatch/5 for more information.

Link to this macro post_json(conn, path_or_action, params) (macro)

Dispatches to the current router with JSON-encoded params.

See dispatch/5 for more information.

Link to this macro put(conn, path_or_action, params_or_body \\ nil) (macro)

Dispatches to the current router.

See dispatch/5 for more information.

Link to this macro put_json(conn, path_or_action, params) (macro)

Dispatches to the current router with JSON-encoded params.

See dispatch/5 for more information.

Link to this function put_req_cookie(conn, key, value) 
put_req_cookie(Plug.Conn.t(), binary(), binary()) :: Plug.Conn.t()

Puts a request cookie.

Link to this function recycle(conn) 
recycle(Plug.Conn.t()) :: Plug.Conn.t()

Recycles the connection.

Recycling receives a connection and returns a new connection, containing cookies and relevant information from the given one.

This emulates behaviour performed by browsers where cookies returned in the response are available in following requests.

Note recycle/1 is automatically invoked when dispatching to the router, unless the connection has already been recycled.

Link to this function redirected_to(conn, status \\ 302) 
redirected_to(Plug.Conn.t(), status :: non_neg_integer()) :: Plug.Conn.t()

Returns the location header from the given redirect response.

Raises if the response does not match the redirect status code (defaults to 302).

Examples 

assert redirected_to(conn) =~ "/foo/bar"
assert redirected_to(conn, 301) =~ "/foo/bar"
assert redirected_to(conn, :moved_permanently) =~ "/foo/bar"
Link to this function response(conn, given) 
response(Plug.Conn.t(), status :: integer() | atom()) :: binary() | no_return()

Asserts the given status code and returns the response body if one was set or sent.

Examples 

conn = get build_conn(), "/"
assert response(conn, 200) =~ "hello world"
Link to this function response_content_type(conn, format) 
response_content_type(Plug.Conn.t(), atom()) :: String.t() | no_return()

Returns the content type as long as it matches the given format.

Examples 

# Assert we have an html response with utf-8 charset
assert response_content_type(conn, :html) =~ "charset=utf-8"
Link to this function text_response(conn, status) 
text_response(Plug.Conn.t(), status :: integer() | atom()) ::
  String.t() | no_return()

Asserts the given status code, that we have an text response and returns the response body if one was set or sent.

Examples 

assert text_response(conn, 200) =~ "hello"
Link to this macro trace(conn, path_or_action, params_or_body \\ nil) (macro)

Dispatches to the current router.

See dispatch/5 for more information.