https://pester.dev/assets/js/0ada7963.bb0ea04c.js

1"use strict";(self.webpackChunkpester_docs=self.webpackChunkpester_docs||[]).push([["3528"],{1810(e,t,n){n.r(t),n.d(t,{metadata:()=>s,default:()=>h,frontMatter:()=>r,contentTitle:()=>o,toc:()=>d,assets:()=>l});var s=JSON.parse('{"id":"migrations/v3-to-v4","title":"Migrating from Pester v3 to v4","description":"Migration from Pester v3 to v4 may require minor changes to your test code. See this guide to get help understanding and making the necessary changes to be compatible with Pester v4","source":"@site/docs/migrations/v3-to-v4.mdx","sourceDirName":"migrations","slug":"/migrations/v3-to-v4","permalink":"/docs/migrations/v3-to-v4","draft":false,"unlisted":false,"editUrl":"https://github.com/pester/docs/edit/main/docs/migrations/v3-to-v4.mdx","tags":[],"version":"current","frontMatter":{"id":"v3-to-v4","title":"Migrating from Pester v3 to v4","sidebar_label":"Pester v3 to v4","description":"Migration from Pester v3 to v4 may require minor changes to your test code. See this guide to get help understanding and making the necessary changes to be compatible with Pester v4"},"sidebar":"docs","previous":{"title":"Breaking changes in v5","permalink":"/docs/migrations/breaking-changes-in-v5"},"next":{"title":"Articles","permalink":"/docs/additional-resources/articles"}}'),i=n(1987),a=n(7008);let r={id:"v3-to-v4",title:"Migrating from Pester v3 to v4",sidebar_label:"Pester v3 to v4",description:"Migration from Pester v3 to v4 may require minor changes to your test code. See this guide to get help understanding and making the necessary changes to be compatible with Pester v4"},o,l={},d=[{value:"Update to New Names",id:"update-to-new-names",level:2},{value:"Update to the new assertions syntax",id:"update-to-the-new-assertions-syntax",level:2},{value:"Old syntax",id:"old-syntax",level:3},{value:"New syntax",id:"new-syntax",level:3},{value:"Mock-Related Changes",id:"mock-related-changes",level:2},{value:"Array-Related Changes",id:"array-related-changes",level:2},{value:"Related (Github) Issues",id:"related-github-issues",level:2}];function c(e){let t={a:"a",admonition:"admonition",br:"br",code:"code",h2:"h2",h3:"h3",li:"li",ol:"ol",p:"p",pre:"pre",ul:"ul",...(0,a.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(t.p,{children:"Migration from Pester 3 to 4 typically involves minor changes to test code. Sometimes the migration requires no changes at all. This guide is meant to help you understand and make the necessary changes to your existing test code to accommodate Pester 4."}),"\n",(0,i.jsx)(t.admonition,{title:"Migrate with an AI assistant",type:"tip",children:(0,i.jsxs)(t.p,{children:["The ",(0,i.jsxs)(t.a,{href:"./v5-to-v6#migrate-with-an-ai-assistant",children:[(0,i.jsx)(t.code,{children:"pester-migration"})," skill"]})," for GitHub Copilot and other agents can do this v3\u2192v4 upgrade for you \u2014 it follows this guide, runs your tests, and fixes them file by file. Install it with ",(0,i.jsx)(t.code,{children:"gh skills install github/awesome-copilot pester-migration"}),"."]})}),"\n",(0,i.jsx)(t.h2,{id:"update-to-new-names",children:"Update to New Names"}),"\n",(0,i.jsx)(t.p,{children:"We recommend performing string replacement on tests written for Pester 3 and earlier as follows:"}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsxs)(t.li,{children:["replace all occurrences of any ",(0,i.jsx)(t.code,{children:"Contain"})," assertion with ",(0,i.jsx)(t.code,{children:"FileContentMatch"}),"."]}),"\n",(0,i.jsxs)(t.li,{children:["rename all occurrences of ",(0,i.jsx)(t.code,{children:"Assert-VerifiableMocks"})," to ",(0,i.jsx)(t.code,{children:"Assert-VerifiableMock"})]}),"\n"]}),"\n",(0,i.jsx)(t.p,{children:"You can use this simple script that can migrate test files in UTF8 and ASCII encoding."}),"\n",(0,i.jsxs)(t.p,{children:["\u26A0\uFE0F","\nPlease verify manually results generated by the script - it can generate false positive replaces!"]}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-powershell",children:"param ($Path = '.')\n\n# version 2017-12-13\n\n$testFiles = $(Get-ChildItem -Path $Path -Recurse *.Tests.ps1).FullName\n\nforeach ($file in $testFiles)\n{\n    \"Migrating '$file'\"\n    $encoding = Get-FileEncoding -Path $file\n    $content = Get-Content -Path $file -Encoding $encoding\n    $content = $content -replace 'Should\\s+\\-?Contain', 'Should -FileContentMatch'\n    $content = $content -replace 'Should\\s+\\-?Not\\s*-?Contain', 'Should -Not -FileContentMatch'\n    $content = $content -replace 'Assert-VerifiableMocks', 'Assert-VerifiableMock'\n    $content | Set-Content -Path $file -Encoding $encoding\n}\n\nfunction Get-FileEncoding {\n    # source https://gist.github.com/jpoehls/2406504\n    # simplified.\n\n    [CmdletBinding()]\n    Param (\n        [Parameter(

1Mandatory = $True, ValueFromPipelineByPropertyName = $True)]\n        [string]$Path\n    )\n\n    [byte[]]$byte = get-content -Encoding byte -ReadCount 4 -TotalCount 4 -Path $Path\n\n    if ( $byte[0] -eq 0xef -and $byte[1] -eq 0xbb -and $byte[2] -eq 0xbf )\n    { Write-Output 'UTF8' }\n\n    else\n    { Write-Output 'ASCII' }\n}\n"})}),"\n",(0,i.jsx)(t.h2,{id:"update-to-the-new-assertions-syntax",children:"Update to the new assertions syntax"}),"\n",(0,i.jsxs)(t.p,{children:["In Pester 4.0 the new assertion syntax was introduced. ",(0,i.jsx)(t.br,{}),"\n","Now assertions can be provided as parameters to Should, that allows richer assertion vocabulary."]}),"\n",(0,i.jsx)(t.h3,{id:"old-syntax",children:"Old syntax"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-powershell",children:"It 'Check something' {\n    10 | Should Be 10\n}\n"})}),"\n",(0,i.jsx)(t.h3,{id:"new-syntax",children:"New syntax"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-powershell",children:"It 'Check something' {\n    10 | Should -Be 10\n}\n"})}),"\n",(0,i.jsx)(t.p,{children:"For most cases tests can be updated using the function provided below."}),"\n",(0,i.jsxs)(t.p,{children:["\u26A0\uFE0F","\nPlease verify manually results generated by the script specially if your scripts are not UTF-8 or ASCII encoded!"]}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-powershell",children:"function Update-PesterTest {\n<#\n    .SYNOPSIS\n    The function intended to update Pester tests notation from version 3.x to 4.x.\n\n    .DESCRIPTION\n    Notation for the Should assertion changed between Pester version 3.x and 4.x.\n    The function helps to update existing Pester 3.x tests to the new notation.\n\n    Please be aware that if your original Pester test files are encoded differently than UTF-8\n    than the final files encoding will be Unicode (UTF-7) / ASCSI.\n\n    .PARAMETER Path\n    Path to the file that contain Pester tests to update.\n\n    .PARAMETER Destination\n    Path to the file for which updated tests will be saved.\n\n    If the Destination parameter is omitted tests will be updated in place.\n    The content of an original file will be replaced.\n\n    .EXAMPLE\n\n    Update-PesterTest -Path .\\Pester3-Tests\\Dummy.Tests.ps1 .\\Pester4-Tests\\Dummy.Tests.ps1\n\n    .NOTES\n    Original author\n    Chris Dent, @indented-automation\n\n    Updates\n    Wojciech Sciesinski, @it-praktyk\n\n    LICENSE\n    Copyright 2017 Chris Dent\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n\n    .LINK\n    https://github.com/pester/Pester/issues/892\n    https://gist.github.com/indented-automation/aeb14825e39dd8849beee44f681fbab3\n    https://gist.github.com/jpoehls/2406504\n#>\n\n    [CmdletBinding()]\n    param (\n        [Parameter(Mandatory=$true, ValueFromPipeline, ValueFromPipelineByPropertyName)]\n        [Alias('FullName')]\n        [System.IO.FileInfo]$Path,\n        [Parameter(Mandatory=$false)]\n        [String]$Destination\n    )\n\n    begin {\n        $shouldParams = [String[]](Get-Command Should).Parameters.Keys\n        $destIsEmpty = [String]::IsNullOrEmpty($Destination)\n    }\n\n    process {\n        $Path = $pscmdlet.GetUnresolvedProviderPathFromPSPath($Path)\n\n        $encoding = Get-FileEncoding -Path $Path\n\n        [String]$MessageText = \"The file {0} will be {1} encoded.\" -f $Path, $encoding\n\n        Write-Verbose -Message $MessageText\n\n        $errors = $tokens = @()\n        $ast = [System.Management.Automation.Language.Parser]::ParseFile(\n            $Path,\n            [Ref]$tokens,\n            [Ref]$errors\n        )\n\n        $script = Get-Content $Path -Raw -Encoding $encoding\n        $ast.FindAll(\n            {\n                param ( $ast )\n\n                $ast -is [System.Management.Automation.Language.CommandAst] -and\n                $ast.GetCommandName() -eq 'Should'\n            },\n            $true\n        ) |\n            ForEach-Object {\n                $_.CommandElements | Where-Object {\n                    $_.StringConstantType -eq 'BareWord' -and\n                    $_.Value -in $shouldParams -or\n                    $_.Value -eq 'Contain'\

1n                }\n            } |\n            Sort-Object { $_.Extent.StartOffset } -Descending |\n            ForEach-Object {\n                if ($_.Value -eq 'Contain') {\n                    $script = $script.Remove($_.Extent.StartOffset, 7).Insert($_.Extent.StartOffset, '-FileContentMatch')\n                } else {\n                    $script = $script.Insert($_.Extent.StartOffset, '-')\n                }\n            }\n\n        if ( $destIsEmpty) { $Destination = $Path }\n\n        Set-Content -Path $Destination -Value $script -NoNewline -Encoding $encoding\n    }\n\n}\n\nfunction Get-FileEncoding {\n    # source https://gist.github.com/jpoehls/2406504\n    # simplified.\n\n    [CmdletBinding()]\n    Param (\n        [Parameter(Mandatory = $True, ValueFromPipelineByPropertyName = $True)]\n        [string]$Path\n    )\n\n    [byte[]]$byte = get-content -Encoding byte -ReadCount 4 -TotalCount 4 -Path $Path\n\n    if ( $byte[0] -eq 0xef -and $byte[1] -eq 0xbb -and $byte[2] -eq 0xbf )\n    { Write-Output 'UTF8' }\n\n    else\n    { Write-Output 'ASCII' }\n}\n"})}),"\n",(0,i.jsx)(t.h2,{id:"mock-related-changes",children:"Mock-Related Changes"}),"\n",(0,i.jsx)(t.p,{children:"We are not 100% sure what implications changing from functions to aliases had on mocking. There are no immediate changes that you need to do, but here are two articles that should help you start figuring out issues if you have any:"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsx)(t.li,{children:(0,i.jsx)(t.a,{href:"https://github.com/pester/Pester/issues/810",children:"Get-Command of mocked function is less complete"})}),"\n",(0,i.jsx)(t.li,{children:(0,i.jsx)(t.a,{href:"https://github.com/pester/Pester/issues/812",children:"Summary of mock scope changes"})}),"\n"]}),"\n",(0,i.jsx)(t.h2,{id:"array-related-changes",children:"Array-Related Changes"}),"\n",(0,i.jsxs)(t.p,{children:["The ",(0,i.jsx)(t.code,{children:"Should"})," command now performs array assertions.  For the most part this change is transparent to existing tests.  There are some edge cases, however, where a test involving an array passes in Pester 3 but fails in Pester 4.  ",(0,i.jsx)(t.a,{href:"https://github.com/pester/Pester/issues/873",children:"This article"})," contains such an example."]}),"\n",(0,i.jsx)(t.h2,{id:"related-github-issues",children:"Related (Github) Issues"}),"\n",(0,i.jsxs)(t.p,{children:["Visit this link for all ",(0,i.jsx)(t.a,{href:"https://github.com/Pester/Pester/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3A%22Pester%20migration%20v3-%3Ev4%22%20",children:"Migration Related Issues"}),"."]})]})}function h(e={}){let{wrapper:t}={...(0,a.R)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}},7008(e,t,n){n.d(t,{R:()=>r,x:()=>o});var s=n(1763);let i={},a=s.createContext(i);function r(e){let t=s.useContext(a);return s.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function o(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:r(e.components),s.createElement(a.Provider,{value:t},e.children)}}}]);