puppet 3.1.1 → 3.2.0.rc1

data/CONTRIBUTING.md

@@ -49,7 +49,7 @@ top of things.
 
 ## Submitting Changes
 
-* Sign the [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign).
+* Sign the [Contributor License Agreement](http://links.puppetlabs.com/cla).
 * Push your changes to a topic branch in your fork of the repository.
 * Submit a pull request to the repository in the puppetlabs organization.
 * Update your Redmine ticket to mark that you have submitted code and are ready for it to be reviewed.
@@ -59,7 +59,7 @@ top of things.
 
 * [More information on contributing](http://links.puppetlabs.com/contribute-to-puppet)
 * [Bug tracker (Redmine)](http://projects.puppetlabs.com)
-* [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign)
+* [Contributor License Agreement](http://links.puppetlabs.com/cla)
 * [General GitHub documentation](http://help.github.com/)
 * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
 * #puppet-dev IRC channel on freenode.org

data/Gemfile

@@ -1,30 +1,42 @@
-source :rubygems
+source "https://rubygems.org"
 
-def location_for(place)
+def location_for(place, fake_version = nil)
   if place =~ /^(git:[^#]*)#(.*)/
-    [{ :git => $1, :branch => $2, :require => false }]
+    [fake_version, { :git => $1, :branch => $2, :require => false }].compact
   elsif place =~ /^file:\/\/(.*)/
-    ['>= 0', { :path => File.expand_path($1), :require => false }]
+    [fake_version, { :path => File.expand_path($1), :require => false }].compact
   else
     [place, { :require => false }]
   end
 end
 
-group(:development, :test) do
-  gem "puppet", *location_for('file://.')
-  gem "facter", *location_for(ENV['FACTER_LOCATION'] || '~> 1.6')
-  gem "hiera", *location_for(ENV['HIERA_LOCATION'] || '~> 1.0')
+# C Ruby (MRI) or Rubinius, but NOT Windows
+platforms :ruby do
+  gem 'pry', :group => :development
+  gem 'yard', :group => :development
+  gem 'redcarpet', :group => :development
+  gem "racc", "~> 1.4", :group => :development
+end
+
+gem "puppet", *location_for("file://#{File.dirname(__FILE__)}", '99.0.0')
+gem "facter", *location_for(ENV['FACTER_LOCATION'] || '~> 1.6')
+gem "hiera", *location_for(ENV['HIERA_LOCATION'] || '~> 1.0', '99.0.0')
+gem "rake", :require => false
+gem "rspec", "~> 2.11.0", :require => false
+gem "mocha", "~> 0.10.5", :require => false
+gem "rgen", "0.6.1", :require => false
+
+gem "yarjuf", "~> 1.0"
+
+group(:extra) do
   gem "rack", "~> 1.4", :require => false
-  gem "rake", :require => false
-  gem "rspec", "~> 2.11.0", :require => false
-  gem "mocha", "~> 0.10.5", :require => false
-  gem "activerecord", *location_for('~> 3.0.7')
-  gem "couchrest", *location_for('~> 1.0')
-  gem "net-ssh", *location_for('~> 2.1')
-  gem "puppetlabs_spec_helper"
-  gem "sqlite3"
-  gem "stomp"
-  gem "tzinfo"
+  gem "activerecord", '~> 3.0.7', :require => false
+  gem "couchrest", '~> 1.0', :require => false
+  gem "net-ssh", '~> 2.1', :require => false
+  gem "puppetlabs_spec_helper", :require => false
+  gem "sqlite3", :require => false
+  gem "stomp", :require => false
+  gem "tzinfo", :require => false
 end
 
 platforms :mswin, :mingw do
@@ -37,8 +49,9 @@ platforms :mswin, :mingw do
   gem "win32-service", "~> 0.7.2", :require => false
   gem "win32-taskscheduler", "~> 0.2.2", :require => false
   gem "win32console", "~> 1.3.2", :require => false
-  gem "windows-api", "~> 0.4.1", :require => false
+  gem "windows-api", "~> 0.4.2", :require => false
   gem "windows-pr", "~> 1.2.1", :require => false
+  gem "minitar", "~> 0.5.4", :require => false
 end
 
 if File.exists? "#{__FILE__}.local"

data/README_DEVELOPER.md

@@ -149,7 +149,7 @@ with the following actions.  The trick is to symlink `gems` to `src`.
     $ cd /workspace
     $ ln -s src gems
     $ mkdir specifications
-    $ pushd specifications; ln -s ../gems/puppet/puppet.gemspec; popd
+    $ pushd specifications; ln -s ../gems/puppet/puppet.gemspec; ln -s ../gems/puppet/lib; popd
     $ export GEM_PATH="/workspace:${GEM_PATH}"
     $ gem list puppet
 
@@ -157,6 +157,13 @@ This should list out
 
     puppet (2.7.19)
 
+The final directory structure should look like this:
+
+    /workspace/src --- git working directory
+              /gems -> src
+              /specifications/puppet.gemspec -> ../gems/puppet/puppet.gemspec
+                             /lib -> ../gems/puppet/lib
+
 ## Bundler ##
 
 With a source checkout of Puppet properly setup as a gem, dependencies can be
@@ -177,6 +184,308 @@ installed using [Bundler](http://gembundler.com/)
     Using bundler (1.1.5)
     Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
 
+# Running Tests #
+
+Puppet Labs projects use a common convention of using Rake to run unit tests.
+The tests can be run with the following rake task:
+
+    rake spec
+    # Or if using Bundler
+    bundle exec rake spec
+
+This allows the Rakefile to set up the environment beforehand if needed. This
+method is how the unit tests are run in [Jenkins](https://jenkins.puppetlabs.com).
+
+Under the hood Puppet's tests use `rspec`.  To run all of them, you can directly
+use 'rspec':
+
+    rspec
+    # Or if using Bundler
+    bundle exec rspec
+
+To run a single file's worth of tests (much faster!), give the filename, and use
+the nested format to see the descriptions:
+
+    rspec spec/unit/ssl/host_spec.rb --format nested
+
+# A brief introduction to testing in Puppet
+
+Puppet relies heavily on automated testing to ensure that Puppet behaves as
+expected and that new features don't interfere with existing behavior. There are
+three primary sets of tests that Puppet uses: _unit tests_, _integration tests_,
+and _acceptance tests_.
+
+- - -
+
+Unit tests are used to test the individual components of Puppet to ensure that
+they function as expected in isolation. Unit tests are designed to hide the
+actual system implementations and provide canned information so that only the
+intended behavior is tested, rather than the targeted code and everything else
+connected to it. Unit tests should never affect the state of the system that's
+running the test.
+
+- - -
+
+Integration tests serve to test different units of code together to ensure that
+they interact correctly. While individual methods might perform correctly, when
+used with the rest of the system they might fail, so integration tests are a
+higher level version of unit tests that serve to check the behavior of
+individual subsystems.
+
+All of the unit and integration tests for Puppet are kept in the spec/ directory.
+
+- - -
+
+Acceptance tests are used to test high level behaviors of Puppet that deal with
+a number of concerns and aren't easily tested with normal unit tests. Acceptance
+tests function by changing system state and checking the system after
+the fact to make sure that the intended behavior occurred. Because of this
+acceptance tests can be destructive, so the systems being tested should be
+throwaway systems.
+
+All of the acceptance tests for Puppet are kept in the acceptance/tests/
+directory.
+
+## Puppet Continuous integration
+
+  * Travis-ci (unit tests only): https://travis-ci.org/puppetlabs/puppet/
+  * Jenkins (unit and acceptance tests): https://jenkins.puppetlabs.com/view/Puppet%20FOSS/
+
+## RSpec
+
+Puppet uses RSpec to perform unit and integration tests. RSpec handles a number
+of concerns to make testing easier:
+
+  * Executing examples and ensuring the actual behavior matches the expected behavior (examples)
+  * Grouping tests (describe and contexts)
+  * Setting up test environments and cleaning up afterwards (before and after blocks)
+  * Isolating tests (mocks and stubs)
+
+#### Examples and expectations
+
+At the most basic level, RSpec provides a framework for executing tests (which
+are called examples) and ensuring that the actual behavior matches the expected
+behavior (which are done with expectations)
+
+```ruby
+# This is an example; it sets the test name and defines the test to run
+specify "one equals one" do
+  # 'should' is an expectation; it adds a check to make sure that the left argument
+  # matches the right argument
+  1.should == 1
+end
+
+# Examples can be declared with either 'it' or 'specify'
+it "one doesn't equal two" do
+  1.should_not == 2
+end
+```
+
+Good examples generally do as little setup as possible and only test one or two
+things; it makes tests easier to understand and easier to debug.
+
+More complete documentation on expectations is available at https://www.relishapp.com/rspec/rspec-expectations/docs
+
+### Example groups
+
+Example groups are fairly self explanatory; they group similar examples into a
+set.
+
+```ruby
+describe "the number one" do
+
+  it "is larger than zero" do
+    1.should be > 0
+  end
+
+  it "is an odd number" do
+    1.odd?.should be true
+  end
+
+  it "is not nil" do
+    1.should_not be_nil
+  end
+end
+```
+
+Example groups have a number of uses that we'll get into later, but one of the
+simplest demonstrations of what they do is how they help to format
+documentation:
+
+```
+rspec ex.rb --format documentation
+
+the number one
+  is larger than zero
+  is an odd number
+  is not nil
+
+Finished in 0.00516 seconds
+3 examples, 0 failures
+```
+
+### Setting up and tearing down tests
+
+Examples may require some setup before they can run, and might need to clean up
+afterwards. `before` and `after` blocks can be used before this, and can be
+used inside of example groups to limit how many examples they affect.
+
+```ruby
+
+describe "something that could warn" do
+  before :each do
+    # Disable warnings for this test
+    $VERBOSE = nil
+  end
+
+  after do
+    # Enable warnings afterwards
+    $VERBOSE = true
+  end
+
+  it "doesn't generate a warning" do
+    MY_CONSTANT = 1
+    # reassigning a normally prints out 'warning: already initialized constant FOO'
+    MY_CONSTANT = 2
+  end
+end
+```
+
+### Setting up helper data
+
+Some examples may require setting up data before hand and making it available to
+tests. RSpec provides helper methods with the `let` method call that can be used
+inside of tests.
+
+```ruby
+describe "a helper object" do
+  # This creates an array with three elements that we can retrieve in tests. A
+  # new copy will be made for each test.
+  let(:my_helper) do
+    ['foo', 'bar', 'baz']
+  end
+
+  it "should be an array" do
+    my_helper.should be_a_kind_of Array
+  end
+
+  it "should have three elements" do
+    my_helper.should have(3).items
+  end
+end
+```
+
+Like `before` blocks, helper objects like this are used to avoid doing a lot of
+setup in individual examples and share setup between similar tests.
+
+### Isolating tests with stubs
+
+RSpec allows you to provide fake data during testing to make sure that
+individual tests are only running the code being tested. You can stub out entire
+objects, or just stub out individual methods on an object. When a method is
+stubbed the method itself will never be called.
+
+While RSpec comes with its own stubbing framework, Puppet uses the Mocha
+framework.
+
+A brief usage guide for Mocha is available at http://gofreerange.com/mocha/docs/#Usage,
+and an overview of Mocha expectations is available at http://gofreerange.com/mocha/docs/Mocha/Expectation.html
+
+```ruby
+describe "stubbing a method on an object" do
+  let(:my_helper) do
+    ['foo', 'bar', 'baz']
+  end
+
+  it 'should have three items before being stubbed' do
+    my_helper.size.should == 3
+  end
+
+  describe 'when stubbing the size' do
+    before do
+      my_helper.stubs(:size).returns 10
+    end
+
+    it 'should have the stubbed value for size' do
+      my_helper.size.should == 10
+    end
+  end
+end
+```
+
+Entire objects can be stubbed as well.
+
+```ruby
+describe "stubbing an object" do
+  let(:my_helper) do
+    stub(:not_an_array, :size => 10)
+  end
+
+  it 'should have the stubbed size'
+    my_helper.size.should == 10
+  end
+end
+```
+
+### Adding expectations with mocks
+
+It's possible to combine the concepts of stubbing and expectations so that a
+method has to be called for the test to pass (like an expectation), and can
+return a fixed value (like a stub).
+
+```ruby
+describe "mocking a method on an object" do
+  let(:my_helper) do
+    ['foo', 'bar', 'baz']
+  end
+
+  describe "when mocking the size" do
+    before do
+      my_helper.expects(:size).returns 10
+    end
+
+    it "adds an expectation that a method was called" do
+      my_helper.size
+    end
+  end
+end
+```
+
+Like stubs, entire objects can be mocked.
+
+```ruby
+describe "mocking an object" do
+  let(:my_helper) do
+    mock(:not_an_array)
+  end
+
+  before do
+    not_an_array.expects(:size).returns 10
+  end
+
+  it "adds an expectation that the method was called" do
+    not_an_array.size
+  end
+end
+```
+
+### RSpec references
+
+  * RSpec core docs: https://www.relishapp.com/rspec/rspec-core/docs
+  * RSpec guidelines with Ruby: http://betterspecs.org/
+
+### Puppet-acceptance
+
+[puppet-acceptance]: https://github.com/puppetlabs/puppet-acceptance
+[test::unit]: http://test-unit.rubyforge.org/
+
+Puppet has a custom acceptance testing framework called
+[puppet-acceptance][puppet-acceptance] for running acceptance tests.
+Puppet-acceptance runs the tests by configuring one or more VMs, copying the
+test cases onto the VMs, performing the tests and collecting the results, and
+ensuring that the results match the intended behavior. It uses
+[test::unit][test::unit] to perform the actual assertions.
+
 # UTF-8 Handling #
 
 As Ruby 1.9 becomes more commonly used with Puppet, developers should be aware
@@ -242,23 +551,32 @@ include `ext/envpuppet.bat` will help.
 To quickly run Puppet from source, assuming you already have Ruby installed
 from [rubyinstaller.org](http://rubyinstaller.org).
 
-    gem install sys-admin win32-process win32-dir win32-taskscheduler --no-rdoc --no-ri
-    gem install win32-service --platform=mswin32 --no-rdoc --no-ri --version 0.7.1
-    net use Z: "\\vmware-host\Shared Folders" /persistent:yes
-    Z:
-    cd <path_to_puppet>
-    set PATH=%PATH%;Z:\<path_to_puppet>\ext
-    envpuppet puppet --version
+    C:\> cd C:\work\puppet
+    C:\work\puppet> set PATH=%PATH%;C:\work\puppet\ext
+    C:\work\puppet> envpuppet bundle install
+    C:\work\puppet> envpuppet puppet --version
     2.7.9
 
-Some spec tests are known to fail on Windows, e.g. no mount provider
-on Windows, so use the following rspec exclude filter:
+When writing a test that cannot possibly run on Windows, e.g. there is
+no mount type on windows, do the following:
+
+    describe Puppet::MyClass, :unless => Puppet.features.microsoft_windows? do
+      ..
+    end
+
+If the test doesn't currently pass on Windows, e.g. due to on going porting, then use an rspec conditional pending block:
+
+    pending("porting to Windows", :if => Puppet.features.microsoft_windows?) do
+      <example1>
+    end
+
+    pending("porting to Windows", :if => Puppet.features.microsoft_windows?) do
+      <example2>
+    end
 
-    cd <path_to_puppet>
-    envpuppet rspec --tag ~fails_on_windows spec
+Then run the test as:
 
-This will give you a shared filesystem with your Mac and allow you to run
-Puppet directly from source without using install.rb or copying files around.
+    C:\work\puppet> envpuppet bundle exec rspec spec
 
 ## Common Issues ##