Phoenix.ConnTest (Phoenix v1.6.0-rc.1) 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:

@endpoint MyAppWeb.Endpoint

test "says welcome on the home page" do
  conn = get(build_conn(), "/")
  assert conn.resp_body =~ "Welcome!"
end

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

The @endpoint module attribute contains the endpoint under testing, most commonly your application endpoint itself. If you are using the MyApp.ConnCase generated by Phoenix, it is automatically set for you.

As in your router and controllers, the connection is 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("/")

You can also create your own helpers, such as json_conn() that uses build_conn/0 and put_req_header/3, so you avoid repeating the connection setup throughout your tests.

Controller testing

The functions in this module can also be used for controller testing. While endpoint testing is preferred over controller testing, especially since the controller in Phoenix plays an integration role between your domain and your views, unit testing controllers may be helpful in some situations.

For such cases, you need to set the @endpoint attribute to your controller and pass an atom representing the action to dispatch:

@endpoint MyAppWeb.HomeController

test "says welcome on the home page" do
  conn = get(build_conn(), :index)
  assert conn.resp_body =~ "Welcome!"
end

Keep in mind that, once the @endpoint variable is set, all tests after setting it will be affected.

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 build_conn/3 helper:

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

While build_conn/0 returns a connection with no request information to it, build_conn/3 returns a connection with the given request information already filled in.

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 build_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" and "authorization" headers, as well as peer data information.

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

bypass_through(conn, router)

Calls the Endpoint and Router pipelines for the current route.

bypass_through(conn, router, pipelines)

Calls the Endpoint and the given Router pipelines.

clear_flash(conn)

Clears up the flash storage.

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.

init_test_session(conn, session)

Inits a session used exclusively for testing.

json_response(conn, status)

Asserts the given status code, that we have a 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, headers \\ ~w(accept accept-language authorization))

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

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. The list of allowed atoms is available in Plug.Conn.Status. 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() | nil) ::
  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 Router pipelines.

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

Note the use of get("/") following bypass_through in the examples below. To execute the plug pipelines, you must issue a request against the router. Most often, you can simply send a GET request against the root path, but you may also specify a different method or path which your pipelines may operate against.

Examples

For example, imagine you are testing an authentication plug in isolation, but you need to invoke the Endpoint plugs and router pipelines to set up session and flash related dependencies. One option is to invoke an existing route that uses the proper pipelines. You can do so by passing the connection and the router name to bypass_through:

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

You can also specify which pipelines you want to run:

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

Alternatively, you could only invoke the Endpoint's plugs:

conn =
  conn
  |> bypass_through()
  |> get("/")
  |> MyApp.RequireAuthentication.call([])

assert conn.halted

bypass_through(conn, router)

Specs

bypass_through(Plug.Conn.t(), module()) :: Plug.Conn.t()

Calls the Endpoint and Router pipelines for the current route.

See bypass_through/1.

bypass_through(conn, router, pipelines)

Specs

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

Calls the Endpoint and the given Router pipelines.

See bypass_through/1.

clear_flash(conn)

Specs

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

Clears up the flash storage.

connect(conn, path_or_action, params_or_body \\ nil)

(macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.

delete(conn, path_or_action, params_or_body \\ nil)

(macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.

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(conn, path_or_action, params_or_body \\ nil)

(macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.

get_flash(conn)

Specs

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

Gets the whole flash storage.

get_flash(conn, key)

Specs

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

Gets the given key from the flash storage.

head(conn, path_or_action, params_or_body \\ nil)

(macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.

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

init_test_session(conn, session)

Specs

init_test_session(Plug.Conn.t(), map() | keyword()) :: Plug.Conn.t()

Inits a session used exclusively for testing.

json_response(conn, status)

Specs

json_response(Plug.Conn.t(), status :: integer() | atom()) ::
  map() | no_return()

Asserts the given status code, that we have a 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"]

options(conn, path_or_action, params_or_body \\ nil)

(macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.

patch(conn, path_or_action, params_or_body \\ nil)

(macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.

post(conn, path_or_action, params_or_body \\ nil)

(macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.

put(conn, path_or_action, params_or_body \\ nil)

(macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.

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, headers \\ ~w(accept accept-language authorization))

Specs

recycle(Plug.Conn.t(), [String.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.

By default, only the headers "accept", "accept-language", and "authorization" are recycled. However, a custom set of headers can be specified by passing a list of strings representing its names as the second argument of the function.

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

redirected_params(conn)

Specs

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)

redirected_to(conn, status \\ 302)

Specs

redirected_to(Plug.Conn.t(), status :: non_neg_integer()) :: String.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 response 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 a text response and returns the response body if one was set or sent.

Examples

assert text_response(conn, 200) =~ "hello"

trace(conn, path_or_action, params_or_body \\ nil)

(macro)

Dispatches to the current endpoint.

See dispatch/5 for more information.