kitchen-pester 1.1.1 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e31dac41f9925e0fb86d2b96a2ead03a1c1dabb42adbf038ef572966aeb6d7db
-  data.tar.gz: 9047b382ad4d31572b7515aeb70d495e54019a87207cad463598938a669c38f7
+  metadata.gz: 2265777e3844674d88d2c9fee716b53e51931370db862b9ae1ab1e0e146a0d3f
+  data.tar.gz: ea5c52a19e982eb5f762d342a098160723120b4800734b611c1da782a0a49b62
 SHA512:
-  metadata.gz: 73bcc2e6ba82f652ca7ffd81d27c05b96d3eb1e0101043b0207d7dd583b8c040979f23a37f1b6c59c719979e026ce2df3ff7f8c319cb1dd41783668d3f0cd3e0
-  data.tar.gz: 7b63adcc2817a530bc5ddc8a2feb159353f80217abd739c8aba2019a222c6a841911c0a543dd8cb2fdf4159a3de9ae16aa3426333d71a4dd8175bb52dc0f9d80
+  metadata.gz: 521b9f823e6e4229dc55753e1a19c809056a70855276a5ab512ebcc4e41f9301396cd05deba5a8fe40528f1df25705f069c73401eeb8d67acd3501d9e7f3e502
+  data.tar.gz: 1294cc1198df01d440000612209d21b23d4904129d0b9fe2092b37a9186030819c87a145b88ea37526f544ce40e2ede8f616d2ea428f57bd878fc01d6b8902cc

data/README.md

@@ -0,0 +1,401 @@
+# kitchen-pester
+
+[![Gem Version](https://badge.fury.io/rb/kitchen-pester.svg)](http://badge.fury.io/rb/kitchen-pester)
+
+Run [Pester](https://pester.dev/) tests against a machine that
+[Test Kitchen](https://kitchen.ci/) built for you.
+
+Test Kitchen creates the machine, your provisioner configures it, and
+kitchen-pester copies your `*.Tests.ps1` files onto it, installs Pester, runs
+the tests, and brings the results back. No Busser layer in between.
+
+It works on Windows and on Linux or macOS instances with
+[PowerShell](https://github.com/PowerShell/PowerShell) installed.
+
+## Quick start
+
+### 1. Install the gem
+
+This verifier ships as part of [Cinc Workstation](https://cinc.sh/start/workstation/).
+If you have Cinc Workstation installed, there is nothing else to install.
+
+To install it into a standalone Ruby:
+
+```bash
+gem install kitchen-pester
+```
+
+or add it to your `Gemfile`:
+
+```ruby
+gem "kitchen-pester"
+```
+
+The examples below use the `cinc` commands. Everything here works identically
+with Chef Workstation — see [Using with Chef](#using-with-chef).
+
+### 2. Point Test Kitchen at it
+
+In `kitchen.yml`:
+
+```yaml
+verifier:
+  name: pester
+```
+
+You can set this at the top level, per platform, or per suite.
+
+### 3. Put your tests where it will find them
+
+For a suite named `default`, that is `tests/integration/default/`:
+
+```text
+tests/
+└── integration/
+    ├── default/
+    │   └── myapp.Tests.ps1
+    └── helpers/            # optional, copied to every suite
+        └── Assertions.ps1
+```
+
+### 4. Write a test
+
+An ordinary Pester file — nothing kitchen-specific:
+
+```powershell
+Describe 'myapp' {
+  It 'installed the binary' {
+    'C:\Program Files\myapp\myapp.exe' | Should -Exist
+  }
+
+  It 'is listening on 8080' {
+    Get-NetTCPConnection -LocalPort 8080 | Should -Not -BeNullOrEmpty
+  }
+}
+```
+
+### 5. Run it
+
+```bash
+cinc kitchen verify
+```
+
+Results are written to `./testresults/PesterTestResults.xml` in NUnit format,
+ready for a CI system to pick up. A failing Pester test fails `cinc kitchen verify`.
+
+## How it works
+
+Worth knowing when something goes wrong:
+
+1. **Sandbox.** Your suite's tests, any `helpers/`, anything in `copy_folders`,
+   and kitchen-pester's own `PesterUtil` PowerShell module are staged into a
+   local temp directory.
+2. **Transfer.** Test Kitchen ships that sandbox to the instance, under
+   `$env:TEMP/verifier` on Windows or `/tmp/verifier` elsewhere.
+3. **Prepare.** kitchen-pester prepends the sandbox's `modules/` folder to
+   `$env:PSModulePath`, then installs Pester and anything in
+   `install_modules`.
+4. **Run.** It writes a `kitchen_cmd.ps1` on the instance and invokes it. Your
+   tests run from the `suites/` folder inside the sandbox.
+5. **Download.** Everything in `downloads` is copied back — including when the
+   run fails, so you always get the results file.
+
+Every step is generated PowerShell. If a run misbehaves, `kitchen_cmd.ps1` on
+the instance is the exact script that ran.
+
+## Pester versions
+
+kitchen-pester supports **Pester 5** (the default) and **Pester 4**.
+
+It detects the installed version on the instance and adapts: Pester 5 gets a
+`PesterConfiguration` object built from your `pester_configuration`, Pester 4
+gets loose `Invoke-Pester` parameters. You do not need to tell it which one
+you are on.
+
+To stay on Pester 4, cap the install:
+
+```yaml
+verifier:
+  name: pester
+  pester_install:
+    MaximumVersion: '4.99.999'
+```
+
+## Configuration
+
+All of these go under `verifier:` in `kitchen.yml`.
+
+### Common
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `test_folder` | string | `tests` | Where your tests live. See [Test discovery](#test-discovery). |
+| `downloads` | map | `{"./PesterTestResults.xml" => "./testresults/"}` | Files to copy back from the instance. See [Downloads](#downloads). |
+| `environment` | map | `{}` | Environment variables to set for your tests. |
+| `copy_folders` | array | `[]` | Local folders to copy to the instance and put on `$env:PSModulePath`. |
+| `pester_configuration` | map | see [below](#pester_configuration) | Passed through to Pester. |
+| `root_path` | string | driver default | Directory on the SUT the sandbox is copied into. Relative `copy_folders` sources and the `suites` directory resolve against it, and `PesterTestResults.xml` is written there. |
+| `suite_name` | string | the suite name | Name of the suite, used when locating its tests. |
+
+### Installing Pester and its dependencies
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `pester_install` | map | `{SkipPublisherCheck: true, Force: true, ErrorAction: "Stop"}` | Splatted to `Install-Module -Name Pester`. |
+| `skip_pester_install` | bool | `false` | Use whatever Pester is already on the box. |
+| `install_modules` | array | `[]` | Extra modules to install from a gallery. |
+| `register_repository` | array | `[]` | PSRepositories to register first, for private feeds. |
+| `bootstrap` | map | `{repository_url: "https://www.powershellgallery.com/api/v2", modules: []}` | Modules to fetch straight from a NuGet feed, before PowerShellGet is usable. |
+| `remove_builtin_pester` | bool | `true` | Remove the Pester 3.4.0 that ships with Windows. |
+| `remove_builtin_powershellget` | bool | `true` | Remove the PowerShellGet and PackageManagement 1.0.0.1 that ship with Windows. |
+
+### Platform and shell
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `shell` | string | `nil` | Shell binary to use. Defaults to `powershell` on Windows, `pwsh` elsewhere. |
+| `sudo` | bool | `false` | Run PowerShell under sudo. Non-Windows only. |
+| `restart_winrm` | bool | `false` | Restart WinRM via a scheduled task before verifying. Windows only. |
+
+### Test discovery
+
+`test_folder` is where kitchen-pester starts looking. It may be relative to
+the directory you run `kitchen` from, or absolute, and it must exist.
+
+If `<test_folder>/integration` exists, that becomes the root instead — which is
+why the default `tests` finds `tests/integration`. Within that root:
+
+- `<root>/<suite_name>/` is copied to the instance and is what Pester runs.
+  Nest files however you like; Pester recurses.
+- `<root>/helpers/` is copied alongside **every** suite.
+
+### Downloads
+
+The key is the file on the instance, the value is where to put it locally.
+
+The **source** may be relative to the verifier folder (`$env:TEMP/verifier` by
+default) or absolute (`/var/tmp/file.zip`, `C:\Windows\Temp\file.zip`).
+
+The **destination** may be relative to the current directory or absolute, may
+end in `/` or `\` to mean "a directory, keep the filename", and may contain
+`%{instance_name}` to keep results from different instances apart:
+
+```yaml
+verifier:
+  name: pester
+  downloads:
+    PesterTestResults.xml: "testresults/%{instance_name}/"
+    kitchen_cmd.ps1: "testresults/%{instance_name}/"
+```
+
+Downloading `kitchen_cmd.ps1` like that is a useful debugging trick: it is the
+generated script that actually ran.
+
+### pester_configuration
+
+Defaults to:
+
+```yaml
+run:
+  path: "."
+  PassThru: true
+TestResult:
+  Enabled: true
+  OutputPath: PesterTestResults.xml
+  TestSuiteName: ""
+Output:
+  Verbosity: Detailed
+```
+
+**On Pester 5**, this becomes a `PesterConfiguration` via
+`New-PesterConfiguration -Hashtable`. Three keys are filled in for you if you
+leave them unset:
+
+| Key | Filled in with |
+| --- | --- |
+| `Run.Path` | `$env:TEMP/verifier/suites` |
+| `TestResult.TestSuiteName` | `Pester - <kitchen instance name>` |
+| `TestResult.OutputPath` | `$env:TEMP/verifier/PesterTestResults.xml` |
+
+**On Pester 4**, keys matching a real `Invoke-Pester` parameter are used and
+the rest are ignored. These defaults apply unless you set them:
+
+| Parameter | Default |
+| --- | --- |
+| `Script` | `$env:TEMP/verifier/suites` |
+| `OutputFile` | `$env:TEMP/verifier/PesterTestResults.xml` |
+| `OutputFormat` | `NUnitXml` |
+| `PassThru` | `true` |
+| `PesterOption` | `New-PesterOption -TestSuiteName "Pester - <instance name>"` |
+
+### register_repository
+
+Each entry is splatted to `Register-PSRepository`, or `Set-PSRepository` if the
+repository already exists:
+
+```yaml
+verifier:
+  name: pester
+  register_repository:
+    - Name: MyPrivateNuget
+      SourceLocation: https://mypsrepo.local/api/v2
+      InstallationPolicy: trusted
+      PackageManagementProvider: Nuget
+```
+
+### install_modules
+
+Plain names, or maps splatted to `Install-Module`:
+
+```yaml
+verifier:
+  name: pester
+  install_modules:
+    - PSScriptAnalyzer
+    - Name: MyModule
+      Repository: MyPrivateRepo
+      SkipPublisherCheck: true
+```
+
+### bootstrap
+
+For machines where PowerShellGet is too old to install anything — notably a
+stock Windows image. Modules are downloaded and unzipped straight from the
+NuGet API, bypassing `Install-Module` entirely.
+
+The feed must serve `$repository_url/package/<ModuleName>`, which some private
+feed implementations do not.
+
+```yaml
+verifier:
+  name: pester
+  bootstrap:
+    repository_url: https://www.powershellgallery.com/api/v2
+    modules:
+      - PackageManagement
+      - PowerShellGet
+```
+
+> **Note:** this key is replaced wholesale, not merged. If you set `modules`,
+> set `repository_url` too.
+
+## Examples
+
+### Testing a PowerShell module you just built
+
+`copy_folders` puts your build output on the instance's `$env:PSModulePath`,
+so your tests can `Import-Module MyModule` as if it were installed:
+
+```yaml
+verifier:
+  name: pester
+  copy_folders:
+    - output/MyModule
+  downloads:
+    PesterTestResults.xml: "testresults/%{instance_name}/"
+```
+
+### A stock Windows image
+
+Windows ships Pester 3.4.0 and PowerShellGet 1.0.0.1, neither of which can
+install a modern Pester on its own. The defaults already remove both; bootstrap
+replacements from NuGet so the install has something to work with:
+
+```yaml
+verifier:
+  name: pester
+  bootstrap:
+    repository_url: https://www.powershellgallery.com/api/v2
+    modules:
+      - PackageManagement
+      - PowerShellGet
+```
+
+### Linux, with PowerShell installed on the fly
+
+Use Test Kitchen's lifecycle hooks to install `pwsh` after the machine comes
+up. A recent `pwsh` ships a usable PowerShellGet, so no bootstrap is needed:
+
+```yaml
+provisioner:
+  name: shell
+  script: tests/integration/provisioning.ps1
+
+verifier:
+  name: pester
+
+platforms:
+  - name: ubuntu-22.04
+    lifecycle:
+      post_create:
+        - remote: sudo snap install powershell --classic
+
+suites:
+  - name: default
+```
+
+If `pwsh` is only reachable through sudo — as with a snap install on some
+systems — add `sudo: true` to the verifier.
+
+### Passing secrets and settings to your tests
+
+```yaml
+verifier:
+  name: pester
+  environment:
+    API_KEY: <%= ENV['API_KEY'] %>
+    PUSH_URI: https://push.example.com
+```
+
+```powershell
+Describe 'configuration' {
+  It 'received the API key' {
+    $env:API_KEY | Should -Not -BeNullOrEmpty
+  }
+}
+```
+
+## Troubleshooting
+
+**`cinc kitchen verify` fails but I get no results file.** You should still get one
+— downloads run even when the verify fails. If the file is missing, the run
+died before Pester started; check the `cinc kitchen verify` output for the install
+step.
+
+**I want to see the script that ran.** Add `kitchen_cmd.ps1` to `downloads`,
+or look for it in `$env:TEMP/verifier` on the instance.
+
+**`Install-Module` cannot find a repository.** The built-in PowerShellGet was
+removed (the default) and nothing replaced it. Either `bootstrap` a newer
+PowerShellGet, or set `remove_builtin_powershellget: false` if the machine's
+own copy works.
+
+**Tests are not found.** Check that your files are under
+`<test_folder>/integration/<suite_name>/` and match Pester's discovery
+pattern (`*.Tests.ps1`), and that the suite name in `kitchen.yml` matches the
+folder name.
+
+**PowerShell is not installed on a Linux instance.** kitchen-pester does not
+install it. Use a lifecycle hook or your provisioner.
+
+## Using with Chef
+
+This verifier runs Pester and does not depend on Cinc or Chef being installed on
+the system under test — it works with any Test Kitchen driver and provisioner.
+
+The examples above use [Cinc Workstation](https://cinc.sh/start/workstation/) and
+the `cinc kitchen` commands. With
+[Chef Workstation](https://www.chef.io/downloads/tools/workstation) run `kitchen`
+instead of `cinc kitchen`. No verifier configuration changes are needed.
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/test-kitchen/kitchen-pester). See
+[CONTRIBUTING.md](CONTRIBUTING.md) for development setup, how to run the unit
+specs, the PowerShell module specs, and the integration suite, and how the
+documentation is generated.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/kitchen-pester.gemspec

@@ -1,25 +1,31 @@
+# frozen_string_literal: true
+
 lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 require "kitchen/verifier/pester_version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "kitchen-pester"
+  spec.name = "kitchen-pester"
+  spec.required_ruby_version = ">= 3.1"
   spec.version       = Kitchen::Verifier::PESTER_VERSION
   spec.authors       = ["Steven Murawski"]
   spec.email         = ["steven.murawski@gmail.com"]
   spec.summary       = "Test-Kitchen verifier for Pester."
   spec.description   = "Skip all that Busser stuff and jump right into Pester."
   spec.homepage      = "https://github.com/test-kitchen/kitchen-pester"
-  spec.license       = "Apache-2.0"
+  spec.license       = "MIT"
 
-  spec.files         = %w{LICENSE kitchen-pester.gemspec Gemfile Rakefile} + Dir.glob("lib/**/*")
+  # README.md is what YARD picks up as the front page of the generated docs,
+  # which is how rubydoc.info renders this gem.
+  spec.files         = %w{LICENSE README.md kitchen-pester.gemspec} + Dir.glob("lib/**/*")
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "minitest",  "~> 5.3", "< 5.15"
-  spec.add_development_dependency "mocha",     "~> 1.1"
-
-  spec.add_dependency "test-kitchen", ">= 1.10", "< 4"
+  spec.add_development_dependency "minitest",  ">= 5.25", "< 7"
+  spec.add_development_dependency "mocha",     ">= 2.0", "< 4"
+  spec.add_development_dependency "yard",      "~> 0.9"
+  # 3.6.0 is the first release to require Ruby >= 3.1, which this gem also
+  # requires, so anything older cannot be installed alongside it in practice.
+  spec.add_dependency "test-kitchen", ">= 3.6", "< 5"
 end

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
@@ -66,6 +95,7 @@ module Kitchen
       default_config :copy_folders, []
       default_config :sudo, false
       default_config :shell, nil
+      default_config :environment, {}
 
       # Creates a new Verifier object using the provided configuration data
       # which will be merged with any default configuration.
@@ -73,6 +103,7 @@ module Kitchen
       # @param config [Hash] provided verifier configuration
       def initialize(config = {})
         init_config(config)
+        raise ClientError.new "Environment Variables must be specified as a hash, not a #{config[:environment].class}" unless config[:environment].is_a?(Hash)
       end
 
       # Creates a temporary directory on the local workstation into which
@@ -93,6 +124,8 @@ module Kitchen
       #       # any further file copies, preparations, etc.
       #     end
       #   end
+      #
+      # @return [void]
       def create_sandbox
         super
         prepare_supporting_psmodules
@@ -188,51 +221,56 @@ module Kitchen
         config[:downloads] = config[:downloads]
           .map do |source, destination|
             source = source.to_s
+            destination = destination.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))
               FileUtils.mkdir_p(File.dirname(destination))
             else
-              info("  Directory #{File.dirname(destination)} seem to exist.")
+              info("  Directory #{File.dirname(destination)} seems to exist.")
             end
 
             [ 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
@@ -240,6 +278,7 @@ module Kitchen
           $TestPath = Join-Path "#{config[:root_path]}" -ChildPath "suites"
           $OutputFilePath = Join-Path "#{config[:root_path]}" -ChildPath 'PesterTestResults.xml'
 
+          #{ps_environment(config[:environment])}
           if ($PesterModule.Version.Major -le 4)
           {
             Write-Host -Object "Invoke Pester with v$($PesterModule.Version) Options"
@@ -304,7 +343,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
@@ -314,6 +353,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?
@@ -361,7 +411,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]
@@ -382,7 +432,7 @@ 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
@@ -410,13 +460,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]}"
@@ -427,6 +495,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)'..."
@@ -435,7 +512,9 @@ module Kitchen
           # Send the pwsh here string to the file kitchen_cmd.ps1
           @'
           try {
-              Set-ExecutionPolicy Unrestricted -force
+              if (@('Bypass', 'Unrestricted') -notcontains (Get-ExecutionPolicy)) {
+                  Set-ExecutionPolicy Unrestricted -Force -Scope Process
+              }
           }
           catch {
               $_ | Out-String | Write-Warning
@@ -450,8 +529,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)'"
@@ -472,6 +558,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)
@@ -491,6 +583,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]}"
@@ -507,8 +609,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" ' \
@@ -520,6 +630,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.")
@@ -575,8 +691,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")
@@ -589,9 +706,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
@@ -611,21 +734,51 @@ 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
 
-      # returns the path of the modules subfolder
-      # in the sandbox, where PS Modules and folders will be copied to.
+      # 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} = #{ps_single_quote(v)}"
+        end
+
+        commands.join("\n")
+      end
+
+      # 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?
@@ -639,12 +792,13 @@ module Kitchen
         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.
+      #
+      # Useful when debugging what has actually been copied to the sandbox.
       #
-      # @return [Array<String>] array of files in a folder
+      # @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, "*"))
@@ -654,6 +808,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.")
@@ -661,15 +816,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)
@@ -686,27 +849,45 @@ 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
+      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.1.1".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.1"
   end
 end

data/lib/support/modules/PesterUtil/PesterUtil.psm1

@@ -1,3 +1,23 @@
+# 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.
+
 [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
 
 function Install-ModuleFromNuget {

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-pester
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.1
 platform: ruby
 authors:
 - Steven Murawski
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-07-16 00:00:00.000000000 Z
+date: 2026-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -25,73 +25,79 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.25'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.25'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.3'
+        version: '2.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '5.15'
+        version: '4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.3'
+        version: '2.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '5.15'
+        version: '4'
 - !ruby/object:Gem::Dependency
-  name: mocha
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '0.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: test-kitchen
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: '3.6'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '4'
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: '3.6'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '4'
+        version: '5'
 description: Skip all that Busser stuff and jump right into Pester.
 email:
 - steven.murawski@gmail.com
@@ -99,16 +105,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- Gemfile
 - LICENSE
-- Rakefile
+- README.md
 - kitchen-pester.gemspec
 - lib/kitchen/verifier/pester.rb
 - lib/kitchen/verifier/pester_version.rb
 - lib/support/modules/PesterUtil/PesterUtil.psm1
 homepage: https://github.com/test-kitchen/kitchen-pester
 licenses:
-- Apache-2.0
+- MIT
 metadata: {}
 post_install_message:
 rdoc_options: []
@@ -118,14 +123,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: Test-Kitchen verifier for Pester.

data/Gemfile

@@ -1,29 +0,0 @@
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in kitchen-pester.gemspec
-gemspec
-
-group :integration do
-  gem "berkshelf"
-  gem "kitchen-inspec"
-  gem "kitchen-azurerm"
-  gem "kitchen-chocolatey"
-end
-
-group :changelog do
-  gem "github_changelog_generator", "1.16.4"
-end
-
-group :debug do
-  gem "pry", "~>0.13.1"
-  gem "pry-byebug", "~>3.9.0"
-  gem "pry-stack_explorer"
-end
-
-group :chefstyle do
-  gem "chefstyle"
-end
-
-group :docs do
-  gem "yard"
-end

data/Rakefile

@@ -1,57 +0,0 @@
-require "bundler/gem_tasks"
-
-require "rake/testtask"
-Rake::TestTask.new(:unit) do |t|
-  t.libs.push "lib"
-  t.test_files = FileList["spec/**/*_spec.rb"]
-  t.verbose = true
-end
-
-task test: :unit
-
-begin
-  require "chefstyle"
-  require "rubocop/rake_task"
-  RuboCop::RakeTask.new(:style) do |task|
-    task.options += ["--display-cop-names", "--no-color"]
-  end
-rescue LoadError
-  puts "chefstyle is not available. (sudo) gem install chefstyle to do style checking."
-end
-
-desc "Run all quality tasks"
-task quality: :style
-
-begin
-  require "yard" unless defined?(YARD)
-  YARD::Rake::YardocTask.new
-rescue LoadError
-  puts "yard is not available. (sudo) gem install yard to generate yard documentation."
-end
-
-task default: %i{test quality}
-
-begin
-  require "github_changelog_generator/task"
-  require "kitchen/verifier/pester_version"
-
-  GitHubChangelogGenerator::RakeTask.new :changelog do |config|
-    config.future_release = "v#{Kitchen::Verifier::PESTER_VERSION}"
-    config.issues = false
-    config.pulls = true
-    config.user = "test-kitchen"
-    config.project = "kitchen-pester"
-  end
-rescue LoadError
-  puts "github_changelog_generator is not available." \
-       " (sudo) gem install github_changelog_generator to generate changelogs"
-end
-
-namespace :docs do
-  desc "Deploy docs"
-  task :deploy do
-    sh "cd docs && hugo"
-    sh "aws --profile chef-cd s3 sync docs/public s3://test-kitchen-legacy.cd.chef.co --delete --acl public-read"
-    sh "aws --profile chef-cd cloudfront create-invalidation --distribution-id EQD8MRW086SRT --paths '/*'"
-  end
-end