kitchen-pester 1.2.0 → 1.2.2

data/lib/kitchen/verifier/pester.rb

@@ -1,31 +1,60 @@
+# frozen_string_literal: true
+
 # Author:: Steven Murawski (<steven.murawski@gmail.com>)
 #
-# Copyright (C) 2015, Steven Murawski
+# Copyright (c) 2015 Steven Murawski
 #
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-#    http://www.apache.org/licenses/LICENSE-2.0
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
 
 require "fileutils" unless defined?(FileUtils)
 require "pathname" unless defined?(Pathname)
 require "kitchen/util"
 require "kitchen/verifier/base"
-require "kitchen/version"
-require "base64" unless defined?(Base64)
 require_relative "pester_version"
 
 module Kitchen
 
   module Verifier
 
+    # A Test Kitchen verifier that runs Pester tests on the system under test.
+    #
+    # The verifier does almost all of its work by generating PowerShell source
+    # locally and handing it to the transport to execute remotely. Each command
+    # hook -- {#install_command}, {#init_command}, {#prepare_command} and
+    # {#run_command} -- returns a script string rather than performing the work
+    # itself.
+    #
+    # Test files, helper files and any folders named in `copy_folders` are
+    # staged into a sandbox by {#create_sandbox}, shipped to the instance, and
+    # discovered there through `$Env:PSModulePath`.
+    #
+    # @example configuring the verifier in kitchen.yml
+    #
+    #   verifier:
+    #     name: pester
+    #     test_folder: tests
+    #     install_modules:
+    #       - PSScriptAnalyzer
+    #     downloads:
+    #       ./PesterTestResults.xml: ./testresults/
+    #
+    # @see https://pester.dev/ Pester
     class Pester < Kitchen::Verifier::Base
 
       kitchen_verifier_api_version 1
@@ -95,6 +124,8 @@ module Kitchen
       #       # any further file copies, preparations, etc.
       #     end
       #   end
+      #
+      # @return [void]
       def create_sandbox
         super
         prepare_supporting_psmodules
@@ -190,15 +221,24 @@ module Kitchen
         config[:downloads] = config[:downloads]
           .map do |source, destination|
             source = source.to_s
-            destination = destination.gsub("%{instance_name}", instance.name)
+            if destination.nil?
+              raise UserError, "The verifier's 'downloads' entry for '#{source}' has no local " \
+                               "destination. Every entry needs one, for example " \
+                               "'#{source}: ./testresults/'."
+            end
+
+            destination = destination.to_s.gsub("%{instance_name}", instance.name)
             info("  resolving remote source's absolute path.")
-            unless source.match?('^/|^[a-zA-Z]:[\\/]') # is Absolute?
+            unless source.match?(%r{^/|^[a-zA-Z]:[\\/]}) # is Absolute?
               info("  '#{source}' is a relative path, resolving to: #{File.join(config[:root_path], source)}")
               source = File.join(config[:root_path], source.to_s).to_s
             end
 
-            if destination.match?('\\$|/$') # is Folder (ends with / or \)
-              destination = File.join(destination, File.basename(source)).to_s
+            if destination.match?(%r{[\\/]$}) # is Folder (ends with / or \)
+              # Append to the separator the user already supplied. File.join
+              # would add a second one, of whichever flavour the workstation
+              # happens to use.
+              destination = "#{destination}#{remote_basename(source)}"
             end
             info("  Destination: #{destination}")
             if !File.directory?(File.dirname(destination))
@@ -209,33 +249,34 @@ module Kitchen
 
             [ source, destination ]
           end
+          .to_h # Hash#map yields pairs; keep :downloads the hash it started as
         nil # make sure we do not return anything
       end
 
-      # Download functionality was added to the base verifier behavior after
-      # version 2.3.4
-      if Gem::Version.new(Kitchen::VERSION) <= Gem::Version.new("2.3.4")
-        def call(state)
-          super
-        ensure
-          info("Ensure download test files.")
-          download_test_files(state) unless config[:downloads].nil?
-          info("Download complete.")
-        end
-      else
-        def call(state)
-          super
-        rescue
-          # If the verifier reports failure, we need to download the files ourselves.
-          # Test Kitchen's base verifier doesn't have the download in an `ensure` block.
-          info("Rescue to download test files.")
-          download_test_files(state) unless config[:downloads].nil?
-          # Rethrow original exception, we still want to register the failure.
-          raise
-        end
+      # Runs the verifier on the instance, retrieving the test results even
+      # when the run fails.
+      #
+      # @param state [Hash] mutable instance state
+      # @raise [Kitchen::ActionFailed] if the verification failed
+      # @return [void]
+      def call(state)
+        super
+      rescue
+        info("Rescue to download test files.")
+        download_test_files(state) unless config[:downloads].nil?
+        # Rethrow the original exception; the failure still has to register.
+        raise
       end
 
-      # private
+      # Returns the PowerShell that imports Pester and invokes it.
+      #
+      # Two dialects are emitted behind a version check evaluated on the SUT:
+      # Pester 4 and earlier take loose parameters, Pester 5 and later take a
+      # `PesterConfiguration` object. The script exits with Pester's failed
+      # test count so the transport registers the failure.
+      #
+      # @return [String] a PowerShell script
+      # @api private
       def invoke_pester_scriptblock
         <<-PS1
           $PesterModule = Import-Module -Name Pester -Force -ErrorAction Stop -PassThru
@@ -308,7 +349,7 @@ module Kitchen
 
           $resultXmlPath = (Join-Path -Path $TestPath -ChildPath 'result.xml')
           if (Test-Path -Path $resultXmlPath) {
-            $result | Export-CliXml -Path
+            $result | Export-CliXml -Path $resultXmlPath
           }
 
           $LASTEXITCODE = $result.FailedCount
@@ -318,6 +359,17 @@ module Kitchen
         PS1
       end
 
+      # Returns the commands that install the bootstrap modules straight from
+      # a NuGet feed.
+      #
+      # This runs before PowerShellGet is available, so it uses
+      # `Install-ModuleFromNuget` from PesterUtil.psm1 rather than
+      # `Install-Module`. Each entry of `bootstrap.modules` may be a plain
+      # module name or a hash of parameters.
+      #
+      # @return [Array<String>, nil] one PowerShell fragment per module, or nil
+      #   when no bootstrap modules are configured
+      # @api private
       def get_powershell_modules_from_nugetapi
         # don't return anything is the modules subkey or bootstrap is null
         return if config.dig(:bootstrap, :modules).nil?
@@ -327,12 +379,13 @@ module Kitchen
         gallery_url_param = bootstrap[:repository_url] ? "-GalleryUrl '#{bootstrap[:repository_url]}'" : ""
 
         info("Bootstrapping environment without PowerShellGet Provider...")
-        Array(bootstrap[:modules]).map do |powershell_module|
+        config_list("bootstrap.modules", bootstrap[:modules]).map do |powershell_module|
           if powershell_module.is_a? Hash
+            module_name = module_name!("bootstrap.modules", powershell_module)
             <<-PS1
-              ${#{powershell_module[:Name]}} = #{ps_hash(powershell_module)}
+              ${#{module_name}} = #{ps_hash(powershell_module)}
 
-              Install-ModuleFromNuget -Module ${#{powershell_module[:Name]}} #{gallery_url_param}
+              Install-ModuleFromNuget -Module ${#{module_name}} #{gallery_url_param}
             PS1
           else
             <<-PS1
@@ -351,13 +404,14 @@ module Kitchen
         return if config[:register_repository].nil?
 
         info("Registering a new PowerShellGet Repository")
-        Array(config[:register_repository]).map do |psrepo|
+        config_list("register_repository", config[:register_repository]).map do |psrepo|
+          repo_name = module_name!("register_repository", psrepo)
           # Using Set-PSRepo from ../../*/*/*/PesterUtil.psm1
-          debug("Command to set PSRepo #{psrepo[:Name]}.")
+          debug("Command to set PSRepo #{repo_name}.")
           <<-PS1
-            Write-Host 'Registering psrepo #{psrepo[:Name]}...'
-            ${#{psrepo[:Name]}} = #{ps_hash(psrepo)}
-            Set-PSRepo -Repository ${#{psrepo[:Name]}}
+            Write-Host 'Registering psrepo #{repo_name}...'
+            ${#{repo_name}} = #{ps_hash(psrepo)}
+            Set-PSRepo -Repository ${#{repo_name}}
           PS1
         end
       end
@@ -365,7 +419,7 @@ module Kitchen
       # Returns the string command set the PSGallery as trusted, and
       # Install Pester from gallery based on the params from Pester_install_params config
       #
-      # @return <String> command to install Pester Module
+      # @return [String] command to install Pester Module
       # @api private
       def install_pester
         return if config[:skip_pester_install]
@@ -386,17 +440,17 @@ module Kitchen
       end
 
       # returns a piece of PS scriptblock for each Module to install
-      # from gallery that has been sepcified in install_modules config.
+      # from gallery that has been specified in install_modules config.
       #
       # @return [Array<String>] array of PS commands.
       # @api private
       def install_modules_from_gallery
         return if config[:install_modules].nil?
 
-        Array(config[:install_modules]).map do |powershell_module|
+        config_list("install_modules", config[:install_modules]).map do |powershell_module|
           if powershell_module.is_a? Hash
             # Sanitize variable name so that $powershell-yaml becomes $powershell_yaml
-            module_name = powershell_module[:Name].gsub(/[\W]/, "_")
+            module_name = module_name!("install_modules", powershell_module).gsub(/[\W]/, "_")
             # so we can splat that variable to install module
             <<-PS1
               $#{module_name} = #{ps_hash(powershell_module)}
@@ -414,13 +468,31 @@ module Kitchen
         end
       end
 
+      # Note for anyone adding to the script builders below: Kitchen::Util.outdent!
+      # mutates the string it is handed, and this file sets
+      # `frozen_string_literal: true`. Interpolated literals are not frozen, so
+      # every heredoc that reaches outdent! today is fine -- but a heredoc with
+      # no `#{}` in it would be frozen and would raise FrozenError at runtime.
+      # Use +dup+ on any such string before passing it along.
+
+      # Wraps generated PowerShell in the platform's shell invocation.
+      #
+      # @param code [String] the PowerShell to run on the instance
+      # @return [String] a shell command string
+      # @api private
       def really_wrap_shell_code(code)
         windows_os? ? really_wrap_windows_shell_code(code) : really_wrap_posix_shell_code(code)
       end
 
-      # Get the defined shell or fall back to pwsh, unless we're on windows where we use powershell
-      # call via sudo if sudo is true.
-      # This allows to use pwsh-preview instead of pwsh, or a full path to a specific binary.
+      # Returns the shell binary used to run the generated script.
+      #
+      # An explicit `shell` config wins, which allows pwsh-preview or a full
+      # path to a specific binary. Otherwise Windows uses powershell and every
+      # other platform uses pwsh. `sudo` is honoured everywhere except the
+      # Windows branch, where it is meaningless.
+      #
+      # @return [String] the shell command, prefixed with sudo when configured
+      # @api private
       def shell_cmd
         if !config[:shell].nil?
           config[:sudo] ? "sudo #{config[:shell]}" : "#{config[:shell]}"
@@ -431,6 +503,15 @@ module Kitchen
         end
       end
 
+      # Wraps PowerShell for a Windows instance.
+      #
+      # The payload is written to kitchen_cmd.ps1 and invoked, rather than
+      # passed on the command line, so that quoting and length limits do not
+      # apply to it.
+      #
+      # @param code [String] the PowerShell to run on the instance
+      # @return [String] a shell command string
+      # @api private
       def really_wrap_windows_shell_code(code)
         my_command = <<-PWSH
           echo "Running as '$(whoami)'..."
@@ -456,8 +537,15 @@ module Kitchen
         wrap_shell_code(Util.outdent!(my_command))
       end
 
-      # Writing the command to a ps1 file, adding the pwsh shebang
-      # invoke the file
+      # Wraps PowerShell for a non-Windows instance.
+      #
+      # Writes the payload to kitchen_cmd.ps1 through a quoted heredoc, so the
+      # POSIX shell does not interpolate PowerShell variables, adds a pwsh
+      # shebang and invokes it.
+      #
+      # @param code [String] the PowerShell to run on the instance
+      # @return [String] a shell command string
+      # @api private
       def really_wrap_posix_shell_code(code)
         my_command = <<-BASH
           echo "Running as '$(whoami)'"
@@ -478,6 +566,12 @@ module Kitchen
         Util.outdent!(my_command)
       end
 
+      # Prefixes a script with the preamble that makes the sandbox's modules
+      # folder importable.
+      #
+      # @param script [String] the PowerShell to run after the preamble
+      # @return [String] the script with the PSModulePath preamble prepended
+      # @api private
       def use_local_powershell_modules(script)
         <<-PS1
           Write-Host -Object ("{0} - PowerShell {1}" -f $PSVersionTable.OS,$PSVersionTable.PSVersion)
@@ -497,6 +591,16 @@ module Kitchen
         PS1
       end
 
+      # Returns the PowerShell that prepares the SUT once the sandbox has been
+      # transferred.
+      #
+      # Runs after the transfer so that PesterUtil.psm1 is available to import.
+      # Composes, in order: the NuGet bootstrap, any PSRepository registration,
+      # the Pester install, and any gallery modules. Each section is omitted
+      # when its config is nil.
+      #
+      # @return [String] a PowerShell script
+      # @api private
       def install_command_script
         <<-PS1
           $PSModPathToPrepend = "#{config[:root_path]}"
@@ -513,8 +617,16 @@ module Kitchen
         PS1
       end
 
+      # Returns the command that schedules and runs a WinRM restart.
+      #
+      # The restart is driven through a scheduled task so that it survives the
+      # WinRM session being torn down by the restart itself.
+      #
+      # @return [String, nil] a shell command string, or nil on a non-Windows
+      #   instance
+      # @api private
       def restart_winrm_service
-        return unless verifier.windows_os?
+        return unless windows_os?
 
         cmd = "schtasks /Create /TN restart_winrm /TR " \
               '"powershell -Command Restart-Service winrm" ' \
@@ -526,6 +638,12 @@ module Kitchen
                                      ))
       end
 
+      # Retrieves the configured result files from the instance.
+      #
+      # @param state [Hash] mutable instance state, used to open the transport
+      #   connection
+      # @return [void]
+      # @api private
       def download_test_files(state)
         if config[:downloads].nil?
           info("Skipped downloading test result file from #{instance.to_str}; 'downloads' hash is empty.")
@@ -581,8 +699,9 @@ module Kitchen
       end
 
       # Copies all common testing helper files into the suites directory in
-      # the sandbox.
+      # the sandbox, stripping the `helpers/` prefix from their paths.
       #
+      # @return [void]
       # @api private
       def prepare_helpers
         base = File.join(test_folder, "helpers")
@@ -595,9 +714,15 @@ module Kitchen
         end
       end
 
-      # Creates a PowerShell hashtable from a ruby map.
-      # The only types supported for now are hash, array, string and Boolean.
+      # Renders a Ruby value as PowerShell source.
       #
+      # Hashes become hashtables, arrays become arrays, booleans become $true
+      # or $false, and everything else is quoted as a string -- PowerShell is
+      # generally able to coerce it back to the type it needs.
+      #
+      # @param obj [Object] the value to render
+      # @param depth [Integer] current nesting depth, used for indentation
+      # @return [String] PowerShell source for the value
       # @api private
       def ps_hash(obj, depth = 0)
         if [true, false].include? obj
@@ -617,51 +742,71 @@ module Kitchen
         else
           # When the object is not a string nor a hash or array, it will be quoted as a string.
           # In most cases, PS is smart enough to convert back to the type it needs.
-          "'" + obj.to_s + "'"
+          ps_single_quote(obj)
         end
       end
 
       # Creates environment variable assignments from a ruby map.
       #
+      # @param obj [Hash] variable names mapped to their values
+      # @return [String] newline-separated `$env:NAME = 'value'` assignments
       # @api private
       def ps_environment(obj)
         commands = obj.map do |k, v|
-          "$env:#{k} = '#{v}'"
+          "$env:#{k} = #{ps_single_quote(v)}"
         end
 
         commands.join("\n")
       end
 
-      # returns the path of the modules subfolder
-      # in the sandbox, where PS Modules and folders will be copied to.
+      # Renders a value as a single-quoted PowerShell string literal.
+      #
+      # PowerShell escapes a literal quote inside a single-quoted string by
+      # doubling it. Without this an apostrophe anywhere in the config -- a
+      # module name, an environment value, a password -- closes the string
+      # early and corrupts the rest of the generated script.
+      #
+      # @param value [Object] any value; #to_s is used
+      # @return [String] a quoted, escaped PowerShell string literal
+      # @api private
+      def ps_single_quote(value)
+        "'#{value.to_s.gsub("'", "''")}'"
+      end
+
+      # Returns the path of the modules subfolder in the sandbox, where PS
+      # modules and folders will be copied to.
       #
+      # @return [String] absolute path to the sandbox's modules folder
       # @api private
       def sandbox_module_path
         File.join(sandbox_path, "modules")
       end
 
-      # copy files into the 'modules' folder of the sandbox,
-      # so that copied folders can be discovered with the updated $Env:PSModulePath.
+      # Copies the folders named in `copy_folders` into the sandbox's modules
+      # folder, so they can be discovered through the updated
+      # $Env:PSModulePath.
       #
+      # @return [void]
       # @api private
       def prepare_copy_folders
         return if config[:copy_folders].nil?
 
         info("Preparing to copy specified folders to #{sandbox_module_path}.")
         kitchen_root_path = config[:kitchen_root]
-        config[:copy_folders].each do |folder|
+        config_list("copy_folders", config[:copy_folders]).each do |folder|
           debug("copying #{folder}")
           folder_to_copy = File.join(kitchen_root_path, folder)
           copy_if_src_exists(folder_to_copy, sandbox_module_path)
         end
       end
 
-      # returns an array of string
-      # Creates a flat list of files contained in a folder.
-      # This is useful when trying to debug what has been copied to
-      # the sandbox.
+      # Creates a flat list of the files contained in a folder.
       #
-      # @return [Array<String>] array of files in a folder
+      # Useful when debugging what has actually been copied to the sandbox.
+      #
+      # @param path [String] the folder to list
+      # @return [Array<String>] paths of the entries at the top level and
+      #   nested beneath it
       # @api private
       def list_files(path)
         base_directory_content = Dir.glob(File.join(path, "*"))
@@ -671,6 +816,7 @@ module Kitchen
 
       # Copies all test suite files into the suites directory in the sandbox.
       #
+      # @return [void]
       # @api private
       def prepare_pester_tests
         info("Preparing to copy files from  '#{suite_test_folder}' to the SUT.")
@@ -678,15 +824,23 @@ module Kitchen
         copy_if_src_exists(suite_test_folder, sandboxed_suites_path)
       end
 
+      # Copies PesterUtil.psm1 into the sandbox's modules folder, where the
+      # updated $Env:PSModulePath will find it.
+      #
+      # @return [void]
+      # @api private
       def prepare_supporting_psmodules
         info("Preparing to copy files from '#{support_psmodule_folder}' to the SUT.")
         sandbox_module_path = File.join(sandbox_path, "modules")
         copy_if_src_exists(support_psmodule_folder, sandbox_module_path)
       end
 
-      # Copies a folder recursively preserving its layers,
-      # mostly used to copy to the sandbox.
+      # Copies a folder recursively, preserving its layers. Mostly used to
+      # copy into the sandbox. Does nothing when the source does not exist.
       #
+      # @param src_to_validate [String] folder to copy
+      # @param destination [String] folder to copy into, created if missing
+      # @return [void]
       # @api private
       def copy_if_src_exists(src_to_validate, destination)
         unless Dir.exist?(src_to_validate)
@@ -703,27 +857,100 @@ module Kitchen
         FileUtils.cp_r(src_to_validate, destination, preserve: true)
       end
 
-      # returns the absolute path of the folders containing the
-      # test suites, use default if not set.
+      # Returns the folder containing the test suites, falling back to
+      # `test_base_path` when `test_folder` is not set.
       #
+      # @return [String] path to the folder holding the suites
       # @api private
       def test_folder
         config[:test_folder].nil? ? config[:test_base_path] : absolute_test_folder
       end
 
-      # returns the absolute path of the relative folders containing the
-      # test suites, use default i not set.
+      # Resolves `test_folder` to an absolute path, descending into an
+      # `integration` subfolder when one exists.
       #
+      # @return [String] absolute path to the folder holding the suites
       # @api private
       def absolute_test_folder
         path = (Pathname.new config[:test_folder]).realpath
         integration_path = File.join(path, "integration")
-        Dir.exist?(integration_path) ? integration_path : path
+        Dir.exist?(integration_path) ? integration_path : path.to_s
+      rescue Errno::ENOENT
+        raise UserError, "The verifier's 'test_folder' is set to " \
+                         "'#{config[:test_folder]}', which does not exist. It is resolved " \
+                         "relative to the directory kitchen runs in, so give it a path that " \
+                         "exists there or an absolute one."
+      end
+
+      # Returns the entries of a config option that is documented as a list.
+      #
+      # YAML makes it easy to write a single mapping where a list of mappings
+      # was meant -- leaving off the leading `- ` is enough. `Array()` turns
+      # such a mapping into a list of `[key, value]` pairs, which then renders
+      # as nonsense PowerShell instead of failing, so reject it here where we
+      # can still say which option is at fault.
+      #
+      # @param key [String] the option's name, for the error message
+      # @param value [Object] the configured value
+      # @return [Array] the entries to iterate over
+      # @raise [Kitchen::UserError] when a single mapping was given
+      # @api private
+      def config_list(key, value)
+        if value.is_a?(Hash)
+          raise UserError, "The verifier's '#{key}' must be a list, but a single mapping " \
+                           "was given. Put a '- ' in front of each entry in kitchen.yml."
+        end
+
+        Array(value)
+      end
+
+      # Returns the Name of a mapping-shaped entry in one of the module or
+      # repository lists.
+      #
+      # The name becomes a PowerShell variable that the generated script splats,
+      # so a missing one either blows up here or emits an empty `${}` that fails
+      # on the instance a long way from its cause.
+      #
+      # @param key [String] the option's name, for the error message
+      # @param entry [Hash] the entry to read the name from
+      # @return [String] the entry's Name
+      # @raise [Kitchen::UserError] when the entry is not a mapping, or has no
+      #   usable Name
+      # @api private
+      def module_name!(key, entry)
+        unless entry.is_a?(Hash)
+          raise UserError, "Every entry under the verifier's '#{key}' must be a mapping with " \
+                           "at least a 'Name'; #{entry.inspect} is a #{entry.class}."
+        end
+
+        name = entry[:Name] || entry["Name"]
+        if name.to_s.empty?
+          raise UserError, "Every mapping under the verifier's '#{key}' needs a 'Name'; " \
+                           "#{entry.inspect} has none."
+        end
+
+        name.to_s
+      end
+
+      # Returns the final segment of a path that lives on the SUT.
+      #
+      # File.basename applies the *workstation's* separator rules, so a Windows
+      # remote path such as 'C:\results\out.xml' comes back unchanged when
+      # kitchen runs on macOS or Linux -- the usual case for a Windows SUT.
+      # Split on either separator instead.
+      #
+      # @param path [String] a path as it exists on the instance
+      # @return [String] the last path segment
+      # @api private
+      def remote_basename(path)
+        path.to_s.split(%r{[\\/]}).last.to_s
       end
 
-      # returns a string of space of the specified depth.
-      # This is used to pad messages or when building PS hashtables.
+      # Returns a run of spaces of the given width, used to pad messages and
+      # indent generated PowerShell hashtables.
       #
+      # @param depth [Integer] number of spaces
+      # @return [String] the padding
       # @api private
       def pad(depth = 0)
         " " * depth

data/lib/kitchen/verifier/pester_version.rb

@@ -1,5 +1,35 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2015 Steven Murawski
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+# Test Kitchen's top-level namespace.
 module Kitchen
+  # Namespace for Test Kitchen verifier plugins.
   module Verifier
-    PESTER_VERSION = "1.2.0".freeze
+    # Version of the kitchen-pester gem.
+    #
+    # Kept in its own file so that the gemspec can read it without loading
+    # test-kitchen, which is not yet available when the gemspec is evaluated.
+    #
+    # @return [String] the gem version
+    PESTER_VERSION = "1.2.2"
   end
 end