Skip to content


Repository files navigation


Gem Version

vagrant-serverspec is a vagrant plugin that implements serverspec as a provisioner.


Standard way

First, install the plugin.

$ vagrant plugin install vagrant-serverspec

In case of fork usage

in case of fork usage you need to build it first

gem build vagrant-serverspec.gemspec

(on windows you may use embedded vagrant ruby for that)

C:\HashiCorp\Vagrant\embedded\bin\gem.bat build vagrant-serverspec.gemspec

after that install plugin from filesystem

vagrant plugin install ./vagrant-serverspec-0.5.0.gem

Example Usage

Next, configure the provisioner in your Vagrantfile.

Vagrant.configure('2') do |config| = 'precise64'
  config.vm.box_url = ''

  config.vm.provision :shell, inline: <<-EOF
    sudo ufw allow 22
    yes | sudo ufw enable

  config.vm.provision :serverspec do |spec|
    # pattern for specfiles to search
    spec.pattern = '*_spec.rb'
    # pattern for specfiles to ignore, similar to rspec's --exclude-pattern option
    spec.exclude_pattern = 'but_not_*_spec.rb'
    # disable error if no specfile was found ( useful with dynamic specfile retrieving through another provisionner like Ansible Galaxy => specfiles can be saved into ansible role repository for example ). Default: true
    spec.error_no_spec_files = false
    # save result into html an report, saved into a 'rspec_html_reports' directory. Default: false
    spec.html_output = true
    # save result into junit xml report, default file name is 'rspec.xml'
    spec.junit_output = true
    # set custom junit xml report file name
    spec.junit_output_file = 'junit.xml'

You may want to override standard settings; a file named spec_helper.rb is usually used for that. Here are some examples of possible overrides.

# Disable sudo
# set :disable_sudo, true

# Set environment variables
# set :env, :LANG => 'C', :LC_MESSAGES => 'C' 

# Set PATH
# set :path, '/sbin:/usr/local/sbin:$PATH'

Then you're ready to write your specs.

require_relative 'spec_helper'

describe package('ufw') do
  it { should be_installed }

describe service('ufw') do
  it { should be_enabled }
  it { should be_running }

describe port(22) do
  it { should be_listening }

##Testing Docker Containers on OSX On OSX the Vagrant docker provider runs a Boot2Docker VM, then launches your docker container on that VM. Vagrant does SSH Proxying to send the commands through that VM and have them reach the Docker Container. Vagrant serverspec handles this the same way by getting the container host VM infromation and proxying the commands to the machine through an SSH Proxy. This functionality was introduced in this PR

Additional informations

SSH connections

SSH connection is closed before each provision run. This is mandatory if the provision is applied to multiple vms in the same run, else all runs will be applied to the first vm (See #22) due to an SSH connection which already exists. This functionality was introduced in this PR

Server spec examples

RSpec examples are clear before each provision run. This is mandatory if the provision is applied to multiple vms in the same run, else each run replay examples of previous calls also. This functionality was introduced in this PR

In case of shared examples

If you use shared examples into your test suite, you need to use 'load' instead of 'require', else errors can occurs (See #23 comments).


vagrant-serverspec aims to adhere to Semantic Versioning 2.0.0.


Pull requests are very welcome! Make sure your patches are well tested. Ideally create a topic branch for every separate change you make. For example:

  1. Fork the repo
  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


Original Idea Jeremy Voorhis (
Current version author and maintainer Vladimir Babchynskyy (
and a growing community of contributors.


MIT license (see LICENSE)


Vagrant plugin that integrates serverspec







No packages published