Phoenix v1.1.3 Phoenix.ConnTest

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.

Summary

Functions

assert_error_sent(status_int_or_atom, func)

Asserts an error was wrapped and sent with the given status

bypass_through(conn)

Calls the Endpoint and bypasses Router match

bypass_through(conn, router, pipelines \\ [])

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

delete_req_cookie(conn, key)

Deletes a request cookie

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_flash(conn)

Gets the whole flash storage

get_flash(conn, key)

Gets the given key from the flash storage

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

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

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