rspec-puppet 2.5.0 → 2.6.0

data/CHANGELOG.md

@@ -2,6 +2,92 @@
 All notable changes to this project will be documented in this file. This
 project adheres to [Semantic Versioning](http://semver.org/).
 
+## [2.6.0]
+
+The Windows parity release. rspec-puppet now officially supports Windows. A lot
+of work has been put in to support cross-platform tests, so that you can now
+test your Windows manifests on \*nix, and your \*nix manifests on Windows.
+
+### Changed
+
+ * Puppet settings are now applied as application overrides, allowing users to
+   call `Puppet.settings` directly to make changes to settings without them
+   getting clobbered by rspec-puppet.
+ * Improved support for setting up the `spec/fixtures/modules` link on Windows
+   by using directory junctions instead of symlinks, removing the need for
+   Administrator access.
+ * When testing for the absence of a parameter on a resource, the error message
+   now contains the value(s) of the parameter(s) that should be undefined.
+ * When testing a defined type, the defined type being tested is no longer part
+   of the coverage report.
+ * The cached catalogue will now be invalidated when hiera-puppet-helper users
+   change their `hiera_data` value.
+ * Multiple instances of a defined type can now be tested at once by providing
+   an array of strings with `let(:title)`.
+ * Explicitly specifying the type of an example group (`:type => :class`) now
+   takes precedence over the type inferred from the spec file's location.
+ * The manifest specified in `RSpec.configuration.manifest` (path to `site.pp`
+   for Puppet < 4.x) is now imported if specified on Puppet >= 4.x.
+ * Puppet functions called when testing a Puppet function now get executed in
+   the same scope as parent function.
+
+### Added
+
+ * The module is now automatically linked into `spec/fixtures/modules` at the
+   start of the rspec-puppet run.
+ * CI testing of PRs on Windows via Appveyor.
+ * Support for setting node parameters (mocking the behaviour of an ENC or
+   Puppet Enterprise Console) using `let(:node_params)`.
+ * Support for injecting Puppet code at the end of the test code using
+   `let(:post_condition)`.
+ * Resource coverage reports for `host` specs.
+ * Puppet functions that take a lambda as a parameter can now be tested by
+   chaining `with_lambda` to the `run` matcher.
+ * Facts and trusted facts are now available when testing Puppet functions.
+ * Hiera configuration can now be specified when testing Puppet functions using
+   `let(:hiera_config)`.
+ * Trusted facts (`$trusted[]`) can now be specified in
+   `RSpec.configuration.default_trusted_facts` or by `let(:trusted_facts)`.
+ * `:default` is now a supported parameter value when passed in by
+   `let(:params)`.
+ * Support for testing Puppet data type aliases.
+
+### Fixed
+
+ * Facts generated from the node name (as set by `let(:node)`) now take
+   precedence over the values specified in `RSpec.configuration.default_facts`
+   or by `let(:facts)`.
+ * Only fact names will now be converted to lowercase, not the fact values.
+ * Matchers now support resources where the namevar has a different value to
+   the title.
+ * Resources created outside of the module being tested by functions like
+   `create_resources` or `ensure_package` are no longer present in the coverage
+   report from Puppet 4.6 onwards.
+ * Guards have been put in place to prevent the possibility of rspec-puppet
+   getting stuck in an infinite recursion when testing the relationships
+   between resources.
+ * A full `spec/spec_helper.rb` file is now written out by `rspec-puppet-init`
+   to fix the `fixture_path` issue on new modules.
+ * The namevar of a resources is no longer taken into account when testing the
+   exact parameters of the resource with `only_with`.
+ * Minimum resource coverage check for RSpec <= 3.2.
+ * Resource parameters that take a hash as their value will no longer have that
+   hash converted into an array.
+ * Testing the value of a parameter with a Proc that returns `nil` now works as
+   expected.
+ * When testing Puppet functions, the function name is no longer automatically
+   coverted to lowercase.
+ * The value of `$::environment` is now forced to be a string as expected for
+   Puppet 4.0 - 4.3.
+ * app\_management is no longer enabled by rspec-puppet for Puppet >= 5.0 as it
+   is already enabled by default.
+ * Failing to provide parameters when testing an application now raises the
+   correct exception (`ArgumentError`).
+ * Ruby symbols in nested hashes or arrays are now converted into strings when
+   passed in by `let(:params)`.
+ * Namespaced resources are now correctly capitalised when being added to the
+   resource coverage filter.
+
 ## [2.5.0]
 
 Headline features are app management, nested hashes in params, and testing for "internal" functions.

data/README.md

@@ -1,5 +1,5 @@
 # RSpec tests for your Puppet manifests & modules
-[![Build Status](https://travis-ci.org/rodjek/rspec-puppet.png)](https://travis-ci.org/rodjek/rspec-puppet)
+[![Build Status](https://travis-ci.org/rodjek/rspec-puppet.svg?branch=master)](https://travis-ci.org/rodjek/rspec-puppet)
 [![Coverage Status](https://coveralls.io/repos/rodjek/rspec-puppet/badge.svg?branch=master)](https://coveralls.io/r/rodjek/rspec-puppet?branch=master)
 
 ## Installation
@@ -14,44 +14,209 @@
 
 When you start out on a new module, run `rspec-puppet-init` to create the necessary files to configure rspec-puppet for your module's tests.
 
+## Configure manifests for Puppet 4
+
+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:
+```ruby
+# /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
+```
+
+## Configuration
+
+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
+```
+
+#### manifest\_dir
+Type   | Default  | Puppet Version(s)
+------ | -------- | -----------------
+String | Required | 2.x, 3.x
+
+The path to the directory containing your basic manifests like `site.pp`.
+
+#### module\_path
+Type   | Default  | Puppet Version(s)
+------ | -------- | -----------------
+String | Required | 2.x, 3.x, 4.x
+
+The path to the directory containing your Puppet modules.
+
+#### default\_facts
+Type | Default | Puppet Version(s)
+---- | ------- | -----------------
+Hash | `{}`    | 2.x, 3.x, 4.x
+
+A hash of default facts that should be used for all the tests.
+
+#### hiera\_config
+Type   | Default       | Puppet Version(s)
+------ | ------------- | -----------------
+String | `"/dev/null"` | 3.x, 4.x
+
+The path to your `hiera.yaml` file (if used).
+
+#### default\_node\_params
+Type | Default | Puppet Version(s)
+---- | ------- | -----------------
+Hash | `{}`    | 4.x
+
+A hash of default node parameters that should be used for all the tests.
+
+#### default\_trusted\_facts
+Type | Default | Puppet Version(s)
+---- | ------- | -----------------
+Hash | `{}`    | 4.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`.
+
+#### trusted\_node\_data
+Type    | Default | Puppet Version(s)
+------- | ------- | -----------------
+Boolean | `false` | 3.x, 4.x
+
+Configures rspec-puppet to use the `$trusted` hash when compiling the
+catalogues.
+
+#### confdir
+Type   | Default         | Puppet Version(s)
+------ | --------------- | -----------------
+String | `"/etc/puppet"` | 2.x, 3.x, 4.x
+
+The path to the main Puppet configuration directory.
+
+#### config
+Type   | Default                | Puppet Version(s)
+------ | ---------------------- | -----------------
+String | Puppet's default value | 2.x, 3.x, 4.x
+
+The path to `puppet.conf`.
+
+#### manifest
+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`.
+
+#### template\_dir
+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.
+
+#### environmentpath
+Type   | Default                               | Puppet Version(s)
+------ | ------------------------------------- | -----------------
+String | `"/etc/puppetlabs/code/environments"` | 4.x
+
+The search path for environment directories.
+
+#### parser
+Type   | Default     | Puppet Version(s)
+------ | ----------- | -----------------
+String | `"current"` | 3.x
+
+This switches between the 3.x (`current`) and 4.x (`future`) parsers.
+
+#### ordering
+Type   | Default        | Puppet Version(s)
+------ | -------------- | -----------------
+String | `"title-hash"` | 3.x, 4.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.
+
+#### strict\_variables
+Type    | Default | Puppet Version(s)
+------- | ------- | -----------------
+Boolean | `false` | 3.x, 4.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`).
+
+#### stringify\_facts
+Type    | Default | Puppet Version(s)
+------- | ------- | -----------------
+Boolean | `true`  | 3.x, 4.x
+
+Makes rspec-puppet coerce all the fact values into strings (matching the
+behaviour of older versions of Puppet).
+
+#### enable\_pathname\_stubbing
+Type    | Default | Puppet Version(s)
+------- | ------- | -----------------
+Boolean |`false`  | 2.x, 3.x, 4.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?`.
+
 ## Naming conventions
 
 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
-           |
-           +-- hosts
-                 |
-                 +-- <host_name>_spec.rb
+    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
 
 ## Example groups
 
@@ -80,6 +245,10 @@ describe 'mytype', :type => :type do
   ...
 end
 
+describe 'My::TypeAlias', :type => :type_alias do
+  ...
+end
+
 describe 'myhost.example.com', :type => :host do
   ...
 end
@@ -327,6 +496,20 @@ When testing custom types, the `be_valid_type` matcher provides a range of expec
 * `with_features(<feature_list>)`: check that the specified features are available
 * `with_set_attributes(<param_value_hash>)`: check that the specified attributes are set
 
+#### Type alias matchers
+
+When testing type aliases, the `allow_value` and `allow_values` matchers are used to check if the
+alias accepts particular values or not:
+
+
+```ruby
+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
+```
+
 ### Writing tests
 
 #### Basic test structure
@@ -449,6 +632,61 @@ end
 Any facts you provide with `let(:facts)` in a spec will automatically be merged on top
 of the default facts.
 
+#### Specifying top-scope variables that should be available to your manifest
+
+You can create top-scope variables much in the same way as an ENC.
+
+
+```ruby
+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:
+
+``` ruby
+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.
+
+#### Specifying extra code to load (pre-conditions)
+
+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.
+
+```ruby
+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.
+
+#### Specifying extra code to load (post-conditions)
+
+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.
+
+```ruby
+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.
+
 #### Specifying the path to find your modules
 
 I recommend setting a default module path by adding the following code to your
@@ -466,6 +704,31 @@ However, if you want to specify it in each example, you can do so
 let(:module_path) { '/path/to/your/module/dir' }
 ```
 
+#### Specifying trusted facts
+
+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']`
+
+```ruby
+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:
+
+```ruby
+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
+```
+
 #### Testing Exported Resources
 
 You can test if a resource was exported from the catalogue by using the
@@ -584,6 +847,16 @@ it 'something' do
 end
 ```
 
+#### Passing lambdas to the function
+
+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.
+
+```ruby
+it { is_expected.to run.with_lambda { |x| x * 2 }
+```
+
 #### Testing the results of the function
 
 You can test the result of a function (if it produces one) using either the
@@ -709,6 +982,9 @@ spec/fixtures/hiera/hiera.yaml
   - 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](https://github.com/voxpupuli/metadata-json-lint)
+to automatically check your metadata.json file before running rspec.
 
 ## Producing coverage reports
 
@@ -737,6 +1013,13 @@ RSpec.configure do |c|
 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.
+
 ## Related projects
 
 * [puppetlabs_spec_helper](https://github.com/puppetlabs/puppetlabs_spec_helper): shared spec helpers to setup puppet

data/lib/rspec-puppet/adapters.rb

@@ -2,19 +2,8 @@ module RSpec::Puppet
   module Adapters
 
     class Base
-      # Set up all Puppet settings applicable for this Puppet version
-      #
-      # @param example_group [RSpec::Core::ExampleGroup] The RSpec context to use for local settings
-      # @return [void]
-      def setup_puppet(example_group)
-        settings_map.each do |puppet_setting, rspec_setting|
-          set_setting(example_group, puppet_setting, rspec_setting)
-        end
-        @environment_name = example_group.environment
-      end
-
-      # Set up a specific Puppet setting.
-      # configuration setting.
+      # Set up all Puppet settings applicable for this Puppet version as
+      # application defaults.
       #
       # Puppet setting values can be taken from the global RSpec configuration, or from the currently
       # executing RSpec context. When a setting is specified both in the global configuration and in
@@ -48,21 +37,36 @@ module RSpec::Puppet
       #   end
       #
       # @param example_group [RSpec::Core::ExampleGroup] The RSpec context to use for local settings
-      # @param puppet_setting [Symbol] The name of the Puppet setting to configure
-      # @param rspec_setting [Symbol] The name of the RSpec context specific or global setting to use
       # @return [void]
-      def set_setting(example_group, puppet_setting, rspec_setting)
-        if example_group.respond_to?(rspec_setting)
-          value = example_group.send(rspec_setting)
+      def setup_puppet(example_group)
+        settings = settings_map.map do |puppet_setting, rspec_setting|
+          [puppet_setting, get_setting(example_group, rspec_setting)]
+        end.flatten
+        default_hash = {:confdir => '/dev/null', :vardir => '/dev/null' }
+        if defined?(Puppet::Test::TestHelper) && Puppet::Test::TestHelper.respond_to?(:app_defaults_for_tests, true)
+          default_hash.merge!(Puppet::Test::TestHelper.send(:app_defaults_for_tests))
+        end
+        settings_hash = default_hash.merge(Hash[*settings])
+
+        if Puppet.settings.respond_to?(:initialize_app_defaults)
+          Puppet.settings.initialize_app_defaults(settings_hash)
         else
-          value = RSpec.configuration.send(rspec_setting)
+          # Set settings the old way for Puppet 2.x, because that's how
+          # they're defaulted in that version of Puppet::Test::TestHelper and
+          # we won't be able to override them otherwise.
+          settings_hash.each do |setting, value|
+            Puppet.settings[setting] = value
+          end
         end
-        begin
-          Puppet[puppet_setting] = value
-        rescue ArgumentError
-          # TODO: this silently swallows errors when applying settings that the current
-          # Puppet version does not accept, which means that user specified settings
-          # are ignored. This may lead to suprising behavior for users.
+
+        @environment_name = example_group.environment
+      end
+
+      def get_setting(example_group, rspec_setting)
+        if example_group.respond_to?(rspec_setting)
+          example_group.send(rspec_setting)
+        else
+          RSpec.configuration.send(rspec_setting)
         end
       end
 
@@ -140,11 +144,15 @@ module RSpec::Puppet
           [:environmentpath, :environmentpath],
           [:hiera_config, :hiera_config],
           [:strict_variables, :strict_variables],
+          [:manifest, :manifest],
         ])
       end
 
       def catalog(node, exported)
         node.environment = current_environment
+        # Override $::environment to workaround PUP-5835, where Puppet otherwise
+        # stores a symbol for the parameter
+        node.parameters['environment'] = current_environment.name.to_s if node.parameters['environment'] != node.parameters['environment'].to_s
         super
       end
 
@@ -198,15 +206,15 @@ module RSpec::Puppet
 
     def self.get
       [
-        [4.0, Adapter4X],
-        [3.0, Adapter3X],
-        [2.7, Adapter27]
+        ['4.0', Adapter4X],
+        ['3.0', Adapter3X],
+        ['2.7', Adapter27]
       ].each do |(version, klass)|
-        if Puppet.version.to_f >= version
+        if Puppet::Util::Package.versioncmp(Puppet.version, version) >= 0
           return klass.new
         end
       end
-      raise "Puppet version #{Puppet.version.to_f} is not supported."
+      raise "Puppet version #{Puppet.version} is not supported."
     end
   end
 end

data/lib/rspec-puppet/coverage.rb

@@ -1,3 +1,14 @@
+unless defined?(RSpec::Core::NullReporter)
+  module RSpec::Core
+    class NullReporter
+      def self.method_missing(*)
+        # ignore
+      end
+      private_class_method :method_missing
+    end
+  end
+end
+
 module RSpec::Puppet
   class Coverage
 
@@ -6,7 +17,8 @@ module RSpec::Puppet
     class << self
       extend Forwardable
       def_delegators(:instance, :add, :cover!, :report!,
-                     :filters, :add_filter, :add_from_catalog)
+                     :filters, :add_filter, :add_from_catalog,
+                     :results)
 
       attr_writer :instance
 
@@ -17,7 +29,7 @@ module RSpec::Puppet
 
     def initialize
       @collection = {}
-      @filters = ['Stage[main]', 'Class[Settings]', 'Class[main]']
+      @filters = ['Stage[main]', 'Class[Settings]', 'Class[main]', 'Node[default]']
     end
 
     def add(resource)
@@ -27,12 +39,21 @@ module RSpec::Puppet
     end
 
     def add_filter(type, title)
-      @filters << "#{type.capitalize}[#{title.capitalize}]"
+      def capitalize_name(name)
+        name.split('::').map { |subtitle| subtitle.capitalize }.join('::')
+      end
+
+      type = capitalize_name(type)
+      if type == 'Class'
+        title = capitalize_name(title)
+      end
+
+      @filters << "#{type}[#{title}]"
     end
 
     # add all resources from catalog declared in module test_module
     def add_from_catalog(catalog, test_module)
-      coverable_resources = catalog.to_a.select { |resource| !filter_resource?(resource, test_module) }
+      coverable_resources = catalog.to_a.reject { |resource| !test_module.nil? && filter_resource?(resource, test_module) }
       coverable_resources.each do |resource|
         add(resource)
       end
@@ -82,8 +103,12 @@ module RSpec::Puppet
         coverage_results = coverage_test.example("Must be at least #{coverage_desired}% of code coverage") {
           expect( coverage_actual.to_f ).to be >= coverage_desired.to_f
         }
-        coverage_test.run
-        passed = coverage_results.execution_result.status == :passed
+        coverage_test.run(RSpec::Core::NullReporter)
+        passed = if coverage_results.execution_result.respond_to? :status then
+                   coverage_results.execution_result.status == :passed
+                 else
+                   coverage_results.execution_result[:status] == 'passed'
+                 end
 
         RSpec.configuration.reporter.example_failed coverage_results unless passed
       else