conn_test.ex

defmodule Phoenix.ConnTest do
  @moduledoc """
  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 created 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 `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/2` 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.
  """

  @doc false
  defmacro __using__(_) do
    quote do
      import Plug.Conn
      import Phoenix.ConnTest
    end
  end

  alias Plug.Conn
  import ExUnit.Assertions, only: [flunk: 1]

  @doc """
  Creates a connection to be used in upcoming requests.
  """
  @spec build_conn() :: Conn.t
  def build_conn() do
    build_conn(:get, "/", nil)
  end

  @doc """
  Deprecated version of `conn/0`. Use `build_conn/0` instead.
  """
  @spec conn() :: Conn.t
  def conn() do
    IO.warn "using conn/0 to build a connection is deprecated. Use build_conn/0 instead"
    build_conn()
  end

  @doc """
  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.
  """
  @spec build_conn(atom | binary, binary, binary | list | map | nil) :: Conn.t
  def build_conn(method, path, params_or_body \\ nil) do
    Plug.Adapters.Test.Conn.conn(%Conn{}, method, path, params_or_body)
    |> Conn.put_private(:plug_skip_csrf_protection, true)
    |> Conn.put_private(:phoenix_recycled, true)
  end

  @doc """
  Deprecated version of `conn/3`. Use `build_conn/3` instead.
  """
  @spec conn(atom | binary, binary, binary | list | map | nil) :: Conn.t
  def conn(method, path, params_or_body \\ nil) do
    IO.warn """
    using conn/3 to build a connection is deprecated. Use build_conn/3 instead.
    #{Exception.format_stacktrace}
    """
    build_conn(method, path, params_or_body)
  end

  @http_methods [:get, :post, :put, :patch, :delete, :options, :connect, :trace, :head]

  for method <- @http_methods do
    @doc """
    Dispatches to the current endpoint.

    See `dispatch/5` for more information.
    """
    defmacro unquote(method)(conn, path_or_action, params_or_body \\ nil) do
      method = unquote(method)
      quote do
        Phoenix.ConnTest.dispatch(unquote(conn), @endpoint, unquote(method),
                                  unquote(path_or_action), unquote(params_or_body))
      end
    end
  end

  @doc """
  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
  """
  def dispatch(conn, endpoint, method, path_or_action, params_or_body \\ nil)
  def dispatch(%Plug.Conn{} = conn, endpoint, method, path_or_action, params_or_body) do
    if is_nil(endpoint) do
      raise "no @endpoint set in test case"
    end

    if is_binary(params_or_body) and is_nil(List.keyfind(conn.req_headers, "content-type", 0)) do
      raise ArgumentError, "a content-type header is required when setting " <>
                           "a binary body in a test connection"
    end

    conn
    |> ensure_recycled()
    |> dispatch_endpoint(endpoint, method, path_or_action, params_or_body)
    |> Conn.put_private(:phoenix_recycled, false)
    |> from_set_to_sent()
  end
  def dispatch(conn, _endpoint, method, _path_or_action, _params_or_body) do
    raise ArgumentError, "expected first argument to #{method} to be a " <>
                         "%Plug.Conn{}, got #{inspect conn}"
  end

  defp dispatch_endpoint(conn, endpoint, method, path, params_or_body) when is_binary(path) do
    conn
    |> Plug.Adapters.Test.Conn.conn(method, path, params_or_body)
    |> endpoint.call(endpoint.init([]))
  end

  defp dispatch_endpoint(conn, endpoint, method, action, params_or_body) when is_atom(action) do
    conn
    |> Plug.Adapters.Test.Conn.conn(method, "/", params_or_body)
    |> endpoint.call(endpoint.init(action))
  end

  defp from_set_to_sent(%Conn{state: :set} = conn), do: Conn.send_resp(conn)
  defp from_set_to_sent(conn), do: conn

  @doc """
  Puts a request cookie.
  """
  @spec put_req_cookie(Conn.t, binary, binary) :: Conn.t
  defdelegate put_req_cookie(conn, key, value), to: Plug.Test

  @doc """
  Deletes a request cookie.
  """
  @spec delete_req_cookie(Conn.t, binary) :: Conn.t
  defdelegate delete_req_cookie(conn, key), to: Plug.Test

  @doc """
  Fetches the flash storage.
  """
  @spec fetch_flash(Conn.t) :: Conn.t
  defdelegate fetch_flash(conn), to: Phoenix.Controller

  @doc """
  Gets the whole flash storage.
  """
  @spec get_flash(Conn.t) :: Conn.t
  defdelegate get_flash(conn), to: Phoenix.Controller

  @doc """
  Gets the given key from the flash storage.
  """
  @spec get_flash(Conn.t, term) :: Conn.t
  defdelegate get_flash(conn, key), to: Phoenix.Controller

  @doc """
  Puts the given value under key in the flash storage.
  """
  @spec put_flash(Conn.t, term, term) :: Conn.t
  defdelegate put_flash(conn, key, value), to: Phoenix.Controller

  @doc """
  Clears up the flash storage.
  """
  @spec clear_flash(Conn.t) :: Conn.t
  defdelegate clear_flash(conn), to: Phoenix.Controller

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

  """
  @spec response_content_type(Conn.t, atom) :: String.t | no_return
  def response_content_type(conn, format) when is_atom(format) do
    case Conn.get_resp_header(conn, "content-type") do
      [] ->
        raise "no content-type was set, expected a #{format} response"
      [h] ->
        if response_content_type?(h, format) do
          h
        else
          raise "expected content-type for #{format}, got: #{inspect h}"
        end
      [_|_] ->
        raise "more than one content-type was set, expected a #{format} response"
    end
  end

  defp response_content_type?(header, format) do
    case parse_content_type(header) do
      {part, subpart} ->
        format = Atom.to_string(format)
        format in MIME.extensions(part <> "/" <> subpart) or
          format == subpart or String.ends_with?(subpart, "+" <> format)
      _  ->
        false
    end
  end

  defp parse_content_type(header) do
    case Plug.Conn.Utils.content_type(header) do
      {:ok, part, subpart, _params} ->
        {part, subpart}
      _ ->
        false
    end
  end

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

  """
  @spec response(Conn.t, status :: integer | atom) :: binary | no_return
  def response(%Conn{state: :unset}, _status) do
    raise """
    expected connection to have a response but no response was set/sent.
    Please verify that you assign to "conn" after a request:

        conn = get(conn, "/")
        assert html_response(conn) =~ "Hello"
    """
  end

  def response(%Conn{status: status, resp_body: body}, given) do
    given = Plug.Conn.Status.code(given)

    if given == status do
      body
    else
      raise "expected response with status #{given}, got: #{status}, with body:\n#{body}"
    end
  end

  @doc """
  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>"
  """
  @spec html_response(Conn.t, status :: integer | atom) :: String.t | no_return
  def html_response(conn, status) do
    body = response(conn, status)
    _    = response_content_type(conn, :html)
    body
  end

  @doc """
  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"
  """
  @spec text_response(Conn.t, status :: integer | atom) :: String.t | no_return
  def text_response(conn, status) do
    body = response(conn, status)
    _    = response_content_type(conn, :text)
    body
  end

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

  """
  @spec json_response(Conn.t, status :: integer | atom) :: map | no_return
  def json_response(conn, status) do
    body = response(conn, status)
    _    = response_content_type(conn, :json)

    Phoenix.json_library().decode!(body)
  end

  @doc """
  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"
  """
  @spec redirected_to(Conn.t, status :: non_neg_integer) :: String.t
  def redirected_to(conn, status \\ 302)

  def redirected_to(%Conn{state: :unset}, _status) do
    raise "expected connection to have redirected but no response was set/sent"
  end

  def redirected_to(conn, status) when is_atom(status) do
    redirected_to(conn, Plug.Conn.Status.code(status))
  end

  def redirected_to(%Conn{status: status} = conn, status) do
    location = Conn.get_resp_header(conn, "location") |> List.first
    location || raise "no location header was set on redirected_to"
  end

  def redirected_to(conn, status) do
    raise "expected redirection with status #{status}, got: #{conn.status}"
  end

  @doc """
  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.
  """
  @spec recycle(Conn.t) :: Conn.t
  def recycle(conn) do
    build_conn()
    |> Map.put(:host, conn.host)
    |> Plug.Test.recycle_cookies(conn)
    |> Plug.Test.put_peer_data(Plug.Conn.get_peer_data(conn))
    |> copy_headers(conn.req_headers, ~w(accept authorization))
  end

  defp copy_headers(conn, headers, copy) do
    headers = for {k, v} <- headers, k in copy, do: {k, v}
    %{conn | req_headers: headers ++ conn.req_headers}
  end

  @doc """
  Ensures the connection is recycled if it wasn't already.

  See `recycle/1` for more information.
  """
  @spec ensure_recycled(Conn.t) :: Conn.t
  def ensure_recycled(conn) do
    if conn.private[:phoenix_recycled] do
      conn
    else
      recycle(conn)
    end
  end

  @doc """
  Calls the Endpoint and bypasses Router match.

  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 simpy send a GET request against the root path, but you
  may also specify a different method or path which your pipelines may operate
  against. If you ommit the request you may find that your tests return
  a `flash not fetched, call fetch_flash/2` or similar error.

  ## 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
  """
  @spec bypass_through(Conn.t) :: Conn.t
  def bypass_through(conn) do
    Plug.Conn.put_private(conn, :phoenix_bypass, :all)
  end

  @doc """
  Calls the Endpoint and bypasses Router match.

  See `bypass_through/1`.
  """
  @spec bypass_through(Conn.t, module, atom | list) :: Conn.t
  def bypass_through(conn, router, pipelines \\ []) do
    Plug.Conn.put_private(conn, :phoenix_bypass, {router, List.wrap(pipelines)})
  end

  @doc """
  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)
  """
  @spec redirected_params(Conn.t) :: map
  def redirected_params(%Plug.Conn{} = conn) do
    router = Phoenix.Controller.router_module(conn)
    %URI{path: path, host: host} = conn |> redirected_to() |> URI.parse()
    path_info = split_path(path)

    {conn, _pipes, _dispatch} = router.__match_route__(conn, "GET", path_info, host || conn.host)
    Enum.into(conn.path_params, %{}, fn {key, val} -> {String.to_atom(key), val} end)
  end
  defp split_path(path) do
    for segment <- String.split(path, "/"), segment != "", do: segment
  end

  @doc """
  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
  """
  @spec assert_error_sent(integer | atom, function) :: {integer, list, term}
  def assert_error_sent(status_int_or_atom, func) do
    expected_status = Plug.Conn.Status.code(status_int_or_atom)
    discard_previously_sent()
    result =
      func
      |> wrap_request()
      |> receive_response(expected_status)

    discard_previously_sent()
    result
  end

  defp receive_response({:ok, conn}, expected_status) do
    if conn.state == :sent do
      flunk "expected error to be sent as #{expected_status} status, but response sent #{conn.status} without error"
    else
      flunk "expected error to be sent as #{expected_status} status, but no error happened"
    end
  end
  defp receive_response({:error, {_kind, exception, stack}}, expected_status) do
    receive do
      {ref, {^expected_status, headers, body}} when is_reference(ref) ->
        {expected_status, headers, body}

      {ref, {sent_status, _headers, _body}} when is_reference(ref) ->
        reraise ExUnit.AssertionError.exception("""
        expected error to be sent as #{expected_status} status, but got #{sent_status} from:

        #{Exception.format_banner(:error, exception)}
        """), stack

    after 0 ->
      reraise ExUnit.AssertionError.exception("""
      expected error to be sent as #{expected_status} status, but got an error with no response from:

      #{Exception.format_banner(:error, exception)}
      """), stack
    end
  end

  defp discard_previously_sent() do
    receive do
      {ref, {_, _, _}} when is_reference(ref) -> discard_previously_sent()
      {:plug_conn, :sent}                     -> discard_previously_sent()
    after
      0 -> :ok
    end
  end

  defp wrap_request(func) do
    try do
      {:ok, func.()}
    catch
      kind, error -> {:error, {kind, error, System.stacktrace()}}
    end
  end
end