A Test Kitchen driver to execute Pester as a verifier
Execute Pester tests, cross platform, right from Test-Kitchen, without having to transit the Busser layer.
For now, this gem hasn't been tested with Pester v5+.
Either
gem install kitchen-pester
or include
gem 'kitchen-pester'
in your Gemfile.
In your .kitchen.yml include
verifier:
name: pester
This can be a top-level declaration, a per-node declaration, or a per-suite declaration.
restart_winrm
- boolean, default is false
. (Windows only)
Restarts the winrm service using a scheduled tasks before proceding.
This setting is ignored on non-windows OSes.
test_folder
- string, default is ./tests/integration/
.
Allows you to specify a custom path (the default is ./test/[integration/]) for your integration tests.
This can be an absolute path or relative to the root of the folder kitchen is running from on the host machine.
This path must exist.
When you specify a folder, it will automatically try to append /integration
to that path.
If it exists, it will use this as the root tests directory.
If it doesn't, it will use the test_folder
.
If you have a helpers
folders under test_folder
(i.e. ./tests/helpers
), those will be copied to the SUT for every test suite.
remove_builtin_powershellget
- bool, default is true
(v.1.0.0.1)
Remove the built-in PowerShellGet and PackageManagement modules on Windows (v1.0.0.1), as they will often cause problems and will be superseded by the bootstrapped versions by default.
remove_builtin_pester
- bool, default is true
(v3.4.0)
Remove the Pester module that is built-in on Windows (v3.4.0), because upgrading to a later version is awkward if this is not first removed (requires both -SkipPublisherCheck
& -Force
, which makes it slow every time you kitchen verify
).
Removing the built-in ensures that the only version in use will be the Pester version specified by the configuration.
bootstrap
- map, default is {}
(PowershellGet & Package Management)
Allows kitchen-pester to download the PowerShellGet and PackageManagement module directly from the Nuget API URL.
Note that it needs to be able to download the nupkg from $galleryUrl/package/PowerShellGet
, which may not be available with some private feed implementations.
register_repository
- array (of maps), default is []
Allows you to register PSRepositories to download modules from. Useful when you want to use a private feed.
This expects a map for each repository to register, the values will be splatted to Register-PSRepository
(or Set-PSRepository
if it already exists).
register_repository:
- Name: MyPrivateNuget
SourceLocation: https://mypsrepo.local/api/v2
InstallationPolicy: trusted
PackageManagementProvider: Nuget
install_modules
- array (of maps), default is []
Array of maps, that will be splatted to the Install-Module parameters.
Useful for installing dependencies from a gallery.
install_modules:
- Name: MyModule
Repository: MyPrivateRepo
SkipPublisherCheck: true
copy_folders
- array, default is []
Folders (relative to the current directory or absolute) to copy to the System Under Test (SUT).
The SUT's $env:PSModulePath
will have the parent folder prepended for the session.
If you are testing a PowerShell module you have built as part of your build process, this enables you to copy the module folder directly to the target machine.
verifier:
name: pester
copy_folders:
- output/MyModule
pester_install:
MaximumVersion: '4.99.999'
skip_pester_install
- bool default is false
Skip installing pester and just use what's available on the box, or what you have copied with the copy_folders
options.
pester_install
- map, default is
{
SkipPublisherCheck: true,
Force: true,
ErrorAction: "Stop",
}
Specify parameters for installing Pester before running the tests.
The map will be splatted to the Install-Module -Name Pester
command.
You can use this to install the module from a private gallery, for instance.
pester_configuration
- hash, defaults to
{
run: {
path: "suites/",
PassThru: true,
},
TestResult: {
Enabled: true,
OutputPath: "PesterTestResults.xml",
TestSuiteName: "",
},
Output: {
Verbosity: "Detailed",
}
}
This object is converted to a hashtable used to create a PesterConfiguration object in Pester v5 ($PesterConfig = New-PesterConfiguration -Hashtable $pester_configuration
), in turn used with invoke pester (Invoke-Pester -Configuration $PesterConfig
).
If some of the following keys are missing, the associated defaults below will be used:
$Env:Temp/verifier/suites
Pester - $KitchenInstanceName
$Env:Temp/verifier/PesterTestResults.xml
If the installed version of Pester is v4, and the pester_configuration
hash is provided, valid parameters for Invoke-Pester
will be used (and invalid parameter names will be ignored).
In the case of Pester v4, and the pester_configuration
hash does not provide the keys for Script
,OutputFile
,OutputFormat
, Passthru
, PesterOption
, the defaults will be:
$Env:Temp/verifier/suites
$Env:Temp/verifier/PesterTestResults.xml
NUnitXml
true
$(New-PesterOption -TestSuiteName "Pester - $KitchenInstanceName)
shell
- string, default is Nil
which makes it call PowerShell on Windows (Windows PowerShell), pwsh on other OSes.
It will honour the sudo
configuration property if set to true on non-windows.
sudo
- bool, default is false
. (non-windows only)
Execute all PowerShell calls as sudo.
This is necessary in certain cases, such as when pwsh
is installed via snap
and is only available via sudo
unless you customise the system's configuration.
downloads
- map[string, string], defaults to {"./PesterTestResults.xml" => "./testresults}"
.
Files to download from SUT to local system, used to download the pester results localy.
The key is the remote file to download, while the value is the destination.
$TEMP/verifier
)/var/tmp/file.zip
or C:\\Windows\\Temp\\file.zip
)%{instance_name}
to indicate the Test Kitchen instance name/
or \\
)downloads:
PesterTestResults.xml: "./output/testResults/"
kitchen_cmd.ps1: "./output/testResults/"
environment
- map[string, string], defaults to {}
.
Environment variables to set in SUT for your pester tests to access.
environment:
API_KEY: api-key-here
PUSH_URI: https://push.example.com
If you're testing on a default image of Windows Server 2019, you probably need to replace the builtin Pester module (v3.4.0), and replace the builtin PackageManagement and PowerShellGet to a more recent for the install to work.
Assuming your tests are written for Peter v4, here's a sample configuration:
verifier:
name: pester
pester_install:
MaximumVersion: '4.99.999'
bootstrap: # installs modules from nuget feed by download and unzip.
repository_url: "https://www.powershellgallery.com/api/v2"
modules:
- PackageManagement
- PowerShellGet
Assuming you are using the AzureRM driver and a Ubuntu image, you may need to install pwsh before being able to execute any PowerShell code. One way to achieve this is by using Test-Kitchen's lifecycle hooks to install it using the snap package management.
Then if your tests are written for Pester v4.x, make sure you specify a maximum version in the install.
As pwsh comes with a recent version of PowerShellGet, it is not necessary to bootstrap the PowerShell environment.
The Install-Module
command should work out of the box.
driver:
name: azurerm
subscription_id: <%= ENV['AZ_SUBSCRIPTION_ID'] %> # use a custom env variable
location: 'westus2'
machine_size: 'Standard_D2s_v3'
provisioner:
name: shell # defaults to bash on linux, so the shebang is important!
script: 'tests/integration/provisioning.ps1'
verifier:
name: pester
pester_install:
MaximumVersion: '4.99.999'
platforms:
- name: ubuntu-18.04
driver:
image_urn: Canonical:UbuntuServer:18.04-LTS:latest
lifecycle:
post_create:
- remote: sudo snap install powershell --classic
suites:
- name: default
If your image is a windows 2012 R2, you will be running on PowerShell v4. Assuming that's what you want, but you still need Pester v4 instead of the built-in 3.4.0, you will need to remove the built-in version, bootsrap the PowerShellGet version to a more recent one, and finally install Pester to your desired version.
verifier:
name: pester
pester_install:
MaximumVersion: '4.99.999'
bootstrap:
repository_url: "https://www.powershellgallery.com/api/v2"
modules:
- PackageManagement
- PowerShellGet
git checkout -b my-new-feature
)git commit -am 'Add some feature'
)git push origin my-new-feature
)