How to write end to end tests for NGINX using Docker and WireMock

A reverse proxy such as NGINX or Apache seems to be a common feature of many systems, yet they often lack the tests associated with the business logic in the application(s) it proxies.  Here I will show how, with the benefit of Docker and WireMock, to write tests that verify your config in isolation.

Git project here.

The Problem


Without tests for a reverse proxy, bugs are found on deployment in a real environment with some other unrelated suite of acceptance tests failing.  This has many drawbacks:

  • Bugs are found later (typically after committing, building and deploying) which increases your edit, compile, debug cycle.
  • It's impossible to approach your development in a TDD fashion.
  • Without tests in the same code base, you have to rely on comments or documentation to describe the intended behaviour.

The Solution 


Test your proxy in isolation, end to end, using WireMock and Docker.

Docker allows us to build and run the proxy in a reliable and repeatable way.  WireMock allows us to start a mocked application server that the proxy (NGINX in this example) forwards requests to.



  • Can verify config fast.  The ./ script takes from eight to twelve seconds on my machine.  I'm sure with more effort this could be optimized.
  • Tests can be run by CI server such as Jenkins or TeamCity on every commit.
  • Bugs found earlier.


Popular posts from this blog

How to connect your docker container to a service on the parent host

Lessons learned from a connection leak in production

How to test for connection leaks