You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Update Skip with note about inconclusive and Set-ItResult
* Cleanup formatting
* Update breaking changes in v5 page to match recent versions
* Update skip.mdx
* Update v5 docs
* Backport ebffe74 to v5 docs
Co-Authored-By: Matthew Harrah <mharrah@paylocity.com>
---------
Co-authored-by: Matthew Harrah <mharrah@paylocity.com>
Copy file name to clipboardExpand all lines: docs/migrations/breaking-changes-in-v5.mdx
+14-12Lines changed: 14 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,34 +6,36 @@ description: Pester v5 included an all-new runtime which lead to some breaking c
6
6
7
7
## Actual breaking changes
8
8
9
-
- The Parameters of `Invoke-Pester` changed significantly, but in 5.0.1, a compatibility parameter set was added. To allow all the v4 parameters to be used, e.g. like this `Invoke-Pester -Script $testFile -PassThru -Verbose -OutputFile $tr -OutputFormat NUnitXml -CodeCoverage "$tmp/*-*.ps1" -CodeCoverageOutputFile $cc -Show All`. The compatibility is not 100%, neither -Script not -CodeCoverage take hashtables, they just take a collection of paths. The `-Strict` parameter and `-PesterOption` are ignored. The `-Output` \ `-Show` parameter takes all the values, but translates only the most used options to Pester 5 compatible options, otherwise it uses `Detailed` output. It also allows all the Pester 5 output options, to allow you to use `Diagnostic` during migration. **This whole Legacy-parameter set is deprecated** and prints a warning when used. For more options and the Advanced interface see [simple and advanced interface](./v4-to-v5#simple-and-advanced-interface) above on how to invoke Pester.
9
+
- The Parameters of `Invoke-Pester` changed significantly, but a compatibility parameter set was added to allow all the v4 parameters to be used, e.g. like this `Invoke-Pester -Script $testFile -PassThru -Verbose -OutputFile $tr -OutputFormat NUnitXml -CodeCoverage "$tmp/*-*.ps1" -CodeCoverageOutputFile $cc -Show All`. Be aware of these limitations and notes:
10
+
- The compatibility is not 100%, neither `-Script` not `-CodeCoverage` take hashtables, they just take a collection of paths.
11
+
- The `-Strict` parameter and `-PesterOption` are ignored.
12
+
- The `-Output` \ `-Show` parameter takes all the values, but translates only the most used options to Pester 5 compatible options, otherwise it uses `Detailed` output. It also allows all the Pester 5 output options, to allow you to use `Diagnostic` during migration.
13
+
-**This whole Legacy-parameter set is deprecated** and prints a warning when used. For more options and the Advanced interface see [simple and advanced interface](./v4-to-v5#simple-and-advanced-interface) above on how to invoke Pester.
10
14
- PowerShell 2 is no longer supported
11
15
- Legacy syntax `Should Be` (without `-`) is removed, see [Migrating from Pester v3 to v4](./v3-to-v4)
12
16
- Mocks are scoped based on their placement, not in whole `Describe` / `Context`. The count also depends on their placement. See [mock scoping](../usage/mocking#mocks-are-scoped-based-on-their-placement)
13
17
-`Assert-VerifiableMocks` was removed, see [Should -Invoke](../usage/mocking#should--invoke)
14
18
- All code placed in the body of `Describe` outside of `It`, `BeforeAll`, `BeforeEach`, `AfterAll`, `AfterEach` will run during discovery and it's state might or might not be available to the test code, see [Discovery and Run](../usage/discovery-and-run)
15
-
16
-
-`-Output` parameter has reduced options to `None`, `Normal`, `Detailed` and `Diagnostic`, `-Show` alias is removed
19
+
-`-Output` parameter has reduced options to `None`, `Normal`, `Detailed` and `Diagnostic`. `-Show` alias is removed
17
20
-`-PesterOption` switch is removed
18
21
-`-TestName` switch is replaced with `-FullNameFilter` switch
19
22
-`-Script` option was renamed to `-Path` and takes paths only, it does not take hashtables. For parametrized scripts, see [Providing external data to tests](../usage/data-driven-tests#providing-external-data-to-tests)
20
23
- Using `$MyInvocation.MyCommand.Path` to locate your script in `BeforeAll` does not work. This does not break it for your scripts and modules. Use `$PSScriptRoot` or `$PSCommandPath`. See [Migrating from Pester v4](../usage/importing-tested-functions#migrating-from-pester-v4) or the [importing ps files](https://jakubjares.com/2020/04/11/pester5-importing-ps-files/) article for detailed information.
21
24
- Should `-Throw` is using `-like` to match the exception message instead of .Contains. Use `*` or any of the other `-like` wildcard to match only part of the message.
22
-
- Variables defined during Discovery, are not available in Before*, After* and It. When generating tests via foreach blocks, make sure you pass all variables into the test using -TestCases / -ForEach.
23
-
- Gherkin is removed, and will later move to it's own module, please keep using Pester version 4.
24
-
-`TestDrive` is defined during Run only, it cannot be used in -TestCases / -ForEach.
25
+
- Variables defined during Discovery, are not available in `BeforeAll/-Each`, `AfterAll/-Each` and `It`. When generating tests via foreach blocks, make sure you pass all variables into the test using `-ForEach`.
26
+
- Gherkin is removed, please keep using Pester version 4.
27
+
-`TestDrive` is defined during Run only, it cannot be used in `-ForEach`.
25
28
26
29
### Deprecated features
27
30
28
-
-`Assert-MockCalled` is deprecated, it is recommended to use [Should -Invoke](../usage/mocking)
29
-
-`Assert-VerifiableMock` is deprecated, it is recommended to use [Should -InvokeVerifiable](../usage/mocking)
31
+
-`Assert-MockCalled` is deprecated, it is recommended to use [Should -Invoke](../usage/mocking).
32
+
-`Assert-VerifiableMock` is deprecated, it is recommended to use [Should -InvokeVerifiable](../usage/mocking).
33
+
- Pending state (`Set-ItResult -Pending`) is deprecated and will be removed in a future version.
30
34
31
35
### Additional issues to be solved future releases
32
36
33
37
-`-Strict` switch is not available
34
-
- Inconclusive and Pending states are currently no longer available, `-Pending` and `-Inconclusive` are translated to `-Skip` both on test blocks and when using `Set-ItResult`
35
-
- Automatic Code coverage via -CI switch currently disabled as it's slow. Can still be enabled using configuration, but is largely untested.
36
-
- Generating tests using foreach during discovery time works mostly, generating them from BeforeAll, to postpone expensive work till it is needed in case the test is filtered out also works, but is hacky. Get in touch if you need it and help me refine it.
37
-
- Running on huge codebases is largely untested
38
+
- Automatic Code coverage via -CI switch currently disabled as it's slow. Can still be enabled using configuraitonis largely untested.
Mocks don't rewrite the scriptblock you provide anymore. You can now set breakpoints into them as well as any of the ParameterFilter or Should -Invoke Parameter filter.
173
+
Mocks don't rewrite the scriptblock you provide anymore. You can now set breakpoints into them as well as any of the `-ParameterFilter` used in `Mock` and `Should -Invoke`.
174
174
175
175
#### Avoid putting in InModuleScope around your Describe and It blocks
Pending is translated to skipped, Inconclusive does not exist anymore.
59
-
:::
60
-
61
57
### Conditional skip
62
58
63
-
Evaluation of the skip-parameter is done as part of the Discovery-phase. This means you can also dynamically skip tests based on values available in that phase. Either as logic done in BeforeDiscovery or based on values passed into a parametrized test.
59
+
Evaluation of the skip-parameter is done as part of the Discovery-phase. This means you can also dynamically skip tests based on values available in that phase. Either as logic done in `BeforeDiscovery` or based on values passed into a parametrized test.
64
60
65
61
```powershell
66
62
$sb = {
@@ -126,3 +122,7 @@ Describing My Describe Block
126
122
Tests completed in 206ms
127
123
Tests Passed: 1, Failed: 0, Skipped: 2 NotRun: 0
128
124
```
125
+
126
+
:::tip Skipping during Run-phase
127
+
In certain scenarios you might need to mark a test as skipped or inconclusive during execution. This is possible using [`Set-ItResult`](../commands/Set-ItResult). Be aware that setup and teardown-blocks will be executed, so use `-Skip` whenever possible.
Copy file name to clipboardExpand all lines: versioned_docs/version-v5/migrations/breaking-changes-in-v5.mdx
+14-12Lines changed: 14 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,34 +6,36 @@ description: Pester v5 included an all-new runtime which lead to some breaking c
6
6
7
7
## Actual breaking changes
8
8
9
-
- (❗ new in 5.0.1) The Parameters of `Invoke-Pester` changed significantly, but in 5.0.1, a compatibility parameter set was added. To allow all the v4 parameters to be used, e.g. like this `Invoke-Pester -Script $testFile -PassThru -Verbose -OutputFile $tr -OutputFormat NUnitXml -CodeCoverage "$tmp/*-*.ps1" -CodeCoverageOutputFile $cc -Show All`. The compatibility is not 100%, neither -Script not -CodeCoverage take hashtables, they just take a collection of paths. The `-Strict` parameter and `-PesterOption` are ignored. The `-Output` \ `-Show` parameter takes all the values, but translates only the most used options to Pester 5 compatible options, otherwise it uses `Detailed` output. It also allows all the Pester 5 output options, to allow you to use `Diagnostic` during migration. **This whole Legacy-parameter set is deprecated** and prints a warning when used. For more options and the Advanced interface see [simple and advanced interface](./v4-to-v5#simple-and-advanced-interface) above on how to invoke Pester.
9
+
- The Parameters of `Invoke-Pester` changed significantly, but a compatibility parameter set was added to allow all the v4 parameters to be used, e.g. like this `Invoke-Pester -Script $testFile -PassThru -Verbose -OutputFile $tr -OutputFormat NUnitXml -CodeCoverage "$tmp/*-*.ps1" -CodeCoverageOutputFile $cc -Show All`. Be aware of these limitations and notes:
10
+
- The compatibility is not 100%, neither `-Script` not `-CodeCoverage` take hashtables, they just take a collection of paths.
11
+
- The `-Strict` parameter and `-PesterOption` are ignored.
12
+
- The `-Output` \ `-Show` parameter takes all the values, but translates only the most used options to Pester 5 compatible options, otherwise it uses `Detailed` output. It also allows all the Pester 5 output options, to allow you to use `Diagnostic` during migration.
13
+
-**This whole Legacy-parameter set is deprecated** and prints a warning when used. For more options and the Advanced interface see [simple and advanced interface](./v4-to-v5#simple-and-advanced-interface) above on how to invoke Pester.
10
14
- PowerShell 2 is no longer supported
11
15
- Legacy syntax `Should Be` (without `-`) is removed, see [Migrating from Pester v3 to v4](./v3-to-v4)
12
16
- Mocks are scoped based on their placement, not in whole `Describe` / `Context`. The count also depends on their placement. See [mock scoping](../usage/mocking#mocks-are-scoped-based-on-their-placement)
13
17
-`Assert-VerifiableMocks` was removed, see [Should -Invoke](../usage/mocking#should--invoke)
14
18
- All code placed in the body of `Describe` outside of `It`, `BeforeAll`, `BeforeEach`, `AfterAll`, `AfterEach` will run during discovery and it's state might or might not be available to the test code, see [Discovery and Run](../usage/discovery-and-run)
15
-
16
-
-`-Output` parameter has reduced options to `None`, `Normal`, `Detailed` and `Diagnostic`, `-Show` alias is removed
19
+
-`-Output` parameter has reduced options to `None`, `Normal`, `Detailed` and `Diagnostic`. `-Show` alias is removed
17
20
-`-PesterOption` switch is removed
18
21
-`-TestName` switch is replaced with `-FullNameFilter` switch
19
22
-`-Script` option was renamed to `-Path` and takes paths only, it does not take hashtables. For parametrized scripts, see [Providing external data to tests](../usage/data-driven-tests#providing-external-data-to-tests)
20
23
- Using `$MyInvocation.MyCommand.Path` to locate your script in `BeforeAll` does not work. This does not break it for your scripts and modules. Use `$PSScriptRoot` or `$PSCommandPath`. See [Migrating from Pester v4](../usage/importing-tested-functions#migrating-from-pester-v4) or the [importing ps files](https://jakubjares.com/2020/04/11/pester5-importing-ps-files/) article for detailed information.
21
24
- Should `-Throw` is using `-like` to match the exception message instead of .Contains. Use `*` or any of the other `-like` wildcard to match only part of the message.
22
-
- Variables defined during Discovery, are not available in Before*, After* and It. When generating tests via foreach blocks, make sure you pass all variables into the test using -TestCases / -ForEach.
23
-
- Gherkin is removed, and will later move to it's own module, please keep using Pester version 4.
24
-
-`TestDrive` is defined during Run only, it cannot be used in -TestCases / -ForEach.
25
+
- Variables defined during Discovery, are not available in `BeforeAll/-Each`, `AfterAll/-Each` and `It`. When generating tests via foreach blocks, make sure you pass all variables into the test using `-ForEach`.
26
+
- Gherkin is removed, please keep using Pester version 4.
27
+
-`TestDrive` is defined during Run only, it cannot be used in `-ForEach`.
25
28
26
29
### Deprecated features
27
30
28
-
-`Assert-MockCalled` is deprecated, it is recommended to use [Should -Invoke](../usage/mocking)
29
-
-`Assert-VerifiableMock` is deprecated, it is recommended to use [Should -InvokeVerifiable](../usage/mocking)
31
+
-`Assert-MockCalled` is deprecated, it is recommended to use [Should -Invoke](../usage/mocking).
32
+
-`Assert-VerifiableMock` is deprecated, it is recommended to use [Should -InvokeVerifiable](../usage/mocking).
33
+
- Pending state (`Set-ItResult -Pending`) is deprecated and will be removed in a future version.
30
34
31
35
### Additional issues to be solved future releases
32
36
33
37
-`-Strict` switch is not available
34
-
- Inconclusive and Pending states are currently no longer available, `-Pending` and `-Inconclusive` are translated to `-Skip` both on test blocks and when using `Set-ItResult`
35
-
- Automatic Code coverage via -CI switch currently disabled as it's slow. Can still be enabled using configuration, but is largely untested.
36
-
- Generating tests using foreach during discovery time works mostly, generating them from BeforeAll, to postpone expensive work till it is needed in case the test is filtered out also works, but is hacky. Get in touch if you need it and help me refine it.
37
-
- Running on huge codebases is largely untested
38
+
- Automatic Code coverage via -CI switch currently disabled as it's slow. Can still be enabled using configuraitonis largely untested.
Mocks don't rewrite the scriptblock you provide anymore. You can now set breakpoints into them as well as any of the ParameterFilter or Should -Invoke Parameter filter.
173
+
Mocks don't rewrite the scriptblock you provide anymore. You can now set breakpoints into them as well as any of the `-ParameterFilter` used in `Mock` and `Should -Invoke`.
174
174
175
175
#### Avoid putting in InModuleScope around your Describe and It blocks
Copy file name to clipboardExpand all lines: versioned_docs/version-v5/usage/output.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,7 +31,7 @@ This option controls the general level of console output. Pester v5 supports the
31
31
32
32
### StackTraceVerbosity
33
33
34
-
**New in Pester 5.3!**
34
+
**New in Pester 5.3.0!**<br/>
35
35
When an error is shown due to a failed setup or test, a stacktrace is included to help you identify where the problem occured. Users might not care much about this while developers need it to identify and fix any issues.
36
36
This option lets you control how much of the stacktrace that will be printed using one of the following levels:
37
37
@@ -50,7 +50,7 @@ The result-object returned from `Run.PassThru / -PassThru` includes a `ErrorReco
50
50
51
51
### CIFormat
52
52
53
-
**New in Pester 5.3!**
53
+
**New in Pester 5.3.0!**<br/>
54
54
Pester supports CI-specific output syntaxes to highlight, log and navigate to errors in your tests for a few popular CI systems. This options lets your control how this behavior should work. The following levels are currently supported:
55
55
56
56
-**None**: Disable all CI-specific syntax. Error messages are presented in the format you're familiar with.
@@ -78,7 +78,7 @@ Auto-detection works by checking if `GITHUB_ACTIONS` environment variable is equ
78
78
79
79
### RenderMode
80
80
81
-
**New in Pester 5.4!**
81
+
**New in Pester 5.4.0!**<br/>
82
82
Pester supports multiple render modes for console output, including ANSI escape sequences which enables colors in CI-logs. The currently supported modes are:
83
83
84
84
-**Auto (default)**: Automatically enables the recommended mode using the following rules:
Pending is translated to skipped, Inconclusive does not exist anymore.
59
-
:::
60
-
61
57
### Conditional skip
62
58
63
-
Evaluation of the skip-parameter is done as part of the Discovery-phase. This means you can also dynamically skip tests based on values available in that phase. Either as logic done in BeforeDiscovery or based on values passed into a parametrized test.
59
+
Evaluation of the skip-parameter is done as part of the Discovery-phase. This means you can also dynamically skip tests based on values available in that phase. Either as logic done in `BeforeDiscovery` or based on values passed into a parametrized test.
64
60
65
61
```powershell
66
62
$sb = {
@@ -126,3 +122,7 @@ Describing My Describe Block
126
122
Tests completed in 206ms
127
123
Tests Passed: 1, Failed: 0, Skipped: 2 NotRun: 0
128
124
```
125
+
126
+
:::tip Skipping during Run-phase
127
+
In certain scenarios you might need to mark a test as skipped or inconclusive during execution. This is possible using [`Set-ItResult`](../commands/Set-ItResult). Be aware that setup and teardown-blocks will be executed, so use `-Skip` whenever possible.
0 commit comments