How do you implement integration tests for a Phoenix API?

That question maybe look as too generic but I really want to have an initial idea about how do you make integration/acceptance tests on a Phoenix API.

Some point are:

  • do you use any libraries or builtins function in ConnCase/ChannelCase are enough?
  • any suggestions with extra content and material about this topic and phoenix/elixir?
  • could you provide a simple example test that can’t be covered with Phoenix’s builtin functions

An API? As in not serving html? Usually I implement these as full integration tests. I use an external library (e.g. Finch) and construct the http request from scratch instead of using a Conn. To do async I either stuff $callers into the user-agent header and use that to connect the cowboy process back to the test, or I use Bypass and instantiate a webserver with the API router as a plug for bypass’ Conn. I almost never use conncase or channelcase in these instances.

I write the integration tests in ExUnit which has the benefit of the tests being ran as part of the normal test suite. I abstract away any Phoenix helpers since they are taking some shortcuts. I follow the approach of Hex: we should be testing behaviours, not the implementation, but the unit of behaviour here is an API endpoint - it’s the public contract. I try to avoid shared setups as much as possible - this way the tests are self-contained. I invest into building helpers to combat code duplication. UserUI is a module with helpers that mimic user actions in the web app (creating account, sending a message, etc.). MobileApi is a module with helpers that basically do HTTP requests but are tailored to this specific API (API-key based auth with JSON). Example test with test helpers:

defmodule MobileApiTest do
  use MyApp.Case, async: true

  alias MyApp.TestHelpers.UserUI
  alias MyApp.TestHelpers.MobileApi

  describe "GET /api/mobile/messages" do
    test "lists messages sent to the person" do
      # Setup...
      account = UserUI.create_account!()
      message1 = UserUI.create_message!(account)
      # More setup...

      assert MobileApi.get("/api/mobile/messages", api_key) == %{
               status: 200,
               body: %{
                 "messages" => [
                     "id" =>,
                     "subject" => message2.subject,
                     "sent_at" => DateTime.to_iso8601(message2.inserted_at)
                     "id" =>,
                     "subject" => message1.subject,
                     "sent_at" => DateTime.to_iso8601(message1.inserted_at)

    test "returns 401 on expired API key" do
      # Setup...

      assert %{
               status: 401,
               body: %{"error" => "expired_api_key"}
             } = MobileApi.get("/api/mobile/messages", api_key)

defmodule MyApp.TestHelpers.MobileApi do
  @moduledoc """
  Test helpers for interacting with the mobile app API.

  alias Plug.Conn
  alias Phoenix.ConnTest
  require Phoenix.ConnTest

  # The default endpoint for testing.
  @endpoint MyApp.Endpoint

  def get(url, api_key \\ nil) do
    %{status: status, resp_body: body} =
      |> build_conn()
      |> ConnTest.get(url)

    %{status: status, body: if(body != "", do: Jason.decode!(body), else: "")}

  defp build_conn(api_key) do
    conn =
      |> Conn.put_req_header("accept", "application/json")

    if api_key do
      conn |> Conn.put_req_header("authorization", "Bearer #{api_key}")

While its certianly possible to do integration tests in elixir itself I also want to mention that you can use other tools as well. I’ve talked to people using e.g. js based browser testing tools to test liveview apps. So if you have experience in non elixir tools already you might not need to shift gears at all.


Using code coverage: mix test --cover be sure to have:

  1. source code statement coverage
  2. combinations for branch (if then else) coverage
  3. do not forget test data