cem_acpt 0.8.7 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd72076945b79db4583d665e691c86214c901331f37ccdfc25e0d07b999b50ca
-  data.tar.gz: f32e25b3c220e20c73aa3bcd7bab9873c2ac753b5d41c61e2f069988eaf29822
+  metadata.gz: dcea95d44401d3a90c8724ac2dbb85753eda2f38564ce84192f5580e1d528eaf
+  data.tar.gz: 6b2b8f267e951c578b35d49a11180bc8640da1695352097dd6652fc3e401aea9
 SHA512:
-  metadata.gz: a9e7b0d71cfd8efedd0faef1e8fb2cb23b0335a049b1b8d270a7325a3cf19b97d1d603042d7326478c6e4e23ae42de890de0b88bc38a21085ab44e19c47d605b
-  data.tar.gz: ab1df006f61525ead0c8b64f38b52fe93a1152a337eea0d7a78535f3496fa3d4856b3fdc46e6f9dd29f8fea038e17af5acd76ced4df502707f3880201d6df511
+  metadata.gz: cbe2360892776beb52c7d83bda5813283fc8b26c43148a45a60c5d8be03d45104976d4a91e48dc4a0207092b65712fd87224df40844cc4000628869fd24f5824
+  data.tar.gz: a6cfb5bc229561cdd0905d15c969de745bd14e5a767a60099543ca579b72659f6abc09cfa4182a44634552e23ace099c38095cc9bdfd06d471a436adebbd76a3

data/.github/workflows/spec.yml

@@ -8,8 +8,6 @@ on:
       - synchronize
     branches:
       - main
-    tags:
-      - v.*
 
 jobs:
   tests:
@@ -18,7 +16,6 @@ jobs:
     strategy:
       matrix:
         ruby:
-          - 2.7
           - 3.2
     steps:
       - name: Checkout Source

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cem_acpt (0.8.7)
+    cem_acpt (0.9.0)
       async-http (>= 0.60, < 0.70)
       bcrypt_pbkdf (>= 1.0, < 2.0)
       deep_merge (>= 1.2, < 2.0)
@@ -36,6 +36,7 @@ GEM
       fiber-local
     deep_merge (1.2.2)
     diff-lcs (1.5.0)
+    docile (1.4.0)
     ed25519 (1.3.0)
     erubi (1.12.0)
     ffi (1.15.5)
@@ -115,6 +116,12 @@ GEM
       rubocop-factory_bot (~> 2.22)
     ruby-progressbar (1.13.0)
     rubyntlm (0.6.3)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
     timers (4.3.5)
     traces (0.9.1)
     unicode-display_width (2.4.2)
@@ -141,6 +148,7 @@ DEPENDENCIES
   rubocop
   rubocop-performance
   rubocop-rspec
+  simplecov
 
 BUNDLED WITH
    2.4.19

data/README.md

@@ -10,7 +10,7 @@ CemAcpt uses [Terraform](#terraform) for provisioning test nodes, and [Goss](#go
 gem install cem_acpt
 ```
 
-`cem_acpt` was developed using Ruby 3.2.1, but other Ruby versions may work.
+`cem_acpt` was developed using Ruby 3.2.1, but other Ruby versions `>= 3.0.0` should work.
 
 ## Usage
 
@@ -101,6 +101,88 @@ To aide in development, you can enable tracing on CemAcpt's Ruby code execution
 
 CemAcpt uses [Terraform](https://www.terraform.io/) for managing the lifecycle of test nodes. Users don't interact with Terraform directly, but you will need it installed to use CemAcpt.
 
+## Bolt task testing
+
+CemAcpt can execute Bolt tasks against the test nodes and perform basic validation against their status and outputs.
+
+### Configuring Bolt tests
+
+Bolt tests expose the following configuration options that can be set via a config file:
+
+* `bolt.inventory_path` - A relative or absolute path to an existing inventory file, or the where the inventory file will be created
+* `bolt.project.name` -  The name of the Bolt project to be created and used during the Bolt tests
+* `bolt.project.analytics` - Whether or not to enable Bolt analytics. Should normally be `false`.
+* `bolt.project.path` - A relative or absolute path to an existing project file, or where the project file will be created
+* `bolt.tests.only` - An array of acceptance tests to only run Bolt tests for. When acceptance test names are specified here, Bolt tasks will only be ran against the nodes created for those acceptance tests.
+* `bolt.tests.ignore` - An array of acceptance tests to not run Bolt tests for. When acceptance test names are specified here, Bolt tasks will not be ran against the nodes created for those acceptance tests.
+* `bolt.tasks.only` - An array of Bolt tasks to only run against nodes. Bolt tasks not listed here will not be ran.
+* `bolt.tasks.ignore` - An array of Bolt tasks to not run against nodes. Bolt tasks specified here will not be ran at all.
+* `bolt.tasks.module_pattern` - If specified, will only run Bolt tasks whose module prefix matches the specified pattern will be ran. The module prefix is the first part of the full task name before the first `::`. This option is interpreted as a RegEx pattern. For example, if `bolt.tasks.module_prefix` is set to `^our_module`, and our we have two tasks, `our_module::the_task` and `other_module::another_task`, only `our_module::task` will be ran.
+* `bolt.tasks.name_filter` - Similar to `module_pattern`, but works on the portion of the task name after the module prefix and is exclusionary. For example, if `bolt.tasks.name_filter` is set to `^another_`, and our we have two tasks, `our_module::the_task` and `other_module::another_task`, only `our_module::the_task` will be ran.
+
+### Creating Bolt tests
+
+Bolt tests are not mandatory as all Bolt tasks that run will automatically be validated based on if they run successfully or not. However, sometimes we may want to test certain aspects of a Bolt task's output or pass a Bolt task parameters. To do this, we need to create a Bolt test file.
+
+Bolt test files are YAML files named `bolt.yaml` that live inside the individual acceptance test directories. For each acceptance test, only one `bolt.yaml` file should exist. The `bolt.yaml` file consists of one or more YAML hashes that take the following form:
+
+```yaml
+'module_name::task_name':
+  params: # Optional, if you want to specify params to pass to the task at runtime
+    param_name: 'param_string_value'
+  status: <success | failure | skipped> # Optional, this is set to 'success' by default
+  other_bolt_json_output_keys: # Optional
+    match: '^a string RegEx pattern$' # Optional
+    not_match: '^a string RegEx pattern$' # Optional
+```
+
+All Bolt tasks are ran with the `--format json` flag, which returns a JSON document of their output. The keys of this document can be validated to either a specified pattern, not match a specified pattern, or both. You can also specify a string value for a key, and then the key's value with be compared for simple string equality with the given value.
+
+Example:
+
+In this example, we will go over how a Bolt task's output would be evaluated by a Bolt test hash. This example assumes one Bolt task named `cem_linux::audit_sssd_certmap` that takes no parameters was ran successfully against two nodes.
+
+Bolt task JSON output:
+
+```json
+{
+  "items": [
+    {
+      "target":"35.212.146.14",
+      "action":"task",
+      "object":"cem_linux::audit_sssd_certmap",
+      "status":"success",
+      "value":{
+        "sssd_certmap_exists":false
+      }
+    },
+    {
+      "target":"35.212.197.53",
+      "action":"task",
+      "object":"cem_linux::audit_sssd_certmap",
+      "status":"success",
+      "value":{
+        "sssd_certmap_exists":false
+      }
+    }
+  ],
+  "target_count": 2,
+  "elapsed_time": 7
+}
+```
+
+Bolt test hash in `bolt.yaml`:
+
+```yaml
+'cem_linux::audit_sssd_certmap':
+  status: 'success'
+  value:
+    match: 'false'
+```
+
+This should result in the following log message after a run:
+`INFO: CemAcpt: SUMMARY: Bolt tests: status: passed, tests total: 1, tests succeeded: 1, tests failed: 0`
+
 ## Platforms
 
 Platforms are the underlying infrastructure that nodes are provisioned on. Currently, only GCP is supported. Each platform has two parts to it: the [platform](#platform) and the [node data](#node-data).
@@ -202,18 +284,18 @@ Much like `name_pattern_vars`, specifying the `image_name_builder` top-level key
 
 ## The acceptance test lifecycle
 
-- Load and merge the config
-- Create the local test directory under `$HOME/.cem_acpt`
-- Build the Puppet module. Uses current dir if no `module_dir` is specified in the config
-- Copy all relevant files into the local test directory
-  - This includes the Terraform files provided by CemAcpt, as well as the files under the specified acceptance test directory, and the built Puppet module
-- Provision test nodes using Terraform
-  - After the node is created, the contents of the local test directory are copied to the node
-  - Additionally, the Puppet module is installed on the node and Puppet is ran once to apply `manifest.pp`
-  - After, the Goss server endpoints are started and exposed on the node
-- Once node is provisioned, make HTTP get requests to the Goss server endpoints to run the tests
-- Destroy the test nodes
-- Report the results of the tests
+* Load and merge the config
+* Create the local test directory under `$HOME/.cem_acpt`
+* Build the Puppet module. Uses current dir if no `module_dir` is specified in the config
+* Copy all relevant files into the local test directory
+  * This includes the Terraform files provided by CemAcpt, as well as the files under the specified acceptance test directory, and the built Puppet module
+* Provision test nodes using Terraform
+  * After the node is created, the contents of the local test directory are copied to the node
+  * Additionally, the Puppet module is installed on the node and Puppet is ran once to apply `manifest.pp`
+  * After, the Goss server endpoints are started and exposed on the node
+* Once node is provisioned, make HTTP get requests to the Goss server endpoints to run the tests
+* Destroy the test nodes
+* Report the results of the tests
 
 ## Generating acceptance test node images
 

data/cem_acpt.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description   = 'Litmus-like library focusing on CEM Acceptance Tests'
   spec.homepage      = 'https://github.com/puppetlabs/cem_acpt'
   spec.license       = 'proprietary'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.0.0')
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/puppetlabs/cem_acpt'
@@ -37,4 +37,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'rubocop-performance'
   spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'simplecov'
 end

data/lib/cem_acpt/action_result.rb

@@ -4,16 +4,22 @@ module CemAcpt
   # Wrapper class for the result of an action. Provides a common interface for
   # getting reportable data from the result.
   class ActionResult
+    attr_reader :result
+
     def initialize(result)
       @result = if result.instance_of?(CemAcpt::Goss::Api::ActionResponse)
                   result
-                else
+                elsif result.instance_of?(CemAcpt::Bolt::Cmd::Output)
+                  result
+                elsif result.is_a?(StandardError)
                   ErrorActionResult.new(result)
+                else
+                  raise ArgumentError, "result must be a CemAcpt::Goss::Api::ActionResponse, CemAcpt::Bolt::Cmd::Output, or StandardError, got #{result.class}"
                 end
     end
 
     def error?
-      @result.is_a?(ErrorActionResult)
+      @result.is_a?(ErrorActionResult) || (@result.respond_to?(:error?) && @result.error?)
     end
 
     def method_missing(method_name, *args, **kwargs, &block)

data/lib/cem_acpt/actions.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'async'
+require 'async/barrier'
+require 'async/http/internet'
+
+module CemAcpt
+  # Provides a way to register actions to be executed if the registered
+  # actions are included in the list of actions to be executed.
+  module Actions
+    # Represents an action to be executed.
+    class Action
+      attr_reader :name, :order
+
+      def initialize(name, order = 0, &block)
+        @name = name.to_sym
+        @order = order
+        @block = block
+      end
+
+      def call(context)
+        @block&.call(context)
+      end
+    end
+
+    # Represents a group of actions.
+    class ActionGroup
+      attr_reader :name, :actions, :async, :order
+
+      def initialize(name = :main, **opts)
+        @name = name.to_sym
+        @actions = []
+        @async = opts[:async] || false
+        @order = opts[:order] || 0
+      end
+
+      # Registers a block to be executed if the registered actions are
+      # included in the list of actions to be executed.
+      # @param action [String, Symbol] the name of the action to be registered
+      # @param order [Integer] the order in which the action should be executed.
+      #   Lower numbers are executed first, but this order is relative to the
+      #   order of the associated action groups' execution order. Defaults to 0.
+      # @param block [Proc] the block to be executed
+      def register_action(name, order: 0, &block)
+        new_action = Action.new(name, order, &block)
+        @actions << new_action
+        sort!
+        self # return self to allow chaining
+      end
+
+      def filter_actions
+        filtered = @actions.dup
+        only = CemAcpt::Actions.config.only
+        except = CemAcpt::Actions.config.except
+        filtered.select! { |action| only.include?(action.name) } unless only.empty?
+        filtered.reject! { |action| except.include?(action.name) } unless except.empty?
+        filtered.sort_by!(&:order)
+        filtered
+      end
+
+      def sort!
+        @actions.sort_by!(&:order)
+      end
+    end
+
+    # Represents the configuration for the Actions module.
+    class ActionConfig
+      attr_reader :groups, :only, :except
+
+      def initialize
+        @groups = {
+          main: ActionGroup.new,
+        }
+        @only = []
+        @except = []
+      end
+
+      # Returns the action group with the specified name.
+      # @param key [String, Symbol] the name of the action group
+      def [](key)
+        groups[key.to_sym]
+      end
+
+      # Registers an action group. Actions groups are logical groups of
+      # actions that can be executed in parallel.
+      # @param name [String, Symbol] the name of the action group
+      # @param async [Boolean] whether the actions in the group should be
+      #   executed in parallel. Defaults to false.
+      # @param order [Integer] the order in which the action group should
+      #   be executed. Lower numbers are executed first.
+      def register_group(name, **opts)
+        return groups[name] if groups.key?(name)
+
+        groups[name] = ActionGroup.new(name, **opts)
+        groups[name]
+      end
+
+      # Returns a list of the names of all registered actions.
+      # @return [Array<String>] the list of all registered action names
+      def action_names(include_all: false)
+        return groups.values.map { |a| a.actions }.flatten.map(&:name).uniq if include_all
+
+        groups.values.map { |a| a.filter_actions }.flatten.map(&:name).uniq
+      end
+
+      def only=(actions)
+        raise ArgumentError, 'only must be an array' unless actions.is_a?(Array)
+
+        @only = actions.map(&:to_sym)
+      end
+
+      def except=(actions)
+        raise ArgumentError, 'except must be an array' unless actions.is_a?(Array)
+
+        @except = actions.map(&:to_sym)
+      end
+    end
+
+    class << self
+      attr_reader :config
+
+      # Configures the Actions module.
+      # @param world_config [CemAcpt::Config::Base] the current config for the "world"
+      # @yield [CemAcpt::Actions::ActionConfig] the config object for the Actions module
+      def configure(world_config)
+        @config = ActionConfig.new
+        @config.only = world_config.get('actions.only') || []
+        @config.except = world_config.get('actions.except') || []
+        yield @config if block_given?
+      end
+
+      # Executes the actions in the current action groups.
+      # @param opts [Hash] the options to be passed to the actions
+      # @option opts [Hash] :context the context to be passed to the actions
+      # @return [Array] the results of the actions
+      def execute(**opts)
+        context = opts[:context] || {}
+        ordered_groups = config.groups.values.sort_by(&:order)
+        ordered_groups.each_with_object([]) do |group, results|
+          actions = group.filter_actions
+          next if actions.empty?
+
+          context[:group] = group.name
+          context[:actions] = actions.map(&:name)
+          actions.each do |action|
+            action_opts = opts[action.name.to_sym] || {}
+            results << action.call(context.merge(action_opts))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cem_acpt/bolt/cmd/base.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'output'
+require_relative '../../logging'
+require_relative '../../utils/shell'
+
+module CemAcpt
+  module Bolt
+    module Cmd
+      # Base class for all Bolt command classes
+      class Base
+        include CemAcpt::Logging
+
+        # Class method that holds the names of all options for the command
+        def self.option_names
+          @option_names ||= []
+        end
+
+        # Class method that defines an option for the command
+        # @param name [String, Symbol] The name of the option
+        # @param flag [String] The flag to use for the option. Ex: '--modulepath'
+        # @param config_path [String] The path to the config value for the option. Ex: 'bolt.module_path'
+        # @param default [String] The default value for the option. Ex: '/home/user/.puppetlabs/bolt/modules'
+        # @param bool_flag [Boolean] Whether the option is a boolean flag or not. If this is true,
+        #   only the flag will be used for the option. For example, if the flag is '--clear-cache'
+        #   and bool_flag is set to true, and the value is 'true', then just '--clear-cache' will
+        #   be added to the command options. This differs from the default behavior of adding
+        #   '--clear-cache <value>' to the command options.
+        def self.option(name, flag, config_path: nil, default: nil, bool_flag: false)
+          name = name.to_sym
+          option_names << name
+
+          define_method(name) do
+            if bool_flag
+              find_val(name, flag: flag, config_path: config_path, default: default) ? flag : nil
+            else
+              val = find_val(name, flag: flag, config_path: config_path, default: default)
+              val ? "#{flag} #{val}" : nil
+            end
+          end
+        end
+
+        # Denotes that the command supports parameters. Calling this method will define a
+        # supports_params? method on the command class that returns true.
+        def self.supports_params
+          define_method(:supports_params?) { true }
+        end
+
+        attr_reader :cmd_env, :cmd_params
+
+        def initialize
+          @cmd_env = { 'BOLT_GEM' => 'TRUE' }
+          @cmd_params = {}
+        end
+
+        def inspect
+          "#{self.class}:\"#{cmd}\""
+        end
+
+        def to_s
+          cmd
+        end
+
+        # Returns the command to run as a string
+        # @return [String] The command to run as a string
+        def cmd
+          raise NotImplementedError, 'cmd method must be implemented in subclass'
+        end
+
+        # Adds an environment variable to the command
+        # @param name [String] The name of the environment variable
+        # @param value [String] The value of the environment variable
+        def add_cmd_env(name, value)
+          @cmd_env[name] = value
+        end
+
+        # Adds a parameter to the command. If passing a complex value, such as a hash, use
+        # the JSON representation of the value.
+        # @param name [String] The name of the parameter
+        # @param value [String] The value of the parameter
+        def add_cmd_param(name, value)
+          @cmd_params[name] = value
+        end
+
+        # Returns the family of the command. This is used to determine which command to run
+        # when multiple commands are available for the same action. For example, the 'task'
+        # command has multiple subcommands, such as 'task show' and 'task run'. The family of the
+        # 'task' command is 'task', and the family of the 'task show' and 'task run' subcommands is
+        # 'task'.
+        # @return [String] The family of the command
+        def command_family
+          raise NotImplementedError, 'command_family method must be implemented in subclass'
+        end
+
+        # Runs the command with the given options and environment variables
+        # @param strict [Boolean] Whether to raise an error if the command returns output that
+        #   does not implement items. Used for commands where the raw JSON output does not
+        #   include an 'items' key. Defaults to true.
+        # @param params [Hash] Parameters to pass to the Bolt command. Only used for some command types.
+        # @return [CemAcpt::Bolt::Cmd::Output] The output of the command
+        def run(strict: true, **params)
+          unless params.empty?
+            logger.debug('CemAcpt::Bolt') { "Setting command parameters: #{params}" }
+            params.each { |k, v| add_cmd_param(k, v) }
+          end
+          logger.debug('CemAcpt::Bolt') { "Running Bolt command: #{cmd}" }
+          logger.debug('CemAcpt::Bolt') { "Bolt command environment: #{cmd_env}" }
+          begin
+            out = CemAcpt::Utils::Shell.run_cmd(cmd, cmd_env, output: nil, raise_on_fail: false)
+            logger.debug('CemAcpt::Bolt') { "Bolt command raw output:\n#{out}" }
+            CemAcpt::Bolt::Cmd::Output.new(out, strict: strict, **(@item_defaults || {}))
+          rescue StandardError => e
+            logger.debug('CemAcpt::Bolt') { "Bolt command error:\n#{e}" }
+            CemAcpt::Bolt::Cmd::Output.new(e, **(@item_defaults || {}))
+          end
+        end
+
+        # Returns the options for the command as a string
+        # @return [String] The options for the command as a string
+        def options
+          opts = ['--format json']
+          recursive_option_names.each do |opt|
+            val = send(opt)
+            opts << val if val
+          end
+          if respond_to?(:supports_params?) && supports_params? && !cmd_params.empty?
+            opts << "--params '#{JSON.generate(cmd_params)}'"
+          end
+          join_array(opts)
+        end
+
+        def bolt_bin
+          @bolt_bin ||= CemAcpt::Utils::Shell.which('bolt', raise_if_not_found: true)
+        end
+
+        private
+
+        attr_reader :config
+
+        def join_array(ary)
+          ary.compact.join(' ')
+        end
+
+        def find_val(name, flag: nil, config_path: nil, default: nil)
+          ivar_safe_get("@#{name}") ||
+            ivar_safe_get("@#{flag.to_s.gsub(%r{[-]+}, '')}") ||
+            config&.get(config_path.to_s) ||
+            config&.get("bolt.tasks.cmd.defaults.#{flag.to_s.gsub(%r{[-]+}, '')}") ||
+            default
+        end
+
+        def ivar_safe_get(name)
+          name = "@#{name}" unless name.to_s.start_with?('@')
+          instance_variable_get(name)
+        rescue StandardError
+          nil
+        end
+
+        # Collects options defined in parent classes
+        def recursive_option_names(klass = self.class)
+          return [] if klass == Object
+          onames = klass.option_names.dup
+
+          if klass.superclass.respond_to?(:option_names)
+            onames.concat(recursive_option_names(klass.superclass))
+          else
+            onames
+          end
+        end
+      end
+    end
+  end
+end