RETIRED: use beaker-rspec instead
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


This project has been retired in favour of beaker and its relevant RSpec bridge beaker-rspec. All tickets/PR's are now closed, future development and work should continue there.


rspec-system-puppet is a Puppet plugin for rspec-system. The goal here is to provide a series of helpers for performing proper system tests on Puppet related modules such as:

  • Pure Puppet DSL content, classes and defined resources
  • Ruby based plugins: facts, functions, faces, types and providers

Relation to rspec-puppet

While unit testing using rspec-puppet is extremely useful for testing your content based on comparing input of parameters, facts etc. with the desired catalog output, it doesn't however do a real test. This library is meant to augment the rspec-puppet test suite, and is designed specifically to work with it. In fact I suggest running both these tests in parallel with rspec-puppet, as rspec-puppet is always going to execute basic tests faster - especially tests that don't need a real run like comparing template output with desired output, or fine-detailed items like expected property values and logical blocks.

Quick Start

Recommended to be installed first:

  • Vagrant 1.2.2 or greater
  • VirtualBox 4.2.10 or greater
  • RVM or RBenv (current instructions are based on RVM however)

Create a nodeset file

In your existing Puppet module project, create a .nodeset.yml with the following contents:

default_set: 'centos-64-x64'
        prefab: 'centos-64-x64'
        prefab: 'debian-70rc1-x64'

Install the gem

The intention is that this gem is used within your project as a development library.

You may install rspec-system-puppet manually with:

# gem install rspec-system-puppet

However it is usually recommended to include gem 'rspec-system-puppet' in your Gemfile and let bundler install it. A bare-minimum example Gemfile is shown below:

source ''

group :development, :test do
  gem 'rake'
  gem 'rspec-system-puppet'

Install using Bundler with:

bundle install --path vendor/bundle

If you're using git, add .rspec_system to your project's .gitignore file. This is the default location for files created by rspec-system.

Create rakefile

Create a Rakefile like so:

require 'rspec-system/rake_task'

Create spec helper

You will need a spec helper for your tests to require. So create the file spec/spec_helper_system.rb:

require 'rspec-system/spec_helper'
require 'rspec-system-puppet/helpers'

include RSpecSystemPuppet::Helpers

RSpec.configure do |c|
  # Project root
  proj_root = File.expand_path(File.join(File.dirname(__FILE__), '..'))

  # Enable colour
  c.tty = true

  # This is where we 'setup' the nodes before running our tests
  c.before :suite do
    # Install puppet

    # Replace mymodule with your module name
    puppet_module_install(:source => proj_root, :module_name => 'mymodule')

Create system spec tests

I advise you to seperate the location of your system and unit tests:

  • spec/system - system tests
  • spec/unit - rspec-puppet and other unit tests

And create your first system tests in say spec/system/basic_spec.rb (make sure it has the _spec.rb suffix!):

require 'spec_helper_system'

describe 'basic tests:' do
  # Using puppet_apply as a subject
  context puppet_apply 'notice("foo")' do
    its(:stdout) { should =~ /foo/ }
    its(:stderr) { should be_empty }
    its(:exit_code) { should be_zero }

  # Using puppet_apply as a helper
  it 'my class should work with no errors' do
    pp = <<-EOS
      class { 'mymodule': }

    # Run it twice and test for idempotency
    puppet_apply(pp) do |r|
      r.exit_code.should_not == 1
      r.exit_code.should be_zero

Run spec tests

Now you should be able to do:

# bundle exec rake spec:system

If you want to test an alternate set, just use the RSPEC_SET environment variable like so:

# RSPEC_SET=debian-70rc1-x64 bundle exec rake spec:system

Consult the .nodeset.yml file for the list of sets, and the rspec-system nodesets introduction to learn how to manage them.

Further Information

  • API Documentation - this provides the Ruby API docs for the Puppet Helpers. In particular look at the Helpers sub-class.
  • rspec-system docs - This is the main library rspec-system-puppet utilises, and should provide more in-depth instructions on doing more complex stuff than what this gem alone provides.
  • puppetlabs-firewall - If you want to see the library in action this module is the primary guinea pig for rspec-system-puppet and should give you some ideas on writing tests of your own. Look under spec/system for the tests.
  • puppetlabs-puppetdb - Another example of the module in action.

CI Integration

For now consult the documentation for rspec-system for more details.