gem install rspec-puppet
Note for ruby 1.8 users: while rspec-puppet itself supports ruby 1.8, you'll need to pin rspec itself to
~> 3.1.0
, as later rspec versions do not work on old rubies anymore.
When you start out on a new module, create a metadata.json file for your module and then run rspec-puppet-init
to create the necessary files to configure rspec-puppet for your module's tests.
With Puppet 3, the manifest is set to $manifestdir/site.pp
. However Puppet 4 defaults to an empty value. In order to test manifests you will need to set appropriate settings.
Puppet configuration reference for manifest
can be found online:
- Puppet 3: https://docs.puppet.com/puppet/3.8/reference/configuration.html#manifest
- Puppet 4: https://docs.puppet.com/puppet/4.8/reference/configuration.html#manifest
Configuration is typically done in a spec/spec_helper.rb
file which each of your spec will require. Example code:
# /spec
base_dir = File.dirname(File.expand_path(__FILE__))
RSpec.configure do |c|
c.module_path = File.join(base_dir, 'fixtures', 'modules')
c.manifest_dir = File.join(base_dir, 'fixtures', 'manifests')
c.manifest = File.join(base_dir, 'fixtures', 'manifests', 'site.pp')
c.environmentpath = File.join(Dir.pwd, 'spec')
# Coverage generation
c.after(:suite) do
RSpec::Puppet::Coverage.report!
end
end
rspec-puppet can be configured by modifying the RSpec.configure
block in your
spec/spec_helper.rb
file.
RSpec.configure do |c|
c.<config option> = <value>
end
Type | Default | Puppet Version(s) |
---|---|---|
String | Required | 2.x, 3.x |
The path to the directory containing your basic manifests like site.pp
.
Type | Default | Puppet Version(s) |
---|---|---|
String | Required | 2.x, 3.x, 4.x, 5.x |
The path to the directory containing your Puppet modules.
Type | Default | Puppet Version(s) |
---|---|---|
Hash | {} |
2.x, 3.x, 4.x, 5.x |
A hash of default facts that should be used for all the tests.
Type | Default | Puppet Version(s) |
---|---|---|
String | "/dev/null" |
3.x, 4.x, 5.x |
The path to your hiera.yaml
file (if used).
Type | Default | Puppet Version(s) |
---|---|---|
Hash | {} |
4.x, 5.x |
A hash of default node parameters that should be used for all the tests.
Type | Default | Puppet Version(s) |
---|---|---|
Hash | {} |
4.x, 5.x |
A hash of default trusted facts that should be used for all the tests
(available in the manifests as the $trusted
hash). In order to use this, the
trusted_node_data
setting must be set to true
.
Type | Default | Puppet Version(s) |
---|---|---|
Boolean | false |
>=3.4, 4.x, 5.x |
Configures rspec-puppet to use the $trusted
hash when compiling the
catalogues.
Type | Default | Puppet Version(s) |
---|---|---|
Boolean | false |
>=4.3, 5.x |
Configures rspec-puppet to use the $server_facts
hash when compiling the
catalogues.
Type | Default | Puppet Version(s) |
---|---|---|
String | "/etc/puppet" |
2.x, 3.x, 4.x, 5.x |
The path to the main Puppet configuration directory.
Type | Default | Puppet Version(s) |
---|---|---|
String | Puppet's default value | 2.x, 3.x, 4.x, 5.x |
The path to puppet.conf
.
Type | Default | Puppet Version(s) |
---|---|---|
String | Puppet's default value | 2.x, 3.x |
The entry-point manifest for Puppet, usually $manifest_dir/site.pp
.
Type | Default | Puppet Version(s) |
---|---|---|
String | nil |
2.x, 3.x |
The path to the directory that Puppet should search for templates that are stored outside of modules.
Type | Default | Puppet Version(s) |
---|---|---|
String | "/etc/puppetlabs/code/environments" |
4.x, 5.x |
The search path for environment directories.
Type | Default | Puppet Version(s) |
---|---|---|
String | "current" |
>= 3.2 |
This switches between the 3.x (current
) and 4.x (future
) parsers.
Type | Default | Puppet Version(s) |
---|---|---|
String | "title-hash" |
>= 3.3, 4.x, 5.x |
How unrelated resources should be ordered when applying a catalogue.
manifest
- Use the order in which the resources are declared in the manifest.title-hash
- Order the resources randomly, but in a consistent manner across runs (the order will only change if the manifest changes).random
- Order the resources randomly.
Type | Default | Puppet Version(s) |
---|---|---|
Boolean | false |
>= 3.5, 4.x, 5.x |
Makes Puppet raise an error when it tries to reference a variable that hasn't
been defined (not including variables that have been explicitly set to
undef
).
Type | Default | Puppet Version(s) |
---|---|---|
Boolean | true |
>= 3.3, 4.x, 5.x |
Makes rspec-puppet coerce all the fact values into strings (matching the behaviour of older versions of Puppet).
Type | Default | Puppet Version(s) |
---|---|---|
Boolean | false |
2.x, 3.x, 4.x, 5.x |
Configures rspec-puppet to stub out Pathname#absolute?
with it's own
implementation. This should only be enabled if you're running into an issue
running cross-platform tests where you have Ruby code (types, providers,
functions, etc) that use Pathname#absolute?
.
Type | Default | Puppet Version(s) |
---|---|---|
Boolean | true |
2.x, 3.x, 4.x, 5.x |
Configures rspec-puppet to automatically create a link from the root of your
module to spec/fixtures/<module name>
at the beginning of the test run.
Type | Default | Puppet Version(s) |
---|---|---|
Boolean | true |
2.x, 3.x, 4.x, 5.x |
If true
, rspec-puppet will override the fdqn
, hostname
, and domain
facts with values that it derives from the node name (specified with
let(:node)
.
In some circumstances (e.g. where your nodename/certname is not the same as
your FQDN), this behaviour is undesirable and can be disabled by changing this
setting to false
.
For clarity and consistency, I recommend that you use the following directory structure and naming convention.
module/
├── manifests/
├── lib/
└── spec/
├── spec_helper.rb
│
├── classes/
│ └── <class_name>_spec.rb
│
├── defines/
│ └── <define_name>_spec.rb
│
├── applications/
│ └── <application_name>_spec.rb
│
├── functions/
│ └── <function_name>_spec.rb
│
├── types/
│ └── <type_name>_spec.rb
│
├── type_aliases/
│ └── <type_alias_name>_spec.rb
│
└── hosts/
└── <host_name>_spec.rb
If you use the above directory structure, your examples will automatically be placed in the correct groups and have access to the custom matchers. If you choose not to, you can force the examples into the required groups as follows.
describe 'myclass', :type => :class do
...
end
describe 'mydefine', :type => :define do
...
end
describe 'myapplication', :type => :application do
...
end
describe 'myfunction', :type => :puppet_function do
...
end
describe 'mytype', :type => :type do
...
end
describe 'My::TypeAlias', :type => :type_alias do
...
end
describe 'myhost.example.com', :type => :host do
...
end
You can test whether the subject catalog compiles cleanly with compile
.
it { is_expected.to compile }
To check the error messages of your class, you can check for raised error messages.
it { is_expected.to compile.and_raise_error(/error message match/) }
You can test if a resource exists in the catalogue with the generic
contain_<resource type>
matcher.
it { is_expected.to contain_augeas('bleh') }
You can also test if a class has been included in the catalogue with the same matcher.
it { is_expected.to contain_class('foo') }
Note that rspec-puppet does none of the class name parsing and lookup that the puppet parser would do for you. The matcher only accepts fully qualified classnames without any leading colons. That is a class foo::bar
will only be matched by foo::bar
, but not by ::foo::bar
, or bar
alone.
If your resource type includes :: (e.g.
foo::bar
simply replace the :: with __ (two underscores).
it { is_expected.to contain_foo__bar('baz') }
You can further test the parameters that have been passed to the resources with
the generic with_<parameter>
chains.
it { is_expected.to contain_package('mysql-server').with_ensure('present') }
If you want to specify that the given parameters should be the only ones passed
to the resource, use the only_with_<parameter>
chains.
it { is_expected.to contain_package('httpd').only_with_ensure('latest') }
You can use the with
method to verify the value of multiple parameters.
it do
is_expected.to contain_service('keystone').with(
'ensure' => 'running',
'enable' => 'true',
'hasstatus' => 'true',
'hasrestart' => 'true'
)
end
The same holds for the only_with
method, which in addition verifies the exact
set of parameters and values for the resource in the catalogue.
it do
is_expected.to contain_user('luke').only_with(
'ensure' => 'present',
'uid' => '501'
)
end
You can also test that specific parameters have been left undefined with the
generic without_<parameter>
chains.
it { is_expected.to contain_file('/foo/bar').without_mode }
You can use the without method to verify that a list of parameters have not been defined
it { is_expected.to contain_service('keystone').without(
['restart', 'status']
)}
You can test the number of resources in the catalogue with the
have_resource_count
matcher.
it { is_expected.to have_resource_count(2) }
The number of classes in the catalogue can be checked with the
have_class_count
matcher.
it { is_expected.to have_class_count(2) }
You can also test the number of a specific resource type, by using the generic
have_<resource type>_resource_count
matcher.
it { is_expected.to have_exec_resource_count(1) }
This last matcher also works for defined types. If the resource type contains ::, you can replace it with __ (two underscores).
it { is_expected.to have_logrotate__rule_resource_count(3) }
NOTE: when testing a class, the catalogue generated will always contain at least one class, the class under test. The same holds for defined types, the catalogue generated when testing a defined type will have at least one resource (the defined type itself).
The following methods will allow you to test the relationships between the resources in your catalogue, regardless of how the relationship is defined. This means that it doesn’t matter if you prefer to define your relationships with the metaparameters (require, before, notify and subscribe) or the chaining arrows (->, ~>, <- and <~), they’re all tested the same.
it { is_expected.to contain_file('foo').that_requires('File[bar]') }
it { is_expected.to contain_file('foo').that_comes_before('File[bar]') }
it { is_expected.to contain_file('foo').that_notifies('File[bar]') }
it { is_expected.to contain_file('foo').that_subscribes_to('File[bar]') }
An array can be used to test a resource for multiple relationships
it { is_expected.to contain_file('foo').that_requires(['File[bar]', 'File[baz]']) }
it { is_expected.to contain_file('foo').that_comes_before(['File[bar]','File[baz]']) }
it { is_expected.to contain_file('foo').that_notifies(['File[bar]', 'File[baz]']) }
it { is_expected.to contain_file('foo').that_subscribes_to(['File[bar]', 'File[baz]']) }
You can also test the reverse direction of the relationship, so if you have the following bit of Puppet code
notify { 'foo': }
notify { 'bar':
before => Notify['foo'],
}
You can test that Notify[bar] comes before Notify[foo]
it { is_expected.to contain_notify('bar').that_comes_before('Notify[foo]') }
Or, you can test that Notify[foo] requires Notify[bar]
it { is_expected.to contain_notify('foo').that_requires('Notify[bar]') }
Note that this notation does not support any of the features you're used from the puppet language. Only a single resource with a single, unquoted title can be referenced here. Class names need to be always fully qualified and not have the leading ::
. It currently does not support inline arrays or quoting.
These work
Notify[foo]
Class[profile::apache]
These will not work
Notify['foo']
Notify[foo, bar]
Class[::profile::apache]
The relationship matchers are recursive in two directions:
- vertical recursion, which checks for dependencies with parents of the resource
(i.e. the resource is contained, directly or not, in the class involved in the relationship).
E.g. where
Package['foo']
comes beforeFile['/foo']
:
class { 'foo::install': } ->
class { 'foo::config': }
class foo::install {
package { 'foo': }
}
class foo::config {
file { '/foo': }
}
- horizontal recursion, which follows indirect dependencies (dependencies of dependencies).
E.g. where
Yumrepo['foo']
comes beforeFile['/foo']
:
class { 'foo::repo': } ->
class { 'foo::install': } ->
class { 'foo::config': }
class foo::repo {
yumrepo { 'foo': }
}
class foo::install {
package { 'foo': }
}
class foo::config {
file { '/foo': }
}
Autorequires are considered in dependency checks.
When testing custom types, the be_valid_type
matcher provides a range of expectations:
with_provider(<provider_name>)
: check that the right provider was selectedwith_properties(<property_list>)
: check that the specified properties are availablewith_parameters(<parameter_list>)
: check that the specified parameters are availablewith_features(<feature_list>)
: check that the specified features are availablewith_set_attributes(<param_value_hash>)
: check that the specified attributes are set
When testing type aliases, the allow_value
and allow_values
matchers are used to check if the
alias accepts particular values or not:
describe 'MyModule::Shape' do
it { is_expected.to allow_value('square') }
it { is_expected.to allow_values('circle', 'triangle') }
it { is_expected.not_to allow_value('blue') }
end
To test that
sysctl { 'baz'
value => 'foo',
}
Will cause the following resource to be in included in catalogue for a host
exec { 'sysctl/reload':
command => '/sbin/sysctl -p /etc/sysctl.conf',
}
We can write the following testcase (in spec/defines/sysctl_spec.rb
)
describe 'sysctl' do
let(:title) { 'baz' }
let(:params) { { 'value' => 'foo' } }
it { is_expected.to contain_exec('sysctl/reload').with_command("/sbin/sysctl -p /etc/sysctl.conf") }
end
let(:title) { 'foo' }
Parameters of a defined type, class or application can be passed defining :params
in a let,
and passing it a hash as seen below.
let(:params) { {'ensure' => 'present', ...} }
For passing Puppet's undef
as a paremeter value, you can simply use :undef
and it will
be translated to undef
when compiling. For example:
let(:params) { {'user' => :undef, ...} }
For references to nodes or resources as seen when using require
or before
properties,
or an application
resource you can pass the string as an argument to the ref
helper:
let(:params) { 'require' => ref('Package', 'sudoku') }
Which translates to:
mydefine { 'mytitle': require => Package['sudoku'] }
Another example, for an application setup (when using app_management
):
let(:params) { { 'nodes' => { ref('Node', 'dbnode') => ref('Myapp::Mycomponent', 'myapp') } } }
Will translate to:
site { myapp { 'myimpl': nodes => { Node['dbnode'] => Myapp::Mycomponent['myimpl'] } } }
If the manifest you're testing expects to run on host with a particular name, you can specify this as follows
let(:node) { 'testhost.example.com' }
If the manifest you're testing expects to evaluate the environment name, you can specify this as follows
let(:environment) { 'production' }
By default, the test environment contains no facts for your manifest to use. You can set them with a hash
let(:facts) { {'operatingsystem' => 'Debian', 'kernel' => 'Linux', ...} }
Facts may be expressed as a value (shown in the previous example) or a structure. Fact keys may be expressed as either symbols or strings. A key will be converted to a lower case string to align with the Facter standard
let(:facts) { {'os' => { 'family' => 'RedHat', 'release' => { 'major' => '7', 'minor' => '1', 'full' => '7.1.1503' } } } }
You can also create a set of default facts provided to all specs in your spec_helper:
RSpec.configure do |c|
c.default_facts = {
'operatingsystem' => 'Ubuntu'
}
end
Any facts you provide with let(:facts)
in a spec will automatically be merged on top
of the default facts.
You can create top-scope variables much in the same way as an ENC.
let(:node_params) { { 'hostgroup' => 'webservers', 'rack' => 'KK04', 'status' => 'maintenance' } }
You can also create a set of default top-scope variables provided to all specs in your spec_helper:
RSpec.configure do |c|
c.default_node_params = {
'owner' => 'itprod',
'site' => 'ams4',
'status' => 'live'
}
end
NOTE Setting top-scope variables is not supported in Puppet < 3.0.
If the manifest being tested relies on another class or variables to be set, these can be added via a pre-condition. This code will be evaluated before the tested class.
let(:pre_condition) { 'include other_class' }
This may be useful when testing classes that are modular, e.g. testing apache::mod::foo
which
relies on a top-level apache
class being included first.
The value may be a raw string to be inserted into the Puppet manifest, or an array of strings (manifest fragments) that will be concatenated.
In some cases, you may need to ensure that the code that you are testing comes
before another set of code. Similar to the :pre_condition
hook, you can add
a :post_condition
hook that will ensure that the added code is evaluated
after the tested class.
let(:post_condition) { 'include other_class' }
This may be useful when testing classes that are modular, e.g. testing class
do_strange_things::to_the_catalog
which must come before class foo
.
The value may be a raw string to be inserted into the Puppet manifest, or an array of strings (manifest fragments) that will be concatenated.
I recommend setting a default module path by adding the following code to your
spec_helper.rb
RSpec.configure do |c|
c.module_path = '/path/to/your/module/dir'
end
However, if you want to specify it in each example, you can do so
let(:module_path) { '/path/to/your/module/dir' }
When testing with Puppet >= 4.3 the trusted facts hash will have the standard trusted fact keys
(certname, domain, and hostname) populated based on the node name (as set with :node
).
By default, the test environment contains no custom trusted facts (as usually obtained
from certificate extensions) and found in the extensions
key. If you need to test against
specific custom certificate extensions you can set those with a hash. The hash will then
be available in $trusted['extensions']
let(:trusted_facts) { {'pp_uuid' => 'ED803750-E3C7-44F5-BB08-41A04433FE2E', '1.3.6.1.4.1.34380.1.2.1' => 'ssl-termination'} }
You can also create a set of default certificate extensions provided to all specs in your spec_helper:
RSpec.configure do |c|
c.default_trusted_facts = {
'pp_uuid' => 'ED803750-E3C7-44F5-BB08-41A04433FE2E',
'1.3.6.1.4.1.34380.1.2.1' => 'ssl-termination'
}
end
You can test if a resource was exported from the catalogue by using the
exported_resources
accessor in combination with any of the standard matchers.
You can use exported_resources
as the subject of a child context:
context 'exported resources' do
subject { exported_resources }
it { is_expected.to contain_file('foo') }
end
You can also use exported_resources
directly in a test:
it { expect(exported_resources).to contain_file('foo') }
Applications in some ways behave as defined resources, but are more complex so require a number of elements already documented above to be combined for testing.
A full example of the simplest rspec test for a single component application:
require 'spec_helper'
describe 'orch_app' do
let(:node) { 'my_node' }
let(:title) { 'my_awesome_app' }
let(:params) do
{
'nodes' => {
ref('Node', node) => ref('Orch_app::Db', title),
}
}
end
it { should compile }
it { should contain_orch_app(title) }
end
Each piece is required:
- You must turn on app_management during testing for the handling to work
- The
:node
definition is required to be set so later on you can reference it in the:nodes
argument within:params
- Applications act like defined resources, and each require a
:title
to be defined - The
:nodes
key in:params
requires the use of node reference mappings to resource mappings. Theref
keyword allows you to provide these (a normal string will not work).
Beyond these requirements, the very basic should compile
test and other matchers
as you would expect will work the same as classes and defined resources.
Note: for the moment, cross-node support is not available and will return an error. Ensure you model your tests to be single-node for the time being.
All of the standard RSpec matchers are available for you to use when testing Puppet functions.
it 'should be able to do something' do
subject.call(['foo']) == 'bar'
end
For your convenience though, a run
matcher exists to provide easier to
understand test cases.
it { is_expected.to run.with_params('foo').and_return('bar') }
require 'spec_helper'
describe '<function name>' do
...
end
The name of the function must be provided in the top level description, e.g.
describe 'split' do
You can specify the arguments to pass to your function during the test(s) using
either the with_params
chain method in the run
matcher
it { is_expected.to run.with_params('foo', 'bar', ['baz']) }
Or by using the call
method on the subject directly
it 'something' do
subject.call(['foo', 'bar', ['baz']])
end
A lambda (block) can be passed to functions that support either a required or
optional lambda by passing a block to the with_lambda
chain method in the
run
matcher.
it { is_expected.to run.with_lambda { |x| x * 2 }
You can test the result of a function (if it produces one) using either the
and_returns
chain method in the run
matcher
it { is_expected.to run.with_params('foo').and_return('bar') }
Or by using any of the existing RSpec matchers on the subject directly
it 'something' do
subject.call(['foo']) == 'bar'
subject.call(['baz']).should be_an Array
end
You can test whether the function throws an exception using either the
and_raises_error
chain method in the run
matcher
it { is_expected.to run.with_params('a', 'b').and_raise_error(Puppet::ParseError) }
it { is_expected.not_to run.with_params('a').and_raise_error(Puppet::ParseError) }
Or by using the existing raises_error
RSpec matcher
it 'something' do
expect { subject.call(['a', 'b']) }.should raise_error(Puppet::ParseError)
expect { subject.call(['a']) }.should_not raise_error(Puppet::ParseError)
end
Some complex functions require access to the current parser's scope, e.g. for stubbing other parts of the system.
before(:each) { scope.expects(:lookupvar).with('some_variable').returns('some_value') }
it { is_expected.to run.with_params('...').and_return('...') }
Note that this does not work when testing manifests which use custom functions. Instead, you'll need to create a replacement function directly.
before(:each) do
Puppet::Parser::Functions.newfunction(:custom_function, :type => :rvalue) { |args|
raise ArgumentError, 'expected foobar' unless args[0] == 'foobar'
'expected value'
}
end
Set the hiera config symbol properly in your spec files:
let(:hiera_config) { 'spec/fixtures/hiera/hiera.yaml' }
hiera = Hiera.new(:config => 'spec/fixtures/hiera/hiera.yaml')
Create your spec hiera files
spec/fixtures/hiera/hiera.yaml
---
:backends:
- yaml
:hierarchy:
- test
:yaml:
:datadir: 'spec/fixtures/hiera'
spec/fixtures/hiera/test.yaml
---
ntpserver: ['ntp1.domain.com','ntpXX.domain.com']
user:
oneuser:
shell: '/bin/bash'
twouser:
shell: '/sbin/nologin'
ntpserver = hiera.lookup('ntpserver', nil, nil)
let(:params) { 'ntpserver' => ntpserver }
If you just want to fetch values from hiera (e.g. because
you're testing code that uses explicit hiera lookups) just specify
the path to the hiera config in your spec_helper.rb
RSpec.configure do |c|
c.hiera_config = 'spec/fixtures/hiera/hiera.yaml'
end
spec/fixtures/hiera/hiera.yaml
---
:backends:
- yaml
:yaml:
:datadir: spec/fixtures/hieradata
:hierarchy:
- common
Please note: In-module hiera data depends on having a correct metadata.json file. It is strongly recommended that you use metadata-json-lint to automatically check your metadata.json file before running rspec.
You can output a basic resource coverage report with the following in
your spec_helper.rb
RSpec.configure do |c|
c.after(:suite) do
RSpec::Puppet::Coverage.report!
end
end
This checks which Puppet resources have been explicitly checked as part of the current test run and outputs both a coverage percentage and a list of untouched resources.
A desired code coverage level can be provided. If this level is not achieved, a test failure will be raised. This can be used with a CI service, such as Jenkins or Bamboo, to enforce code coverage. The following example requires the code coverage to be at least 95%.
RSpec.configure do |c|
c.after(:suite) do
RSpec::Puppet::Coverage.report!(95)
end
end
Resources declared outside of the module being tested (i.e. forge dependencies) are automatically removed from the coverage report. There is one exception for this though: prior to Puppet 4.6.0, resources created by functions (create_resources(), ensure_package(), etc) did not have the required information in them to determine which manifest they came from and so can not be excluded from the coverage report.
-
puppetlabs_spec_helper: shared spec helpers to setup puppet
-
rspec-puppet-augeas: RSpec tests for Augeas resources inside Puppet manifests
-
jimdo-rspec-puppet-helpers: Tests the contents of a file with a source
-
puppet-catalog_rspec: Ease development of specs by dumping the Puppet catalog as RSpec code
-
Fact providers
- rspec-puppet-facts: Simplify your unit tests by looping on every supported Operating System and populating facts.
- rspec-puppet-osmash: Provides Operation System hashes and validations for rspec-puppet
- puppet_spec_facts: Gem to provide puppet fact hashes for rspec-puppet testing
For a list of other module development tools see https://puppet.community/plugins/