Ever struggled with mocking external HTTP services in Elixir tests? Found yourself writing brittle mocks that don’t catch real-world encoding issues? I just released v0.5.0 of moxinet, a library that solves these problems by mocking at the HTTP layer instead of the Elixir code level.

What is moxinet
Think of it as “mox for HTTP” - it lets you mock external services by running an actual server, giving you the confidence that your HTTP layer works correctly,

This comes with some benefits:

• A unified way of testing HTTP interactions among multiple libraries/clients
• Ability to test/verify what is actually received on an external server (I’ve more than once experienced that the step where a passed data structure is encoded to JSON often happens so deep inside HTTP clients, that errors/bugs in those steps are hard to identify during testing)
• More control to test unusual behaviours like timeouts/capped connections
• Code that runs in tests no longer differs from code in production.
• Minimal setup

Why I built moxinet
I built Moxinet after experiencing production issues where the mock worked perfectly, but the actual HTTP request failed due to header or encoding issues. In that specific case, the data to be sent was encoded to JSON via a @derive declaration within the HTTP client.

I had used the strategy of spinning up test servers to interact with during testing in other languages, but failed to find a similar alternative in the Elixir ecosystem.

How it works
Moxinet spins up its own plug-based server, which you’ll route your requests to in the test environment. In your tests, you define expectations that specify how the server will respond; you can even make assertions about the payload/headers. The server expects an x-moxinet-ref header that helps identify which test-pid it originated from (automatically added by the adapter when using req)

A normal setup looks like this:

# config/test.exs

config :req, default_options: [adapter: Moxinet.ReqTestAdapter]

config :my_app, GithubAPI,
  endpoint: http://localhost:4040/github

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

defmodule MyApp.MockServer do
  use Moxinet.Server

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

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

alias Moxinet.Response

describe "create_pr/1" do
  test "creates a PR and returns its id" do
    GithubMock.expect(:post, "/pull-requests/123", fn _payload ->
      %Response{status: 202, body: %{id: "pull-request-id"}, headers: [{"X-Rate-Limit", 10}]}
    end)

    assert {:ok,
      %{
       status: 202,
       body: %{"id" => "pull-request-id"},
       headers: [
         {"X-Rate-Limit", 10},
         {"Content-Type", "application/json"}
       ]
      }
    } = GithubAPI.create_pr(title: "My PR")
  end
end

Hex: moxinet | Hex
Github:

I’d love to hear about your use cases!