Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Tree: ba768bb9dd
Fetching contributors…

Cannot retrieve contributors at this time

142 lines (87 sloc) 4.406 kB


A collection of helper methods to test your nginx module.


Add this line to your application's Gemfile:

gem 'nginx_test_helper'

And then execute:

$ bundle

Or install it yourself as:

$ gem install nginx_test_helper


Create a module called NginxConfiguration with two class methods: default_configuration, which should return a hash with the default configuration values, and template_configuration which should return the Nginx configuration template.

You can use the command bellow to generate this file

$ nginx_test_helper init

The init command also create a example_spec.rb to show how to use the main methods:


Starts the server with the given configuration and template, stop it and return the stderr and error log to be possible to check some condition.

nginx_test_configuration({:unknown_value => 0}).should include('unknown directive "unknown_directive"')


Starts the server, execute the given block inside a Timeout block and stop the server.

nginx_run_server({:return_code => 422}) do
  uri = URI.parse("http://#{nginx_host}:#{nginx_port}/")
  response = Net::HTTP.get_response(uri)
  response.code.should eql("422")

You can customize the timeout value, default 5 seconds, using the second parameter of nginx_run_server method.

nginx_run_server({}, {:timeout => 1}) do
  sleep 2

start_server / stop_server

If you want to start the server and run many test cases with the same configuration you can use start_server / stop_server methods.

before(:all) do
  configuration = {} # Your configuration hash
  @config ="example_config_id", configuration)

after(:all) do


You can use this method to delete the files created by configuration. One usecase is call it after the test, if it has passed, like:

RSpec.configure do |config|
  config.after(:each) do
    NginxTestHelper::Config.delete_config_and_log_files(config_id) if has_passed?

Environment variables

Some default values can be overwriten by environment variables. Check the list bellow:

  1. NGINX_EXEC - set which nginx executable to be used on tests, default: '/usr/local/nginx/sbin/nginx'
  2. NGINX_HOST - set the host returned by nginx_host method, default: ''
  3. NGINX_PORT - set the port returned by nginx_port method, default: 9990
  4. NGINX_WORKERS - set the number of workers returned by nginx_workers method, default: 1
  5. NGINX_TESTS_TMP_DIR - set the dir where temporary files, logs and configuration files, will be stored, default: '/tmp/nginx_tests'

Easter eggs


You can set a key named configuration_template on your configuration with a template different from the one on template_configuration method to be used when writing configuration file.


You can set a key named disable_start_stop_server on your configuration with true value to avoid the start and stop server steps. This can be useful when debugging how a test is failing.


You can use the method write_directive on your configuration template to be easier to deal with null values.

write_directive("directive_name", value)

with value = nil results in
#directive_name "";

with value != nil, 10 as example, results in
directive_name "10";

There is a third optional parameter which is used as comment to directive.

write_directive("directive_name", 10, "directive comment")

#directive comment
directive_name "10";


There are two available mathers.


To check if the value is in a range, >= min and <= max

10.5.should be_in_the_interval(10.3, 10.6) # true
10.5.should be_in_the_interval(10.6, 10.8) # false


To check if the value match the given pattern

"foo".should match_the_pattern(/O/i) # true "foo".should match_the_pattern(/A/i) # false


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
Jump to Line
Something went wrong with that request. Please try again.