rspec-puppet 2.11.0 → 4.0.0

data/README.md

@@ -1,16 +1,17 @@
 # RSpec tests for your Puppet manifests & modules
-[![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)
+
+[![Code Owners](https://img.shields.io/badge/owners-DevX--team-blue)](https://github.com/puppetlabs/rspec-puppet/blob/main/CODEOWNERS)
+![ci](https://github.com/puppetlabs/rspec-puppet/actions/workflows/ci.yml/badge.svg)
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/puppetlabs/rspec-puppet)
 
 #### Table of Contents
 
 * [Installation](#installation)
 * [Starting out with a new module](#starting-out-with-a-new-module)
-* [Configure manifests for Puppet 4](#configure-manifests-for-puppet-4)
 * [Configuration](#configuration)
 * [Naming conventions](#naming-conventions)
 * [Example groups](#example-groups)
-* [Defined Types, Classes & Applications](#defined-types-classes--applications)
+* [Defined Types and Classes](#defined-types-and-classes)
 * [Functions](#functions)
 * [Hiera integration](#hiera-integration)
 * [Producing coverage reports](#producing-coverage-reports)
@@ -20,35 +21,17 @@
 
     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.
-
 ## Starting out with a new module
 
 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.
 
-
-## 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__))
 
+```ruby
 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.module_path     = File.join(File.dirname(File.expand_path(__FILE__)), 'fixtures', 'modules')
   c.environmentpath = File.join(Dir.pwd, 'spec')
-
+  c.manifest        = File.join(File.dirname(File.expand_path(__FILE__)), 'fixtures', 'manifests', 'site.pp')
   # Coverage generation
   c.after(:suite) do
     RSpec::Puppet::Coverage.report!
@@ -61,60 +44,59 @@ end
 rspec-puppet can be configured by modifying the `RSpec.configure` block in your
 `spec/spec_helper.rb` file.
 
-```
+```ruby
 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, 5.x
+String | Required | any
 
 The path to the directory containing your Puppet modules.
 
 #### default\_facts
 Type | Default | Puppet Version(s)
 ---- | ------- | ------------------
-Hash | `{}`    | 2.x, 3.x, 4.x, 5.x
+Hash | `{}`    | any
 
 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, 5.x
+String | `"/dev/null"` | any
 
 The path to your `hiera.yaml` file (if used).
 
+#### manifest
+Type   | Default                | Puppet Version(s)
+------ | ---------------------- | -----------------
+String | Puppet's default value | any
+
+Path to test manifest. Typically `spec/fixtures/manifests/site.pp`.
+
 #### default\_node\_params
 Type | Default | Puppet Version(s)
 ---- | ------- | -----------------
-Hash | `{}`    | 4.x, 5.x
+Hash | `{}`    | any
 
 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, 5.x
+Hash | `{}`    | any
 
 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`.
+(available in the manifests as the `$trusted` hash).
 
 #### trusted\_node\_data
 Type    | Default | Puppet Version(s)
 ------- | ------- | -----------------
-Boolean | `false` | >=3.4, 4.x, 5.x
+Boolean | `false` | any
 
 Configures rspec-puppet to use the `$trusted` hash when compiling the
 catalogues.
@@ -122,7 +104,7 @@ catalogues.
 #### trusted\_server\_facts
 Type    | Default | Puppet Version(s)
 ------- | ------- | -----------------
-Boolean | `false` | >=4.3, 5.x
+Boolean | `false` | any
 
 Configures rspec-puppet to use the `$server_facts` hash when compiling the
 catalogues.
@@ -130,62 +112,28 @@ catalogues.
 #### confdir
 Type   | Default         | Puppet Version(s)
 ------ | --------------- | ------------------
-String | `"/etc/puppet"` | 2.x, 3.x, 4.x, 5.x
+String | `"/etc/puppet"` | any
 
 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, 5.x
+String | Puppet's default value | any
 
 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, 5.x
+String | `"/etc/puppetlabs/code/environments"` | any
 
 The search path for environment directories.
 
-#### parser
-Type   | Default     | Puppet Version(s)
------- | ----------- | -----------------
-String | `"current"` | >= 3.2
-
-This switches between the 3.x (`current`) and 4.x (`future`) parsers.
-
-#### ordering
-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.
-
 #### strict\_variables
 Type    | Default | Puppet Version(s)
 ------- | ------- | -----------------
-Boolean | `false` | >= 3.5, 4.x, 5.x
+Boolean | `false` | any
 
 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
@@ -194,7 +142,7 @@ been defined (not including variables that have been explicitly set to
 #### stringify\_facts
 Type    | Default | Puppet Version(s)
 ------- | ------- | -----------------
-Boolean | `true`  | >= 3.3, 4.x, 5.x
+Boolean | `true`  | any
 
 Makes rspec-puppet coerce all the fact values into strings (matching the
 behaviour of older versions of Puppet).
@@ -202,7 +150,7 @@ behaviour of older versions of Puppet).
 #### enable\_pathname\_stubbing
 Type    | Default | Puppet Version(s)
 ------- | ------- | ------------------
-Boolean |`false`  | 2.x, 3.x, 4.x, 5.x
+Boolean |`false`  | any
 
 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
@@ -212,7 +160,7 @@ functions, etc) that use `Pathname#absolute?`.
 #### setup\_fixtures
 Type    | Default | Puppet Version(s)
 ------- | ------- | ------------------
-Boolean | `true`  | 2.x, 3.x, 4.x, 5.x
+Boolean | `true`  | any
 
 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.
@@ -220,7 +168,7 @@ module to `spec/fixtures/<module name>` at the beginning of the test run.
 #### derive\_node\_facts\_from\_nodename
 Type    | Default | Puppet Version(s)
 ------- | ------- | -----------------
-Boolean | `true`  | 2.x, 3.x, 4.x, 5.x
+Boolean | `true`  | any
 
 If `true`, rspec-puppet will override the `fdqn`, `hostname`, and `domain`
 facts with values that it derives from the node name (specified with
@@ -233,7 +181,7 @@ setting to `false`.
 #### facter\_implementation
 Type    | Default  | Puppet Version(s)
 ------- | -------- | -----------------
-String  | `facter` | 6.25+, 7.12+
+String  | `facter` | any
 
 Configures rspec-puppet to use a specific Facter implementation for running
 unit tests. If the `rspec` implementation is set and Puppet does not support
@@ -261,9 +209,6 @@ structure and naming convention.
            ├── defines/
            │     └── <define_name>_spec.rb
            │
-           ├── applications/
-           │     └── <application_name>_spec.rb
-           │
            ├── functions/
            │     └── <function_name>_spec.rb
            │
@@ -291,10 +236,6 @@ describe 'mydefine', :type => :define do
   ...
 end
 
-describe 'myapplication', :type => :application do
-  ...
-end
-
 describe 'myfunction', :type => :puppet_function do
   ...
 end
@@ -312,7 +253,7 @@ describe 'myhost.example.com', :type => :host do
 end
 ```
 
-## Defined Types, Classes & Applications
+## Defined Types and Classes
 
 ### Matchers
 
@@ -603,7 +544,7 @@ let(:title) { 'foo' }
 
 #### Specifying the parameters to pass to a resources or parameterised class
 
-Parameters of a defined type, class or application can be passed defining `:params` in a let,
+Parameters of a defined type or class can be passed defining `:params` in a let,
 and passing it a hash as seen below.
 
 ```ruby
@@ -617,8 +558,13 @@ be translated to `undef` when compiling. For example:
 let(:params) { {'user' => :undef, ...} }
 ```
 
+For passing a sensitive value you can use the sensitive function with a value in brackets. For example
+```ruby
+let(:params) { {'password' =>sensitive('secret') } }
+```
+
 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:
+you can pass the string as an argument to the `ref` helper:
 
 ```ruby
 let(:params) { 'require' => ref('Package', 'sudoku') }
@@ -630,18 +576,6 @@ Which translates to:
 mydefine { 'mytitle': require => Package['sudoku'] }
 ```
 
-Another example, for an application setup (when using `app_management`):
-
-```ruby
-let(:params) { { 'nodes' => { ref('Node', 'dbnode') => ref('Myapp::Mycomponent', 'myapp') } } }
-```
-
-Will translate to:
-
-```puppet
-site { myapp { 'myimpl': nodes => { Node['dbnode'] => Myapp::Mycomponent['myimpl'] } } }
-```
-
 #### Specifying the FQDN of the test node
 
 If the manifest you're testing expects to run on host with a particular name,
@@ -711,8 +645,6 @@ RSpec.configure do |c|
 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
@@ -764,7 +696,7 @@ 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
+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
@@ -789,8 +721,7 @@ end
 
 #### Specifying trusted external data
 
-When testing with Puppet >= 6.14, the trusted facts hash will have an additional `external`
-key for trusted external data.
+The trusted facts hash will have an `external` key for trusted external data.
 
 By default, the test environment contains no trusted external data (as usually obtained from
 trusted external commands and found in the `external` key). If you need to test against specific
@@ -832,46 +763,6 @@ You can also use `exported_resources` directly in a test:
 it { expect(exported_resources).to contain_file('foo') }
 ```
 
-#### Testing applications
-
-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:
-
-```ruby
-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. The `ref` 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.
-
 ## Functions
 
 ### Matchers
@@ -982,8 +873,17 @@ Some complex functions require access to the current parser's scope, e.g. for
 stubbing other parts of the system.
 
 ```ruby
-before(:each) { scope.expects(:lookupvar).with('some_variable').returns('some_value') }
-it { is_expected.to run.with_params('...').and_return('...') }
+context 'when called with top-scope vars foo and bar set' do
+  before do
+    # :lookupvar is the method on scope that puppet calls internally to
+    # resolve the value of a variable.
+    allow(scope).to receive(:lookupvar).and_call_original
+    allow(scope).to receive(:lookupvar).with('::foo').and_return('Hello')
+    allow(scope).to receive(:lookupvar).with('::bar').and_return('World')
+  end
+
+  it { is_expected.to run.with_params().and_return('Hello World') }
+end
 ```
 
 Note that this does not work when testing manifests which use custom functions. Instead,
@@ -1096,23 +996,26 @@ 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.
+are automatically removed from the coverage report.
 
 ## Related projects
 
 * [puppetlabs_spec_helper](https://github.com/puppetlabs/puppetlabs_spec_helper): shared spec helpers to setup puppet
-* [rspec-puppet-augeas](https://github.com/domcleal/rspec-puppet-augeas): RSpec tests for Augeas resources inside Puppet manifests
-* [jimdo-rspec-puppet-helpers](https://github.com/Jimdo/jimdo-rspec-puppet-helpers): Tests the contents of a file with a source
-* Ease development of specs
-  * [puppet-catalog_rspec](https://github.com/enterprisemodules/puppet-catalog_rspec): Dump the Puppet Catalog as RSpec code at compile time
-  * [create_specs](https://github.com/alexharv074/create_specs.git): A different implementation that takes a compiled catalog and writes out RSpec code with various options
 * Fact providers
-  * [rspec-puppet-facts](https://github.com/mcanevet/rspec-puppet-facts): Simplify your unit tests by looping on every supported Operating System and populating facts.
-  * [rspec-puppet-osmash](https://github.com/Aethylred/rspec-puppet-osmash): Provides Operation System hashes and validations for rspec-puppet
-  * [puppet_spec_facts](https://github.com/danieldreier/puppet_spec_facts): Gem to provide puppet fact hashes for rspec-puppet testing
+  * [rspec-puppet-facts](https://github.com/voxpupuli/rspec-puppet-facts): Simplify your unit tests by looping on every supported Operating System and populating facts.
+
+For a list of other module development tools see [DevX Tools](https://puppetlabs.github.io/content-and-tooling-team/tools/), or from our trusted Voxpupuli community [here](https://voxpupuli.org/plugins/).
+
+## Reporting bugs or incorrect results
+
+If you find a bug in Puppet Lint or its results, please create an issue in the repo issues tracker. Bonus points will be awarded if you also include a patch that fixes the issue.
+
+## Development
+
+If you run into an issue with this tool or would like to request a feature you can raise a PR with your suggested changes. Alternatively, you can raise a Github issue with a feature request or to report any bugs. Every other Tuesday the DevX team holds office hours in the Puppet Community Slack, where you can ask questions about this and any other supported tools. This session runs at 15:00 (GMT/BST) for about an hour.
+
+If you have problems getting this tool up and running, please contact Support.
+
+## Thank you
 
-For a list of other module development tools see https://puppet.community/plugins/
+Many thanks to the original author of rspec-puppet Tim Sharpe (@rodjek).

data/bin/rspec-puppet-init

@@ -1,16 +1,17 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-$:.unshift File.join(File.dirname(__FILE__), *%w[.. lib])
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), *%w[.. lib])
 
 require 'rspec-puppet'
 require 'optparse'
 
 options = {
-  :module_name => nil,
+  module_name: nil
 }
 
 OptionParser.new do |opts|
-  opts.banner = "Usage: rspec-puppet-init [options]"
+  opts.banner = 'Usage: rspec-puppet-init [options]'
 
   opts.on('-n', '--name NAME', 'The name of the module (override autodetection)') do |v|
     options[:module_name] = v