Bump to Pester 5

This is super painful since pester 5 had a lot of small, subtle and
otherwise small cahgnes which break back compat, like scoping, error
handling and a variety of other small things.

I also did some cleanup to standardise on calling conventions and
pulled in all the missed Pester 3 -> 4 changes as well.

It will also no longer try test directories with no tests, since that
throws up a really ugly error.

Author: aramprice

README-powershell-modules.md

@@ -9,12 +9,8 @@ The test suite for each module currently assumes that the tests are being run wi
 
 This requires iterating through the module directories to run all the tests:
 
-Two copies of BOSH Powershell Modules exist in this repo:
-- `stembuild/modules`
-- `modules`
-
 ```powershell
-# Where MODULES_DIR is ""ci/tasks/delete-vms/delete-vms.iml, or "modules"
+# Where MODULES_DIR is "stembuild/modules", or "modules"
 cd $MODULES_DIR
 foreach ($module in (Get-ChildItem "./modules").Name) {
   Push-Location "modules/$module"
@@ -30,20 +26,71 @@ echo "Failed Tests: $result"
 If you just need to test a single module, you could do this:
 
 ```powershell
-cd "$MODULES_DIR\BOSH.<module>"
+# Where MODULES_DIR is "stembuild/modules", or "modules"
+cd "${MODULES_DIR}/BOSH.<module>"
+Install-Module -Name Pester -Force
 Invoke-Pester
 ```
 
-## Running a subset of tests on macOS
+### Running tests via Concourse
+
+```shell
+# Where MODULES_DIR is "stembuild/modules", or "modules"
+export MODULES_DIR="${MODULES_DIR}"
+
+WINDOWS_STEMCELL_BUILDER=${WINDOWS_STEMCELL_BUILDER:-~/workspace/bosh-windows-stemcell-builder}
+
+fly -t "${CONCOURSE_TARGET:-bosh-ecosystem}" \
+    --tag="${WINDOWS_TAG:-windows-nimbus}" \
+    --input=stemcell-builder="${WINDOWS_STEMCELL_BUILDER}" \
+    --input-mapping="bosh-windows-stemcell-builder-ci=stemcell-builder" \
+    --inputs-from=stemcells-windows-2019/test-bosh-psmodules \
+    --config "${WINDOWS_STEMCELL_BUILDER}/ci/tasks/test-units-bosh-psmodules/task.yml"
+```
+
+### Running a subset of tests on macOS
 
 You can use Powershell and macOS to run the tests that do not require Windows system calls:
 
 ```shell
 cd ~/workspace
 brew install powershell
-git clone --depth 1 --branch 4.4.0 [email protected]:pester/Pester.git
 pwsh
-Import-Module ./Pester/Pester.psm1
+```
+
+Then from within `pwsh`:
+
+```powershell
+Install-Module -Name Pester -Force
 cd stembuild/module/BOSH.<module>
 Invoke-Pester
 ```
+
+## Debugging
+
+You can debug powershell scripts using VSCode. It has some dependencies:
+- dotnet runtime `brew install dotnet`
+- powershell binary `brew install powershell`
+- vscode extensions: `Powershell`, `C#` and `C# Dev Kit` (the latter may not be required)
+
+You can create a launch.json file like:
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+
+        {
+            "name": "PowerShell: Run Pester Tests",
+            "type": "PowerShell",
+            "request": "launch",
+            "script": "Invoke-Pester",
+            "createTemporaryIntegratedConsole": true,
+            "attachDotnetDebugger": true,
+            "cwd": "${file}"
+        }
+    ]
+}
+```
+
+And you should be able to run tests for a single file using the debug view. If you're missing extensions
+you'll see odd failures such as the wrong CWD leading to import failures.

modules/BOSH.Account/BOSH.Account.Tests.ps1

@@ -1,27 +1,30 @@
-Remove-Module -Name BOSH.Account -ErrorAction Ignore
-Import-Module ./BOSH.Account.psm1
+BeforeAll {
+    Remove-Module -Name BOSH.Account -ErrorAction Ignore
+    Import-Module ./BOSH.Account.psm1
 
-Remove-Module -Name BOSH.Utils -ErrorAction Ignore
-Import-Module ../BOSH.Utils/BOSH.Utils.psm1
+    Remove-Module -Name BOSH.Utils -ErrorAction Ignore
+    Import-Module ../BOSH.Utils/BOSH.Utils.psm1
+}
 
 Describe "Account" {
-
     Context "when username is not provided" {
         It "throws" {
-            { Add-Account } | Should Throw "Provide a user name"
+            { Add-Account } | Should -Throw "Provide a user name"
         }
     }
 
     Context "when password is not provided" {
         It "throws" {
-            { Add-Account -User hello } | Should Throw "Provide a password"
+            { Add-Account -User hello } | Should -Throw "Provide a password"
         }
     }
 
     Context "when the username and password are valid" {
-        $timestamp=(get-date -UFormat "%s" -Millisecond 0)
-        $user = "TestUser_$timestamp"
-        $password = "Password123!"
+        BeforeAll {
+            $timestamp=(get-date -UFormat "%s" -Millisecond 0)
+            $user = "TestUser_$timestamp"
+            $password = "Password123!"
+        }
 
          BeforeEach {
             $userExists = !!(Get-LocalUser | Where {$_.Name -eq $user})
@@ -34,14 +37,11 @@ Describe "Account" {
             Add-Account -User $user -Password $password
             mkdir "C:\Users\$user" -ErrorAction Ignore
             $adsi = [ADSI]"WinNT://$env:COMPUTERNAME"
-            $existing = $adsi.Children | where {$_.SchemaClassName -eq 'user' -and $_.Name -eq $user }
-            $existing | Should Not Be $null
+            $existing = $adsi.Children | Where-Object {$_.SchemaClassName -eq 'user' -and $_.Name -eq $user }
+            $existing | Should -Not -Be $null
             Remove-Account -User $user
-            $existing = $adsi.Children | where {$_.SchemaClassName -eq 'user' -and $_.Name -eq $user }
-            $existing | Should Be $null
+            $existing = $adsi.Children | Where-Object {$_.SchemaClassName -eq 'user' -and $_.Name -eq $user }
+            $existing | Should -Be $null
         }
     }
 }
-
-Remove-Module -Name BOSH.Account -ErrorAction Ignore
-Remove-Module -Name BOSH.Utils -ErrorAction Ignore