rspec-puppet 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 99267b05af6dbb02ad504453ec338ea2617e1768
-  data.tar.gz: ffb1e195adc74932acdbc6581eae52317018dc08
+  metadata.gz: c9c6c2a6e166342f02c503667f8312efd1d411e5
+  data.tar.gz: 407d9b0fc06f52c63428320819fd634eee4cf049
 SHA512:
-  metadata.gz: f1036132529e546b54f1e475c69f437402c994328795cf8d2828a619cd2e7cb2e1d7a6e51fc01dd95860e4623f650bac6983f3eaf432d8c664ea223370ba2ec3
-  data.tar.gz: 9d0e5709f38c09486749c1cd4bea517aa2757988e2bb55f430b241ed029d88bb2afa939392924378bf7f15924625d13a051fddef342b04052642241971cbb5bc
+  metadata.gz: e1c780ece606028d4a134797cec9740204529a597b2b4a14400dd4dbf623c8b689ba067726d4ebcac7f09ce792c7867ab47860b8d5fbd82304e1204be46c5b74
+  data.tar.gz: c5b11365c94d792e111b804c87a225583461f68570b5e29be03bb1e87a621cef66b08283c04e5bf42eb120c50afaae57375a8483a0be33f1ea569eaf2fa71617

data/CHANGELOG.md

@@ -2,6 +2,46 @@
 All notable changes to this project will be documented in this file. This
 project adheres to [Semantic Versioning](http://semver.org/).
 
+## [2.3.0]
+
+Rspec-puppet now supports testing custom types, `:undef` values in params, structured facts, and checks resource dependencies recursively.
+
+The settings in `module_path` and `manifest` are now respected throughout the code base. The former default for `module_path` (`'/etc/puppet/modules'`) was dropped to avoid accidentally poisoning the test environment with unrelated code.
+
+To reduce the maintenance overhead of boilerplate code, rspec-puppet now provides some of the code that rspec-puppet-init deployed in helper files that you can just `require` instead.
+
+This release also reduces memory usage on bigger testsuites drastically by reducing the caching of compiled catalogs.
+
+### Changed
+- Limit the catalogue cache to 16 entries. Significant memory savings and reduced runtime were observed in testing this.
+- Prevent Puppet 3's \_timestamp fact from invalidating cache.
+- Extracted catalog cache from RSpec::Puppet::Support.
+- Updated README to use the rspec 3 syntax, and additional explanations.
+- `contain_file(...).with_content(...)` will now only show the diff and not the full contents of the file.
+
+### Added
+- Custom type testing example group and matcher.
+- before/require/subscribe/notify checking now searches recursively through all dependencies. `File[a] -> File[b] -> File[c]` is now matched by `contain_file('a').that_comes_before('File[c]')`, whereas earlier versions would have missed that.
+- `let(:params)` now allows `:undef` to pass a literal undef value through to the subject.
+- Support structured facts with keys as symbols or strings (\#295).
+- rspec-puppet-init now creates smaller files, using rspec-puppet helpers, instead of pasting code into the module.
+- Added a list of related projects to the README.
+
+### Fixed
+- Fix #276: `compile.and_raise_error` now correctly considers successful compilation an error
+- Puppet's `modulepath` can now contain multiple entries and rspec-puppet will configure puppet to load code from all of them
+- Support running with rspec 2.99 again
+- non-class resources are now covered by the coverage code
+- Fix #323/MODULES-2374: autorequires checking doesn't abort on "undefined method \`[]' for nil:NilClass"
+- improved documentation for hiera integration, added example spec
+- document the `scope` property
+
+### Credits
+
+Thanks to Adrien Thebo, Alex Harvey, Brian, Dan Bode, Dominic Cleal, Javier Palacios, Jeff McCune, Jordan Moldow, Peter van Zetten, Raphaël Pinson, Simon Kohlmeyer, and Tristan Colgate for their contributions to this release.
+
+  -- David Schmitt
+
 ## [2.2.0]
 ### Added
 - Settings for ordering, strict_variables, stringify_facts, and trusted_node_data
@@ -47,6 +87,9 @@ project adheres to [Semantic Versioning](http://semver.org/).
 ## 1.0.1 and earlier
 For changelog of versions 1.0.1 and earlier, see http://rspec-puppet.com/changelog/
 
+[2.x]: https://github.com/rodjek/rspec-puppet/compare/v2.3.0...master
+[2.3.0]: https://github.com/rodjek/rspec-puppet/compare/v2.2.0...v2.3.0
+[2.2.0]: https://github.com/rodjek/rspec-puppet/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/rodjek/rspec-puppet/compare/v2.0.1...v2.1.0
 [2.0.1]: https://github.com/rodjek/rspec-puppet/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/rodjek/rspec-puppet/compare/v1.0.1...v2.0.0

data/README.md

@@ -1,9 +1,19 @@
-# RSpec tests for your Puppet manifests & modules [![Build Status](https://travis-ci.org/rodjek/rspec-puppet.png)](https://travis-ci.org/rodjek/rspec-puppet)
+# RSpec tests for your Puppet manifests & modules
+[![Build Status](https://travis-ci.org/rodjek/rspec-puppet.png)](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
 
     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, run `rspec-puppet-init` to create the necessary files to configure rspec-puppet for your module's tests.
+
 ## Naming conventions
 
 For clarity and consistency, I recommend that you use the following directory
@@ -31,6 +41,10 @@ structure and naming convention.
            |     |
            |     +-- <function_name>_spec.rb
            |
+           +-- types
+           |     |
+           |     +-- <type_name>_spec.rb
+           |
            +-- hosts
                  |
                  +-- <host_name>_spec.rb
@@ -54,6 +68,10 @@ describe 'myfunction', :type => :puppet_function do
   ...
 end
 
+describe 'mytype', :type => :type do
+  ...
+end
+
 describe 'myhost.example.com', :type => :host do
   ...
 end
@@ -63,76 +81,96 @@ end
 
 ### Matchers
 
+#### Checking if the catalog compiles
+
+You can test whether the subject catalog compiles cleanly with `compile`.
+
+```ruby
+it { is_expected.to compile }
+```
+
+To check the error messages of your class, you can check for raised error messages.
+
+```ruby
+it { is_expected.to compile.and_raise_error(/error message match/) }
+```
+
 #### Checking if a resource exists
 
 You can test if a resource exists in the catalogue with the generic
 `contain_<resource type>` matcher.
 
 ```ruby
-it { should contain_augeas('bleh') }
+it { is_expected.to contain_augeas('bleh') }
 ```
 
 You can also test if a class has been included in the catalogue with the
 same matcher.
 
 ```ruby
-it { should contain_class('foo') }
+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).
 
 ```ruby
-it { should contain_foo__bar('baz') }
+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.
 
 ```ruby
-it { should contain_package('mysql-server').with_ensure('present') }
+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.
 
 ```ruby
-it { should contain_package('httpd').only_with_ensure('latest') }
+it { is_expected.to contain_package('httpd').only_with_ensure('latest') }
 ```
 
 You can use the `with` method to verify the value of multiple parameters.
 
 ```ruby
-it do should contain_service('keystone').with(
-  'ensure'     => 'running',
-  'enable'     => 'true',
-  'hasstatus'  => 'true',
-  'hasrestart' => 'true'
-) end
+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.
 
 ```ruby
-it do should contain_user('luke').only_with(
-  'ensure'    => 'present',
-  'uid'    => '501'
-) end
+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.
 
 ```ruby
-it { should contain_file('/foo/bar').without_mode }
+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
 
 ```ruby
-it { should contain_service('keystone').without(
+it { is_expected.to contain_service('keystone').without(
   ['restart', 'status']
 )}
 ```
@@ -143,28 +181,28 @@ You can test the number of resources in the catalogue with the
 `have_resource_count` matcher.
 
 ```ruby
-it { should have_resource_count(2) }
+it { is_expected.to have_resource_count(2) }
 ```
 
 The number of classes in the catalogue can be checked with the
 `have_class_count` matcher.
 
 ```ruby
-it { should have_class_count(2) }
+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.
 
 ```ruby
-it { should have_exec_resource_count(1) }
+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).
 
 ```ruby
-it { should have_logrotate__rule_resource_count(3) }
+it { is_expected.to have_logrotate__rule_resource_count(3) }
 ```
 
 *NOTE*: when testing a class, the catalogue generated will always contain at
@@ -177,19 +215,19 @@ catalogue generated when testing a defined type will have at least one resource
 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.
 
 ```ruby
-it { should contain_file('foo').that_requires('File[bar]') }
-it { should contain_file('foo').that_comes_before('File[bar]') }
-it { should contain_file('foo').that_notifies('File[bar]') }
-it { should contain_file('foo').that_subscribes_to('File[bar]') }
+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
 
 ```ruby
-it { should contain_file('foo').that_requires(['File[bar]', 'File[baz]']) }
-it { should contain_file('foo').that_comes_before(['File[bar]','File[baz]']) }
-it { should contain_file('foo').that_notifies(['File[bar]', 'File[baz]']) }
-it { should contain_file('foo').that_subscribes_to(['File[bar]', 'File[baz]']) }
+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
@@ -204,14 +242,83 @@ notify { 'bar':
 You can test that **Notify[bar]** comes before **Notify[foo]**
 
 ```ruby
-it { should contain_notify('bar').that_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]**
 
 ```ruby
-it { should contain_notify('foo').that_requires('Notify[bar]') }
+it { is_expected.to contain_notify('foo').that_requires('Notify[bar]') }
+```
+
+##### Match target syntax
+
+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]`
+
+##### Recursive dependencies
+
+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 before `File['/foo']`:
+
+```puppet
+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 before `File['/foo']`:
+
+```puppet
+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
+
+Autorequires are considered in dependency checks.
+
+#### Type matcher
+
+When testing custom types, the `be_valid_type` matcher provides a range of expectations:
+
+* `with_provider(<provider_name>)`: check that the right provider was selected
+* `with_properties(<property_list>)`: check that the specified properties are available
+* `with_parameters(<parameter_list>)`: check that the specified parameters are available
+* `with_features(<feature_list>)`: check that the specified features are available
+* `with_set_attributes(<param_value_hash>)`: check that the specified attributes are set
+
 ### Writing tests
 
 #### Basic test structure
@@ -235,7 +342,7 @@ describe 'sysctl' do
   let(:title) { 'baz' }
   let(:params) { { :value => 'foo' } }
 
-  it { should contain_exec('sysctl/reload').with_command("/sbin/sysctl -p /etc/sysctl.conf") }
+  it { is_expected.to contain_exec('sysctl/reload').with_command("/sbin/sysctl -p /etc/sysctl.conf") }
 end
 ```
 
@@ -245,12 +352,18 @@ end
 let(:title) { 'foo' }
 ```
 
-#### Specifying the parameters to pass to a resources or parametised class
+#### Specifying the parameters to pass to a resources or parameterised class
 
 ```ruby
 let(:params) { {:ensure => 'present', ...} }
 ```
 
+##### Passing Puppet's `undef` as a parameter value
+
+```ruby
+let(:params) { {:user => :undef, ...} }
+```
+
 #### Specifying the FQDN of the test node
 
 If the manifest you're testing expects to run on host with a particular name,
@@ -278,6 +391,14 @@ 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
+
+```ruby
+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:
 
 ``` ruby
@@ -325,7 +446,7 @@ For your convenience though, a `run` matcher exists to provide easier to
 understand test cases.
 
 ```ruby
-it { should run.with_params('foo').and_return('bar') }
+it { is_expected.to run.with_params('foo').and_return('bar') }
 ```
 
 ### Writing tests
@@ -354,7 +475,7 @@ 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
 
 ```ruby
-it { should run.with_params('foo', 'bar', ['baz']) }
+it { is_expected.to run.with_params('foo', 'bar', ['baz']) }
 ```
 
 Or by using the `call` method on the subject directly
@@ -371,7 +492,7 @@ You can test the result of a function (if it produces one) using either the
 `and_returns` chain method in the `run` matcher
 
 ```ruby
-it { should run.with_params('foo').and_return('bar') }
+it { is_expected.to run.with_params('foo').and_return('bar') }
 ```
 
 Or by using any of the existing RSpec matchers on the subject directly
@@ -389,8 +510,8 @@ You can test whether the function throws an exception using either the
 `and_raises_error` chain method in the `run` matcher
 
 ```ruby
-it { should run.with_params('a', 'b').and_raise_error(Puppet::ParseError) }
-it { should_not run.with_params('a').and_raise_error(Puppet::ParseError) }
+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
@@ -402,6 +523,16 @@ it 'something' do
 end
 ```
 
+#### Accessing the parser scope where the function is running
+
+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('...') }
+```
+
 ## Hiera integration
 
 ### Configuration
@@ -455,6 +586,18 @@ RSpec.configure do |c|
 end
 ```
 
+spec/fixtures/hiera/hiera.yaml
+```yaml
+---
+:backends:
+  - yaml
+:yaml:
+  :datadir: spec/fixtures/hieradata
+:hierarchy:
+  - common
+```
+
+
 ## Producing coverage reports
 
 You can output a basic resource coverage report with the following in
@@ -467,3 +610,16 @@ at_exit { RSpec::Puppet::Coverage.report! }
 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.
+
+## 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
+
+* 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
+
+For a list of other module development tools see https://puppet.community/plugins/

data/lib/rspec-puppet/cache.rb

@@ -0,0 +1,30 @@
+module RSpec::Puppet
+  class Cache
+
+    MAX_ENTRIES = 16
+
+    # @param [Proc] default_proc The default proc to use to fetch objects on cache miss
+    def initialize(&default_proc)
+      @default_proc = default_proc
+      @cache = {}
+      @lra = []
+    end
+
+    def get(*args, &blk)
+      if !@cache.has_key? args
+        @cache[args] = (blk || @default_proc).call(*args)
+        @lra << args
+        expire!
+      end
+
+      @cache[args]
+    end
+
+    private
+
+    def expire!
+      expired = @lra.slice!(0, @lra.size - MAX_ENTRIES)
+      expired.each { |key| @cache.delete(key) } if expired
+    end
+  end
+end

data/lib/rspec-puppet/coverage.rb

@@ -28,31 +28,8 @@ module RSpec::Puppet
 
     # add all resources from catalog declared in module test_module
     def add_from_catalog(catalog, test_module)
-      catalog.to_a.each do |resource|
-        # check filters
-        next if @filters.include?(resource.to_s)
-        if resource.type == 'Class'
-          # if the resource is a class, make sure the class belongs to
-          # module test_module
-          module_name = resource.title.split('::').first.downcase
-          next if module_name != test_module
-        elsif resource.file
-          # otherwise, the source file should be available, so make
-          # sure the manifest declaring the resource is in
-          # test_module's directory tree or the site manifest(s)
-          if Puppet.version.to_f >= 4.0
-            paths = [
-              (Pathname.new(Puppet[:environmentpath]) + 'fixtures' + test_module + 'manifests').to_s,
-              (Pathname.new(Puppet[:environmentpath]) + 'fixtures' + 'manifests' + 'site.pp').to_s
-            ]
-          else
-            paths = Puppet[:modulepath].split(File::PATH_SEPARATOR).map do |dir|
-              (Pathname.new(dir) + test_module + 'manifests').to_s
-            end
-            paths << Puppet[:manifest]
-          end
-          next unless paths.any? { |path| resource.file.include?(path) }
-        end
+      coverable_resources = catalog.to_a.select { |resource| !filter_resource?(resource, test_module) }
+      coverable_resources.each do |resource|
         add(resource)
       end
     end
@@ -105,39 +82,91 @@ module RSpec::Puppet
 
     private
 
-      def find(resource)
-        @collection[resource.to_s]
+    # Should this resource be excluded from coverage reports?
+    #
+    # The resource is not included in coverage reports if any of the conditions hold:
+    #
+    #   * The resource has been explicitly filtered out.
+    #     * Examples: autogenerated resources such as 'Stage[main]'
+    #   * The resource is a class but does not belong to the module under test.
+    #     * Examples: Class dependencies included from a fixture module
+    #   * The resource was declared in a file outside of the test module or site.pp
+    #     * Examples: Resources declared in a dependency of this module.
+    #
+    # @param resource [Puppet::Resource] The resource that may be filtered
+    # @param test_module [String] The name of the module under test
+    # @return [true, false]
+    def filter_resource?(resource, test_module)
+      if @filters.include?(resource.to_s)
+        return true
       end
 
-      def exists?(resource)
-        !find(resource).nil?
+      if resource.type == 'Class'
+        module_name = resource.title.split('::').first.downcase
+        if module_name != test_module
+          return true
+        end
       end
 
-      class ResourceWrapper
-        attr_reader :resource
-
-        def initialize(resource = nil)
-          @resource = resource
+      if resource.file
+        paths = module_paths(test_module)
+        unless paths.any? { |path| resource.file.include?(path) }
+          return true
         end
+      end
 
-        def to_s
-          @resource.to_s
-        end
+      return false
+    end
 
-        def to_hash
-          {
-            'touched' => touched?,
-          }
+    # Find all paths that may contain testable resources for a module.
+    #
+    # @return [Array<String>]
+    def module_paths(test_module)
+      if Puppet.version.to_f >= 4.0
+        modulepath = RSpec.configuration.module_path || File.join(Puppet[:environmentpath], 'fixtures', 'modules')
+        manifest = RSpec.configuration.manifest || File.join(Puppet[:environmentpath], 'fixtures', 'manifests', 'site.pp')
+        paths = [File.join(modulepath, test_module, 'manifests'), manifest]
+      else
+        paths = Puppet[:modulepath].split(File::PATH_SEPARATOR).map do |dir|
+          File.join(dir, test_module, 'manifests')
         end
+        paths << Puppet[:manifest]
+      end
+      paths
+    end
 
-        def touch!
-          @touched = true
-        end
+    def find(resource)
+      @collection[resource.to_s]
+    end
 
-        def touched?
-          !!@touched
-        end
+    def exists?(resource)
+      !find(resource).nil?
+    end
+
+    class ResourceWrapper
+      attr_reader :resource
+
+      def initialize(resource = nil)
+        @resource = resource
+      end
+
+      def to_s
+        @resource.to_s
       end
 
+      def to_hash
+        {
+          'touched' => touched?,
+        }
+      end
+
+      def touch!
+        @touched = true
+      end
+
+      def touched?
+        !!@touched
+      end
+    end
   end
 end