chefspec 7.0.0 → 7.1.0

data/lib/chefspec/api/notifications.rb

@@ -1,38 +1,35 @@
 module ChefSpec::API
-  # @since 0.9.0
-  module NotificationsMatchers
-    #
-    # Assert that a resource notifies another. Given a Chef Recipe that
-    # notifies a template resource to restart apache:
-    #
-    #     template '/etc/apache2/config' do
-    #       notifies :restart, 'service[apache2]'
-    #     end
-    #
-    # The Examples section demonstrates the different ways to test an
-    # notifications on a resource with ChefSpec.
-    #
-    # @example Assert the template notifies apache of something
-    #   template = chef_run.template('/etc/apache2.conf')
-    #   expect(template).to notify('service[apache2]')
-    #
-    # @example Assert the template notifies apache to restart
-    #   expect(template).to notify('service[apache2]').to(:restart)
-    #
-    # @example Assert the template notifies apache to restart immediately
-    #   expect(template).to notify('service[apache2]').to(:restart).immediately
-    #
-    # @example Assert the template notifies apache to restart delayed
-    #   expect(template).to notify('service[apache2]').to(:restart).delayed
-    #
-    #
-    # @param [String] signature
-    #   the signature of the notification to match
-    #
-    # @return [ChefSpec::Matchers::NotificationsMatcher]
-    #
-    def notify(signature)
-      ChefSpec::Matchers::NotificationsMatcher.new(signature)
-    end
+  #
+  # Assert that a resource notifies another. Given a Chef Recipe that
+  # notifies a template resource to restart apache:
+  #
+  #     template '/etc/apache2/config' do
+  #       notifies :restart, 'service[apache2]'
+  #     end
+  #
+  # The Examples section demonstrates the different ways to test an
+  # notifications on a resource with ChefSpec.
+  #
+  # @example Assert the template notifies apache of something
+  #   template = chef_run.template('/etc/apache2.conf')
+  #   expect(template).to notify('service[apache2]')
+  #
+  # @example Assert the template notifies apache to restart
+  #   expect(template).to notify('service[apache2]').to(:restart)
+  #
+  # @example Assert the template notifies apache to restart immediately
+  #   expect(template).to notify('service[apache2]').to(:restart).immediately
+  #
+  # @example Assert the template notifies apache to restart delayed
+  #   expect(template).to notify('service[apache2]').to(:restart).delayed
+  #
+  #
+  # @param [String] signature
+  #   the signature of the notification to match
+  #
+  # @return [ChefSpec::Matchers::NotificationsMatcher]
+  #
+  def notify(signature)
+    ChefSpec::Matchers::NotificationsMatcher.new(signature)
   end
 end

data/lib/chefspec/api/reboot.rb

@@ -1,18 +1,9 @@
 module ChefSpec::API
-  # @since 0.5.0
-  module RebootMatchers
-    ChefSpec.define_matcher :reboot
-
-    def now_reboot(resource_name)
-      ChefSpec::Matchers::ResourceMatcher.new(:reboot, :reboot_now, resource_name)
-    end
-
-    def request_reboot(resource_name)
-      ChefSpec::Matchers::ResourceMatcher.new(:reboot, :request_reboot, resource_name)
-    end
+  def now_reboot(resource_name)
+    ChefSpec::Matchers::ResourceMatcher.new(:reboot, :reboot_now, resource_name)
+  end
 
-    def cancel_reboot(resource_name)
-      ChefSpec::Matchers::ResourceMatcher.new(:reboot, :cancel, resource_name)
-    end
+  def request_reboot(resource_name)
+    ChefSpec::Matchers::ResourceMatcher.new(:reboot, :request_reboot, resource_name)
   end
 end

data/lib/chefspec/api/render_file.rb

@@ -1,35 +1,32 @@
 module ChefSpec::API
-  # @since 3.0.0
-  module RenderFileMatchers
-    #
-    # Assert that a file is rendered by the Chef run. This matcher works for
-    # +template+, +file+, and +cookbook_file+ resources. The content from the
-    # resource must be convertable to a string; verifying the content of a
-    # binary file is not permissible at this time.
-    #
-    # @example Assert a template is rendered
-    #   expect(chef_run).to render_file('/etc/foo')
-    #
-    # @example Assert a template is rendered with certain content
-    #   expect(template).to render_file('/etc/foo').with_content('This is a file')
-    #
-    # @example Assert a template is rendered with matching content
-    #   expect(template).to render_file('/etc/foo').with_content(/^This(.+)$/)
-    #
-    # @example Assert a template is rendered with content matching any RSpec matcher
-    #   expect(template).to render_file('/etc/foo').with_content(starts_with('This'))
-    #
-    # @example Assert a partial path to a template is rendered with matching content
-    #   expect(template).to render_file(/\/etc\/foo-(\d+)$/).with_content(/^This(.+)$/)
-    #
-    #
-    # @param [String] path
-    #   the path of the file to render
-    #
-    # @return [ChefSpec::Matchers::RenderFileMatcher]
-    #
-    def render_file(path)
-      ChefSpec::Matchers::RenderFileMatcher.new(path)
-    end
+  #
+  # Assert that a file is rendered by the Chef run. This matcher works for
+  # +template+, +file+, and +cookbook_file+ resources. The content from the
+  # resource must be convertable to a string; verifying the content of a
+  # binary file is not permissible at this time.
+  #
+  # @example Assert a template is rendered
+  #   expect(chef_run).to render_file('/etc/foo')
+  #
+  # @example Assert a template is rendered with certain content
+  #   expect(template).to render_file('/etc/foo').with_content('This is a file')
+  #
+  # @example Assert a template is rendered with matching content
+  #   expect(template).to render_file('/etc/foo').with_content(/^This(.+)$/)
+  #
+  # @example Assert a template is rendered with content matching any RSpec matcher
+  #   expect(template).to render_file('/etc/foo').with_content(starts_with('This'))
+  #
+  # @example Assert a partial path to a template is rendered with matching content
+  #   expect(template).to render_file(/\/etc\/foo-(\d+)$/).with_content(/^This(.+)$/)
+  #
+  #
+  # @param [String] path
+  #   the path of the file to render
+  #
+  # @return [ChefSpec::Matchers::RenderFileMatcher]
+  #
+  def render_file(path)
+    ChefSpec::Matchers::RenderFileMatcher.new(path)
   end
 end

data/lib/chefspec/api/state_attrs.rb

@@ -1,28 +1,25 @@
 module ChefSpec::API
-  # @since 3.1.0
-  module StateAttrsMatcher
-    #
-    # Assert that a Chef resource has certain state attributes (since Chef
-    # 11.8.0):
-    #
-    #     state_attrs :time, :temperature
-    #
-    # @see https://github.com/opscode/chef/blob/e43d7ebda/lib/chef/resource/file.rb#L32-L37
-    #
-    # The Examples section demonstrates the different ways to test a
-    # resource's +state_attrs+ with ChefSpec.
-    #
-    # @example Assert the +lwrp+ resource has two state attributes
-    #   expect(lwrp).to have_state_attrs(:time, :temperature)
-    #
-    #
-    # @param [Array] state_attrs
-    #   the list of state attributes to assert
-    #
-    # @return [ChefSpec::Matchers::StateAttrsMatcher]
-    #
-    def have_state_attrs(*state_attrs)
-      ChefSpec::Matchers::StateAttrsMatcher.new(state_attrs)
-    end
+  #
+  # Assert that a Chef resource has certain state attributes (since Chef
+  # 11.8.0):
+  #
+  #     state_attrs :time, :temperature
+  #
+  # @see https://github.com/opscode/chef/blob/e43d7ebda/lib/chef/resource/file.rb#L32-L37
+  #
+  # The Examples section demonstrates the different ways to test a
+  # resource's +state_attrs+ with ChefSpec.
+  #
+  # @example Assert the +lwrp+ resource has two state attributes
+  #   expect(lwrp).to have_state_attrs(:time, :temperature)
+  #
+  #
+  # @param [Array] state_attrs
+  #   the list of state attributes to assert
+  #
+  # @return [ChefSpec::Matchers::StateAttrsMatcher]
+  #
+  def have_state_attrs(*state_attrs)
+    ChefSpec::Matchers::StateAttrsMatcher.new(state_attrs)
   end
 end

data/lib/chefspec/api/subscriptions.rb

@@ -1,35 +1,32 @@
 module ChefSpec::API
-  # @since 3.2.0
-  module SubscriptionsMatchers
-    #
-    # Assert that a resource subscribes to another. Given a Chef Recipe that
-    # subscribes a template resource to restart apache:
-    #
-    #     service 'apache2' do
-    #       subscribes :create, 'template[/etc/apache2/config]'
-    #     end
-    #
-    # The Examples section demonstrates the different ways to test a
-    # subscription on a resource with ChefSpec.
-    #
-    # @example Assert a basic subscription
-    #   service = chef_run.service('apache2')
-    #   expect(service).to subscribe_to('template[/etc/apache2/config]')
-    #
-    # @example Assert a subscription with specified action
-    #   expect(service).to subscribe_to('template[/etc/apache2/config]').on(:restart)
-    #
-    # @example Assert a subscription with specified action and timing
-    #   expect(service).to subscribe_to('template[/etc/apache2/config]').on(:restart).immediately
-    #
-    #
-    # @param [String] signature
-    #   the signature of the notification to match
-    #
-    # @return [ChefSpec::Matchers::NotificationsMatcher]
-    #
-    def subscribe_to(signature)
-      ChefSpec::Matchers::SubscribesMatcher.new(signature)
-    end
+  #
+  # Assert that a resource subscribes to another. Given a Chef Recipe that
+  # subscribes a template resource to restart apache:
+  #
+  #     service 'apache2' do
+  #       subscribes :create, 'template[/etc/apache2/config]'
+  #     end
+  #
+  # The Examples section demonstrates the different ways to test a
+  # subscription on a resource with ChefSpec.
+  #
+  # @example Assert a basic subscription
+  #   service = chef_run.service('apache2')
+  #   expect(service).to subscribe_to('template[/etc/apache2/config]')
+  #
+  # @example Assert a subscription with specified action
+  #   expect(service).to subscribe_to('template[/etc/apache2/config]').on(:restart)
+  #
+  # @example Assert a subscription with specified action and timing
+  #   expect(service).to subscribe_to('template[/etc/apache2/config]').on(:restart).immediately
+  #
+  #
+  # @param [String] signature
+  #   the signature of the notification to match
+  #
+  # @return [ChefSpec::Matchers::NotificationsMatcher]
+  #
+  def subscribe_to(signature)
+    ChefSpec::Matchers::SubscribesMatcher.new(signature)
   end
 end

data/lib/chefspec/api/user.rb

@@ -1,228 +1,225 @@
 module ChefSpec::API
-  # @since 0.3.0
-  module UserMatchers
-    ChefSpec.define_matcher :user
+  ChefSpec.define_matcher :user
 
-    #
-    # Assert that a +user+ resource exists in the Chef run with the
-    # action +:create+. Given a Chef Recipe that creates "apache2" as a
-    # +user+:
-    #
-    #     user 'apache2' do
-    #       action :create
-    #     end
-    #
-    # The Examples section demonstrates the different ways to test a
-    # +user+ resource with ChefSpec.
-    #
-    # @example Assert that a +user+ was created
-    #   expect(chef_run).to create_user('apache2')
-    #
-    # @example Assert that a +user+ was created with predicate matchers
-    #   expect(chef_run).to create_user('apache2').with_uid(1234)
-    #
-    # @example Assert that a +user+ was created with attributes
-    #   expect(chef_run).to create_user('apache2').with(uid: 1234)
-    #
-    # @example Assert that a +user+ was created using a regex
-    #   expect(chef_run).to create_user('apache2').with(uid: /\d+/)
-    #
-    # @example Assert that a +user+ was _not_ created
-    #   expect(chef_run).to_not create_user('apache2')
-    #
-    #
-    # @param [String, Regex] resource_name
-    #   the name of the resource to match
-    #
-    # @return [ChefSpec::Matchers::ResourceMatcher]
-    #
-    def create_user(resource_name)
-      ChefSpec::Matchers::ResourceMatcher.new(:user, :create, resource_name)
-    end
+  #
+  # Assert that a +user+ resource exists in the Chef run with the
+  # action +:create+. Given a Chef Recipe that creates "apache2" as a
+  # +user+:
+  #
+  #     user 'apache2' do
+  #       action :create
+  #     end
+  #
+  # The Examples section demonstrates the different ways to test a
+  # +user+ resource with ChefSpec.
+  #
+  # @example Assert that a +user+ was created
+  #   expect(chef_run).to create_user('apache2')
+  #
+  # @example Assert that a +user+ was created with predicate matchers
+  #   expect(chef_run).to create_user('apache2').with_uid(1234)
+  #
+  # @example Assert that a +user+ was created with attributes
+  #   expect(chef_run).to create_user('apache2').with(uid: 1234)
+  #
+  # @example Assert that a +user+ was created using a regex
+  #   expect(chef_run).to create_user('apache2').with(uid: /\d+/)
+  #
+  # @example Assert that a +user+ was _not_ created
+  #   expect(chef_run).to_not create_user('apache2')
+  #
+  #
+  # @param [String, Regex] resource_name
+  #   the name of the resource to match
+  #
+  # @return [ChefSpec::Matchers::ResourceMatcher]
+  #
+  def create_user(resource_name)
+    ChefSpec::Matchers::ResourceMatcher.new(:user, :create, resource_name)
+  end
 
-    #
-    # Assert that a +user+ resource exists in the Chef run with the
-    # action +:remove+. Given a Chef Recipe that removes "apache2" as a
-    # +user+:
-    #
-    #     user 'apache2' do
-    #       action :remove
-    #     end
-    #
-    # The Examples section demonstrates the different ways to test a
-    # +user+ resource with ChefSpec.
-    #
-    # @example Assert that a +user+ was remove
-    #   expect(chef_run).to remove_user('apache2')
-    #
-    # @example Assert that a +user+ was remove with predicate matchers
-    #   expect(chef_run).to remove_user('apache2').with_uid(1234)
-    #
-    # @example Assert that a +user+ was remove with attributes
-    #   expect(chef_run).to remove_user('apache2').with(uid: 1234)
-    #
-    # @example Assert that a +user+ was remove using a regex
-    #   expect(chef_run).to remove_user('apache2').with(uid: /\d+/)
-    #
-    # @example Assert that a +user+ was _not_ remove
-    #   expect(chef_run).to_not remove_user('apache2')
-    #
-    #
-    # @param [String, Regex] resource_name
-    #   the name of the resource to match
-    #
-    # @return [ChefSpec::Matchers::ResourceMatcher]
-    #
-    def remove_user(resource_name)
-      ChefSpec::Matchers::ResourceMatcher.new(:user, :remove, resource_name)
-    end
+  #
+  # Assert that a +user+ resource exists in the Chef run with the
+  # action +:remove+. Given a Chef Recipe that removes "apache2" as a
+  # +user+:
+  #
+  #     user 'apache2' do
+  #       action :remove
+  #     end
+  #
+  # The Examples section demonstrates the different ways to test a
+  # +user+ resource with ChefSpec.
+  #
+  # @example Assert that a +user+ was remove
+  #   expect(chef_run).to remove_user('apache2')
+  #
+  # @example Assert that a +user+ was remove with predicate matchers
+  #   expect(chef_run).to remove_user('apache2').with_uid(1234)
+  #
+  # @example Assert that a +user+ was remove with attributes
+  #   expect(chef_run).to remove_user('apache2').with(uid: 1234)
+  #
+  # @example Assert that a +user+ was remove using a regex
+  #   expect(chef_run).to remove_user('apache2').with(uid: /\d+/)
+  #
+  # @example Assert that a +user+ was _not_ remove
+  #   expect(chef_run).to_not remove_user('apache2')
+  #
+  #
+  # @param [String, Regex] resource_name
+  #   the name of the resource to match
+  #
+  # @return [ChefSpec::Matchers::ResourceMatcher]
+  #
+  def remove_user(resource_name)
+    ChefSpec::Matchers::ResourceMatcher.new(:user, :remove, resource_name)
+  end
 
-    #
-    # Assert that a +user+ resource exists in the Chef run with the
-    # action +:modify+. Given a Chef Recipe that modifies "apache2" as a
-    # +user+:
-    #
-    #     user 'apache2' do
-    #       action :modify
-    #     end
-    #
-    # The Examples section demonstrates the different ways to test a
-    # +user+ resource with ChefSpec.
-    #
-    # @example Assert that a +user+ was modified
-    #   expect(chef_run).to modify_user('apache2')
-    #
-    # @example Assert that a +user+ was modified with predicate matchers
-    #   expect(chef_run).to modify_user('apache2').with_uid(1234)
-    #
-    # @example Assert that a +user+ was modified with attributes
-    #   expect(chef_run).to modify_user('apache2').with(uid: 1234)
-    #
-    # @example Assert that a +user+ was modified using a regex
-    #   expect(chef_run).to modify_user('apache2').with(uid: /\d+/)
-    #
-    # @example Assert that a +user+ was _not_ modified
-    #   expect(chef_run).to_not modify_user('apache2')
-    #
-    #
-    # @param [String, Regex] resource_name
-    #   the name of the resource to match
-    #
-    # @return [ChefSpec::Matchers::ResourceMatcher]
-    #
-    def modify_user(resource_name)
-      ChefSpec::Matchers::ResourceMatcher.new(:user, :modify, resource_name)
-    end
+  #
+  # Assert that a +user+ resource exists in the Chef run with the
+  # action +:modify+. Given a Chef Recipe that modifies "apache2" as a
+  # +user+:
+  #
+  #     user 'apache2' do
+  #       action :modify
+  #     end
+  #
+  # The Examples section demonstrates the different ways to test a
+  # +user+ resource with ChefSpec.
+  #
+  # @example Assert that a +user+ was modified
+  #   expect(chef_run).to modify_user('apache2')
+  #
+  # @example Assert that a +user+ was modified with predicate matchers
+  #   expect(chef_run).to modify_user('apache2').with_uid(1234)
+  #
+  # @example Assert that a +user+ was modified with attributes
+  #   expect(chef_run).to modify_user('apache2').with(uid: 1234)
+  #
+  # @example Assert that a +user+ was modified using a regex
+  #   expect(chef_run).to modify_user('apache2').with(uid: /\d+/)
+  #
+  # @example Assert that a +user+ was _not_ modified
+  #   expect(chef_run).to_not modify_user('apache2')
+  #
+  #
+  # @param [String, Regex] resource_name
+  #   the name of the resource to match
+  #
+  # @return [ChefSpec::Matchers::ResourceMatcher]
+  #
+  def modify_user(resource_name)
+    ChefSpec::Matchers::ResourceMatcher.new(:user, :modify, resource_name)
+  end
 
-    #
-    # Assert that a +user+ resource exists in the Chef run with the
-    # action +:manage+. Given a Chef Recipe that manages "apache2" as a
-    # +user+:
-    #
-    #     user 'apache2' do
-    #       action :manage
-    #     end
-    #
-    # The Examples section demonstrates the different ways to test a
-    # +user+ resource with ChefSpec.
-    #
-    # @example Assert that a +user+ was managed
-    #   expect(chef_run).to manage_user('apache2')
-    #
-    # @example Assert that a +user+ was managed with predicate matchers
-    #   expect(chef_run).to manage_user('apache2').with_uid(1234)
-    #
-    # @example Assert that a +user+ was managed with attributes
-    #   expect(chef_run).to manage_user('apache2').with(uid: 1234)
-    #
-    # @example Assert that a +user+ was managed using a regex
-    #   expect(chef_run).to manage_user('apache2').with(uid: /\d+/)
-    #
-    # @example Assert that a +user+ was _not_ managed
-    #   expect(chef_run).to_not manage_user('apache2')
-    #
-    #
-    # @param [String, Regex] resource_name
-    #   the name of the resource to match
-    #
-    # @return [ChefSpec::Matchers::ResourceMatcher]
-    #
-    def manage_user(resource_name)
-      ChefSpec::Matchers::ResourceMatcher.new(:user, :manage, resource_name)
-    end
+  #
+  # Assert that a +user+ resource exists in the Chef run with the
+  # action +:manage+. Given a Chef Recipe that manages "apache2" as a
+  # +user+:
+  #
+  #     user 'apache2' do
+  #       action :manage
+  #     end
+  #
+  # The Examples section demonstrates the different ways to test a
+  # +user+ resource with ChefSpec.
+  #
+  # @example Assert that a +user+ was managed
+  #   expect(chef_run).to manage_user('apache2')
+  #
+  # @example Assert that a +user+ was managed with predicate matchers
+  #   expect(chef_run).to manage_user('apache2').with_uid(1234)
+  #
+  # @example Assert that a +user+ was managed with attributes
+  #   expect(chef_run).to manage_user('apache2').with(uid: 1234)
+  #
+  # @example Assert that a +user+ was managed using a regex
+  #   expect(chef_run).to manage_user('apache2').with(uid: /\d+/)
+  #
+  # @example Assert that a +user+ was _not_ managed
+  #   expect(chef_run).to_not manage_user('apache2')
+  #
+  #
+  # @param [String, Regex] resource_name
+  #   the name of the resource to match
+  #
+  # @return [ChefSpec::Matchers::ResourceMatcher]
+  #
+  def manage_user(resource_name)
+    ChefSpec::Matchers::ResourceMatcher.new(:user, :manage, resource_name)
+  end
 
-    #
-    # Assert that a +user+ resource exists in the Chef run with the
-    # action +:lock+. Given a Chef Recipe that locks "apache2" as a
-    # +user+:
-    #
-    #     user 'apache2' do
-    #       action :lock
-    #     end
-    #
-    # The Examples section demonstrates the different ways to test a
-    # +user+ resource with ChefSpec.
-    #
-    # @example Assert that a +user+ was locked
-    #   expect(chef_run).to lock_user('apache2')
-    #
-    # @example Assert that a +user+ was locked with predicate matchers
-    #   expect(chef_run).to lock_user('apache2').with_uid(1234)
-    #
-    # @example Assert that a +user+ was locked with attributes
-    #   expect(chef_run).to lock_user('apache2').with(uid: 1234)
-    #
-    # @example Assert that a +user+ was locked using a regex
-    #   expect(chef_run).to lock_user('apache2').with(uid: /\d+/)
-    #
-    # @example Assert that a +user+ was _not_ locked
-    #   expect(chef_run).to_not lock_user('apache2')
-    #
-    #
-    # @param [String, Regex] resource_name
-    #   the name of the resource to match
-    #
-    # @return [ChefSpec::Matchers::ResourceMatcher]
-    #
-    def lock_user(resource_name)
-      ChefSpec::Matchers::ResourceMatcher.new(:user, :lock, resource_name)
-    end
+  #
+  # Assert that a +user+ resource exists in the Chef run with the
+  # action +:lock+. Given a Chef Recipe that locks "apache2" as a
+  # +user+:
+  #
+  #     user 'apache2' do
+  #       action :lock
+  #     end
+  #
+  # The Examples section demonstrates the different ways to test a
+  # +user+ resource with ChefSpec.
+  #
+  # @example Assert that a +user+ was locked
+  #   expect(chef_run).to lock_user('apache2')
+  #
+  # @example Assert that a +user+ was locked with predicate matchers
+  #   expect(chef_run).to lock_user('apache2').with_uid(1234)
+  #
+  # @example Assert that a +user+ was locked with attributes
+  #   expect(chef_run).to lock_user('apache2').with(uid: 1234)
+  #
+  # @example Assert that a +user+ was locked using a regex
+  #   expect(chef_run).to lock_user('apache2').with(uid: /\d+/)
+  #
+  # @example Assert that a +user+ was _not_ locked
+  #   expect(chef_run).to_not lock_user('apache2')
+  #
+  #
+  # @param [String, Regex] resource_name
+  #   the name of the resource to match
+  #
+  # @return [ChefSpec::Matchers::ResourceMatcher]
+  #
+  def lock_user(resource_name)
+    ChefSpec::Matchers::ResourceMatcher.new(:user, :lock, resource_name)
+  end
 
-    #
-    # Assert that a +user+ resource exists in the Chef run with the
-    # action +:unlock+. Given a Chef Recipe that unlocks "apache2" as a
-    # +user+:
-    #
-    #     user 'apache2' do
-    #       action :unlock
-    #     end
-    #
-    # The Examples section demonstrates the different ways to test a
-    # +user+ resource with ChefSpec.
-    #
-    # @example Assert that a +user+ was unlocked
-    #   expect(chef_run).to unlock_user('apache2')
-    #
-    # @example Assert that a +user+ was unlocked with predicate matchers
-    #   expect(chef_run).to unlock_user('apache2').with_uid(1234)
-    #
-    # @example Assert that a +user+ was unlocked with attributes
-    #   expect(chef_run).to unlock_user('apache2').with(uid: 1234)
-    #
-    # @example Assert that a +user+ was unlocked using a regex
-    #   expect(chef_run).to unlock_user('apache2').with(uid: /\d+/)
-    #
-    # @example Assert that a +user+ was _not_ unlocked
-    #   expect(chef_run).to_not unlock_user('apache2')
-    #
-    #
-    # @param [String, Regex] resource_name
-    #   the name of the resource to match
-    #
-    # @return [ChefSpec::Matchers::ResourceMatcher]
-    #
-    def unlock_user(resource_name)
-      ChefSpec::Matchers::ResourceMatcher.new(:user, :unlock, resource_name)
-    end
+  #
+  # Assert that a +user+ resource exists in the Chef run with the
+  # action +:unlock+. Given a Chef Recipe that unlocks "apache2" as a
+  # +user+:
+  #
+  #     user 'apache2' do
+  #       action :unlock
+  #     end
+  #
+  # The Examples section demonstrates the different ways to test a
+  # +user+ resource with ChefSpec.
+  #
+  # @example Assert that a +user+ was unlocked
+  #   expect(chef_run).to unlock_user('apache2')
+  #
+  # @example Assert that a +user+ was unlocked with predicate matchers
+  #   expect(chef_run).to unlock_user('apache2').with_uid(1234)
+  #
+  # @example Assert that a +user+ was unlocked with attributes
+  #   expect(chef_run).to unlock_user('apache2').with(uid: 1234)
+  #
+  # @example Assert that a +user+ was unlocked using a regex
+  #   expect(chef_run).to unlock_user('apache2').with(uid: /\d+/)
+  #
+  # @example Assert that a +user+ was _not_ unlocked
+  #   expect(chef_run).to_not unlock_user('apache2')
+  #
+  #
+  # @param [String, Regex] resource_name
+  #   the name of the resource to match
+  #
+  # @return [ChefSpec::Matchers::ResourceMatcher]
+  #
+  def unlock_user(resource_name)
+    ChefSpec::Matchers::ResourceMatcher.new(:user, :unlock, resource_name)
   end
 end