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]>
pester · Nov 12, 2024 · 42e75ba · 42e75ba
1 parent dda61f2
commit 42e75ba
Show file tree

Hide file tree

Showing 170 changed files with 16,596 additions and 296 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -22,7 +22,7 @@
 
   // Use 'postCreateCommand' to run commands after the container is created.
   "postCreateCommand": "yarn install",
-  
+
   // Configure tool-specific properties.
   "customizations": {
     "vscode": {
@@ -33,7 +33,8 @@
         "dbaeumer.vscode-eslint",
         "unifiedjs.vscode-mdx",
         "ms-vscode.powershell",
-        "EditorConfig.EditorConfig"
+        "EditorConfig.EditorConfig",
+        "github.vscode-github-actions"
       ]
     }
   }

diff --git a/.editorconfig b/.editorconfig
@@ -9,5 +9,5 @@ trim_trailing_whitespace = true
 indent_size = 4
 max_line_length = 80
 
-[*.{json,ps1xml,props,xml,yaml,css}]
+[*.{js,jsx,ts,tsx,json,ps1xml,props,xml,yml,yaml,css}]
 indent_size = 2
diff --git a/.github/workflows/generate-pester-docs.yml b/.github/workflows/generate-pester-docs.yml
@@ -0,0 +1,98 @@
+name: Update Pester Docs
+run-name: Update Pester ${{ github.event.inputs.docs_version }} docs to v${{ github.event.inputs.pester_version }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      docs_version:
+        description: 'Docs version to update'
+        required: true
+        default: 'v5'
+        type: choice
+        options:
+          - Current
+          - v5
+          - v4
+      pester_version:
+        description: 'Pester version to use for docs generation. Format: 5.6.0 or 6.0.0-alpha1'
+        required: true
+        type: string
+
+jobs:
+  generate_docs:
+    name: Docs PR
+    runs-on: ubuntu-latest
+    env:
+      PESTER: ${{ github.event.inputs.pester_version }}
+      DOCS: ${{ github.event.inputs.docs_version }}
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Validate Pester version input
+        run: |
+          echo "Validating that the provided pester_version input is a valid version-format (x.y.z or x.y.z-suffix)"
+          echo "${{ env.PESTER }}" | grep -P '^\d+.\d+.\d+(?:-\w+)?$'
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      # This step will also install and import modules incl. selected Pester-version
+      - name: Update Command Reference
+        id: commands
+        shell: pwsh
+        run: |
+          ./generate-command-reference.ps1 -PesterVersion '${{ env.PESTER }}' -DocsVersion '${{ env.DOCS }}'
+
+          # Output if any files were modified
+          $updated = $null -ne (git status -s | Select-String '/commands/')
+          "updated=$updated" >> $env:GITHUB_OUTPUT
+      - name: Update PesterConfiguration docs
+        if: ${{ env.DOCS != 'v4' }}
+        id: config
+        shell: pwsh
+        run: |
+          ./generate-pesterconfiguration-docs.ps1 -PesterVersion '${{ env.PESTER }}' -Style Table -DocsVersion '${{ env.DOCS }}'
+
+          # Output if any files were modified
+          $updated = $null -ne (git status -s | Select-String '/usage/Configuration.mdx')
+          "updated=$updated" >> $env:GITHUB_OUTPUT
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@6d6857d36972b65feb161a90e484f2984215f83e # v6.0.5
+        id: create-pr
+        env:
+          PR_BRANCH: "docs-update/${{ env.DOCS }}-v${{ env.PESTER }}"
+          TITLE_DOCS_VERSION: "${{ env.DOCS != 'Current' && format('{0} ', env.DOCS) || '' }}"
+        with:
+          branch: ${{ env.PR_BRANCH }}
+          branch-suffix: short-commit-hash
+          draft: false
+          # Should always be reviewed by author to fix typos or other errors
+          reviewers: ${{ github.actor }}
+          # Set user triggering the workflow as author (default in action)
+          author: ${{ github.actor }} <${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com>
+          # Github Action as commit (explicit default)
+          committer: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
+          commit-message: "Update generated docs to ${{ env.PESTER }}"
+          add-paths: |
+            docs
+            versioned_docs
+          title: Update ${{ env.TITLE_DOCS_VERSION }}docs to Pester v${{ env.PESTER }}
+          body: |
+            Updates generated documentation using the specified Pester-version.
+
+            **Docs version:** ${{ env.DOCS }}
+            **Pester version:** ${{ env.PESTER }}
+
+            | Documentation updated | Result |
+            |-----------------------|--------|
+            | Command Reference | ${{ steps.commands.outputs.updated }} |
+            | PesterConfiguration section | ${{ steps.config.outputs.updated }} |
+
+            *PR created using 'Update Pester Docs' workflow*
+
+      - name: Output PR details
+        if: ${{ steps.create-pr.outputs.pull-request-number }}
+        run: |
+          echo "### Update Pester Docs successfully completed! :rocket:" >> $GITHUB_STEP_SUMMARY
+          echo "See [pull request #${{ steps.create-pr.outputs.pull-request-number }}](${{ steps.create-pr.outputs.pull-request-url }})" >> $GITHUB_STEP_SUMMARY
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,10 +5,10 @@
     "version": "0.2.0",
     "configurations": [
         {
-            "command": "yarn start --poll",
+            "command": "yarn start --host 0.0.0.0 --poll 1000",
             "name": "Start Docusaurus (with polling)",
             "request": "launch",
             "type": "node-terminal"
         }
     ]
-}
+}
diff --git a/docs/additional-resources/projects.mdx b/docs/additional-resources/projects.mdx
@@ -15,7 +15,7 @@ import { columns, projects } from "./projects.table";
 />
 
 :::note Compatibility
-Many projects above were designed for earlier versions of Pester and might not yet be updated to support Pester v5.
+Many projects above were designed for earlier versions of Pester and might not yet be updated to support Pester v5 and later.
 :::
 
 <PesterDataButton

diff --git a/docs/assertions/assertions.mdx b/docs/assertions/assertions.mdx
@@ -1,6 +1,6 @@
 ---
 id: assertions
-title: Assertion Reference
+title: Assertion Reference (v4/v5)
 description: Introduction to the built-in assertion operators in Pester to get you started with the most common scenarios
 ---
 

diff --git a/docs/assertions/should-command.mdx b/docs/assertions/should-command.mdx
@@ -1,8 +1,130 @@
 ---
 title: Should
-description: Introduction to the Should command that's used to define assertions that fail or pass the test
+description: Introduction to the Pester's built-in Should assertions which can be used to fail or pass a test
 ---
 
+:::warning Work in progress 🛠️
+This page is incomplete and will be updated as we get closer to release.
+:::
+
+## Overview
+
+Pester includes a comprehensive set of assertions that you can use to either fail or pass a test.
+In fact, Pester v6 actually includes two sets of assertions:
+
+- All new `Should-*` assertions introduced in Pester v6, e.g. `Should-BeString`, `Should-BeTrue` etc.
+- The `Should` command known from previous version of Pester, invoked using parameter sets like `Should -Be`, `Should -BeTrue` etc.
+
+Both types of assertions are supported side-by-side in Pester v6, but we recommend your try out and migrate to the newer assertions.
+
+## `Should-*` assertions (v6)
+
+Pester v6 comes with a new set of `Should-*` assertions that have been built from the ground up.
+If you've previously tested the [`Assert`](https://github.com/nohwnd/assert)-module, these will be familiar.
+Check out Command Reference in the sidebar to read more about the new assertions, e.g. [`Should-BeString`](../commands/Should-BeString.mdx).
+
+These new assertions are split these categories based on their usage:
+
+- [Value](#value-assertions)
+  - [Generic](#generic-value-assertions)
+  - [Type specific](#type-specific-value-assertions)
+- [Collection](#collection-assertions)
+  - Generic
+  - Combinator
+
+Each of these categories treats `$Actual` and `$Expected` values differently, to provide a consistent behavior when using the `|` syntax.
+
+### Value vs. Collection assertions
+
+The `$Actual` value can be provided by two syntaxes, either by pipeline (`|`) or by parameter (`-Actual`):
+
+```powershell
+1 | Should-Be -Expected 1
+Should-Be -Actual 1 -Expected 1
+```
+
+#### Using pipeline syntax
+
+When using the pipeline syntax, PowerShell unwraps the input and we lose the type of the collection on the left side.
+We are provided with a collection that can be either $null, empty or have items.
+Notably, we cannot distinguish between a single value being provided, and an array of single item:
+
+```powershell
+1 | Should-Be
+@(1) | Should-Be
+```
+
+These will both be received by the assertion as `@(1)`.
+For this reason a value assertion will handle this as `1`, but a collection assertion will handle this input as `@(1)`.
+Another special case is `@()`. A value assertion will handle it as `$null`, but a collection assertion will handle it as `@()`.
+
+`$null` remains `$null` in both cases.
+
+```powershell
+# Should-Be is a value assertion:
+1 | Should-Be -Expected 1
+@(1) | Should-Be -Expected 1
+$null | Should-Be -Expected $null
+@() | 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.
+# $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?
+
+# This fails, because -Expected does not allow collections.
+@() | Should-Be -Expected @()
+
+```powershell
+# Should-BeCollection is a collection assertion:
+1 | Should-BeCollection -Expected @(1)
+@(1) | Should-BeCollection -Expected @(1)
+@() | Should-BeCollection -Expected @()
+
+# This fails, because -Expected requires a collection.
+$null | Should-BeCollection -Expected $null
+```
+
+#### Using the -Actual syntax
+
+The value provides to `-Actual`, is always exactly the same as provided.
+
+```powershell
+Should-Be -Actual 1 -Expected 1
+
+# This fails, Actual is collection, while expected is int.
+Should-Be -Actual @(1) -Expected 1
+```
+
+### Value assertions
+
+#### Generic value assertions
+
+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`.
+
+The `$Expected` accepts any input that is not a collection.
+The type of `$Expected` determines the type to be used for the comparison.
+`$Actual` is automatically converted to that type.
+
+```powershell
+1 | Should-Be -Expected $true
+Get-Process -Name Idle | Should-Be -Expected "System.Diagnostics.Process (Idle)"
+```
+
+The assertions in the above examples will both pass:
+- `1` converts to `bool`-value as `$true`, which is the expected value.
+- `Get-Process` retrieves the `Idle` process (on Windows). This process object gets converted to `string` which is equal to the expected value.
+
+#### Type specific value assertions
+
+Type specific assertions are for asserting on a single value of a given type like `boolean`.
+These assertions take the advantage of being more specialized to provide a type specific functionality, such as `Should-BeString -IgnoreWhitespace`.
+
+- `$Expected` accepts input that has the same type as the assertion type. E.g. `Should-BeString -Expected "my string"`.
+- `$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`.
+
+### Collection assertions
+
+<mark>TODO</mark>
+
+## `Should` (v4/v5)
+
 `Should` is used to do an assertion that fails or passes the test.
 
 An example of assertion is comparing two strings in case insensitive manner:

diff --git a/docs/commands/Add-ShouldOperator.mdx b/docs/commands/Add-ShouldOperator.mdx
@@ -49,7 +49,7 @@ function BeAwesome($ActualValue, [switch] $Negate) {
         }
     }
 
-    return New-Object psobject -Property @{
+    return [PSCustomObject]@{
         Succeeded      = $succeeded
         FailureMessage = $failureMessage
     }
@@ -166,4 +166,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/AfterAll.mdx b/docs/commands/AfterAll.mdx
@@ -107,4 +107,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/AfterEach.mdx b/docs/commands/AfterEach.mdx
@@ -104,4 +104,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/BeforeAll.mdx b/docs/commands/BeforeAll.mdx
@@ -116,4 +116,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/BeforeDiscovery.mdx b/docs/commands/BeforeDiscovery.mdx
@@ -94,4 +94,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/BeforeEach.mdx b/docs/commands/BeforeEach.mdx
@@ -101,4 +101,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/Context.mdx b/docs/commands/Context.mdx
@@ -183,4 +183,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/ConvertTo-JUnitReport.mdx b/docs/commands/ConvertTo-JUnitReport.mdx
@@ -118,4 +118,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/ConvertTo-NUnitReport.mdx b/docs/commands/ConvertTo-NUnitReport.mdx
@@ -145,4 +145,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/ConvertTo-Pester4Result.mdx b/docs/commands/ConvertTo-Pester4Result.mdx
@@ -86,4 +86,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/Describe.mdx b/docs/commands/Describe.mdx
@@ -193,4 +193,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/Export-JUnitReport.mdx b/docs/commands/Export-JUnitReport.mdx
@@ -105,4 +105,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*
diff --git a/docs/commands/Export-NUnitReport.mdx b/docs/commands/Export-NUnitReport.mdx
@@ -121,4 +121,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## VERSION
 
-*This page was generated using comment-based help in [Pester 5.6.0](https://github.com/pester/pester).*
+*This page was generated using comment-based help in [Pester 6.0.0-alpha1](https://github.com/pester/pester).*