Module: BoltSpec

Defined in:: lib/bolt_spec/run.rb,
lib/bolt_spec/plans.rb,
lib/bolt_spec/bolt_context.rb,
lib/bolt_spec/plans/action_stubs.rb,
lib/bolt_spec/plans/publish_stub.rb,
lib/bolt_spec/plans/mock_executor.rb,
lib/bolt_spec/plans/action_stubs/plan_stub.rb,
lib/bolt_spec/plans/action_stubs/task_stub.rb,
lib/bolt_spec/plans/action_stubs/script_stub.rb,
lib/bolt_spec/plans/action_stubs/upload_stub.rb,
lib/bolt_spec/plans/action_stubs/command_stub.rb,
lib/bolt_spec/plans/action_stubs/download_stub.rb

Overview

This helper is used to create the Bolt context necessary to load Bolt plan datatypes and functions. It accomplishes this by replacing bolt’s executor with a mock executor. The mock executor allows calls to run_* functions to be stubbed out for testing. By default this executor will fail on any run_* call but stubs can be set up with allow_* and expect_* functions.

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

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.

Stubs:

allow_command(cmd), expect_command(cmd): expect the exact command
allow_script(script), expect_script(script): expect the script as <module>/path/to/file or an absolute path
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 source file as <module>/path/to/file or an absolute path
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)

Files with absolute path (for upload and script) must exist or those functions will fail.

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
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

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

return(&block): invoke the block to construct a Bolt::ResultSet. The blocks parameters differ based on action

command: `{ |targets:, command:, 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

Example:

describe "mymod::myfunction" do
 include BoltSpec::BoltContext

  around :each do |example|
    in_bolt_context do
      example.run
    end
  end

  it "bolt_context runs a Puppet function with Bolt datatypes" do
    expect_out_message.with_params("Loaded TargetSpec localhost")
    is_expected.to run.with_params('localhost').and_return('localhost')
  end
end

Defined Under Namespace

Modules: BoltContext, Plans, Run