bolt 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1188441f6f0d4a4012c0e1bedbfeff66dcafa7624911448865e4081950510c3
-  data.tar.gz: 5add229df85ea63038f8a2492adcd1086ad3d3201280bed7b22fb7cfdaf205a3
+  metadata.gz: 8afdc9d66e35557fd6dee9433d0c5dd62f9620fb111a7b56d3ba11e7a0b66e73
+  data.tar.gz: d2ea3502f583cfa8cd136f8e04eaebac50364c822f892595eb0782c8e6c6f175
 SHA512:
-  metadata.gz: 49cdd374d0607bfd3ff6367d1c9b3be6061df74a7c1ed57940e07b78f9ae7f9fc8e235769fb741b63b85b136f127ee289ac26110b692c47d03d19cf543e0e495
-  data.tar.gz: 5bdb2cea2de3c6a8696b7e3b76a2ece602d94480f42b30feb8c2531bc93ca5ebadf3ba1b3f6d3bfe9cc5ba0effc0e9d0949729af7df20313d159fcbac554eb03
+  metadata.gz: 3c15b22e1ab464ba249372b62161da08c69e31db4c55ff2a89b590fde7abccde114dc0559e1b3b32eae3fcae69ef09afd1f142fe89e1976d682247f4e1e16bdc
+  data.tar.gz: d1b82c13cb0faf8b80e5b37bf6800a24a7837e4ed572690257163fcf95da6dcd2a14f25a0f23e7fd33c7e797683e00eda3f0f2933a319785ce92a40f5bdfcc01

data/bolt-modules/boltlib/lib/puppet/functions/add_to_group.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Adds a target to specified inventory group.
+Puppet::Functions.create_function(:add_to_group) do
+  # @param targets A pattern or array of patterns identifying a set of targets.
+  # @param group The name of the group to add targets to.
+  # @example Add new Target to group.
+  #   Target.new('foo@example.com', 'password' => 'secret').add_to_group('group1')
+  # @example Add new target to group by name.
+  #   add_to_group('bolt:bolt@web.com', 'group1')
+  # @example Add an array of targets to group by name.
+  #   add_to_group(['host1', 'group1', 'winrm://host2:54321'], 'group1')
+  # @example Add a comma separated list list of targets to group by name.
+  #   add_to_group('foo,bar,baz', 'group1')
+  dispatch :add_to_group do
+    param 'Boltlib::TargetSpec', :targets
+    param 'String[1]', :group
+  end
+
+  def add_to_group(targets, group)
+    inventory = Puppet.lookup(:bolt_inventory) { nil }
+
+    unless inventory && Puppet.features.bolt?
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Puppet::Pops::Issues::TASK_MISSING_BOLT, action: _('process targets through inventory')
+      )
+    end
+
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call('add_to_group')
+
+    inventory.add_to_group(inventory.get_targets(targets), group)
+  end
+end

data/lib/bolt/analytics.rb

@@ -19,7 +19,9 @@ module Bolt
       inventory_nodes: :cd2,
       inventory_groups: :cd3,
       target_nodes: :cd4,
-      output_format: :cd5
+      output_format: :cd5,
+      statement_count: :cd6,
+      resource_mean: :cd7
     }.freeze
 
     def self.build_client
@@ -82,7 +84,11 @@ module Bolt
         submit(base_params.merge(screen_view_params))
       end
 
-      def event(category, action, label = nil, value = nil)
+      def event(category, action, label: nil, value: nil, **kwargs)
+        custom_dimensions = Bolt::Util.walk_keys(kwargs) do |k|
+          CUSTOM_DIMENSIONS[k] || raise("Unknown analytics key '#{k}'")
+        end
+
         event_params = {
           # Type
           t: 'event',
@@ -90,7 +96,7 @@ module Bolt
           ec: category,
           # Event Action
           ea: action
-        }
+        }.merge(custom_dimensions)
 
         # Event Label
         event_params[:el] = label if label
@@ -160,7 +166,7 @@ module Bolt
         @logger.debug "Skipping submission of '#{screen}' screenview because analytics is disabled"
       end
 
-      def event(category, action, _label = nil, _value = nil)
+      def event(category, action, **_kwargs)
         @logger.debug "Skipping submission of '#{category} #{action}' event because analytics is disabled"
       end
 

data/lib/bolt/applicator.rb

@@ -134,12 +134,24 @@ module Bolt
 
       targets = @inventory.get_targets(args[0])
 
-      ast = Puppet::Pops::Serialization::ToDataConverter.convert(apply_body, rich_data: true, symbol_to_string: true)
+      apply_ast(apply_body, targets, options, plan_vars)
+    end
 
-      apply_ast(ast, targets, options, plan_vars)
+    # Count the number of top-level statements in the AST.
+    def count_statements(ast)
+      case ast
+      when Puppet::Pops::Model::Program
+        count_statements(ast.body)
+      when Puppet::Pops::Model::BlockExpression
+        ast.statements.count
+      else
+        1
+      end
     end
 
-    def apply_ast(ast, targets, options, plan_vars = {})
+    def apply_ast(raw_ast, targets, options, plan_vars = {})
+      ast = Puppet::Pops::Serialization::ToDataConverter.convert(raw_ast, rich_data: true, symbol_to_string: true)
+
       notify = proc { |_| nil }
 
       r = @executor.log_action('apply catalog', targets) do
@@ -154,12 +166,15 @@ module Bolt
         result_promises = targets.zip(futures).flat_map do |target, future|
           @executor.queue_execute([target]) do |transport, batch|
             @executor.with_node_logging("Applying manifest block", batch) do
+              catalog = future.value
+              raise future.reason if future.rejected?
+
               arguments = {
-                'catalog' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(future.value),
+                'catalog' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(catalog),
                 'plugins' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(plugins),
                 '_noop' => options['_noop']
               }
-              raise future.reason if future.rejected?
+
               results = transport.batch_task(batch, catalog_apply_task, arguments, options, &notify)
               Array(results).map { |result| ApplyResult.from_task_result(result) }
             end
@@ -169,6 +184,10 @@ module Bolt
         @executor.await_results(result_promises)
       end
 
+      # Allow for report to exclude event metrics (apply_result doesn't require it to be present)
+      resource_counts = r.ok_set.map { |result| result.event_metrics&.fetch('total') }.compact
+      @executor.report_apply(count_statements(raw_ast), resource_counts)
+
       if !r.ok && !options['_catch_errors']
         raise Bolt::ApplyFailure, r
       end

data/lib/bolt/executor.rb

@@ -165,18 +165,32 @@ module Bolt
 
     def report_transport(transport, count)
       name = transport.class.name.split('::').last.downcase
-      @analytics&.event('Transport', 'initialize', name, count) unless @reported_transports.include?(name)
+      unless @reported_transports.include?(name)
+        @analytics&.event('Transport', 'initialize', label: name, value: count)
+      end
       @reported_transports.add(name)
     end
 
     def report_function_call(function)
-      @analytics&.event('Plan', 'call_function', function)
+      @analytics&.event('Plan', 'call_function', label: function)
     end
 
     def report_bundled_content(mode, name)
       if @bundled_content&.include?(name)
-        @analytics&.event('Bundled Content', mode, name)
+        @analytics&.event('Bundled Content', mode, label: name)
+      end
+    end
+
+    def report_apply(statement_count, resource_counts)
+      data = { statement_count: statement_count }
+
+      unless resource_counts.empty?
+        sum = resource_counts.inject(0) { |accum, i| accum + i }
+        # Intentionally rounded to an integer. High precision isn't useful.
+        data[:resource_mean] = sum / resource_counts.length
       end
+
+      @analytics&.event('Apply', 'ast', data)
     end
 
     def with_node_logging(description, batch)

data/lib/bolt/inventory.rb

@@ -93,6 +93,19 @@ module Bolt
       targets.map { |t| update_target(t) }
     end
 
+    def add_to_group(targets, desired_group)
+      if group_names.include?(desired_group)
+        targets.each do |target|
+          if group_names.include?(target.name)
+            raise ValidationError.new("Group #{target.name} conflicts with node of the same name", target.name)
+          end
+          add_node(@groups, target, desired_group)
+        end
+      else
+        raise ValidationError.new("Group #{desired_group} does not exist in inventory", nil)
+      end
+    end
+
     def set_var(target, key, value)
       data = { key => value }
       set_vars_from_hash(target.name, data)
@@ -243,5 +256,40 @@ module Bolt
       end
     end
     private :set_facts
+
+    def add_node(current_group, target, desired_group, track = { 'all' => nil })
+      if current_group.name == desired_group
+        # Group to add to is found
+        t_name = target.name
+        # Add target to nodes hash
+        current_group.nodes[t_name] = { 'name' => t_name }.merge(target.options)
+        # Inherit facts, vars, and features from hierarchy
+        current_group_data = { facts: current_group.facts, vars: current_group.vars, features: current_group.features }
+        data = inherit_data(track, current_group.name, current_group_data)
+        set_facts(t_name, @target_facts[t_name] ? data[:facts].merge(@target_facts[t_name]) : data[:facts])
+        set_vars_from_hash(t_name, @target_vars[t_name] ? data[:vars].merge(@target_vars[t_name]) : data[:vars])
+        data[:features].each do |feature|
+          set_feature(target, feature)
+        end
+        return true
+      end
+      # Recurse on children Groups if not desired_group
+      current_group.groups.each do |child_group|
+        track[child_group.name] = current_group
+        add_node(child_group, target, desired_group, track)
+      end
+    end
+    private :add_node
+
+    def inherit_data(track, name, data)
+      unless track[name].nil?
+        data[:facts] = track[name].facts.merge(data[:facts])
+        data[:vars] = track[name].vars.merge(data[:vars])
+        data[:features].concat(track[name].features)
+        inherit_data(track, track[name].name, data)
+      end
+      data
+    end
+    private :inherit_data
   end
 end

data/lib/bolt/inventory/group.rb

@@ -5,7 +5,7 @@ module Bolt
     # Group is a specific implementation of Inventory based on nested
     # structured data.
     class Group
-      attr_accessor :name, :nodes, :groups, :config, :rest
+      attr_accessor :name, :nodes, :groups, :config, :rest, :facts, :vars, :features
 
       def initialize(data)
         @logger = Logging.logger[self]

data/lib/bolt/pal.rb

@@ -180,8 +180,7 @@ module Bolt
     # Parses a snippet of Puppet manifest code and returns the AST represented
     # in JSON.
     def parse_manifest(code, filename)
-      raw_ast = Puppet::Pops::Parser::EvaluatingParser.new.parse_string(code, filename)
-      Puppet::Pops::Serialization::ToDataConverter.convert(raw_ast, rich_data: true, symbol_to_string: true)
+      Puppet::Pops::Parser::EvaluatingParser.new.parse_string(code, filename)
     rescue Puppet::Error => e
       raise Bolt::PAL::PALError, "Failed to parse manifest: #{e}"
     end

data/lib/bolt/plan_result.rb

@@ -36,5 +36,9 @@ module Bolt
     def to_json(*args)
       @value.to_json(*args)
     end
+
+    def to_s
+      to_json
+    end
   end
 end

data/lib/bolt/transport/ssh.rb

@@ -54,10 +54,7 @@ module Bolt
         begin
           require 'net/ssh/krb'
         rescue LoadError
-          logger.debug {
-            "Authentication method 'gssapi-with-mic' is not available. "\
-            "Please install the kerberos gem with `gem install net-ssh-krb`"
-          }
+          logger.debug("Authentication method 'gssapi-with-mic' (Kerberos) is not available.")
         end
 
         @transport_logger = Logging.logger[Net::SSH]

data/lib/bolt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bolt
-  VERSION = '1.3.0'
+  VERSION = '1.4.0'
 end

data/lib/bolt_spec/plans.rb

@@ -38,7 +38,6 @@ require 'bolt/pal'
 #
 #
 #  TODO:
-#  - allow stubbing for commands, scripts and file uploads
 #  - 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
@@ -52,6 +51,36 @@ require 'bolt/pal'
 #  - resultset matchers to help testing canary like plans?
 #  - inventory matchers to help testing plans that change inventory
 #
+# 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
+# - allow_task(task), expect_task(task): expect the named task
+# - 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
+#
+# 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, 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
+# - 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
+# - 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:| ... }`
+# - error_with(err): return a failing Bolt::ResultSet, with Bolt::Result objects with the identified err hash
+#
 # Example:
 #   describe "my_plan" do
 #     it 'should return' do
@@ -87,8 +116,16 @@ require 'bolt/pal'
 #         'node2' => {'result_key' => 6} })
 #       expect(run_plan('my_plan', { 'param1' => 10 })).to eq(13)
 #     end
+#
+#     it 'should construct a custom return value' do
+#       expect_task('my_task').return do |targets:, task:, params:|
+#         Bolt::ResultSet.new(targets.map { |targ| Bolt::Result.new(targ, {'result_key' => 10'})})
+#       end
+#       expect(run_plan('my_plan', { 'param1' => 10 })).to eq(10)
+#     end
 #   end
 #
+# See spec/bolt_spec/plan_spec.rb for more examples.
 module BoltSpec
   module Plans
     def self.init
@@ -110,9 +147,11 @@ module BoltSpec
 
     # Override in your tests
     def config
-      config = Bolt::Config.new(Bolt::Boltdir.new('.'), {})
-      config.modulepath = modulepath
-      config
+      @config ||= begin
+        conf = Bolt::Config.new(Bolt::Boltdir.new('.'), {})
+        conf.modulepath = [modulepath].flatten
+        conf
+      end
     end
 
     # Override in your tests
@@ -120,8 +159,11 @@ module BoltSpec
       @inventory ||= Bolt::Inventory.new({})
     end
 
+    # Provided as a class so expectations can be placed on it.
+    class MockPuppetDBClient; end
+
     def puppetdb_client
-      @puppetdb_client ||= mock('puppetdb_client')
+      @puppetdb_client ||= MockPuppetDBClient.new
     end
 
     def run_plan(name, params)
@@ -132,30 +174,46 @@ module BoltSpec
         raise executor.error_message
       end
 
-      executor.assert_call_expectations
+      begin
+        executor.assert_call_expectations
+      rescue StandardError => e
+        raise "#{e.message}\nPlan result: #{result}"
+      end
 
       result
     end
 
-    # Allowed task stubs can be called up to be_called_times number
-    # of times
-    def allow_task(task_name)
-      executor.stub_task(task_name).add_stub
+    MOCKED_ACTIONS.each do |action|
+      # Allowed action stubs can be called up to be_called_times number of times
+      define_method :"allow_#{action}" do |object|
+        executor.send(:"stub_#{action}", object).add_stub
+      end
+
+      # Expected action stubs must be called exactly the expected number of times
+      # or at least once without be_called_times
+      define_method :"expect_#{action}" do |object|
+        send(:"allow_#{action}", object).expect_call
+      end
+
+      # This stub will catch any action call if there are no stubs specifically for that task
+      define_method :"allow_any_#{action}" do
+        executor.send(:"stub_#{action}", :default).add_stub
+      end
     end
 
-    # Expected task stubs must be called exactly the expected number of times
-    # or at least once without be_called_times
-    def expect_task(task_name)
-      allow_task(task_name).expect_call
+    def allow_apply_prep
+      allow_task('puppet_agent::version').always_return('version' => '6.0')
+      allow_task('apply_helpers::custom_facts')
+      nil
     end
 
-    # This stub will catch any task call if there are no stubs specifically for that task
-    def allow_any_task
-      executor.stub_task(:default).add_stub
+    def allow_apply
+      executor.stub_apply
+      nil
     end
 
     # Example helpers to mock other run functions
-    # The with_targets method  makes sense for all stubs
+    # The with_targets method makes sense for all stubs
     # with_params could be reused for options
     # They probably need special stub methods for other arguments through
 
@@ -180,7 +238,7 @@ module BoltSpec
 
     # intended to be private below here
     def executor
-      @executor ||= BoltSpec::Plans::MockExecutor.new
+      @executor ||= BoltSpec::Plans::MockExecutor.new(modulepath)
     end
   end
 end

data/lib/bolt_spec/plans/action_stubs.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'bolt/result'
+require 'bolt/util'
+
+module BoltSpec
+  module Plans
+    # Nothing in the ActionDouble is 'public'
+    class ActionDouble
+      def initialize(action_stub)
+        @stubs = []
+        @action_stub = action_stub
+      end
+
+      def process(*args)
+        matches = @stubs.select { |s| s.matches(*args) }
+        unless matches.empty?
+          matches[0].call(*args)
+        end
+      end
+
+      def assert_called(object)
+        @stubs.each { |s| s.assert_called(object) }
+      end
+
+      def add_stub
+        stub = Plans.const_get(@action_stub).new
+        @stubs.unshift stub
+        stub
+      end
+    end
+
+    class ActionStub
+      attr_reader :invocation
+
+      def initialize(expect = false)
+        @calls = 0
+        @expect = expect
+        @expected_calls = 1
+        # invocation spec
+        @invocation = {}
+        # return value
+        @data = { default: {} }
+      end
+
+      def assert_called(object)
+        satisfied = if @expect
+                      (@expected_calls.nil? && @calls > 0) || @calls == @expected_calls
+                    else
+                      @expected_calls.nil? || @calls <= @expected_calls
+                    end
+        unless satisfied
+          unless (times = @expected_calls)
+            times = @expect ? "at least one" : "any number of"
+          end
+          message = "Expected #{object} to be called #{times} times"
+          message += " with targets #{@invocation[:targets]}" if @invocation[:targets]
+          message += " with parameters #{parameters}" if parameters
+          raise message
+        end
+      end
+
+      # This changes the stub from an allow to an expect which will validate
+      # that it has been called.
+      def expect_call
+        @expect = true
+        self
+      end
+
+      # Used to create a valid Bolt::Result object from result data.
+      def default_for(target)
+        case @data[:default]
+        when Bolt::Error
+          Bolt::Result.from_exception(target, @data[:default])
+        when Hash
+          result_for(target, Bolt::Util.walk_keys(@data[:default], &:to_sym))
+        else
+          raise 'Default result must be a Hash'
+        end
+      end
+
+      def check_resultset(result_set, object)
+        unless result_set.is_a?(Bolt::ResultSet)
+          raise "Return block for #{object} did not return a Bolt::ResultSet"
+        end
+        result_set
+      end
+
+      # Below here are the intended 'public' methods of the stub
+
+      # Restricts the stub to only match invocations with
+      # the correct targets
+      def with_targets(targets)
+        targets = [targets] unless targets.is_a? Array
+        @invocation[:targets] = targets.map do |target|
+          if target.is_a? String
+            target
+          else
+            target.name
+          end
+        end
+        self
+      end
+
+      # limit the maximum number of times an allow stub may be called or
+      # specify how many times an expect stub must be called.
+      def be_called_times(times)
+        @expected_calls = times
+        self
+      end
+
+      # error if the stub is called at all.
+      def not_be_called
+        @expected_calls = 0
+        self
+      end
+
+      def return(&block)
+        raise "Cannot set return values and return block." if @data_set
+        @return_block = block
+        self
+      end
+
+      # Set different result values for each target. May use string or symbol keys, but allowed key names
+      # are restricted based on action.
+      def return_for_targets(data)
+        data.each_with_object(@data) do |(target, result), hsh|
+          raise "Mocked results must be hashes: #{target}: #{result}" unless result.is_a? Hash
+          hsh[target] = result_for(Bolt::Target.new(target), Bolt::Util.walk_keys(result, &:to_sym))
+        end
+        raise "Cannot set return values and return block." if @return_block
+        @data_set = true
+        self
+      end
+
+      # Set a default return value for all targets, specific targets may be overridden with return_for_targets.
+      # Follows the same rules for data as return_for_targets.
+      def always_return(data)
+        @data[:default] = data
+        @data_set = true
+        self
+      end
+
+      # Set a default error result for all targets.
+      def error_with(data)
+        data = Bolt::Util.walk_keys(data, &:to_s)
+        if data['msg'] && data['kind'] && (data.keys - %w[msg kind details issue_code]).empty?
+          @data[:default] = Bolt::Error.new(data['msg'], data['kind'], data['details'], data['issue_code'])
+        else
+          STDERR.puts "In the future 'error_with()' may require msg and kind, and " \
+                      "optionally accept only details and issue_code."
+          @data[:default] = data
+        end
+        @data_set = true
+        self
+      end
+    end
+  end
+end
+
+require_relative 'action_stubs/command_stub'
+require_relative 'action_stubs/script_stub'
+require_relative 'action_stubs/task_stub'
+require_relative 'action_stubs/upload_stub'

data/lib/bolt_spec/plans/action_stubs/command_stub.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module BoltSpec
+  module Plans
+    class CommandStub < ActionStub
+      def matches(targets, _command, options)
+        if @invocation[:targets] && Set.new(@invocation[:targets]) != Set.new(targets.map(&:name))
+          return false
+        end
+
+        if @invocation[:options] && options != @invocation[:options]
+          return false
+        end
+
+        true
+      end
+
+      def call(targets, command, options)
+        @calls += 1
+        if @return_block
+          check_resultset(@return_block.call(targets: targets, command: command, params: options), command)
+        else
+          Bolt::ResultSet.new(targets.map { |target| @data[target.name] || default_for(target) })
+        end
+      end
+
+      def parameters
+        @invocation[:options]
+      end
+
+      def result_for(target, stdout: '', stderr: '')
+        Bolt::Result.for_command(target, stdout, stderr, 0)
+      end
+
+      # Public methods
+
+      def with_params(params)
+        @invocation[:options] = params
+        self
+      end
+    end
+  end
+end

data/lib/bolt_spec/plans/action_stubs/script_stub.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module BoltSpec
+  module Plans
+    class ScriptStub < ActionStub
+      def matches(targets, _script, arguments, options)
+        if @invocation[:targets] && Set.new(@invocation[:targets]) != Set.new(targets.map(&:name))
+          return false
+        end
+
+        if @invocation[:arguments] && arguments != @invocation[:arguments]
+          return false
+        end
+
+        if @invocation[:options] && options != @invocation[:options]
+          return false
+        end
+
+        true
+      end
+
+      def call(targets, script, arguments, options)
+        @calls += 1
+        if @return_block
+          # Merge arguments and options into params to match puppet function signature.
+          params = options.merge('arguments' => arguments)
+          check_resultset(@return_block.call(targets: targets, script: script, params: params), script)
+        else
+          Bolt::ResultSet.new(targets.map { |target| @data[target.name] || default_for(target) })
+        end
+      end
+
+      def parameters
+        @invocation[:arguments] + @invocation[:options]
+      end
+
+      def result_for(target, stdout: '', stderr: '')
+        Bolt::Result.for_command(target, stdout, stderr, 0)
+      end
+
+      # Public methods
+
+      def with_params(params)
+        @invocation[:arguments] = params['arguments']
+        @invocation[:options] = params.select { |k, _v| k.start_with?('_') }
+        self
+      end
+    end
+  end
+end

data/lib/bolt_spec/plans/action_stubs/task_stub.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module BoltSpec
+  module Plans
+    class TaskStub < ActionStub
+      def matches(targets, _task, arguments, options)
+        if @invocation[:targets] && Set.new(@invocation[:targets]) != Set.new(targets.map(&:name))
+          return false
+        end
+
+        if @invocation[:arguments] && arguments != @invocation[:arguments]
+          return false
+        end
+
+        if @invocation[:options] && options != @invocation[:options]
+          return false
+        end
+
+        true
+      end
+
+      def call(targets, task, arguments, options)
+        @calls += 1
+        if @return_block
+          # Merge arguments and options into params to match puppet function signature.
+          check_resultset(@return_block.call(targets: targets, task: task, params: arguments.merge(options)), task)
+        else
+          Bolt::ResultSet.new(targets.map { |target| @data[target.name] || default_for(target) })
+        end
+      end
+
+      def parameters
+        @invocation[:arguments] + @invocation[:options]
+      end
+
+      # Allow any data.
+      def result_for(target, data)
+        Bolt::Result.new(target, value: Bolt::Util.walk_keys(data, &:to_s))
+      end
+
+      # Public methods
+
+      # Restricts the stub to only match invocations with certain parameters.
+      # All parameters must match exactly.
+      def with_params(params)
+        @invocation[:arguments] = params.reject { |k, _v| k.start_with?('_') }
+        @invocation[:options] = params.select { |k, _v| k.start_with?('_') }
+        self
+      end
+    end
+  end
+end

data/lib/bolt_spec/plans/action_stubs/upload_stub.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module BoltSpec
+  module Plans
+    class UploadStub < ActionStub
+      def matches(targets, _source, destination, options)
+        if @invocation[:targets] && Set.new(@invocation[:targets]) != Set.new(targets.map(&:name))
+          return false
+        end
+
+        if @invocation[:destination] && destination != @invocation[:destination]
+          return false
+        end
+
+        if @invocation[:options] && options != @invocation[:options]
+          return false
+        end
+
+        true
+      end
+
+      def call(targets, source, destination, options)
+        @calls += 1
+        if @return_block
+          results = @return_block.call(targets: targets, source: source, destination: destination, params: options)
+          check_resultset(results, source)
+        else
+          results = targets.map do |target|
+            if @data[:default].is_a?(Bolt::Error)
+              default_for(target)
+            else
+              Bolt::Result.for_upload(target, source, destination)
+            end
+          end
+          Bolt::ResultSet.new(results)
+        end
+      end
+
+      def parameters
+        @invocation[:options]
+      end
+
+      def result_for(_target, _data)
+        raise 'Upload result cannot be changed'
+      end
+
+      # Public methods
+
+      def always_return(_data)
+        raise 'Upload result cannot be changed'
+      end
+
+      def with_destination(destination)
+        @invocation[:destination] = destination
+        self
+      end
+
+      def with_params(params)
+        @invocation[:options] = params
+        self
+      end
+    end
+  end
+end

data/lib/bolt_spec/plans/mock_executor.rb

@@ -1,191 +1,71 @@
 # frozen_string_literal: true
 
+require 'bolt_spec/plans/action_stubs'
 require 'bolt/error'
 require 'bolt/result_set'
 require 'bolt/result'
+require 'pathname'
 require 'set'
 
 module BoltSpec
   module Plans
-    class UnexpectedInvocation < ArgumentError; end
-
-    # Nothing in the TaskDouble is 'public'
-    class TaskDouble
-      def initialize
-        @stubs = []
-      end
-
-      def process(targets, task, arguments, options)
-        # TODO: should we bother matching at all? or just call each
-        # stub until one works?
-        matches = @stubs.select { |s| s.matches(targets, task, arguments, options) }
-        unless matches.empty?
-          matches[0].call(targets, task, arguments, options)
-        end
-      end
+    MOCKED_ACTIONS = %i[command script task upload].freeze
 
-      def assert_called(taskname)
-        @stubs.each { |s| s.assert_called(taskname) }
-      end
-
-      def add_stub
-        stub = TaskStub.new
-        @stubs.unshift stub
-        stub
-      end
-    end
+    class UnexpectedInvocation < ArgumentError; end
 
-    class TaskStub
-      attr_reader :invocation
+    # Nothing on the executor is 'public'
+    class MockExecutor
+      attr_reader :noop, :error_message
+      attr_accessor :run_as
 
-      def initialize(expect = false)
-        @calls = 0
-        @expect = expect
-        @expected_calls = 1
-        # invocation spec
-        @invocation = {}
-        # return value
-        @data = { default: {} }
+      def initialize(modulepath)
+        @noop = false
+        @run_as = nil
+        @error_message = nil
+        @allow_apply = false
+        @modulepath = [modulepath].flatten.map { |path| File.absolute_path(path) }
+        MOCKED_ACTIONS.each { |action| instance_variable_set(:"@#{action}_doubles", {}) }
       end
 
-      def matches(targets, _task, arguments, options)
-        if @invocation[:targets] && Set.new(@invocation[:targets]) != Set.new(targets.map(&:name))
-          return false
-        end
+      def module_file_id(file)
+        modpath = @modulepath.select { |path| file =~ /^#{path}/ }
+        raise "Could not identify module path containing #{file}: #{modpath}" unless modpath.size == 1
 
-        if @invocation[:arguments] && arguments != @invocation[:arguments]
-          return false
-        end
-
-        if @invocation[:options] && options != @invocation[:options]
-          return false
-        end
-
-        true
+        path = Pathname.new(file)
+        relative = path.relative_path_from(Pathname.new(modpath.first))
+        segments = relative.to_path.split('/')
+        ([segments[0]] + segments[2..-1]).join('/')
       end
 
-      def call(targets, task, arguments, options)
-        @calls += 1
-        if @return_block
-          # Merge arguments and options into params to match puppet function signature.
-          result_set = @return_block.call(targets: targets, task: task, params: arguments.merge(options))
-          unless result_set.is_a?(Bolt::ResultSet)
-            raise "Return block for #{task} did not return a Bolt::ResultSet"
-          end
-          result_set
-        else
-          results = targets.map do |target|
-            val = @data[target.name] || @data[:default]
-            Bolt::Result.new(target, value: val)
-          end
-          Bolt::ResultSet.new(results)
+      def run_command(targets, command, options = {})
+        result = nil
+        if (doub = @command_doubles[command] || @command_doubles[:default])
+          result = doub.process(targets, command, options)
         end
-      end
-
-      def assert_called(taskname)
-        satisfied = if @expect
-                      (@expected_calls.nil? && @calls > 0) || @calls == @expected_calls
-                    else
-                      @expected_calls.nil? || @calls <= @expected_calls
-                    end
-        unless satisfied
-          unless (times = @expected_calls)
-            times = @expect ? "at least one" : "any number of"
-          end
-          message = "Expected #{taskname} to be called #{times} times"
-          message += " with targets #{@invocation[:targets]}" if @invocation[:targets]
-          message += " with parameters #{@invocations[:parameters]}" if @invocation[:parameters]
-          raise message
+        unless result
+          targets = targets.map(&:name)
+          @error_message = "Unexpected call to 'run_command(#{command}, #{targets}, #{options})'"
+          raise UnexpectedInvocation, @error_message
         end
+        result
       end
 
-      # This changes the stub from an allow to an expect which will validate
-      # that it has been called.
-      def expect_call
-        @expect = true
-        self
-      end
-
-      # Below here are the intended 'public' methods of the stub
-
-      # Restricts the stub to only match invocations with
-      # the correct targets
-      def with_targets(targets)
-        targets = [targets] unless targets.is_a? Array
-        @invocation[:targets] = targets.map do |target|
-          if target.is_a? String
-            target
-          else
-            target.name
-          end
+      def run_script(targets, script_path, arguments, options = {})
+        script = module_file_id(script_path)
+        result = nil
+        if (doub = @script_doubles[script] || @script_doubles[:default])
+          result = doub.process(targets, script, arguments, options)
         end
-        self
-      end
-
-      # Restricts the stub to only match invocations with certain parameters
-      # All parameters must match exactly and since arguments and options are
-      # treated differently at the executor this won't work with some '_*' options
-      # TODO: Fix handling of '_*' options probably by breaking them into other helpers
-      def with_params(params)
-        @invocation[:parameters] = params
-        @invocation[:arguments] = params.reject { |k, _v| k.start_with?('_') }
-        @invocation[:options] = params.select { |k, _v| k.start_with?('_') }
-        self
-      end
-
-      # limit the maximum number of times an allow stub may be called or
-      # specify how many times an expect stub must be called.
-      def be_called_times(times)
-        @expected_calls = times
-        self
-      end
-
-      # error if the stub is called at all.
-      def not_be_called
-        @expected_calls = 0
-        self
-      end
-
-      def return(&block)
-        raise "Cannot set return values and return block." if @data_set
-        @return_block = block
-        self
-      end
-
-      # Set different result values for each target
-      def return_for_targets(data)
-        data.each do |target, result|
-          raise "Mocked results must be hashes: #{target}: #{result}" unless result.is_a? Hash
+        unless result
+          targets = targets.map(&:name)
+          params = options.merge('arguments' => arguments)
+          @error_message = "Unexpected call to 'run_script(#{script}, #{targets}, #{params})'"
+          raise UnexpectedInvocation, @error_message
         end
-        raise "Cannot set return values and return block." if @return_block
-        @data = data
-        @data_set = true
-        self
-      end
-
-      # Set a default return value for all targets, specific targets may be overridden with return_for_targets
-      def always_return(default_data)
-        return_for_targets(default: default_data)
-      end
-
-      # Set a default error result for all targets.
-      def error_with(error_data)
-        always_return("_error" => error_data)
-      end
-    end
-
-    # Nothing on the executor is 'public'
-    class MockExecutor
-      attr_reader :noop, :error_message
-
-      def initialize
-        @noop = false
-        @task_doubles = {}
-        @allow_any_task = true
-        @error_message = nil
+        result
       end
 
-      def run_task(targets, task, arguments, options)
+      def run_task(targets, task, arguments, options = {})
         result = nil
         if (doub = @task_doubles[task.name] || @task_doubles[:default])
           result = doub.process(targets, task.name, arguments, options)
@@ -199,18 +79,44 @@ module BoltSpec
         result
       end
 
+      def upload_file(targets, source_path, destination, options = {})
+        source = module_file_id(source_path)
+        result = nil
+        if (doub = @upload_doubles[source] || @upload_doubles[:default])
+          result = doub.process(targets, source, destination, options)
+        end
+        unless result
+          targets = targets.map(&:name)
+          @error_message = "Unexpected call to 'upload_file(#{source}, #{destination}, #{targets}, #{options})'"
+          raise UnexpectedInvocation, @error_message
+        end
+        result
+      end
+
       def assert_call_expectations
-        @task_doubles.map do |taskname, doub|
-          doub.assert_called(taskname)
+        MOCKED_ACTIONS.each do |action|
+          instance_variable_get(:"@#{action}_doubles").map do |object, doub|
+            doub.assert_called(object)
+          end
+        end
+      end
+
+      MOCKED_ACTIONS.each do |action|
+        define_method(:"stub_#{action}") do |object|
+          instance_variable_get(:"@#{action}_doubles")[object] ||= ActionDouble.new(:"#{action.capitalize}Stub")
         end
       end
 
-      def stub_task(task_name)
-        @task_doubles[task_name] ||= TaskDouble.new
+      def stub_apply
+        @allow_apply = true
       end
 
       def wait_until_available(targets, _options)
-        targets.map { |target| Bolt::Result.new(target) }
+        Bolt::ResultSet.new(targets.map { |target| Bolt::Result.new(target) })
+      end
+
+      def log_action(*_args)
+        yield
       end
 
       def log_plan(_plan_name)
@@ -224,6 +130,24 @@ module BoltSpec
       def report_function_call(_function); end
 
       def report_bundled_content(_mode, _name); end
+
+      def report_apply(_statements, _resources); end
+
+      # Mocked for Apply so it does not compile and execute.
+      def with_node_logging(_description, targets)
+        raise "Unexpected call to apply(#{targets})" unless @allow_apply
+      end
+
+      def queue_execute(targets)
+        raise "Unexpected call to apply(#{targets})" unless @allow_apply
+        targets
+      end
+
+      def await_results(promises)
+        raise "Unexpected call to apply(#{targets})" unless @allow_apply
+        Bolt::ResultSet.new(promises.map { |target| Bolt::ApplyResult.new(target) })
+      end
+      # End Apply mocking
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-14 00:00:00.000000000 Z
+date: 2018-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -283,6 +283,7 @@ files:
 - bolt-modules/boltlib/lib/puppet/datatypes/resultset.rb
 - bolt-modules/boltlib/lib/puppet/datatypes/target.rb
 - bolt-modules/boltlib/lib/puppet/functions/add_facts.rb
+- bolt-modules/boltlib/lib/puppet/functions/add_to_group.rb
 - bolt-modules/boltlib/lib/puppet/functions/apply_prep.rb
 - bolt-modules/boltlib/lib/puppet/functions/facts.rb
 - bolt-modules/boltlib/lib/puppet/functions/fail_plan.rb
@@ -360,6 +361,11 @@ files:
 - lib/bolt_server/schemas/winrm-run_task.json
 - lib/bolt_server/transport_app.rb
 - lib/bolt_spec/plans.rb
+- lib/bolt_spec/plans/action_stubs.rb
+- lib/bolt_spec/plans/action_stubs/command_stub.rb
+- lib/bolt_spec/plans/action_stubs/script_stub.rb
+- lib/bolt_spec/plans/action_stubs/task_stub.rb
+- lib/bolt_spec/plans/action_stubs/upload_stub.rb
 - lib/bolt_spec/plans/mock_executor.rb
 - lib/bolt_spec/run.rb
 - libexec/apply_catalog.rb