Skip to content

Commit 42e75ba

Browse files
fflatennohwnd
fflaten
and
nohwnd
authored
Add v6 preview docs (#316)
* Version v5 docs and keep as latest * Set ident size to 2 spaces for js and ts files * Generate PesterConfiguration section on Configuration page * Update configuration docs * Update installation requirements * Rename PesterConfiguration docs script * Update Command Reference to 6.0.0-alpha1 * Update Command Reference from unreleased build * Update TestRegistry to remove guid-reference * Update TestDrive * Redirect versioned URIs for lastVersion * Make versioned redirect temporary to avoid indexing * Use /docs/v6 paths during preview * Fix launch config for devcontainer use Docker or VSCode has become strict on using 0.0.0.0 to forward to host * Use New-PesterConfiguration in usage-docs * Scaffold new migration guide to v6 * Remove new in 5.x references and outdated workarounds * Update generate-command-reference.ps1 Add support for versioned docs and prerelease modules * Add PesterConfiguration docs for v5 * Add manual workflow to automate docs update * Update generate-command-reference.ps1 Format and replace deprecated GH output command * Update workflow * Fix version references and minor updates * Update mocking function in method example * Update TestRegistry example to v5+ * Add WIP docs for v6 assertions * Fix table overflow on mobile in Configuration.mdx * Use fully qualified options names * Update v5 PesterConfiguration docs * Update docs/usage/configuration.mdx * Update breaking changes in v6 * Add notice about empty or null data * Update docs/migrations/v5-to-v6.mdx --------- Co-authored-by: Jakub Jareš <[email protected]>
1 parent dda61f2 commit 42e75ba

File tree

170 files changed

+16596
-296
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

170 files changed

+16596
-296
lines changed

‎.devcontainer/devcontainer.json

+3-2
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222

2323
// Use 'postCreateCommand' to run commands after the container is created.
2424
"postCreateCommand": "yarn install",
25-
25+
2626
// Configure tool-specific properties.
2727
"customizations": {
2828
"vscode": {
@@ -33,7 +33,8 @@
3333
"dbaeumer.vscode-eslint",
3434
"unifiedjs.vscode-mdx",
3535
"ms-vscode.powershell",
36-
"EditorConfig.EditorConfig"
36+
"EditorConfig.EditorConfig",
37+
"github.vscode-github-actions"
3738
]
3839
}
3940
}

‎.editorconfig

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,5 @@ trim_trailing_whitespace = true
99
indent_size = 4
1010
max_line_length = 80
1111

12-
[*.{json,ps1xml,props,xml,yaml,css}]
12+
[*.{js,jsx,ts,tsx,json,ps1xml,props,xml,yml,yaml,css}]
1313
indent_size = 2

‎.github/workflows/generate-pester-docs.yml

+98
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
name: Update Pester Docs
2+
run-name: Update Pester ${{ github.event.inputs.docs_version }} docs to v${{ github.event.inputs.pester_version }}
3+
4+
on:
5+
workflow_dispatch:
6+
inputs:
7+
docs_version:
8+
description: 'Docs version to update'
9+
required: true
10+
default: 'v5'
11+
type: choice
12+
options:
13+
- Current
14+
- v5
15+
- v4
16+
pester_version:
17+
description: 'Pester version to use for docs generation. Format: 5.6.0 or 6.0.0-alpha1'
18+
required: true
19+
type: string
20+
21+
jobs:
22+
generate_docs:
23+
name: Docs PR
24+
runs-on: ubuntu-latest
25+
env:
26+
PESTER: ${{ github.event.inputs.pester_version }}
27+
DOCS: ${{ github.event.inputs.docs_version }}
28+
permissions:
29+
contents: write
30+
pull-requests: write
31+
steps:
32+
- name: Validate Pester version input
33+
run: |
34+
echo "Validating that the provided pester_version input is a valid version-format (x.y.z or x.y.z-suffix)"
35+
echo "${{ env.PESTER }}" | grep -P '^\d+.\d+.\d+(?:-\w+)?$'
36+
37+
- name: Checkout code
38+
uses: actions/checkout@v4
39+
40+
# This step will also install and import modules incl. selected Pester-version
41+
- name: Update Command Reference
42+
id: commands
43+
shell: pwsh
44+
run: |
45+
./generate-command-reference.ps1 -PesterVersion '${{ env.PESTER }}' -DocsVersion '${{ env.DOCS }}'
46+
47+
# Output if any files were modified
48+
$updated = $null -ne (git status -s | Select-String '/commands/')
49+
"updated=$updated" >> $env:GITHUB_OUTPUT
50+
- name: Update PesterConfiguration docs
51+
if: ${{ env.DOCS != 'v4' }}
52+
id: config
53+
shell: pwsh
54+
run: |
55+
./generate-pesterconfiguration-docs.ps1 -PesterVersion '${{ env.PESTER }}' -Style Table -DocsVersion '${{ env.DOCS }}'
56+
57+
# Output if any files were modified
58+
$updated = $null -ne (git status -s | Select-String '/usage/Configuration.mdx')
59+
"updated=$updated" >> $env:GITHUB_OUTPUT
60+
- name: Create Pull Request
61+
uses: peter-evans/create-pull-request@6d6857d36972b65feb161a90e484f2984215f83e # v6.0.5
62+
id: create-pr
63+
env:
64+
PR_BRANCH: "docs-update/${{ env.DOCS }}-v${{ env.PESTER }}"
65+
TITLE_DOCS_VERSION: "${{ env.DOCS != 'Current' && format('{0} ', env.DOCS) || '' }}"
66+
with:
67+
branch: ${{ env.PR_BRANCH }}
68+
branch-suffix: short-commit-hash
69+
draft: false
70+
# Should always be reviewed by author to fix typos or other errors
71+
reviewers: ${{ github.actor }}
72+
# Set user triggering the workflow as author (default in action)
73+
author: ${{ github.actor }} <${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com>
74+
# Github Action as commit (explicit default)
75+
committer: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
76+
commit-message: "Update generated docs to ${{ env.PESTER }}"
77+
add-paths: |
78+
docs
79+
versioned_docs
80+
title: Update ${{ env.TITLE_DOCS_VERSION }}docs to Pester v${{ env.PESTER }}
81+
body: |
82+
Updates generated documentation using the specified Pester-version.
83+
84+
**Docs version:** ${{ env.DOCS }}
85+
**Pester version:** ${{ env.PESTER }}
86+
87+
| Documentation updated | Result |
88+
|-----------------------|--------|
89+
| Command Reference | ${{ steps.commands.outputs.updated }} |
90+
| PesterConfiguration section | ${{ steps.config.outputs.updated }} |
91+
92+
*PR created using 'Update Pester Docs' workflow*
93+
94+
- name: Output PR details
95+
if: ${{ steps.create-pr.outputs.pull-request-number }}
96+
run: |
97+
echo "### Update Pester Docs successfully completed! :rocket:" >> $GITHUB_STEP_SUMMARY
98+
echo "See [pull request #${{ steps.create-pr.outputs.pull-request-number }}](${{ steps.create-pr.outputs.pull-request-url }})" >> $GITHUB_STEP_SUMMARY

‎.vscode/launch.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@
55
"version": "0.2.0",
66
"configurations": [
77
{
8-
"command": "yarn start --poll",
8+
"command": "yarn start --host 0.0.0.0 --poll 1000",
99
"name": "Start Docusaurus (with polling)",
1010
"request": "launch",
1111
"type": "node-terminal"
1212
}
1313
]
14-
}
14+
}

‎docs/additional-resources/projects.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ import { columns, projects } from "./projects.table";
1515
/>
1616

1717
:::note Compatibility
18-
Many projects above were designed for earlier versions of Pester and might not yet be updated to support Pester v5.
18+
Many projects above were designed for earlier versions of Pester and might not yet be updated to support Pester v5 and later.
1919
:::
2020

2121
<PesterDataButton

‎docs/assertions/assertions.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: assertions
3-
title: Assertion Reference
3+
title: Assertion Reference (v4/v5)
44
description: Introduction to the built-in assertion operators in Pester to get you started with the most common scenarios
55
---
66

‎docs/assertions/should-command.mdx

+123-1
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,130 @@
11
---
22
title: Should
3-
description: Introduction to the Should command that's used to define assertions that fail or pass the test
3+
description: Introduction to the Pester's built-in Should assertions which can be used to fail or pass a test
44
---
55

6+
:::warning Work in progress 🛠️
7+
This page is incomplete and will be updated as we get closer to release.
8+
:::
9+
10+
## Overview
11+
12+
Pester includes a comprehensive set of assertions that you can use to either fail or pass a test.
13+
In fact, Pester v6 actually includes two sets of assertions:
14+
15+
- All new `Should-*` assertions introduced in Pester v6, e.g. `Should-BeString`, `Should-BeTrue` etc.
16+
- The `Should` command known from previous version of Pester, invoked using parameter sets like `Should -Be`, `Should -BeTrue` etc.
17+
18+
Both types of assertions are supported side-by-side in Pester v6, but we recommend your try out and migrate to the newer assertions.
19+
20+
## `Should-*` assertions (v6)
21+
22+
Pester v6 comes with a new set of `Should-*` assertions that have been built from the ground up.
23+
If you've previously tested the [`Assert`](https://github.com/nohwnd/assert)-module, these will be familiar.
24+
Check out Command Reference in the sidebar to read more about the new assertions, e.g. [`Should-BeString`](../commands/Should-BeString.mdx).
25+
26+
These new assertions are split these categories based on their usage:
27+
28+
- [Value](#value-assertions)
29+
- [Generic](#generic-value-assertions)
30+
- [Type specific](#type-specific-value-assertions)
31+
- [Collection](#collection-assertions)
32+
- Generic
33+
- Combinator
34+
35+
Each of these categories treats `$Actual` and `$Expected` values differently, to provide a consistent behavior when using the `|` syntax.
36+
37+
### Value vs. Collection assertions
38+
39+
The `$Actual` value can be provided by two syntaxes, either by pipeline (`|`) or by parameter (`-Actual`):
40+
41+
```powershell
42+
1 | Should-Be -Expected 1
43+
Should-Be -Actual 1 -Expected 1
44+
```
45+
46+
#### Using pipeline syntax
47+
48+
When using the pipeline syntax, PowerShell unwraps the input and we lose the type of the collection on the left side.
49+
We are provided with a collection that can be either $null, empty or have items.
50+
Notably, we cannot distinguish between a single value being provided, and an array of single item:
51+
52+
```powershell
53+
1 | Should-Be
54+
@(1) | Should-Be
55+
```
56+
57+
These will both be received by the assertion as `@(1)`.
58+
For this reason a value assertion will handle this as `1`, but a collection assertion will handle this input as `@(1)`.
59+
Another special case is `@()`. A value assertion will handle it as `$null`, but a collection assertion will handle it as `@()`.
60+
61+
`$null` remains `$null` in both cases.
62+
63+
```powershell
64+
# Should-Be is a value assertion:
65+
1 | Should-Be -Expected 1
66+
@(1) | Should-Be -Expected 1
67+
$null | Should-Be -Expected $null
68+
@() | Should-Be -Expected $null #< --- TODO: this is not the case right now, we special case this as empty array, but is that correct? it does not play well with the value and collection assertion, and we special case it just because we can.
69+
# $null | will give $local:input -> $null , and @() | will give $local:input -> @(), is that distinction important when we know that we will only check against values?
70+
71+
# This fails, because -Expected does not allow collections.
72+
@() | Should-Be -Expected @()
73+
74+
```powershell
75+
# Should-BeCollection is a collection assertion:
76+
1 | Should-BeCollection -Expected @(1)
77+
@(1) | Should-BeCollection -Expected @(1)
78+
@() | Should-BeCollection -Expected @()
79+
80+
# This fails, because -Expected requires a collection.
81+
$null | Should-BeCollection -Expected $null
82+
```
83+
84+
#### Using the -Actual syntax
85+
86+
The value provides to `-Actual`, is always exactly the same as provided.
87+
88+
```powershell
89+
Should-Be -Actual 1 -Expected 1
90+
91+
# This fails, Actual is collection, while expected is int.
92+
Should-Be -Actual @(1) -Expected 1
93+
```
94+
95+
### Value assertions
96+
97+
#### Generic value assertions
98+
99+
Generic value assertions, such as `Should-Be`, are for asserting on a single value. They behave quite similar to PowerShell operators, e.g. `Should-Be` maps to `-eq`.
100+
101+
The `$Expected` accepts any input that is not a collection.
102+
The type of `$Expected` determines the type to be used for the comparison.
103+
`$Actual` is automatically converted to that type.
104+
105+
```powershell
106+
1 | Should-Be -Expected $true
107+
Get-Process -Name Idle | Should-Be -Expected "System.Diagnostics.Process (Idle)"
108+
```
109+
110+
The assertions in the above examples will both pass:
111+
- `1` converts to `bool`-value as `$true`, which is the expected value.
112+
- `Get-Process` retrieves the `Idle` process (on Windows). This process object gets converted to `string` which is equal to the expected value.
113+
114+
#### Type specific value assertions
115+
116+
Type specific assertions are for asserting on a single value of a given type like `boolean`.
117+
These assertions take the advantage of being more specialized to provide a type specific functionality, such as `Should-BeString -IgnoreWhitespace`.
118+
119+
- `$Expected` accepts input that has the same type as the assertion type. E.g. `Should-BeString -Expected "my string"`.
120+
- `$Actual` accepts input that has the same type as the assertion type. The input is **not** converted to the destination type unless the assertion specifies it, e.g. `Should-BeFalsy` will convert to `bool`.
121+
122+
### Collection assertions
123+
124+
<mark>TODO</mark>
125+
126+
## `Should` (v4/v5)
127+
6128
`Should` is used to do an assertion that fails or passes the test.
7129

8130
An example of assertion is comparing two strings in case insensitive manner:

‎docs/commands/Add-ShouldOperator.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ function BeAwesome($ActualValue, [switch] $Negate) {
4949
}
5050
}
5151
52-
return New-Object psobject -Property @{
52+
return [PSCustomObject]@{
5353
Succeeded = $succeeded
5454
FailureMessage = $failureMessage
5555
}
@@ -166,4 +166,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
166166
167167
## VERSION
168168
169-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
169+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/AfterAll.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -107,4 +107,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
107107
108108
## VERSION
109109
110-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
110+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/AfterEach.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -104,4 +104,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
104104
105105
## VERSION
106106
107-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
107+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/BeforeAll.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -116,4 +116,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
116116

117117
## VERSION
118118

119-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
119+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/BeforeDiscovery.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -94,4 +94,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
9494
9595
## VERSION
9696
97-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
97+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/BeforeEach.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -101,4 +101,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
101101
102102
## VERSION
103103
104-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
104+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/Context.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -183,4 +183,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
183183
184184
## VERSION
185185
186-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
186+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/ConvertTo-JUnitReport.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -118,4 +118,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
118118
119119
## VERSION
120120
121-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
121+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/ConvertTo-NUnitReport.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -145,4 +145,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
145145
146146
## VERSION
147147
148-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
148+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/ConvertTo-Pester4Result.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -86,4 +86,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
8686
8787
## VERSION
8888
89-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
89+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/Describe.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -193,4 +193,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
193193
194194
## VERSION
195195
196-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
196+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/Export-JUnitReport.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -105,4 +105,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
105105
106106
## VERSION
107107
108-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
108+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

‎docs/commands/Export-NUnitReport.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -121,4 +121,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
121121
122122
## VERSION
123123
124-
*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
124+
*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*

0 commit comments

Comments
 (0)