Phoenix v0.14.0 → Overview → Phoenix → ConnTest

Phoenix.ConnTest

Summary
Functions
Macros

Conveniences for testing Phoenix endpoints and connection related helpers.

You likely want to use this module or make it part of your ExUnit.CaseTemplate. Once used, this module automatically imports all functions defined here as well as the functions in Plug.Conn.

Endpoint testing

Phoenix.ConnTest typically works against endpoints. That’s the preferred way to test anything that your router dispatches to.

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

conn = post 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. conn() returns a new connection and functions in this module can be used to manipulate the connection before dispatching to the endpoint.

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

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

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

Controller testing

The functions in this module can also be used for controller testing. While endpoint 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 conn(), :index
assert conn.resp_body =~ "Welcome!"

Views testing

Under other circumstances, you may be testing a view or another layer that requires a connection for processing. For such cases, a connection can be created using the conn/3 helper:

MyApp.UserView.render "hello.html",
                       conn: conn(:get, "/")

Recycling

Browsers implement a storage by using cookies. When a cookie is set in the response, the browser stores it and sends it in the next request.

To emulate this behaviour, this module provides the idea of recycling. The recycle/1 function receives a connection and returns a new connection, similar to the one returned by conn/0 with all the response cookies from the previous connection defined as request headers. This is useful when testing multiple routes that require cookies or session to work.

Keep in mind Phoenix will automatically recycle the connection between dispatches. This usually works out well most times but it may discard information if you are modifying the connection before the next dispatch:

# No recycling as the connection is fresh
conn = get conn(), "/"

# The connection is recycled, creating a new one behind the scenes
conn = post conn, "/login"

# We can also recycle manually in case we want custom headers
conn = recycle(conn)
conn = put_req_header("x-special", "nice")

# No recycling as we did it explicitly
conn = delete conn, "/logout"

Recycling also recycles the “accept” header.

Source

Summary↑

clear_flash(conn)	Clears up the flash storage
conn()	Creates a connection to be used in upcoming requests
conn(method, path, params_or_body \\ nil)	Creates a connection to be used in upcoming requests with a preset method, path and body
connect(conn, path_or_action, params_or_body \\ nil)	Dispatches to the current endpoint
delete(conn, path_or_action, params_or_body \\ nil)	Dispatches to the current endpoint
delete_req_cookie(conn, key)	Deletes a request cookie
delete_req_header(conn, key)	Deletes a request header
dispatch(conn, endpoint, method, path_or_action, params_or_body \\ nil)	Dispatches the connection to the given endpoint
ensure_recycled(conn)	Ensures the connection is recycled if it wasn’t already
fetch_flash(conn)	Fetches the flash storage
get(conn, path_or_action, params_or_body \\ nil)	Dispatches to the current endpoint
get_flash(conn)	Gets the whole flash storage
get_flash(conn, key)	Gets the given key from the flash storage
head(conn, path_or_action, params_or_body \\ nil)	Dispatches to the current endpoint
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)	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 endpoint
patch(conn, path_or_action, params_or_body \\ nil)	Dispatches to the current endpoint
post(conn, path_or_action, params_or_body \\ nil)	Dispatches to the current endpoint
put(conn, path_or_action, params_or_body \\ nil)	Dispatches to the current endpoint
put_flash(conn, key, value)	Puts the given value under key in the flash storage
put_req_cookie(conn, key, value)	Puts a request cookie
put_req_header(conn, key, value)	Puts a new request header
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 endpoint

Functions

clear_flash(conn)

(function) # ↑

Specs:

clear_flash(Plug.Conn.t) :: Plug.Conn.t

Clears up the flash storage.

Source

conn()

(function) # ↑

Specs:

conn :: Plug.Conn.t
conn :: Plug.Conn.t

Creates a connection to be used in upcoming requests.

Source

conn(method, path, params_or_body \\ nil)

(function) # ↑

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.

Source

delete_req_cookie(conn, key)

(function) # ↑

Specs:

delete_req_cookie(Plug.Conn.t, binary) :: Plug.Conn.t

Deletes a request cookie.

Source

delete_req_header(conn, key)

(function) # ↑

Specs:

delete_req_header(Plug.Conn.t, binary) :: Plug.Conn.t

Deletes a request header.

Source

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

(function) # ↑

Dispatches the connection to the given endpoint.

When invoked via get/3, post/3 and friends, the endpoint is automatically retrieved from the @endpoint 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 conn(), "/", some: "param"
  get 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

Source

ensure_recycled(conn)

(function) # ↑

Ensures the connection is recycled if it wasn’t already.

See recycle/1 for more information.

Source

fetch_flash(conn)

(function) # ↑

Specs:

fetch_flash(Plug.Conn.t) :: Plug.Conn.t

Fetches the flash storage.

Source

get_flash(conn)

(function) # ↑

Specs:

get_flash(Plug.Conn.t) :: Plug.Conn.t

Gets the whole flash storage.

Source

get_flash(conn, key)

(function) # ↑

Specs:

get_flash(Plug.Conn.t, term) :: Plug.Conn.t

Gets the given key from the flash storage.

Source

html_response(conn, status)

(function) # ↑

Specs:

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>"

Source

json_response(conn, status)

(function) # ↑

Specs:

json_response(Plug.Conn.t, status :: integer | atom) :: %{} | no_return

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"]

Source

put_flash(conn, key, value)

(function) # ↑

Specs:

put_flash(Plug.Conn.t, term, term) :: Plug.Conn.t

Puts the given value under key in the flash storage.

Source

put_req_cookie(conn, key, value)

(function) # ↑

Specs:

put_req_cookie(Plug.Conn.t, binary, binary) :: Plug.Conn.t

Puts a request cookie.

Source

put_req_header(conn, key, value)

(function) # ↑

Specs:

put_req_header(Plug.Conn.t, binary, binary) :: Plug.Conn.t

Puts a new request header.

Previous entries of the same header are overridden.

Source

recycle(conn)

(function) # ↑

Specs:

recycle(Plug.Conn.t) :: Plug.Conn.t
recycle(Plug.Conn.t) :: Plug.Conn.t

Recycles the connection.

Recycling receives an 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 endpoint, unless the connection has already been recycled.

Source

redirected_to(conn, status \\ 302)

(function) # ↑

Specs:

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"

Source

response(conn, given)

(function) # ↑

Specs:

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 conn(), "/"
assert response(conn, 200) =~ "hello world"

Source

response_content_type(conn, format)

(function) # ↑

Specs:

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 repsonse with utf-8 charset
assert response_content_type(conn, :html) =~ "charset=utf-8"

Source

text_response(conn, status)

(function) # ↑

Specs:

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"

Source