TestServer - No fuzz mocking of third-party services

danschultzer

Pow Core Team

Hi everyone!

TestServer is an easy way to mock third-party services in ExUnit.

Features

HTTP/1
HTTP/2
WebSocket
TLS with self-signed certificates
Flexible FIFO match rules
Catches unexpected requests
When test finishes verifies there’s no pending routes or websocket handlers to call

Example

test "fetch_url/0" do
  # The test server will autostart the current test server, if not already running
  TestServer.add("/", via: :get)
  TestServer.add("/", via: :get, to: fn conn -> Plug.Conn.send_resp(conn, 200, "second call") end)

  # The URL is derived from the current test server instance
  Application.put_env(:my_app, :url, TestServer.url())

  assert {:ok, "HTTP"} = MyApp.fetch_url()
  assert {:ok, "second call"} = MyApp.fetch_url()
end

Enabling TLS

TestServer.start(scheme: :https)

The key and certificate is generated with x509 on the fly.

WebSocket Example

test "WebSocketClient" do
  {:ok, socket} = TestServer.websocket_init("/ws")
  :ok = TestServer.websocket_handle(socket, to: fn {:text, "ping"}, state -> {:reply, {:text, "pong"}, state})

  {:ok, client} = WebSocketClient.start_link(TestServer.url("/ws"))
  :ok = WebSocketClient.send(client, "ping")
  {:ok, "pong"} = WebSocketClient.receive(client)

  :ok = TestServer.websocket_info(socket, fn state -> {:reply, {:text, "ping"}, state} end)
  {:ok, "ping"} = WebSocketClient.receive(client)
end

I’ve been using this for testing a JSON RPC endpoint and testing the SSL configuration for http adapters in assent.

I hope you find it useful, feel free to contribute!

https://github.com/danschultzer/test_server

8 comments

#api #library #testing #mocking

15 2120 8

2025-05-27 08:57:55 UTC

Showing Posts 1 to 8

Show Best Posts
Show All (oldest first)
Show All (newest first)

trisolaran

Hi @danschultzer thanks for releasing this. This looks like a considerable improvement over Bypass. Especially being able to define multiple rules for the same url, which is something you can’t do in Bypass and has always annoyed me. Will try this out as soon as I have to write the next test for an external service.

Post #1

danschultzer

Pow Core Team

Especially being able to define multiple rules for the same url, which is something you can’t do in Bypass and has always annoyed me.

True, it was what prompted me to build this library. JSON RPC was impossible to test well with bypass. On top of that I couldn’t use bypass to test handling of bad SSL certificates, and I wished it was a lot more ergonomic for request matching.

Post #2

danschultzer

Pow Core Team

New exiciting release!

v0.1.8 no longer has Plug.Cowboy as a required dependency, and instead will use Bandit, Plug.Cowboy, or :httpd depending what is available (in that order). You can also set up a custom web server.

My own belief is that libraries should attempt limit the dependency graph as much as possible. This helps prevent dreaded dependency conflicts, improve auditing, and maybe even helps with perfomance/build time gains.

And I didn’t know :httpd was a thing! Included in OTP so of course TestServer should support it as the default web server if Bandit or Plug.Cowboy is not available. I’ve seen almost no love for :httpd, and maybe that’s for a reason.

All to say, now there’s only two required dependency left in TestServer - the x509 package and Plug.

Try it out and let me know what you think!

https://github.com/danschultzer/test_server

Post #3

danschultzer

Pow Core Team

v0.1.9 is out!

This release makes it a lot easier to test IPv6-only networks. All you need to do is set the :ipfamily option:

 TestServer.start(ipfamily: :inet6)

Post #4

rhcarvalho

I’ve been trying to replace Bypass + Mox with TestServer, and I really appreciate the simplification and ease of understanding it brought back to my tests

The one case that’s been bugging me and preventing me from shipping it is how to handle a test involving Phoenix.Presence. As far as I understand, depending on timing/scheduling my test server gets hit with a different number of requests.

If I TestServer.add one too little I get a warning in the test output, even though the test passes:

warning: ** (RuntimeError) TestServer.Instance #PID<0.471.0> received an unexpected GET request at /v1/users/79e78660-718c-4f59-8e4c-51b61599d868

If I TestServer.add one too many, then the test fails:

(RuntimeError) TestServer.Instance #PID<0.465.0> did not receive a request for these routes before the test ended

Is there a blessed way in TestServer to say “this handler should match at least once (or N times)?”
Alternatively, any other ideas of what I could consider doing? Thanks!

Post #5

Schultzer

Are you sure you don’t have conflicting tests?

This could happen with async tests.

Post #6

rhcarvalho

Tests are run synchronously, and the issue is reproducible running a single test case in isolation as well.

I could be doing something wrong in the “testing Phoenix.Presence” side of things. I’ve read the few threads on the topic I could find in this forum, including Handling Phoenix Presence during testing - #3 by luizpvasc. I originally worked on this already some time ago, memory is a bit vague, but I think it is related to how Presence “fetchers” work asynchronously, process linking and termination.

So I considered posting on that topic, but then thought maybe TestServer could just be less strict about the number of calls. Reading the implementation a bit more last night, I believe that’s not possible, though.

https://github.com/danschultzer/test_server/blob/21ec25c4c9ab9c1988643d2d1acadba5210d3abd/lib/test_server.ex#L67-L75

https://github.com/danschultzer/test_server/blob/21ec25c4c9ab9c1988643d2d1acadba5210d3abd/lib/test_server.ex#L77-L89

https://github.com/danschultzer/test_server/blob/21ec25c4c9ab9c1988643d2d1acadba5210d3abd/lib/test_server.ex#L91-L103

https://github.com/danschultzer/test_server/blob/21ec25c4c9ab9c1988643d2d1acadba5210d3abd/lib/test_server.ex#L117-L132

TestServer always sets up an ExUnit on_exit callback that checks routes: if anything is left unvisited it errors out.

And when an unexpected request comes, it produces the warning:

https://github.com/danschultzer/test_server/blob/21ec25c4c9ab9c1988643d2d1acadba5210d3abd/lib/test_server/plug.ex#L18-L22

I think either I need to understand how to test Phoenix.Presence in a more deterministic way, spin up a dumb server that doesn’t assert on the number of mocked calls, or mock at the HTTP client level.

Post #7

rhcarvalho

Solved it with the snippet in Phoenix.Presence — Phoenix v1.8.8. Waiting for fetchers to terminate has worked fine coupled with TestServer, while combining that with Bypass+Mox didn’t – so I’m double happy for removing the mental complexity of Bypass and Mox from the code base