diff --git a/BUILD.md b/BUILD.md index 3d255fd19..8409649b6 100644 --- a/BUILD.md +++ b/BUILD.md @@ -1,13 +1,70 @@ -## Building Pester +# Building Pester -Pester has a C# Solution which requires .Net Framework SDKs and Developer Packs in order to compile. The targetted frameworks can be found in `src\csharp\Pester\Pester.csproj`. +Pester is written in Powershell and C#. The Microsoft .NET Framework 4.5.2 is required to build the Pester binaries. -### Required Software +Pester has a C# Solution which requires .NET Framework SDKs and Developer Packs in order to compile. The targeted frameworks can be found in `src\csharp\Pester\Pester.csproj`. -#### Install .NET Core 3.1 SDK +## Required Software + +### Install .NET Core 3.1 SDK [Download Link](https://dotnet.microsoft.com/download/dotnet-core/3.1) -#### .Net Framework 4.5 Developer Pack +### .Net Framework 4.5 Developer Pack [Download Link](https://dotnet.microsoft.com/download/dotnet-framework/net452) + + +## Running Tests + +In Powershell, run test.ps1. This defines the inherited function InPesterModuleScope and some types required for the tests. + +Afterwards, each test can be run individually using Invoke-Pester. + +Test.ps1 and optionally -skipPTests to skip the .ts.ps1 files. + +## test.ps1 + +test.ps1 can be run locally with the following parameters: + +```powershell +.\test.ps1 -File +``` + +To skip P tests: + +```powershell +.\test.ps1 -File -SkipPTests +``` + +### Test Parameters + +```powershell +.PARAMETER CI + Exits after run. Enables test results and code coverage on `/src/*`. Enable exit with 1 if tests don't pass. Forces P Tests to fail when `dt` is left in the tests. `dt` only runs the specified test, so leaving it in code would run only one test from the file on the server. +.PARAMETER SkipPTests + Skips Passthrough P tests. Skip the tests written using the P module, Unit Tests for the Runtime, and Acceptance Tests for Pester +.NoBuild + Skips running build.ps1. Do not build the underlying csharp components. Used in CI pipeline since a clean build has already been run prior to Test. +.File + If specified, set file path to test file, otherwise set to /tst folder. Pass the file to run Pester (not P) tests from. + */demo/*, */examples/*, */testProjects/* are excluded from tests. +``` + +Tests are excluded with Tags VersionChecks, StyleRules, Help. + +## Continuous Integration + +The Azure Devops Pipeline azure-pipelines.yml file contains the code definition used for builds, unit and integration tests in the CI pipeline. + +Within the pipeline, tests are executed against PS7 Core on a strategy matrix of machines, including Ubuntu 16.04, 18.04, macOS Mojave 10.14, Catalina 10.15, Windows Server 2016, 2019. Tests are also executed against PS6.2, PS4, PS3. + +## Documentation + +Documentation is available in the repo, the [Pester wiki](https://github.com/pester/Pester/wiki), and at + +Documentation is written in Markdown. Comment-based Documentation and parts of the documentation web site are generated using Docusaurus Powershell. + +Multi-line examples added to comments should use fenced code. + + diff --git a/src/Pester.ps1 b/src/Pester.ps1 index 0a443022d..973cab3a1 100644 --- a/src/Pester.ps1 +++ b/src/Pester.ps1 @@ -18,6 +18,17 @@ function Add-ShouldOperator { Register a Should Operator with Pester .DESCRIPTION This function allows you to create custom Should assertions. +.PARAMETER Name + The name of the assertion. This will become a Named Parameter of Should. +.PARAMETER Test + The test function. The function must return a PSObject with a [Bool]succeeded and a [string]failureMessage property. +.PARAMETER Alias + A list of aliases for the Named Parameter. +.PARAMETER SupportsArrayInput + Does the test function support the passing an array of values to test. +.PARAMETER InternalName + If -Name is different from the actual function name, record the actual function name here. + Used by Get-ShouldOperator to pull function help. .EXAMPLE function BeAwesome($ActualValue, [switch] $Negate) { @@ -49,17 +60,6 @@ function Add-ShouldOperator { PS C:\> "bad" | should -BeAwesome {bad} is not Awesome -.PARAMETER Name - The name of the assertion. This will become a Named Parameter of Should. -.PARAMETER Test - The test function. The function must return a PSObject with a [Bool]succeeded and a [string]failureMessage property. -.PARAMETER Alias - A list of aliases for the Named Parameter. -.PARAMETER SupportsArrayInput - Does the test function support the passing an array of values to test. -.PARAMETER InternalName - If -Name is different from the actual function name, record the actual function name here. - Used by Get-ShouldOperator to pull function help. #> [CmdletBinding()] param ( diff --git a/src/functions/Describe.ps1 b/src/functions/Describe.ps1 index ca50610ba..cde6fdab8 100644 --- a/src/functions/Describe.ps1 +++ b/src/functions/Describe.ps1 @@ -57,12 +57,28 @@ Describe "Add-Numbers" { } } +.LINK +https://pester.dev/docs/commands/Describe + +.LINK +https://github.com/pester/Pester/wiki/Describe + .LINK It + +.LINK Context + +.LINK Invoke-Pester + +.LINK about_Should + +.LINK about_Mocking + +.LINK about_TestDrive #> diff --git a/src/functions/New-MockObject.ps1 b/src/functions/New-MockObject.ps1 index c9d6d2d68..a0d13d292 100644 --- a/src/functions/New-MockObject.ps1 +++ b/src/functions/New-MockObject.ps1 @@ -17,6 +17,13 @@ $obj = New-MockObject -Type 'System.Diagnostics.Process' $obj.GetType().FullName System.Diagnostics.Process ``` + +.LINK +https://pester.dev/docs/commands/New-MockObject + +.LINK +https://pester.dev/docs/usage/mocking + #> param ( diff --git a/src/functions/assertions/Should.ps1 b/src/functions/assertions/Should.ps1 index c886224bb..78f069d92 100644 --- a/src/functions/assertions/Should.ps1 +++ b/src/functions/assertions/Should.ps1 @@ -22,23 +22,86 @@ function New-ShouldErrorRecord ([string] $Message, [string] $File, [string] $Lin function Should { <# .SYNOPSIS - Should is a keyword what is used to define an assertion inside It block. + Should is a keyword that is used to define an assertion inside an It block. .DESCRIPTION - Should is a keyword what is used to define an assertion inside the It block. - Should provides assertion methods for verify assertion e.g. comparing objects. - If assertion is not met the test fails and an exception is throwed up. + Should is a keyword that is used to define an assertion inside an It block. + Should provides assertion methods to verify assertions e.g. comparing objects. + If assertion is not met the test fails and an exception is thrown. Should can be used more than once in the It block if more than one assertion - need to be verified. Each Should keywords need to be located in a new line. + need to be verified. Each Should keyword needs to be on a separate line. Test will be passed only when all assertion will be met (logical conjuction). .LINK - https://github.com/pester/Pester/wiki/Should + https://pester.dev/docs/usage/assertions .LINK about_Should + + .LINK about_Pester + + .EXAMPLE + ```ps + Describe "d1" { + BeforeEach { $be = 1 } + It "i1" { + $be = 2 + } + AfterEach { Write-Host "AfterEach: $be" } + } + ``` + + .EXAMPLE + ```ps + Describe "d1" { + It "i1" { + $user = Get-User + $user | Should -NotBeNullOrEmpty -ErrorAction Stop + $user | + Should -HaveProperty Name -Value "Jakub" | + Should -HaveProperty Age -Value 30 + } + } + ``` + + .EXAMPLE + ```ps + Describe "d1" { + It "i1" { + Mock Get-Command { } + Get-Command -CommandName abc + Should -Invoke Get-Command -Times 1 -Exactly + } + } + ``` + + .EXAMPLE + ```ps + Describe "d1" { + It "i1" { + Mock Get-Command { } + Get-Command -CommandName abc + Should -Invoke Get-Command -Times 1 -Exactly + } + } + ``` + + .EXAMPLE + $true | Should -BeFalse + + .EXAMPLE + $a | Should -Be 10 + + .EXAMPLE + Should -Invoke Get-Command -Times 1 -Exactly + + .EXAMPLE + $user | Should -NotBeNullOrEmpty -ErrorAction Stop + + .EXAMPLE + $planets.Name | Should -Be $Expected #> [CmdletBinding()] @@ -157,7 +220,7 @@ function Should { AddErrorCallback = $addErrorCallback } - if (-not $entry) { return } + if (-not $entry) { return } if ($inputArray.Count -eq 0) { Invoke-Assertion @assertionParams -ValueToTest $null