W3cubDocs

/Phoenix

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

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

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

Macros

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

get(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint

head(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint

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

trace(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint

Functions

assert_error_sent(status_int_or_atom, func)

Specs

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

build_conn()

Specs

build_conn :: Plug.Conn.t

Creates a connection to be used in upcoming requests.

build_conn(method, path, params_or_body \\ nil)

Specs

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.

bypass_through(conn)

Specs

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 pipline 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(MyApp.Router, [:browser])
  |> get("/")
  |> MyApp.RequireAuthentication.call([])
assert conn.halted

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

conn =
  conn
  |> bypass_through(MyApp.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

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

Specs

bypass_through(Plug.Conn.t, module, :atom | list) :: Plug.Conn.t

Calls the Endpoint and bypasses Router match.

See bypass_through/1.

clear_flash(conn)

Specs

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

Clears up the flash storage.

conn()

Specs

conn :: Plug.Conn.t

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

conn(method, path, params_or_body \\ nil)

Specs

conn(atom | binary, binary, binary | list | map) :: Plug.Conn.t

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

delete_req_cookie(conn, key)

Specs

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

Deletes a request cookie.

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

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

ensure_recycled(conn)

Specs

ensure_recycled(Plug.Conn.t) :: Plug.Conn.t

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

See recycle/1 for more information.

fetch_flash(conn)

Specs

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

Fetches the flash storage.

get_flash(conn)

Specs

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

Gets the whole flash storage.

get_flash(conn, key)

Specs

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

Gets the given key from the flash storage.

html_response(conn, status)

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

json_response(conn, status)

Specs

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

put_flash(conn, key, value)

Specs

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

Puts the given value under key in the flash storage.

put_req_cookie(conn, key, value)

Specs

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

Puts a request cookie.

recycle(conn)

Specs

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.

redirected_to(conn, status \\ 302)

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"

response(conn, given)

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

response_content_type(conn, format)

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"

text_response(conn, status)

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"

Macros

connect(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint.

See dispatch/5 for more information.

delete(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint.

See dispatch/5 for more information.

get(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint.

See dispatch/5 for more information.

head(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint.

See dispatch/5 for more information.

options(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint.

See dispatch/5 for more information.

patch(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint.

See dispatch/5 for more information.

post(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint.

See dispatch/5 for more information.

put(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint.

See dispatch/5 for more information.

trace(conn, path_or_action, params_or_body \\ nil)

Dispatches to the current endpoint.

See dispatch/5 for more information.

© 2014 Chris McCord
Licensed under the MIT License.
https://hexdocs.pm/phoenix/Phoenix.ConnTest.html