Phoenix.ConnTest

Parsed documentation:
View on GitHub
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("accepts", "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 circunstances, 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.
No suggestions.
Please help! Open an issue on GitHub if this assessment is incorrect.