Pester Migration
Experimental / preview. The v5→v6 guidance tracks Pester 6 while it is a release
candidate and may change; verify against the current
release notes. v3→v4 and v4→v5 cover stable releases.
Pester is the test framework for PowerShell. Test files end in *.Tests.ps1 and use
Describe / Context / It blocks with Should assertions. This skill upgrades an existing
suite from one major Pester version to the next and gets it green again.
Mental model: each major jump has a different character. v3→v4 is mostly a syntax
rename. v4→v5 is a fundamental runtime change (the Discovery/Run split) and is the hard
one. v5→v6 is largely backwards-compatible — a handful of previously-deprecated things now
throw. Migrate one major at a time; never skip a version.
Detailed, symptom-driven guides live in references/ — load the one(s) for the jump you are doing.
References
| Reference |
When to load |
| v3-to-v4.md |
Should Be → Should -Be, Contain → FileContentMatch, Assert-VerifiableMocks → Assert-VerifiableMock, array-assertion edge cases. |
| v4-to-v5.md |
The big one. Discovery/Run phases, BeforeAll setup, $PSScriptRoot, BeforeDiscovery, -ForEach, mock scoping, Should -Throw wildcards, Invoke-Pester → New-PesterConfiguration. |
| v5-to-v6.md |
PowerShell 5.1/7.4+ only, per-file discovery+run, empty -ForEach throws, duplicate setup blocks throw, name <...> templates evaluate, Assert-MockCalled removed, mocks no longer fall through, code-coverage tracer, legacy Invoke-Pester params removed. |
Canonical source: the official migration guides at https://pester.dev/docs/migrations/ — this skill
mirrors them. When in doubt, prefer the website.
Step 0 — Detect where you are and where you're going
Find the installed version(s) and the version the tests were written for. These can differ.
# Installed Pester version(s) on this machine
Get-Module Pester -ListAvailable | Select-Object Name, Version, Path
# Version currently imported in the session
(Get-Module Pester).Version
Tell the source version from the test code with these heuristics:
You see in *.Tests.ps1 / build scripts |
Suite was written for |
Should Be / Should Contain (no dash) |
v3 or earlier → start at v3-to-v4 |
$MyInvocation.MyCommand.Path + dot-source at the top of the file; arbitrary code directly under Describe |
v4 → v4-to-v5 |
Assert-MockCalled, Assert-VerifiableMock, Set-ItResult -Pending |
v4 / early-v5 (these are removed in v6) |
Invoke-Pester -Script … -OutputFile … -CodeCoverage … (legacy params) |
v4 invocation → map to config |
BeforeAll { . $PSScriptRoot/… }, New-PesterConfiguration, Should -Invoke |
already v5-style → v5-to-v6 |
Install the target version when ready:
# Latest stable v5 — pin the major so this keeps installing v5 even after v6 goes GA
Install-Module Pester -MaximumVersion 5.99.99 -Force
# Pester 6 (currently a release candidate — needs -AllowPrerelease)
Install-Module Pester -AllowPrerelease -Force
On Windows PowerShell 5.1 the OS ships a Microsoft-signed built-in Pester 3 that PowerShellGet
won't overwrite with the differently-signed newer Pester — add -SkipPublisherCheck there to
install side-by-side. Not needed on PowerShell 7+. See
https://pester.dev/docs/introduction/installation.
Migration workflow
Run this loop for each major jump. Do not jump two majors at once — go v4→v5, then v5→v6.
- Baseline. Run the suite on the current version first and record pass/fail. You need a
known-good (or known) starting point so you can tell migration regressions apart from
pre-existing failures.
# Bare Invoke-Pester works on every major; exact parameters differ
# (v3/v4: -Script/-OutputFile; v5+/v6: -Path/-Output).
Invoke-Pester
- Read the reference for this jump (table above) so you know the full scope before editing.
- Edit file by file. Apply the mechanical changes (see per-jump cheat sheets below and in the
reference). Keep changes small and reviewable — one file or one concern at a time.
- Switch versions with
Install-Module (Step 0), then re-import: Remove-Module Pester; Import-Module Pester (or start a fresh session).
- Run and fix. Re-run with
-Output Detailed; use -Output Diagnostic (v4→v5) or read the
explicit v6 error messages to locate problems. Match each failure to the symptom → fix
tables in the reference.
- Green, diff, commit. Re-run until the result matches the baseline (or better). Review the
diff, then commit. Migrating in small commits makes regressions trivial to bisect.
What actually changes (scope per jump)
| Jump |
Difficulty |
Nature |
| v3 → v4 |
Low |
Assertion-syntax rename (Should -Be). Largely script-automatable. |
| v4 → v5 |
High |
New two-phase runtime. Test structure changes: setup must move into BeforeAll, discovery-time code into BeforeDiscovery, file location via $PSScriptRoot. Not a pure find-replace. |
| v5 → v6 |
Low–Medium |
Backwards-compatible runtime; deprecated features now throw. Mostly small, targeted fixes. Your Should -Be assertions keep working unchanged. |
Quick cheat sheets
v4 → v5 (most common fixes)
# 1. Move file import into BeforeAll, use $PSScriptRoot (NOT $MyInvocation.MyCommand.Path)
# BEFORE
$here = Split-Path -Parent $MyInvocation.MyCommand.Path
. "$here\Get-Thing.ps1"
# AFTER
BeforeAll { . $PSScriptRoot/Get-Thing.ps1 }
# 2. Any code that DISCOVERS/generates tests must be in BeforeDiscovery
BeforeDiscovery { $cases = Get-Content $PSScriptRoot/cases.json | ConvertFrom-Json }
# 3. Should -Throw matches with -like wildcards, not .Contains
{ throw 'a long message' } | Should -Throw '*long*'
# 4. Invoke-Pester legacy params → New-PesterConfiguration (see reference for full map)
Full details, scoping rules, and the parameter→config table: references/v4-to-v5.md.
v5 → v6 (most common fixes)
# 1. Mock assertions: removed verbs — rename (old -> new):
# Assert-MockCalled -> Should -Invoke
# Assert-VerifiableMock -> Should -InvokeVerifiable
Should -Invoke Get-Thing -Times 1 -Exactly
Should -InvokeVerifiable
# 2. Add a default mock — unmatched calls no longer run the real command
Mock Get-Thing { 'default' }
Mock Get-Thing -ParameterFilter { $Name -eq 'a' } -MockWith { 'a' }
# 3. Empty/$null -ForEach now throws; allow it only where empty is expected
Describe 'Optional' -ForEach $cases -AllowNullOrEmptyForEach { }
# 4. Combine duplicate BeforeAll/BeforeEach/AfterAll/AfterEach in the same block into one
Full breaking-change list with symptoms and fixes: references/v5-to-v6.md.
Safety rules
- Tests are the spec. Migration must not change what a test asserts — only how the suite is
structured and invoked. If a test starts passing/failing differently for any reason other than a
documented breaking change, investigate before accepting it.
- Automated migration scripts produce false positives. The community scripts (linked in the
references) help with
Should syntax and dot-sourcing, but always review the diff and re-run the
suite afterward. Never bulk-edit and commit unchecked.
- Mind file encoding when scripting replacements over
*.Tests.ps1 — preserve the original
encoding (UTF-8 vs ASCII) so you don't mangle non-ASCII test names.
- Work on a branch, commit per file/concern. Small commits keep
git bisect useful if a
migrated test goes red later.
1---2name: pester-migration3description: 'Experimental (preview) Pester migration skill for upgrading PowerShell Pester test suites across major versions — v3→v4, v4→v5, and v5→v6. The v5→v6 path tracks Pester 6, which is still a release candidate, so that guidance may change. Covers the Discovery/Run two-phase model, moving setup into BeforeAll, $PSScriptRoot vs $MyInvocation, mock changes (Assert-MockCalled → Should -Invoke, removed fall-through), Invoke-Pester parameters → PesterConfiguration, data-driven -ForEach/-TestCases, and the v6 breaking changes. Use when the user asks to upgrade, migrate, or modernize Pester tests, fix *.Tests.ps1 files that broke after bumping the Pester version, or convert legacy Should / Invoke-Pester syntax.'4metadata:5 source: https://skillmd.com/skills/github/pester-migration6---78# Pester Migration910> **Experimental / preview.** The **v5→v6** guidance tracks Pester 6 while it is a release11> candidate and may change; verify against the current12> [release notes](https://github.com/pester/Pester/releases). v3→v4 and v4→v5 cover stable releases.1314Pester is the test framework for PowerShell. Test files end in `*.Tests.ps1` and use15`Describe` / `Context` / `It` blocks with `Should` assertions. This skill upgrades an existing16suite from one major Pester version to the next and gets it green again.1718> **Mental model:** each major jump has a different character. **v3→v4** is mostly a syntax19> rename. **v4→v5** is a *fundamental runtime change* (the Discovery/Run split) and is the hard20> one. **v5→v6** is largely backwards-compatible — a handful of previously-deprecated things now21> throw. Migrate **one major at a time**; never skip a version.2223Detailed, symptom-driven guides live in `references/` — load the one(s) for the jump you are doing.2425## References2627| Reference | When to load |28|---|---|29| [v3-to-v4.md](references/v3-to-v4.md) | `Should Be` → `Should -Be`, `Contain` → `FileContentMatch`, `Assert-VerifiableMocks` → `Assert-VerifiableMock`, array-assertion edge cases. |30| [v4-to-v5.md](references/v4-to-v5.md) | The big one. Discovery/Run phases, `BeforeAll` setup, `$PSScriptRoot`, `BeforeDiscovery`, `-ForEach`, mock scoping, `Should -Throw` wildcards, `Invoke-Pester` → `New-PesterConfiguration`. |31| [v5-to-v6.md](references/v5-to-v6.md) | PowerShell 5.1/7.4+ only, per-file discovery+run, empty `-ForEach` throws, duplicate setup blocks throw, name `<...>` templates evaluate, `Assert-MockCalled` removed, mocks no longer fall through, code-coverage tracer, legacy `Invoke-Pester` params removed. |3233Canonical source: the official migration guides at https://pester.dev/docs/migrations/ — this skill34mirrors them. When in doubt, prefer the website.3536## Step 0 — Detect where you are and where you're going3738Find the installed version(s) and the version the **tests** were written for. These can differ.3940```powershell41# Installed Pester version(s) on this machine42Get-Module Pester -ListAvailable | Select-Object Name, Version, Path4344# Version currently imported in the session45(Get-Module Pester).Version46```4748Tell the source version from the **test code** with these heuristics:4950| You see in `*.Tests.ps1` / build scripts | Suite was written for |51|---|---|52| `Should Be` / `Should Contain` (no dash) | v3 or earlier → start at [v3-to-v4](references/v3-to-v4.md) |53| `$MyInvocation.MyCommand.Path` + dot-source at the **top** of the file; arbitrary code directly under `Describe` | v4 → [v4-to-v5](references/v4-to-v5.md) |54| `Assert-MockCalled`, `Assert-VerifiableMock`, `Set-ItResult -Pending` | v4 / early-v5 (these are **removed in v6**) |55| `Invoke-Pester -Script … -OutputFile … -CodeCoverage …` (legacy params) | v4 invocation → map to config |56| `BeforeAll { . $PSScriptRoot/… }`, `New-PesterConfiguration`, `Should -Invoke` | already v5-style → [v5-to-v6](references/v5-to-v6.md) |5758Install the target version when ready:5960```powershell61# Latest stable v5 — pin the major so this keeps installing v5 even after v6 goes GA62Install-Module Pester -MaximumVersion 5.99.99 -Force6364# Pester 6 (currently a release candidate — needs -AllowPrerelease)65Install-Module Pester -AllowPrerelease -Force66```6768> On **Windows PowerShell 5.1** the OS ships a Microsoft-signed built-in Pester 3 that PowerShellGet69> won't overwrite with the differently-signed newer Pester — add `-SkipPublisherCheck` there to70> install side-by-side. Not needed on PowerShell 7+. See71> https://pester.dev/docs/introduction/installation.7273## Migration workflow7475Run this loop for each major jump. **Do not jump two majors at once** — go v4→v5, then v5→v6.76771. **Baseline.** Run the suite on the **current** version first and record pass/fail. You need a78 known-good (or known) starting point so you can tell migration regressions apart from79 pre-existing failures.80 ```powershell81 # Bare Invoke-Pester works on every major; exact parameters differ82 # (v3/v4: -Script/-OutputFile; v5+/v6: -Path/-Output).83 Invoke-Pester84 ```852. **Read the reference** for this jump (table above) so you know the full scope before editing.863. **Edit file by file.** Apply the mechanical changes (see per-jump cheat sheets below and in the87 reference). Keep changes small and reviewable — one file or one concern at a time.884. **Switch versions** with `Install-Module` (Step 0), then re-import: `Remove-Module Pester;89 Import-Module Pester` (or start a fresh session).905. **Run and fix.** Re-run with `-Output Detailed`; use `-Output Diagnostic` (v4→v5) or read the91 explicit v6 error messages to locate problems. Match each failure to the **symptom → fix**92 tables in the reference.936. **Green, diff, commit.** Re-run until the result matches the baseline (or better). Review the94 diff, then commit. Migrating in small commits makes regressions trivial to bisect.9596## What actually changes (scope per jump)9798| Jump | Difficulty | Nature |99|---|---|---|100| v3 → v4 | Low | Assertion-syntax rename (`Should -Be`). Largely script-automatable. |101| v4 → v5 | **High** | New two-phase runtime. Test **structure** changes: setup must move into `BeforeAll`, discovery-time code into `BeforeDiscovery`, file location via `$PSScriptRoot`. Not a pure find-replace. |102| v5 → v6 | Low–Medium | Backwards-compatible runtime; deprecated features now throw. Mostly small, targeted fixes. Your `Should -Be` assertions keep working unchanged. |103104## Quick cheat sheets105106### v4 → v5 (most common fixes)107```powershell108# 1. Move file import into BeforeAll, use $PSScriptRoot (NOT $MyInvocation.MyCommand.Path)109# BEFORE110$here = Split-Path -Parent $MyInvocation.MyCommand.Path111. "$here\Get-Thing.ps1"112# AFTER113BeforeAll { . $PSScriptRoot/Get-Thing.ps1 }114115# 2. Any code that DISCOVERS/generates tests must be in BeforeDiscovery116BeforeDiscovery { $cases = Get-Content $PSScriptRoot/cases.json | ConvertFrom-Json }117118# 3. Should -Throw matches with -like wildcards, not .Contains119{ throw 'a long message' } | Should -Throw '*long*'120121# 4. Invoke-Pester legacy params → New-PesterConfiguration (see reference for full map)122```123Full details, scoping rules, and the parameter→config table: [references/v4-to-v5.md](references/v4-to-v5.md).124125### v5 → v6 (most common fixes)126```powershell127# 1. Mock assertions: removed verbs — rename (old -> new):128# Assert-MockCalled -> Should -Invoke129# Assert-VerifiableMock -> Should -InvokeVerifiable130Should -Invoke Get-Thing -Times 1 -Exactly131Should -InvokeVerifiable132133# 2. Add a default mock — unmatched calls no longer run the real command134Mock Get-Thing { 'default' }135Mock Get-Thing -ParameterFilter { $Name -eq 'a' } -MockWith { 'a' }136137# 3. Empty/$null -ForEach now throws; allow it only where empty is expected138Describe 'Optional' -ForEach $cases -AllowNullOrEmptyForEach { }139140# 4. Combine duplicate BeforeAll/BeforeEach/AfterAll/AfterEach in the same block into one141```142Full breaking-change list with symptoms and fixes: [references/v5-to-v6.md](references/v5-to-v6.md).143144## Safety rules145146- **Tests are the spec.** Migration must not change what a test asserts — only how the suite is147 structured and invoked. If a test starts passing/failing differently for any reason other than a148 documented breaking change, investigate before accepting it.149- **Automated migration scripts produce false positives.** The community scripts (linked in the150 references) help with `Should` syntax and dot-sourcing, but always review the diff and re-run the151 suite afterward. Never bulk-edit and commit unchecked.152- **Mind file encoding** when scripting replacements over `*.Tests.ps1` — preserve the original153 encoding (UTF-8 vs ASCII) so you don't mangle non-ASCII test names.154- **Work on a branch, commit per file/concern.** Small commits keep `git bisect` useful if a155 migrated test goes red later.