Phoenix

v1.3.0-rc.3

Phoenix

Phoenix v1.3.0-rc.3 Phoenix.ConnTest View Source

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 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 endpoint.

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

build_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 build_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 build_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 =
  conn
  |> recycle()
  |> put_req_header("x-special", "nice")

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

Recycling also recycles the “accept” header.

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

bypass_through(conn)

Calls the Endpoint and bypasses Router match

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

Calls the Endpoint and bypasses Router match

clear_flash(conn)

Clears up the flash storage

conn()

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

conn(method, path, params_or_body \\ nil)

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

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

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

recycle(conn)

Recycles the connection

redirected_params(conn)

Returns the matched params from the URL the connection was redirected to

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

Link to this section Functions

Link to this function assert_error_sent(status_int_or_atom, func) View Source 
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() View Source 
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) View Source 
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 bypass_through(conn) View Source 
bypass_through(Plug.Conn.t) :: Plug.Conn.t

Calls the Endpoint and bypasses Router match.

Useful for unit testing Plugs where Endpoint and/or router pipeline plugs are required for proper setup.

Examples

For example, imagine you are testing an authentication plug in isolation, but you need to invoke the Endpoint plugs and :browser pipeline of your Router for session and flash related dependencies:

conn =
  conn
  |> bypass_through(MyAppWeb.Router, [:browser])
  |> get("/")
  |> MyApp.RequireAuthentication.call([])
assert conn.halted

Alternatively, you could invoke only the Endpoint, and Router:

conn =
  conn
  |> bypass_through(MyAppWeb.Router, [])
  |> get("/")
  |> MyApp.RequireAuthentication.call([])
assert conn.halted

Or only invoke the Endpoint’s plugs:

conn =
  conn
  |> bypass_through()
  |> get("/")
  |> MyApp.RequireAuthentication.call([])
assert conn.halted
Link to this function bypass_through(conn, router, pipelines \\ []) View Source 
bypass_through(Plug.Conn.t, module, :atom | list) :: Plug.Conn.t

Calls the Endpoint and bypasses Router match.

See bypass_through/1.

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

Clears up the flash storage.

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

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

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

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

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

Dispatches to the current endpoint.

See dispatch/5 for more information.

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

Dispatches to the current endpoint.

See dispatch/5 for more information.

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

Deletes a request cookie.

Link to this function dispatch(conn, endpoint, method, path_or_action, params_or_body \\ nil) View Source

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 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 function ensure_recycled(conn) View Source 
ensure_recycled(Plug.Conn.t) :: Plug.Conn.t

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

See recycle/1 for more information.

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

Fetches the flash storage.

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

Dispatches to the current endpoint.

See dispatch/5 for more information.

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

Gets the whole flash storage.

Link to this function get_flash(conn, key) View Source 
get_flash(Plug.Conn.t, term) :: Plug.Conn.t

Gets the given key from the flash storage.

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

Dispatches to the current endpoint.

See dispatch/5 for more information.

Link to this function html_response(conn, status) View Source 
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) View Source 
json_response(Plug.Conn.t, status :: integer | atom) ::
  map |
  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"]
Link to this macro options(conn, path_or_action, params_or_body \\ nil) View Source (macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.

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

Dispatches to the current endpoint.

See dispatch/5 for more information.

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

Dispatches to the current endpoint.

See dispatch/5 for more information.

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

Dispatches to the current endpoint.

See dispatch/5 for more information.

Link to this function put_flash(conn, key, value) View Source 
put_flash(Plug.Conn.t, term, term) :: Plug.Conn.t

Puts the given value under key in the flash storage.

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

Puts a request cookie.

Link to this function recycle(conn) View Source 
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 endpoint, unless the connection has already been recycled.

Link to this function redirected_params(conn) View Source 
redirected_params(Plug.Conn.t) :: map

Returns the matched params from the URL the connection was redirected to.

Uses the provided %Plug.Conn{}s router matched in the previous request. Raises if the response’s location header is not set.

Examples 

assert redirected_to(conn) =~ "/posts/123"
assert %{id: "123"} = redirected_params(conn)
Link to this function redirected_to(conn, status \\ 302) View Source 
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) View Source 
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) View Source 
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) View Source 
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) View Source (macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.