bolt 0.21.3 → 0.21.4

data/lib/bolt_spec/plans.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'bolt_spec/plans/mock_executor'
+require 'bolt/config'
+
+# These helpers are intended to be used for plan unit testing without calling
+# out to target nodes. 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.
+#
+#
+#  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
+#  - 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
+#
+#  MAYBE TODO?:
+#  - allow stubbing for subplans
+#  - 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
+#
+# Example:
+#   describe "my_plan" do
+#     it 'should return' do
+#       allow_task('my_task').always_return({'result_key' => 10})
+#       expect(run_plan('my_plan', { 'param1' => 10 })).to be
+#     end
+#
+#     it 'should call task with param1' do
+#       expect_task('my_task').with_params('param1' => 10).always_return({'result_key' => 10})
+#       expect(run_plan('my_plan', { 'param1' => 10 })).to eq(10)
+#     end
+#
+#     it 'should call task with param1 once' do
+#       expect_task('my_task').with_params('param1' => 10).always_return({'result_key' => 10}).be_called_times(1)
+#       expect(run_plan('my_plan', { 'param1' => 10 })).to eq(10)
+#     end
+#
+#     it 'should not_call task with 100' do
+#       allow_task('my_task').always_return({'result_key' => 10})
+#       # Any call with param1 => 100 will match this since it's added second
+#       expect_task('my_task').with_params('param1' => 100).not_be_called
+#       expect(run_plan('my_plan', { 'param1' => 10 })).to eq(10)
+#     end
+#
+#     it 'should be called on both node1 and node2' do
+#       expect_task('my_task').with_targets(['node1', 'node2']).always_return({'result_key' => 10})
+#       expect(run_plan('my_plan', { 'param1' => 10 })).to eq(10)
+#     end
+#
+#     it 'should average results from targets' do
+#       expect_task('my_task').return_for_targets({
+#         'node1' => {'result_key' => 20},
+#         'node2' => {'result_key' => 6} })
+#       expect(run_plan('my_plan', { 'param1' => 10 })).to eq(13)
+#     end
+#   end
+#
+module BoltSpec
+  module Plans
+    # Override in your tests if needed
+    def modulepath
+      [RSpec.configuration.module_path]
+    rescue NoMethodError
+      raise "RSpec.configuration.module_path not defined set up rspec puppet or define modulepath for this test"
+    end
+
+    # Override in your tests
+    def config
+      config = Bolt::Config.new(Bolt::Boltdir.new('.'), {})
+      config.modulepath = modulepath
+      config
+    end
+
+    # Override in your tests
+    def inventory
+      @inventory ||= Bolt::Inventory.new({})
+    end
+
+    def puppetdb_client
+      @puppetdb_client ||= mock('puppetdb_client')
+    end
+
+    def run_plan(name, params)
+      pal = Bolt::PAL.new(config.modulepath, config.hiera_config)
+      result = pal.run_plan(name, params, executor, inventory, puppetdb_client)
+
+      if executor.error_message
+        raise executor.error_message
+      end
+
+      executor.assert_call_expectations
+
+      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
+    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
+    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
+    end
+
+    # Example helpers to mock other run functions
+    # 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
+
+    # Scripts can be mocked like tasks by their name
+    # arguments is an array instead of a hash though
+    # so it probably should be set separately
+    # def allow_script(script_name)
+    #
+    # file uploads have a single destination and no arguments
+    # def allow_file_upload(source_name)
+    #
+    # Most of the information in commands is in the command string itself
+    # we may need more flexible allows than just the name/command string
+    # Only option params exist on a command.
+    # def allow_command(command)
+    # def allow_command_matching(command_regex)
+    # def allow_command(&block)
+    #
+    # Plan execution does not flow through the executor mocking may make sense but
+    # will be a separate effort.
+    # def allow_plan(plan_name)
+
+    # intended to be private below here
+    def executor
+      @executor ||= BoltSpec::Plans::MockExecutor.new
+    end
+  end
+end

data/lib/bolt_spec/plans/mock_executor.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/result_set'
+require 'bolt/result'
+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
+
+      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 TaskStub
+      attr_reader :invocation
+
+      def initialize(expect = false)
+        @calls = 0
+        @expect = expect
+        @expected_calls = 1
+        # invocation spec
+        @invocation = {}
+        # return value
+        @data = { default: {} }
+      end
+
+      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.
+          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)
+        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
+        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
+
+      # 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
+
+      # 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
+        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
+      end
+
+      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)
+        end
+        unless result
+          targets = targets.map(&:name)
+          params = arguments.merge(options)
+          @error_message = "Unexpected call to 'run_task(#{task.name}, #{targets}, #{params})'"
+          raise UnexpectedInvocation, @error_message
+        end
+        result
+      end
+
+      def assert_call_expectations
+        @task_doubles.map do |taskname, doub|
+          doub.assert_called(taskname)
+        end
+      end
+
+      def stub_task(task_name)
+        @task_doubles[task_name] ||= TaskDouble.new
+      end
+
+      def report_function_call(_function); end
+
+      def report_bundled_content(_mode, _name); end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 0.21.3
+  version: 0.21.4
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-17 00:00:00.000000000 Z
+date: 2018-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -94,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: r10k
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: terminal-table
   requirement: !ruby/object:Gem::Requirement
@@ -297,7 +311,10 @@ files:
 - lib/bolt/analytics.rb
 - lib/bolt/applicator.rb
 - lib/bolt/bolt_option_parser.rb
+- lib/bolt/boltdir.rb
 - lib/bolt/catalog.rb
+- lib/bolt/catalog/compiler.rb
+- lib/bolt/catalog/logging.rb
 - lib/bolt/cli.rb
 - lib/bolt/config.rb
 - lib/bolt/error.rb
@@ -317,6 +334,7 @@ files:
 - lib/bolt/puppetdb.rb
 - lib/bolt/puppetdb/client.rb
 - lib/bolt/puppetdb/config.rb
+- lib/bolt/r10k_log_proxy.rb
 - lib/bolt/result.rb
 - lib/bolt/result_set.rb
 - lib/bolt/target.rb
@@ -330,9 +348,11 @@ files:
 - lib/bolt/transport/winrm.rb
 - lib/bolt/transport/winrm/connection.rb
 - lib/bolt/util.rb
-- lib/bolt/util/on_access.rb
+- lib/bolt/util/puppet_log_level.rb
 - lib/bolt/version.rb
 - lib/bolt_ext/puppetdb_inventory.rb
+- lib/bolt_spec/plans.rb
+- lib/bolt_spec/plans/mock_executor.rb
 - libexec/apply_catalog.rb
 - libexec/bolt_catalog
 - modules/aggregate/lib/puppet/functions/aggregate/count.rb