rspec-system-puppet 0.3.4 → 1.0.0

data/README.md

@@ -1,3 +1,163 @@
 # rspec-system-puppet
 
-`rspec-system-puppet` is a Puppet plugin for [rspec-system](https://rubygems.org/gems/rspec-system).
+`rspec-system-puppet` is a Puppet plugin for [rspec-system](https://rubygems.org/gems/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](https://rubygems.org/gems/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.1.5 or greater
+* VirtualBox 4.2.10 or greater
+* RVM or RBenv (current instructions are based on RVM however)
+
+In your existing Puppet module project, create a `.nodeset.yml` with the following contents:
+
+    ---
+    default_set: 'centos-64-x64'
+    sets:
+      'centos-59-x64':
+        nodes:
+          "main.foo.vm":
+            prefab: 'centos-59-x64'
+      'centos-64-x64':
+        nodes:
+          "main.foo.vm":
+            prefab: 'centos-64-x64'
+      'fedora-18-x64':
+        nodes:
+          "main.foo.vm":
+            prefab: 'fedora-18-x64'
+      'debian-607-x64':
+        nodes:
+          "main.foo.vm":
+            prefab: 'debian-607-x64'
+      'debian-70rc1-x64':
+        nodes:
+          "main.foo.vm":
+            prefab: 'debian-70rc1-x64'
+      'ubuntu-server-10044-x64':
+        nodes:
+          "main.foo.vm":
+            prefab: 'ubuntu-server-10044-x64'
+      'ubuntu-server-12042-x64':
+        nodes:
+          "main.foo.vm":
+            prefab: 'ubuntu-server-12042-x64'
+
+Make sure you have a `Gemfile` like the one below, this includes `rspec-puppet` test content as well:
+
+    source 'https://rubygems.org'
+
+    group :development, :test do
+      gem 'rake'
+      gem 'puppetlabs_spec_helper', :require => false
+      gem 'rspec-system-puppet', '~>0.3.1'
+      gem 'puppet-lint', '~> 0.3.2'
+    end
+
+    if puppetversion = ENV['PUPPET_GEM_VERSION']
+      gem 'puppet', puppetversion, :require => false
+    else
+      gem 'puppet', :require => false
+    end
+
+Create a `Rakefile` like so:
+
+    require 'rubygems'
+    require 'bundler/setup'
+
+    Bundler.require :default
+
+    require 'rspec/core/rake_task'
+    require 'puppetlabs_spec_helper/rake_tasks'
+    require 'rspec-system/rake_task'
+
+    task :default do
+      sh %{rake -T}
+    end
+
+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'
+
+    RSpec.configure do |c|
+      # Project root for the firewall code
+      proj_root = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+      # Enable colour in Jenkins
+      c.tty = true
+
+      # This is where we 'setup' the nodes before running our tests
+      c.system_setup_block = proc do
+        # TODO: find a better way of importing this into this namespace
+        include RSpecSystemPuppet::Helpers
+
+        # Install puppet
+        puppet_install
+        puppet_master_install
+
+        # Replace mymodule with your module name
+        puppet_module_install(:source => proj_root, :module_name => 'mymodule')
+      end
+    end
+
+Now if you are using rspec-puppet, 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
+      # Here we create the var 'pp' to be later tested
+      let(pp) do
+        pp = <<-EOS
+          class { 'mymodule': }
+        EOS
+      end
+
+      it 'my class should work with no errors' do
+        # Run it once and make sure it doesn't bail with errors
+        puppet_apply(pp) do |r|
+          r[:exit_code].should_not eq(1)
+        end
+      end
+
+      it 'my class should be idempotent' do
+        # Run it again and make sure no changes occurred this time, proving idempotency
+        puppet_apply(pp) do |r|
+          r[:exit_code].should == 0
+        end
+      end
+    end
+
+Now start by creating a gemset environment for your run:
+
+    # rvm --create --ruby-version use ruby-1.9.3@mymodule
+
+Then grab the gemset bundle:
+
+    # bundle update
+
+Now you should be able to do:
+
+    # rake spec:system
+
+## Further Information
+
+* [API Documentation](http://rubydoc.info/gems/rspec-system-puppet/) - this provides the Ruby API docs for the Puppet Helpers. In particular look at the [Helpers](http://rubydoc.info/gems/rspec-system-puppet/RSpecSystemPuppet/Helpers) sub-class.
+* [rspec-system docs](http://rubydoc.info/gems/rspec-system) - 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](http://github.com/puppetlabs/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.
+
+## CI Integration
+
+For now consult the documentation for [rspec-system](http://rubygems.org/gems/rspec-system) for more details.

data/rspec-system-puppet.gemspec

@@ -2,7 +2,7 @@
 Gem::Specification.new do |s|
   # Metadata
   s.name        = "rspec-system-puppet"
-  s.version     = "0.3.4"
+  s.version     = "1.0.0"
   s.authors     = ["Ken Barber"]
   s.email       = ["ken@bob.sh"]
   s.homepage    = "https://github.com/kbarber/rspec-system-puppet"
@@ -16,5 +16,5 @@ Gem::Specification.new do |s|
 
   # Dependencies
   s.required_ruby_version = '>= 1.8.7'
-  s.add_runtime_dependency "rspec-system", '~> 0.3.0'
+  s.add_runtime_dependency "rspec-system", '~> 1.0.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rspec-system-puppet
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: 
   segments: 
+  - 1
   - 0
-  - 3
-  - 4
-  version: 0.3.4
+  - 0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Ken Barber
@@ -25,12 +25,12 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 19
+        hash: 23
         segments: 
+        - 1
         - 0
-        - 3
         - 0
-        version: 0.3.0
+        version: 1.0.0
   type: :runtime
   version_requirements: *id001
 description: