johantell / moxinet

A set of tools to help test external services asyncronously

Moxinet

Mocking server that, just like mox, allows parallel testing.

HexDocs: https://hexdocs.pm/moxinet

Installation

Install the package by adding moxinet to your list of dependencies in mix.exs:

def deps do
  [
    {:moxinet, "~> 0.2.1", only: :test}
  ]
end

Getting started

To use moxinet you must first define your mock server, from which you'll forward mock-specific requests:

# test/support/mock_server.ex

defmodule MyApp.MockServer do
  use Moxinet.Server

  forward("/github", to: GithubMock)
end

Then create the mock module (in this example GithubMock):

# test/support/mock_servers/github_mock.ex

defmodule GithubMock do
  use Moxinet.Mock
end

Start moxinet in your test helper (before ExUnit.start())

# test/test_helper.exs
{:ok, _} = Moxinet.start(port: 4040, router: MyApp.MockServer)

ExUnit.start()

Let the API configuration decide whether the API should call the remote server or the local mock server:

# config/config.exs
config :my_app, GithubAPI,
  url: "https://api.github.com"

# config/test.exs
config :my_app, GithubAPI,
  url: "http://localhost:4040/github"

---

If you're familiar with plug, you'll see that our mock server is indeed a plug and can therefore be extended like one.

After you've added your server, mocks can be defined:

# test/support/mocks/github_mock.ex
defmodule GithubMock do
  use Moxinet.Mock
end

In tests, you can create rules for how your mocks should behave through expect/4:

alias Moxinet.Response

describe "create_pr/1" do
  test "creates a pull request when" do
    GithubMock.expect(:post, "/pull-requests/123", fn _payload ->
      %Response{status: 202, body: %{id: "pull-request-id"}}
    end)

    assert {:ok, %{status: 202, body: %{"id" => "pull-request-id"}}}} = GithubAPI.create_pr(title: "My PR")
  end
end

NOTE: One small caveat with moxinet is that in order for us to be able to match a mock defined in a request with an incoming request, the requests must send the x-moxinet-ref header. Most HTTP libraries allows adding custom headers to your requests, but that might not always be the case.

It's also not recommended to send the x-moxinet-ref header outside your test environment, meaning you'd likely want to do find a way to conditionally add it. Here is one example on how to achieve it in req:

defmodule GithubAPI do
  def client do
    Req.new([
      # ...
    ])
    |> add_moxinet_header()
  end

  defmacrop add_moxinet_header(req) do
    if Mix.env() == :test do
      quote do
        {header_name, header_value} = Moxinet.build_mock_header()
      
        Req.Request.put_new_header(unquote(req), header_name, header_value)
      end
    else
      quote do
        unquote(req)
      end
    end
  end
end

Why not use mox instead?

When testing calls to external servers mox tends to guide the user towards replacing the whole HTTP layer which is usually fine when the code is controlled by an external library, holding the responsibility of correctness on its own.

A commonly seen pattern where behaviors play the centric role like the following:

defmodule GithubAPI do
  defmodule HTTPBehaviour do
    @callback post(String.t(), Keyword.t()) :: {:ok, Map.t()} | {:error, :atom}
  end

  defmodule HTTP do
    @behaviour GithubAPI.HTTPBehaviour
    def post(url, opts) do
      # Perform HTTP request
    end
  end

  def create_pr(attrs) do
    impl().post("/pull-requests", body: attrs)
  end

  defp impl, do: Application.get_env(:github_api_http_module, HTTP)
end

will absolutely do the job, but there are a few drawbacks:

1. The HTTP remains untested as that is not being used by the test suite
2. HTTP client libraries (like tesla) usually allow defining headers, authentication, and in most cases also encodes passed data structures to JSON, where custom behavior that filters/encodes data in certain ways can be included. I've seen cases where a @derive {Jason, only: [...]} caused a bug that wasn't a bug according to all tests that verified the expected data was sent to the HTTP layer.

moxinet aims to fill those gaps while also reducing the need for behaviors and mocks

How it works

Moxinet works a lot similar to mox except it'll focus on solving the same issue for HTTP request.

The test pid will be registered in the mock registry, where it can later be accessed from inside the mock.

flowchart TD
    TP[Test pid] --> MR[Mock registry]
    GMS <--> MR
    TP --> API[Github API]
    API -.HTTP request.-> MS[Mock server]
    MS --> GMS[Github Mock]
    GMS -.HTTP response.-> API

Loading