Module: BoltSpec

Defined in:


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.


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.


  • 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


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

  around :each do |example|
    in_bolt_context do

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

Defined Under Namespace

Modules: BoltContext, Plans, Run