AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

pester-migration

Pester migration skill for upgrading PowerShell Pester test suites across major versions — v3→v4, v4→v5, and v5→v6. 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.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--pester-migration at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/v4-to-v5.md

Migrating Pester v4 → v5

This is the hard jump. v5 introduced a new runtime that splits a test run into two phases — Discovery and Run — and that changes how you must structure tests. It is not a pure find-and-replace. Read this whole file before editing a suite.

Official guide: https://pester.dev/docs/migrations/v4-to-v5 · Breaking changes: https://pester.dev/docs/migrations/breaking-changes-in-v5


The one concept that explains everything: Discovery and Run

A v5+ run happens in two passes:

  • Discovery — Pester executes each *.Tests.ps1 file top to bottom but only to find tests. It invokes the Describe/Context script blocks to collect the tree of Its, evaluates It -Name strings and -TestCases/-ForEach data, and records BeforeAll/It/etc. script blocks without running them.
  • Run — Pester then executes the recorded setups, tests, and teardowns with correct scoping.

The two rules that make a suite v5-correct:

  1. Put all test code inside It, BeforeAll, BeforeEach, AfterAll, or AfterEach.
  2. Put no test code directly in Describe/Context bodies or at the top of the file — unless it is meant to build tests, in which case it goes in BeforeDiscovery.

Code that sits loose in a Describe body or at file top-level runs during Discovery, and its results are usually not available during Run. This is the root cause of most "it worked in v4, it's $null in v5" bugs.


Fix 1 — Move file setup into BeforeAll and use $PSScriptRoot

The classic v4 header dot-sources the system-under-test at file scope using $MyInvocation.MyCommand.Path. Both the placement and that variable break in v5.

# BEFORE (v4)
$here = Split-Path -Parent $MyInvocation.MyCommand.Path
$sut  = (Split-Path -Leaf $MyInvocation.MyCommand.Path).Replace('.Tests.', '.')
. "$here\$sut"

Describe 'Get-Cactus' {
    It 'Returns 🌵' { Get-Cactus | Should -Be '🌵' }
}
# AFTER (v5+)
BeforeAll {
    # Do NOT use $MyInvocation.MyCommand.Path here.
    . $PSScriptRoot/Get-Cactus.ps1
    # or, by convention from the test file name:
    # . $PSCommandPath.Replace('.Tests.ps1', '.ps1')
}

Describe 'Get-Cactus' {
    It 'Returns 🌵' { Get-Cactus | Should -Be '🌵' }
}

Why $MyInvocation.MyCommand.Path fails: it returns the path only when evaluated directly in the script body. Inside any function or script block (and BeforeAll is a script block) Path is empty. Use $PSScriptRoot (the test file's directory) or $PSCommandPath (the test file's full path) instead. string.Replace('.Tests.ps1','.ps1') is case-sensitive — keep the .Tests.ps1 casing exact.

$MyInvocation.MyCommand.Path is fine inside your module/product code — the change only affects the test-file header pattern. See https://pester.dev/docs/usage/importing-tested-functions#migrating-from-pester-v4.

There is a community migration script that does the BeforeAll wrap for you (review its output): https://gist.github.com/nohwnd/d488bd14ab4572f92ae77e208f476ada


Fix 2 — Generate tests with BeforeDiscovery + -ForEach, not loose foreach

A very common v4 pattern builds tests from data with a top-level foreach. In v5 the data often isn't defined at Discovery time, so no tests get generated, or the per-item variable is missing inside It.

# BROKEN in v5: $files is set in BeforeAll (Run phase), but the foreach runs in Discovery
BeforeAll { $files = Get-ChildItem *.ps1 }
foreach ($file in $files) {
    Describe "$file is correct" {
        It 'has empty line at end' { }
    }
}

Two things must change: build the data in BeforeDiscovery (so it exists during Discovery), and pass per-item data into the test with -ForEach/-TestCases (so It can see it during Run):

BeforeDiscovery {
    $files = Get-ChildItem *.ps1            # runs during Discovery
}

Describe 'script <_> is correct' -ForEach $files {
    It 'has an empty line at the end' {
        # $_ is the current file here
    }
}

Prefer -ForEach on the block/It over a hand-written foreach; it both creates the copies and makes the current item available. Use <_> (or <Name> for hashtable items) in the name to template per-item titles. Reference: https://pester.dev/docs/usage/data-driven-tests.


Fix 3 — -Skip and -TestCases are evaluated during Discovery

Because filters and data are resolved during Discovery, conditions computed in BeforeAll are not available yet.

# DOES NOT skip: $isSkipped is set in BeforeAll (Run), but -Skip is read in Discovery
Describe 'd' {
    BeforeAll { $isSkipped = Get-IsSkipped }
    It 'i' -Skip:$isSkipped { }
}

Move cheap skip logic to file scope (it runs on every Discovery) or, better, base it on a static global like $IsWindows:

$isSkipped = -not $IsWindows
Describe 'd' {
    It 'i' -Skip:$isSkipped { }
}

Keep Discovery-time code cheap — it runs every time the file is discovered, which can be often.


Fix 4 — Variables don't leak from Discovery into the test

Variables defined during Discovery are not visible in BeforeAll/-Each, AfterAll/-Each, or It. If you compute something while generating tests and need it at run time, attach it to the test via -ForEach/-TestCases. (TestDrive is Run-only and likewise can't be used in -ForEach.)


Fix 5 — Should -Throw matches with -like wildcards

In v5, Should -Throw <message> matches the exception message with -like, not .Contains(). A substring that used to match now needs wildcards.

# v4: matched a substring
{ throw 'connection failed: timeout' } | Should -Throw 'timeout'
# v5+: use wildcards to match part of the message
{ throw 'connection failed: timeout' } | Should -Throw '*timeout*'

Fix 6 — Mocks: scoping, debugging, and InModuleScope

  • Scope follows placement. In v5, mocks (and their call counts) are scoped to where you put them — the current block/test — not the entire Describe/Context. Define the Mock in the same BeforeAll/It scope where it applies, and assert counts in that scope.
  • Assert-VerifiableMocks was removed. Use Should -InvokeVerifiable. (Assert-MockCalled and Assert-VerifiableMock still exist but are deprecated in v5 and removed in v6 — prefer Should -Invoke / Should -InvokeVerifiable now to save a second migration. See v5-to-v6.md.)
  • Mocks are debuggable. v5 no longer rewrites your mock script block, so you can set breakpoints inside -MockWith and inside -ParameterFilter.
  • Avoid InModuleScope around Describe/It. It loads the module during Discovery (slowing it down) and lets you test internals instead of the published surface. Prefer -ModuleName on Mock and on Should -Invoke; if you must use InModuleScope, keep it inside It. See https://pester.dev/docs/usage/mocking.
# Prefer this over wrapping the whole Describe in InModuleScope
Mock Get-Internal -ModuleName MyModule { 'mocked' }
Should -Invoke Get-Internal -ModuleName MyModule -Times 1 -Exactly

Fix 7 — Invoke-Pester parameters → New-PesterConfiguration

Invoke-Pester's interface was overhauled. v5 kept a deprecated compatibility set so v4 calls mostly still run (with a warning), but you should move to either the Simple parameters or the Advanced -Configuration object. (v6 removes the legacy set entirely — migrate now.)

Simple interface (parameter → config property):

| Simple parameter | Configuration property | |---|---| | -Path | Run.Path | | -ExcludePath | Run.ExcludePath | | -Tag | Filter.Tag | | -ExcludeTag | Filter.ExcludeTag | | -FullNameFilter | Filter.FullName | | -Output | Output.Verbosity | | -CI | TestResult.Enabled + Run.Exit (both $true) | | -PassThru | Run.PassThru |

Legacy (v4) parameters → config:

| v4 parameter | Configuration property | |---|---| | -Script | Run.Path (paths only — no hashtables) | | -EnableExit | Run.Exit | | -TestName | replaced by -FullNameFilter / Filter.FullName | | -CodeCoverage | CodeCoverage.Path (+ CodeCoverage.Enabled = $true) | | -CodeCoverageOutputFile | CodeCoverage.OutputPath | | -CodeCoverageOutputFileEncoding | CodeCoverage.OutputEncoding | | -CodeCoverageOutputFileFormat | CodeCoverage.OutputFormat | | -OutputFile | TestResult.OutputPath (+ TestResult.Enabled = $true) | | -OutputFormat | TestResult.OutputFormat | | -Show / -Output | Output.Verbosity (see mapping below) | | -PesterOption, -Strict | ignored / not available |

-Show value → Output.Verbosity: All/Default/Detailed → Detailed; Fails/Normal → Normal; Diagnostic → Diagnostic; Minimal → Minimal; None → None.

# BEFORE (v4 legacy)
Invoke-Pester -Script ./tests -CodeCoverage ./src/*.ps1 `
    -OutputFile result.xml -OutputFormat NUnitXml -EnableExit

# AFTER (v5 Advanced)
$config = New-PesterConfiguration
$config.Run.Path = './tests'
$config.Run.Exit = $true
$config.CodeCoverage.Enabled = $true
$config.CodeCoverage.Path = './src'
$config.TestResult.Enabled = $true
$config.TestResult.OutputPath = 'result.xml'
$config.TestResult.OutputFormat = 'NUnitXml'
Invoke-Pester -Configuration $config

-Output Diagnostic is your best friend while migrating — it shows Discovery/Skip/Mock decisions.


The new result object

The v5 result object is much richer and is what Pester uses internally. To keep a v4-era CI pipeline working, convert it with ConvertTo-Pester4Result. For NUnit output use ConvertTo-NUnitReport, or pass -CI to enable NUnit output, code coverage, and a failing exit code in one switch. Each test's -TestCases/-ForEach item is available on the test object's Data property.


Other removed / changed things in v5

  • PowerShell 2 is no longer supported.
  • Legacy Should Be (no dash) is removed — convert to Should -Be (v3-to-v4.md).
  • Gherkin was removed — stay on Pester v4 if you need it.
  • -Output/-Show reduced to None, Normal, Detailed, Diagnostic.
  • -TestName → -FullNameFilter; -Script → -Path (paths only); -PesterOption removed.

v4 → v5 checklist

  • [ ] Suite runs green on v4 first (baseline).
  • [ ] File import moved into BeforeAll; $MyInvocation.MyCommand.Path replaced with $PSScriptRoot/$PSCommandPath.
  • [ ] No loose code in Describe/Context bodies or at file top-level; test-generating code moved to BeforeDiscovery.
  • [ ] foreach-generated tests converted to -ForEach; per-item data passed via -ForEach/-TestCases.
  • [ ] -Skip: conditions don't depend on BeforeAll variables.
  • [ ] Should -Throw messages use -like wildcards (*...*).
  • [ ] Mocks defined in the right scope; Assert-VerifiableMocks → Should -InvokeVerifiable; InModuleScope removed from around Describe/It in favor of -ModuleName.
  • [ ] Invoke-Pester call converted to Simple params or New-PesterConfiguration.
  • [ ] Suite green on v5 with -Output Detailed; diff reviewed; committed.