plans.rb in bolt-3.1.0

- old
+ new
@@ -3,121 +3,13 @@
 require 'bolt_spec/bolt_context'
 require 'bolt_spec/plans/mock_executor'
 require 'bolt/pal'
 
 # These helpers are intended to be used for plan unit testing without calling
-# out to target nodes. It uses the BoltContext helper to set up a mock executor
+# out to targets. It uses the BoltContext helper to set up a mock executor
 # which allows calls to run_* functions to be stubbed for testing. The context
 # helper also loads Bolt datatypes and plan functions to be used by the code
 # being tested.
-#
-# Stub matching
-#
-# Stubs match invocations of run_* functions by default matching any call but
-# with_targets and with_params helpers can further restrict the stub to match
-# more exact invocations. It's possible a call to run_* could match multiple
-# stubs. In this case the mock executor will first check for stubs specifically
-# matching the task being run after which it will use the last stub that
-# matched
-#
-#
-# allow vs expect
-#
-# Stubs have two general modes bases on whether the test is making assertions
-# on whether function was called. Allow stubs allow the run_* invocation  to
-# be called any number of times while expect stubs will fail if no run_*
-# invocation matches them. The be_called_times(n) stub method can be used to
-# ensure an allow stub is not called more than n times or that an expect stub
-# is called exactly n times.
-#
-# Configuration
-#
-#  To configure Puppet and Bolt at the beginning of tests, add the following
-#  line to your spec_helper.rb:
-#
-#  BoltSpec::Plans.init
-#
-#  By default the plan helpers use the modulepath set up for rspec-puppet and
-#  an otherwise empty bolt config and inventory. To create your own values for
-#  these override the modulepath, config, or inventory methods.
-#
-# Sub-plan Execution
-#
-#  When testing a plan, often times those plans call other plans in order to
-#  build complex workflows. To support this we offer running in two different
-#  modes:
-#    execute_any_plan (default) - This mode will execute any plan that is encountered
-#      without having to be stubbed/mocked. This default mode allows for plan control
-#      flow to behave as normal. If you choose to stub/mock out a sub-plan in this mode
-#      that will be honored and the sub-plan will not be executed. We will use the modifiers
-#      on the stub to check for the conditions specified (example: be_called_times(3))
-#
-#    execute_no_plan - This mode will not execute a plans that it encounters. Instead, when
-#      a plan is encountered it will throw an error unless the plan is mocked out. This
-#      mode is useful for ensuring that there are no plans called that you do not expect.
-#      This plan requires authors to mock out all sub-plans that may be invoked when running
-#      tests.
-#
-#  TODO:
-#  - Allow description based stub matching
-#  - Better testing of plan errors
-#  - Better error collection around call counts. Show what stubs exists and more than a single failure
-#  - Allow stubbing with a block(at the double level? As a matched stub?)
-#  - package code so that it can be used for testing modules outside of this repo
-#  - set subject from describe and provide matchers similar to rspec puppets function tests
-#  - Allow specific plans to be executed when running in execute_no_plan mode.
-#
-#  MAYBE TODO?:
-#  - validate call expectations at the end of the example instead of in run_plan
-#  - resultset matchers to help testing canary like plans?
-#  - inventory matchers to help testing plans that change inventory
-#
-# Flags:
-# - execute_any_plan: execute any plan that is encountered unless it is mocked (default)
-# - execute_no_plan: throw an error if a plan is encountered that is not stubbed
-#
-# Stubs:
-# - allow_command(cmd), expect_command(cmd): expect the exact command
-# - allow_plan(plan), expect_plan(plan): expect the named plan
-# - allow_script(script), expect_script(script): expect the script as <module>/path/to/file
-# - allow_task(task), expect_task(task): expect the named task
-# - allow_download(file), expect_download(file): expect the identified source file
-# - allow_upload(file), expect_upload(file): expect the identified source file
-# - allow_apply_prep: allows `apply_prep` to be invoked in the plan but does not allow modifiers
-# - allow_apply: allows `apply` to be invoked in the plan but does not allow modifiers
-# - allow_out_message, expect_out_message: expect a message to be passed to out::message (only modifiers are
-#   be_called_times(n), with_params(params), and not_be_called)
-#
-# Stub modifiers:
-# - be_called_times(n): if allowed, fail if the action is called more than 'n' times
-#                       if expected, fail unless the action is called 'n' times
-# - not_be_called: fail if the action is called
-# - with_targets(targets): target or list of targets that you expect to be passed to the action
-#                          plan: does not support this modifier
-# - with_params(params): list of params and metaparams (or options) that you expect to be passed to the action.
-#                        Corresponds to the action's last argument.
-# - with_destination(dest): for upload_file and download_file, the expected destination path
-# - always_return(value): return a Bolt::ResultSet of Bolt::Result objects with the specified value Hash
-#                         plan: returns a Bolt::PlanResult with the specified value with a status of 'success'
-#                         command and script: only accept 'stdout' and 'stderr' keys
-#                         upload: does not support this modifier
-#                         download: does not support this modifier
-# - return_for_targets(targets_to_values): return a Bolt::ResultSet of Bolt::Result objects from the Hash mapping
-#                                          targets to their value Hashes
-#                                          command and script: only accept 'stdout' and 'stderr' keys
-#                                          upload: does not support this modifier
-#                                          download: does not support this modifier
-#                                          plan: does not support this modifier
-# - return(&block): invoke the block to construct a Bolt::ResultSet. The blocks parameters differ based on action
-#                   command: `{ |targets:, command:, params:| ... }`
-#                   plan: `{ |plan:, params:| ... }`
-#                   script: `{ |targets:, script:, params:| ... }`
-#                   task: `{ |targets:, task:, params:| ... }`
-#                   upload: `{ |targets:, source:, destination:, params:| ... }`
-#                   download: `{ |targets:, source:, destination:, params:| ... }`
-# - error_with(err): return a failing Bolt::ResultSet, with Bolt::Result objects with the identified err hash
-#                    plans will throw a Bolt::PlanFailure that will be returned as the value of
-#                    the Bolt::PlanResult object with a status of 'failure'.
 #
 # Example:
 #   describe "my_plan" do
 #     it 'should return' do
 #       allow_task('my_task').always_return({'result_key' => 10})