1"use strict";(self.webpackChunkpester_docs=self.webpackChunkpester_docs||[]).push([["3458"],{8850(e,t,s){s.r(t),s.d(t,{metadata:()=>n,default:()=>h,frontMatter:()=>a,contentTitle:()=>o,toc:()=>c,assets:()=>l});var n=JSON.parse('{"id":"quick-start","title":"Quick Start","description":"What is Pester?","source":"@site/versioned_docs/version-v4/quick-start.mdx","sourceDirName":".","slug":"/quick-start","permalink":"/docs/v4/quick-start","draft":false,"unlisted":false,"editUrl":"https://github.com/pester/docs/edit/main/versioned_docs/version-v4/quick-start.mdx","tags":[],"version":"v4","frontMatter":{"id":"quick-start","title":"Quick Start","sidebar_label":"Quick Start"},"sidebar":"docs","next":{"title":"Installation","permalink":"/docs/v4/introduction/installation"}}'),r=s(1987),i=s(7008);let a={id:"quick-start",title:"Quick Start",sidebar_label:"Quick Start"},o,l={},c=[{value:"What is Pester?",id:"what-is-pester",level:2},{value:"Creating a Pester Test",id:"creating-a-pester-test",level:2},{value:"Running a Pester test",id:"running-a-pester-test",level:2},{value:"Pester and Continuous Integration (CI)",id:"pester-and-continuous-integration-ci",level:2},{value:"Other Examples",id:"other-examples",level:2}];function d(e){let t={a:"a",code:"code",em:"em",h2:"h2",li:"li",p:"p",pre:"pre",ul:"ul",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(t.h2,{id:"what-is-pester",children:"What is Pester?"}),"\n",(0,r.jsxs)(t.p,{children:[(0,r.jsx)(t.a,{href:"https://github.com/pester/Pester/blob/rel/4.x.x/Pester.psm1",children:"Pester"})," is a Behavior-Driven\nDevelopment (BDD) based test runner and mocking framework for PowerShell."]}),"\n",(0,r.jsx)(t.p,{children:"Pester provides a framework for running Unit Tests to execute and validate PowerShell commands.\nPester follows a file naming convention for naming tests to be discovered by pester at test time\nand a simple set of functions that expose a Testing DSL for isolating, running, evaluating and\nreporting the results of PowerShell commands."}),"\n",(0,r.jsx)(t.p,{children:"Pester tests can execute any command or script that is accessible to a pester test file. This can\ninclude functions, Cmdlets, Modules and scripts. Pester can be run in ad-hoc style in a console or\nit can be integrated into the Build scripts of a Continuous Integration system."}),"\n",(0,r.jsxs)(t.p,{children:["Pester contains a powerful set of Mocking Functions that allow tests to mimic and mock the\nfunctionality of any command inside of a piece of PowerShell code being tested. See\n",(0,r.jsx)(t.a,{href:"./usage/mocking",children:"Mocking with Pester"}),"."]}),"\n",(0,r.jsxs)(t.p,{children:["Pester can produce artifacts such as Test Results and can be used for Generating\n",(0,r.jsx)(t.a,{href:"./usage/code-coverage",children:"Code Coverage Metrics"})," metrics output files which can be used\nfor reporting purposes and in build pipelines. See ",(0,r.jsx)(t.a,{href:"./usage/test-results",children:"Showing Test-Results in CI"}),"."]}),"\n",(0,r.jsx)(t.h2,{id:"creating-a-pester-test",children:"Creating a Pester Test"}),"\n",(0,r.jsxs)(t.p,{children:["To start using Pester, use the optional ",(0,r.jsx)(t.a,{href:"./commands/New-Fixture",children:"New-Fixture"})," function to scaffold\nboth a new implementation function and a test function. New-Fixture assumes that you will be testing\nthe contents of a ",(0,r.jsx)(t.code,{children:".ps1"})," file (not a ",(0,r.jsx)(t.code,{children:".psm1"})," file, or Script Module), that the test script should be\nin the same directory as the script under test, and that the name of the test script should be\n",(0,r.jsx)(t.code,{children:"<Name of Script Under Test>.Tests.ps1"}),"."]}),"\n",(0,r.jsx)(t.p,{children:"To scaffold a new project, use the script below to generate a placeholder function script and test script."}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-powershell",children:'New-Fixture deploy Clean\n\n<#\nCreates two files:\n./deploy/Clean.ps1\n#>\n\nfunction Clean {\n\n}\n\n# ./deploy/Clean.Tests.ps1\n\n$here = Split-Path -Parent $MyInvocation.MyCommand.Path\n$sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path) -replace \'\\.Tests\\.\', \'.\'\n. "$here\\$sut"\n\nDescribe "Clean" {\n It "does something useful" {\n $true | Should -Be $false\n }\n}\n'})}),"\n",(0,r.jsx)(t.p,{children:'With this skeleton of a function called "Clean" and a failing test, Test-Driven Development activities can start.'}),"\n",(0,r.jsxs)(t.p,{children:["Pester test script filenames ",(0,r.jsx)(t.em,{children:"must"})," end with ",(0,r.jsx)(t.code,{children:".Tests.ps1"})," suffix in order for ",(0,r.jsx)(t.a,{href:"./commands/Invoke-Pester",children:"Invoke-Pester"}),"\nto discover and run them. (eg. MyScript.Tests.ps1)."]}),"\n",(0,r.jsx)(t.p,{children:"Test scripts named with or without this suffix can be run manually using -Script parameter."}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-powershell",children:"Invoke-Pester -Script .\\Test-ScriptWithPesterTest.ps1\n"})}),"\n",(0,r.jsxs)(t.p,{children:["In addition to filename discovery of the ",(0,r.jsx)(t.code,{children:"\\*.Tests.ps1"})," pattern by the ",(0,r.jsx)(t.a,{href:"./commands/Invoke-Pester",children:"Invoke-Pester"}),"\ncommand, Pester discovers ",(0,r.jsx)(t.code,{children:"Describe"})," blocks (logical groupings of tests) within the test file\n(see ",(0,r.jsx)(t.a,{href:"./commands/Describe",children:"Describe"}),")."]}),"\n",(0,r.jsxs)(t.p,{children:["The ",(0,r.jsx)(t.code,{children:"Describe"})," block can contain several behavior validations expressed in ",(0,r.jsx)(t.a,{href:"./commands/It",children:"It"})," blocks (see ",(0,r.jsx)(t.a,{href:"./commands/It",children:"It"}),").\nEach ",(0,r.jsx)(t.a,{href:"./commands/It",children:"It"})," block should test one thing and throw an exception if the test fails. Pester will c
1onsider any\n",(0,r.jsx)(t.a,{href:"./commands/It",children:"It"})," block that throws an exception to be a failed test."]}),"\n",(0,r.jsxs)(t.p,{children:["Pester provides a command called ",(0,r.jsx)(t.a,{href:"./commands/Should",children:"Should"})," that can perform various comparisons between the values emitted\nor altered by a command and an expected value (see ",(0,r.jsx)(t.a,{href:"./commands/Should",children:"Should"}),")."]}),"\n",(0,r.jsx)(t.h2,{id:"running-a-pester-test",children:"Running a Pester test"}),"\n",(0,r.jsxs)(t.p,{children:["Use the ",(0,r.jsx)(t.a,{href:"./commands/Invoke-Pester",children:"Invoke-Pester"})," command to run tests (see ",(0,r.jsx)(t.a,{href:"./commands/Invoke-Pester",children:"Invoke-Pester"}),"). ",(0,r.jsx)(t.a,{href:"./commands/Invoke-Pester",children:"Invoke-Pester"})," can be run against all the\n",(0,r.jsx)(t.code,{children:"\\*.Tests.ps1"})," files in an entire tree of directories or it can zero in on just one test group (",(0,r.jsx)(t.code,{children:"Describe"})," block)\nusing ",(0,r.jsx)(t.code,{children:"-TestName"})," parameter. The ",(0,r.jsx)(t.code,{children:"-Tag"})," parameter in the ",(0,r.jsx)(t.a,{href:"./commands/Describe",children:"Describe"})," block can also be used for targeted testing,\ncategorization and filtering of tests."]}),"\n",(0,r.jsxs)(t.p,{children:["As of Pester version 3.0, direct execution of any ",(0,r.jsx)(t.code,{children:".Tests.ps1"})," script file is available without using\n",(0,r.jsx)(t.a,{href:"./commands/Invoke-Pester",children:"Invoke-Pester"})," test harness; with test output written to the console. By running tests directly, many\nof the benefits of the test framework are unavailable."]}),"\n",(0,r.jsxs)(t.p,{children:["Benefits to running from ",(0,r.jsx)(t.a,{href:"./commands/Invoke-Pester",children:"Invoke-Pester"})," test framework include the following:"]}),"\n",(0,r.jsxs)(t.ul,{children:["\n",(0,r.jsx)(t.li,{children:"Produce NUnit XML files or other output objects"}),"\n",(0,r.jsx)(t.li,{children:"Code Coverage analysis."}),"\n",(0,r.jsx)(t.li,{children:"Exit codes from PowerShell.exe"}),"\n",(0,r.jsx)(t.li,{children:"Filtering of tests to execute"}),"\n",(0,r.jsx)(t.li,{children:"Status summary of tests executed / failed when test run is complete."}),"\n"]}),"\n",(0,r.jsx)(t.h2,{id:"pester-and-continuous-integration-ci",children:"Pester and Continuous Integration (CI)"}),"\n",(0,r.jsxs)(t.p,{children:["Pester integrates with almost any build automation solution. See ",(0,r.jsx)(t.a,{href:"./usage/test-results",children:"Showing Test Results in CI (TeamCity, AppVeyor, Azure DevOps)"})]}),"\n",(0,r.jsx)(t.p,{children:"An example of a PowerShell script to run against a single pester test file using an Azure Devops Inline Powershell script task."}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-powershell",children:"# This updates pester not always necessary but worth noting\nInstall-Module -Name Pester -MaximumVersion 4.99 -Force -SkipPublisherCheck\n\nImport-Module Pester\n\nInvoke-Pester -Script $(System.DefaultWorkingDirectory)\\MyFirstModule.test.ps1 -OutputFile $(System.DefaultWorkingDirectory)\\Test-Pester.XML -OutputFormat NUnitXML\n"})}),"\n",(0,r.jsx)(t.p,{children:"An example of an MSBuild target that calls Pester's convenience helper Batch file to run a suite of tests:"}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-xml",children:'<Target Name="Tests">\n <Exec Command="cmd /c $(baseDir)pester\\bin\\pester.bat" />\n</Target>\n'})}),"\n",(0,r.jsxs)(t.p,{children:["The MSBuild example will start a PowerShell session, import the Pester Module and call ",(0,r.jsx)(t.a,{href:"./commands/Invoke-Pester",children:"Invoke-Pester"}),"\nwithin the current directory. If any test fails, it will return an exit code equal to the number of failed\ntests and all test results will be saved to Test.xml using NUnit's Schema. This file can be published as\ntest results as part of the build into most build systems like Azure Devops, CruiseControl, TeamCity, TFS\nor Jenkins. See ",(0,r.jsx)(t.a,{href:"./usage/test-results",children:"Showing Test Results in CI (TeamCity, AppVeyor, Azure DevOps)"})]}),"\n",(0,r.jsx)(t.h2,{id:"other-examples",children:"Other Examples"}),"\n",(0,r.jsxs)(t.ul,{children:["\n",(0,r.jsxs)(t.li,{children:["Pester's own Test ",(0,r.jsx)(t.a,{href:"https://github.com/pester/Pester/tree/rel/4.x.x/Examples",children:"Examples"}),". See all files in the Pester Functions folder containing ",(0,r.jsx)(t.code,{children:".Tests.ps1"})]}),"\n",(0,r.jsx)(t.li,{children:"Chocolatey tests. Chocolatey is a popular PowerShell-based Windows package management system. It uses Pester tests to validate its own functionality."}),"\n"]})]})}function h(e={}){let{wrapper:t}={...(0,i.R)(),...e.components};return t?(0,r.jsx)(t,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},7008(e,t,s){s.d(t,{R:()=>a,x:()=>o});var n=s(1763);let r={},i=n.createContext(r);function a(e){let t=n.useContext(i);return n.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(r):e.components||r:a(e.components),n.createElement(i.Provider,{value:t},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.