rename #expect_definitions to #stub_shellout and document

This method was previously misnamed - we are not setting any
expectations, but instead stubbing Mixlib::ShellOut so that
its #stdout command returns given values which can then be
tested against.

Also rename the parameters for clarity, and add some explanatory
comments.

spec/helpers/cib_object.rb

@@ -8,20 +8,32 @@ require File.expand_path('../../libraries/pacemaker/cib_object',
 module Chef::RSpec
   module Pacemaker
     module CIBObject
-      # "crm configure show" is executed by load_current_resource, and
-      # again later on for the :create action, to see whether to create or
-      # modify.
-      def shellout_double(definition)
+      # Return a Mixlib::ShellOut double which mimics successful
+      # execution of a command, returning the given string on STDOUT.
+      def shellout_double(string)
         shellout = double(Mixlib::ShellOut)
         shellout.stub(:environment).and_return({})
         shellout.stub(:run_command)
         shellout.stub(:error!)
-        expect(shellout).to receive(:stdout).and_return(definition)
+        expect(shellout).to receive(:stdout).and_return(string)
         shellout
       end
 
-      def expect_definitions(*definitions)
-        doubles = definitions.map { |d| shellout_double(d) }
+      # This stubs Mixlib::ShellOut.new with a sequence of doubles
+      # whose #stdout methods return a corresponding sequence of strings.
+      # This allows us to simulate the output of a series of shell
+      # commands being run via Mixlib::ShellOut.
+      #
+      # For example, "crm configure show" is executed by
+      # #load_current_resource, and again later on for the :create
+      # action, to see whether to create or modify.  So the first
+      # double in the sequence would return an empty definition if we
+      # wanted to test creation of a new CIB object, or an existing
+      # definition if we wanted to test modification of an existing
+      # one.  If the test needs subsequent doubles to return different
+      # values then stdout_strings can have more than one element.
+      def stub_shellout(*stdout_strings)
+        doubles = stdout_strings.map { |string| shellout_double(string) }
         Mixlib::ShellOut.stub(:new).and_return(*doubles)
       end
     end
@@ -40,7 +52,7 @@ shared_examples "a CIB object" do
   end
 
   it "should be instantiated via Pacemaker::CIBObject.from_name" do
-    expect_definitions(fixture.definition_string)
+    stub_shellout(fixture.definition_string)
     obj = Pacemaker::CIBObject.from_name(fixture.name)
     expect_to_match_fixture(obj)
   end
@@ -51,7 +63,7 @@ shared_examples "a CIB object" do
   end
 
   it "should barf if the loaded definition's type is not colocation" do
-    expect_definitions("clone foo blah blah")
+    stub_shellout("clone foo blah blah")
     expect { fixture.load_definition }.to \
       raise_error(Pacemaker::CIBObject::TypeMismatch,
                   "Expected #{object_type} type but loaded definition was type clone")
@@ -62,7 +74,7 @@ shared_examples "action on non-existent resource" do |action, cmd, expected_erro
   include Chef::RSpec::Pacemaker::CIBObject
 
   it "should not attempt to #{action.to_s} a non-existent resource" do
-    expect_definitions("")
+    stub_shellout("")
 
     if expected_error
       expect { provider.run_action action }.to \

spec/helpers/runnable_resource.rb

@@ -21,7 +21,7 @@ shared_examples "a runnable resource" do |fixture|
       :delete, "crm configure delete #{fixture.name}", nil
 
     it "should not delete a running resource" do
-      expect_definitions(fixture.definition_string)
+      stub_shellout(fixture.definition_string)
       expect_running(true)
 
       expected_error = "Cannot delete running #{fixture}"
@@ -34,7 +34,7 @@ shared_examples "a runnable resource" do |fixture|
     end
 
     it "should delete a non-running resource" do
-      expect_definitions(fixture.definition_string)
+      stub_shellout(fixture.definition_string)
       expect_running(false)
 
       provider.run_action :delete
@@ -52,7 +52,7 @@ shared_examples "a runnable resource" do |fixture|
       "Cannot start non-existent #{fixture}"
 
     it "should do nothing to a started resource" do
-      expect_definitions(fixture.definition_string)
+      stub_shellout(fixture.definition_string)
       expect_running(true)
 
       provider.run_action :start
@@ -64,7 +64,7 @@ shared_examples "a runnable resource" do |fixture|
 
     it "should start a stopped resource" do
       config = fixture.definition_string.sub("Started", "Stopped")
-      expect_definitions(config)
+      stub_shellout(config)
       expect_running(false)
 
       provider.run_action :start
@@ -82,7 +82,7 @@ shared_examples "a runnable resource" do |fixture|
       "Cannot stop non-existent #{fixture}"
 
     it "should do nothing to a stopped resource" do
-      expect_definitions(fixture.definition_string)
+      stub_shellout(fixture.definition_string)
       expect_running(false)
 
       provider.run_action :stop
@@ -93,7 +93,7 @@ shared_examples "a runnable resource" do |fixture|
     end
 
     it "should stop a started resource" do
-      expect_definitions(fixture.definition_string)
+      stub_shellout(fixture.definition_string)
       expect_running(true)
 
       provider.run_action :stop

spec/providers/colocation_spec.rb

@@ -35,7 +35,7 @@ describe "Chef::Provider::PacemakerColocation" do
     def test_modify(expected_cmds)
       yield
 
-      expect_definitions(fixture.definition_string)
+      stub_shellout(fixture.definition_string)
 
       provider.run_action :create
 

spec/providers/group_spec.rb

@@ -36,7 +36,7 @@ describe "Chef::Provider::PacemakerGroup" do
     def test_modify(expected_cmds)
       yield
 
-      expect_definitions(fixture.definition_string)
+      stub_shellout(fixture.definition_string)
 
       provider.run_action :create
 

spec/providers/primitive_spec.rb

@@ -38,7 +38,7 @@ describe "Chef::Provider::PacemakerPrimitive" do
     def test_modify(expected_cmds)
       yield
 
-      expect_definitions(fixture.definition_string)
+      stub_shellout(fixture.definition_string)
 
       provider.run_action :create
 
@@ -102,7 +102,7 @@ describe "Chef::Provider::PacemakerPrimitive" do
       # The first time, Mixlib::ShellOut needs to return an empty definition.
       # Then the resource gets created so the second time it needs to return
       # the definition used for creation.
-      expect_definitions("", fixture.definition_string)
+      stub_shellout("", fixture.definition_string)
 
       provider.run_action :create
 
@@ -113,7 +113,7 @@ describe "Chef::Provider::PacemakerPrimitive" do
     it "should barf if the primitive is already defined with the wrong agent" do
       existing_agent = "ocf:openstack:something-else"
       definition = fixture.definition_string.sub(fixture.agent, existing_agent)
-      expect_definitions(definition)
+      stub_shellout(definition)
 
       expected_error = \
         "Existing #{fixture} has agent '#{existing_agent}' " \