mirror of
https://github.com/github/awesome-copilot.git
synced 2026-07-16 19:03:26 +00:00
github-actions[bot]
93 lines
3.7 KiB
Markdown
93 lines
3.7 KiB
Markdown
# Migrating Pester v3 → v4
|
|
|
|
This is the smallest jump — mostly an assertion-syntax rename. Many suites need only minor changes,
|
|
some need none. It is largely script-automatable, but always review the diff and re-run the suite.
|
|
|
|
Official guide: https://pester.dev/docs/migrations/v3-to-v4
|
|
|
|
> Heads-up: if your goal is a modern Pester (5 or 6), v3→v4 is only the first step. Do it, get
|
|
> green, then continue with [v4-to-v5.md](v4-to-v5.md) and [v5-to-v6.md](v5-to-v6.md).
|
|
|
|
---
|
|
|
|
## Change 1 — Dashed `Should` assertion syntax
|
|
|
|
v4 introduced the parameter-style `Should` syntax. The bareword form still ran in v4 but is
|
|
**removed in v5**, so converting now saves a later migration.
|
|
|
|
```powershell
|
|
# v3 (bareword)
|
|
It 'checks something' { 10 | Should Be 10 }
|
|
|
|
# v4+ (dashed)
|
|
It 'checks something' { 10 | Should -Be 10 }
|
|
```
|
|
|
|
The rename applies to every operator: `Be`, `BeExactly`, `Match`, `Throw`, `BeNullOrEmpty`,
|
|
`Contain`, etc. → `-Be`, `-BeExactly`, `-Match`, `-Throw`, `-BeNullOrEmpty`, …
|
|
|
|
There is a well-known AST-based converter, `Update-PesterTest` (Chris Dent / Wojciech Sciesinski),
|
|
that inserts the dashes safely by parsing the file rather than regexing it:
|
|
https://gist.github.com/indented-automation/aeb14825e39dd8849beee44f681fbab3 — it's also reproduced
|
|
in the official v3→v4 guide. Review its output, especially for non-UTF-8/ASCII files, where it can
|
|
change encoding.
|
|
|
|
---
|
|
|
|
## Change 2 — `Contain` → `FileContentMatch`
|
|
|
|
The `Contain` assertion was renamed to `FileContentMatch` (it tests file **contents**, which the
|
|
old name made ambiguous against collection containment).
|
|
|
|
```powershell
|
|
# Should Contain -> Should -FileContentMatch
|
|
# Should Not Contain -> Should -Not -FileContentMatch
|
|
'app.config' | Should -FileContentMatch 'setting'
|
|
'app.config' | Should -Not -FileContentMatch 'secret'
|
|
```
|
|
|
|
A simple regex-based migration script from the official guide (verify results — it can produce
|
|
false positives):
|
|
|
|
```powershell
|
|
$content = Get-Content -Path $file -Encoding $encoding
|
|
$content = $content -replace 'Should\s+\-?Contain', 'Should -FileContentMatch'
|
|
$content = $content -replace 'Should\s+\-?Not\s*-?Contain', 'Should -Not -FileContentMatch'
|
|
$content = $content -replace 'Assert-VerifiableMocks', 'Assert-VerifiableMock'
|
|
$content | Set-Content -Path $file -Encoding $encoding
|
|
```
|
|
|
|
---
|
|
|
|
## Change 3 — `Assert-VerifiableMocks` → `Assert-VerifiableMock`
|
|
|
|
The cmdlet was renamed (dropped the trailing `s`). Rename all occurrences.
|
|
|
|
> In Pester 5 this is *deprecated* and in Pester 6 it is *removed* — when you continue past v4,
|
|
> switch to `Should -InvokeVerifiable`. See [v5-to-v6.md](v5-to-v6.md).
|
|
|
|
---
|
|
|
|
## Change 4 — Array assertions (watch for edge cases)
|
|
|
|
`Should` gained array assertions in v4. This is transparent for most tests, but there are edge
|
|
cases where an array test that passed under v3 fails under v4. If an array-related test changes
|
|
result after the rename, inspect it manually rather than forcing it to pass. Background:
|
|
https://github.com/pester/Pester/issues/873.
|
|
|
|
Mocking also shifted subtly when Pester moved from functions to aliases; there are no required
|
|
changes, but if mocked-command behavior looks off, see
|
|
https://github.com/pester/Pester/issues/810 and https://github.com/pester/Pester/issues/812.
|
|
|
|
---
|
|
|
|
## v3 → v4 checklist
|
|
|
|
- [ ] Suite runs on v3 first (baseline).
|
|
- [ ] All `Should <Operator>` converted to `Should -<Operator>` (prefer the AST converter).
|
|
- [ ] `Should Contain` → `Should -FileContentMatch` (and the `-Not` form).
|
|
- [ ] `Assert-VerifiableMocks` → `Assert-VerifiableMock`.
|
|
- [ ] Array-assertion behavior changes reviewed manually.
|
|
- [ ] File encoding preserved by any scripted replacement.
|
|
- [ ] Suite green on v4; diff reviewed; committed.
|