Nginx application showcasing how to do lightweight tests with ruby rspec
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


This is an example of how to set up a test environment for an Nginx gateway, with tests implemented using Ruby Rspec.

Please read our blog posts Lightweight Tests for your Nginx API Gateway to understand the details of our testing approach.


Project structure explained

├── nginx (Gateway configuration)
│   ├── conf.d
│   │   └── api-gateway.conf (Location directives)
│   ├── dns.conf (DNS resolver)
│   └── nginx.conf (Main config)
└── tests
    ├── hosts
    │   └── hosts (DNS resolutions for internal services)
    ├── nginx
    │   ├── conf.d
    │   │   └── services.conf (Internal services mock)
    │   └── dns.conf (Test DNS resolver)

Setting up the test docker container required 4 extra steps on top of the target Nginx setup:

  • Install and run dnsmasq (Step 1)
  • Override /etc/hosts file with DNS names for our internal services (Step 2)
  • Override production DNS resolver and inject virtual server configuration mocking internal services (Step 3)
  • Include self signed ssl certificate used in internal services mock (Step 4)
# Production config
COPY nginx/*                        /etc/nginx/
COPY nginx/conf.d/*                 /etc/nginx/conf.d/

# Test setup

# Step 1
RUN apt-get update; apt-get install dnsmasq -y

# Step 2 - we can not directly copy it to /etc/hosts since docker will
# regenerate the file and overwrite our changes. We will copy content from
# /etc/test.hosts to /etc/hosts on runtime in script
COPY tests/hosts/hosts                /etc/test.hosts

# Step 3
COPY tests/nginx                      /etc/nginx/

# Step 4
COPY tests/ssl/nginx-selfsigned.crt   /etc/ssl/certs/nginx-selfsigned.crt
COPY tests/ssl/nginx-selfsigned.key   /etc/ssl/private/nginx-selfsigned.key

Run tests

Set up testing environment:

$ make compose-up-test

Execute tests:

$ make test