I spent a lot of time trying to figure out how to do something pretty simple:

        Mock Copy-Item {
            $originalCopyItem = Get-Command Copy-Item -CommandType Cmdlet
            & $originalCopyItem @PesterBoundParameters
        }

There are actually two things here that I think should be documented:

1. How to mock something, but still call the original something from within the mock; and
2. How to generically forward parameters to that original thing (@PesterBoundParameters).

While not needed for most mocks, this is a valuable technique, and deserves to be mentioned somewhere.

IMPORTANT

Please do NOT provide feedback here but instead on the theme preview PR at #29.

Theme specifications

https://v2.docusaurus.io/docs/styling-layout

General

Most important: similar to https://powershellgallery.com, at least applied to:

• color palette
• typography (UNSURE, psgallery fonts seem small, perhaps test-run)
• links
• navbar (blue #004880, not black)
• landing page hero
• content navigation (left sidebar, right sidebar)

Logo

• current logo including blue background looks good on black (navbar) background
• however, logo would look better in the theme without the blue background
• there is no .svg logo yet
  • do we really need svg and if so, why?
  • do we have the (.ai?) source files and if so, can they be used to create an svg? YES: #28 (comment)

Navbar

• should not change color when switching between dark mode

Landing Page

In general, similar to https://componentkit.org/ with the following notes:

• hero must have config based text and (svg?) image
• sub heros must have config based text and (svg?) images
• sub hero images look 'n' feel: similar to componentkit.org

Sponsors:

Instead of the Also available component on componentkit.org's landing page:

• a component to list opencollective.com sponsors

See:

• https://docs.opencollective.com/help/collectives/data-export
• https://opencollective.com/pester/contributors.svg
• https://opencollective.com/pester/organizations.svg

Syntax highlighting

• might need to be updated to match new typography Dropped as it inherits main theme

Footer

• update Community row with these socials
• replace Social row with Sponsor row to include links to OpenCollective, Github, etc

Did we miss anything?

Not specified before but yes, we forgot about the styling of the sortable markdown tables, used a lot under the Additional Resources section. If possible:

• make left column width max out (to prevent weird looking tables)
• some pointers/help on making the sort arrow visible

Bonus features (thanks @lex111)

• make landing page look cool on mobile too
• add sort icons to the tables

Installing from sources is incorrect for v5. It states that you can just download the Pester source and run it build it requires build. We can either:

• redirect it to downloading and extracting the psgallery nuget package
• remove that section entirely
• redirect to build instructions
• start publishing the module as zip

The first options is probably the best and I already checked that you can just Manual Download and unzip.

Under this link, shouldn't it be under "Or to update"?

choco upgrade Pester

instead of

choco install Pester

?

• Pester version: 5.1.0
• Function: Add-ShouldOperator

General summary of the issue

The documentation for Add-ShouldOperator indicates that the -Test parameter is supposed to receive a [ScriptBlock] containing the assertion to be run. However, there isn't any documentation on how to pass in test/reference values, etc. etc. (either from the pipeline or via named/positional parameters).

I was able to find a blog post that partially covered it in passing, but some in-module documentation would be really useful here.

Some questions that a user should be able to answer from the documentation (either via examples or from the text itself) are:

• How can I define a parameter in my test block such-that it's exposed to users when they call it via Should?
• Are there any required/special-use parameters (e.g. $Negate)?
• Are there any special steps required for receiving pipeline input from Should?

The Broken Link Checker detected one or more ⚰️ links on the pester.dev website.

Please review the results and resolve as appropriate.

Pro-Tip: use search filter ─BROKEN─ to highlight failures

TODO list for when we seek help from someone who can style Docusaurus:

Caution block that is emited when

:::caution
blah blah
:::

is used in the .mdx has poor contrast.

^^^
Nothing wrong with code, but these blocks should probably have more contrast. Can be hard to read in light mode.

Originally posted by @fflaten in #70 (comment)

Switching to dark mode not all items are switched, (this started happening after the version dropdown).

Pester logo turns black on hover.

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://pester.dev.

View results

Use search filter ─BROKEN─ to highlight failures

I am getting the error below pointed to function GetHTTPHeader ($url)

ParameterBindingException: Missing an argument for parameter 'InFile'. Specify a parameter of type 'System.String' and try again.

https://pester.dev/docs/usage/mocking#mocking-a-native-application

Describe 'Mocking native commands' {
    It "Mock bash" {
        function GetHTTPHeader ($url) {
            & curl --url $url `
            -I
        }

        Mock curl { Write-Warning "$args" }

        GetHTTPHeader -url "https://google.com"

        Should -Invoke -CommandName "curl" -Exactly -Times 1 -ParameterFilter { $args[0] -eq '--url' -and $args[1] -eq 'https://google.com'}

        # By converting args to string (will concat using space by default) you can match a pattern if order might change. remember linebreaks
        Should -Invoke -CommandName "curl" -Exactly -Times 1 -ParameterFilter { "$args" -match "--url https://google.com -I" }
    }
}

How can I fix this?

Pester version: 5.3.1

The Broken Link Checker found ⚰️ links on the pester.dev website.

View results

@nohwnd, I (finally) figured out how to prevent Netlify from altering the docusaurus links (which is now causing causing 301 redirects and 404 problems).

See facebook/docusaurus#2394 (comment)

Changes settings take effect immediately, After changing, try by browsing directly to e.g. https://pester.dev/docs/commands/Add-AssertionOperator (the casing should not change to lower).

Looks like these are missing another \ escape character

. "$here$sut" instead of . "$here$sut"

I must be missing something obvious. None of the quick start guides in these two locations work.

https://github.com/pester/Pester
https://pester.dev/docs/quick-start

Output

PS F:\git\kanopy\Scripts> Invoke-Pester  .\Get-Planet.Tests.ps1

 [-] Error occurred in test script 'F:\git\kanopy\Scripts\Get-Planet.Tests.ps1' 17ms
   RuntimeException: The BeforeAll command may only be used inside a Describe block.
   at Assert-DescribeInProgress, C:\Program Files\WindowsPowerShell\Modules\Pester\3.4.0\Functions\Describe.ps1: line 125
   at BeforeAll, C:\Program Files\WindowsPowerShell\Modules\Pester\3.4.0\Functions\SetupTeardown.ps1: line 56
   at <ScriptBlock>, F:\git\kanopy\Scripts\Get-Planet.Tests.ps1: line 1
   at <ScriptBlock>, C:\Program Files\WindowsPowerShell\Modules\Pester\3.4.0\Pester.psm1: line 297
   at Invoke-Pester, C:\Program Files\WindowsPowerShell\Modules\Pester\3.4.0\Pester.psm1: line 310
   at <ScriptBlock>, <No file>: line 1
Tests completed in 17ms
Passed: 0 Failed: 1 Skipped: 0 Pending: 0 Inconclusive: 0

Get-Planet.Tests.ps1

BeforeAll {
    # your function
    function Get-Planet ([string]$Name='*')
    {
        $planets = @(
            @{ Name = 'Mercury' }
            @{ Name = 'Venus'   }
            @{ Name = 'Earth'   }
            @{ Name = 'Mars'    }
            @{ Name = 'Jupiter' }
            @{ Name = 'Saturn'  }
            @{ Name = 'Uranus'  }
            @{ Name = 'Neptune' }
        ) | foreach { [PSCustomObject]$_ }

        $planets | where { $_.Name -like $Name }
    }
}

# Pester tests
Describe 'Get-Planet' {
  It "Given no parameters, it lists all 8 planets" {
    $allPlanets = Get-Planet
    $allPlanets.Count | Should -Be 8
  }

  Context "Filtering by Name" {
    It "Given valid -Name '<Filter>', it returns '<Expected>'" -TestCases @(
      @{ Filter = 'Earth'; Expected = 'Earth' }
      @{ Filter = 'ne*'  ; Expected = 'Neptune' }
      @{ Filter = 'ur*'  ; Expected = 'Uranus' }
      @{ Filter = 'm*'   ; Expected = 'Mercury', 'Mars' }
    ) {
      param ($Filter, $Expected)

      $planets = Get-Planet -Name $Filter
      $planets.Name | Should -Be $Expected
    }

    It "Given invalid parameter -Name 'Alpha Centauri', it returns `$null" {
      $planets = Get-Planet -Name 'Alpha Centauri'
      $planets | Should -Be $null
    }
  }
}

Pages contains multiple links to the same page which does not really make sense and makes reading the docs more difficult/distracting.

An example: Invoke-Pester is referenced as a link on the quick-start page multiple times.

TestDrive docs should make it clear that test drive is setup just once for the whole top level block, no matter if it is called Describe or Context, and is not setup for every block in the top level block.

Original issue:

The documentation could be clearer about this. (It explicitly says Context block when it's actually any nested Context or Describe block.)

Originally posted by @Axiometry in pester/Pester#1837 (comment)

If you copy paste the example on a ps1 file and invoke-pester it is looking for a file that does not exist. This is the example:

function Build ($version) {
    Write-Host "a build was run for version: $version"
}

function BuildIfChanged {
    $thisVersion = Get-Version
    $nextVersion = Get-NextVersion
    if ($thisVersion -ne $nextVersion) { Build $nextVersion }
    return $nextVersion
}

$here = Split-Path -Parent $MyInvocation.MyCommand.Path
$sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path) -replace '\.Tests\.', '.'
. "$here\$sut"

Describe "BuildIfChanged" {
    Context "When there are Changes" {
        Mock Get-Version {return 1.1}
        Mock Get-NextVersion {return 1.2}
        Mock Build {} -Verifiable -ParameterFilter {$version -eq 1.2}

        $result = BuildIfChanged

        It "Builds the next version" {
            Assert-VerifiableMocks
        }
        It "returns the next version number" {
            $result | Should Be 1.2
        }
    }
    Context "When there are no Changes" {
        Mock Get-Version { return 1.1 }
        Mock Get-NextVersion { return 1.1 }
        Mock Build {}

        $result = BuildIfChanged

        It "Should not build the next version" {
            Assert-MockCalled Build -Times 0 -ParameterFilter {$version -eq 1.1}
        }
    }
}

I think it has not been yet migrated to Pester5. These are the minimum changes I had to apply to make it work:

BeforeAll{
    function Build ($version) {
        Write-Host "a build was run for version: $version"
    }
    
    function Get-Version{
        return 'Version'
    }
    
    function Get-NextVersion {
        return 'NextVersion'
    }
    
    function BuildIfChanged {
        $thisVersion = Get-Version
        $nextVersion = Get-NextVersion
        if ($thisVersion -ne $nextVersion) { Build $nextVersion }
        return $nextVersion
    }
}

Describe "BuildIfChanged" {
    Context "When there are Changes" {
        BeforeEach{
            Mock Get-Version {return 1.1}
            Mock Get-NextVersion {return 1.2}
            Mock Build {} -Verifiable -ParameterFilter {$version -eq 1.2}
    
            $result = BuildIfChanged
        }

        It "Builds the next version" {
            Assert-VerifiableMock
        }
        
        It "returns the next version number" {
            $result | Should -Be 1.2
        }
    }
    Context "When there are no Changes" {
        BeforeEach{
            Mock Get-Version { return 1.1 }
            Mock Get-NextVersion { return 1.1 }
            Mock Build {}
    
            $result = BuildIfChanged
        }

        It "Should not build the next version" {
            Assert-MockCalled Build -Times 0 -ParameterFilter {$version -eq 1.1}
        }
    }
}

They are on this PR #66

Thanks for your work! :)

@bravo-kernel I'd like to rename master to main to keep up with the new naming standards. I know that I need to change it in Netlify, and there are bunch of mentions in the repo as well.

Is there anything else that I don't see?

Found Broken Links

Please review and fix.

The Pester Github Repo Wiki page for the Should assertion presently points to https://pester.dev/docs/usage/assertions which leads to a 404.

This link is no longer valid, it should (haha) instead, point to https://pester.dev/docs/assertions/should-command

The Broken Link Checker found ⚰️ links on the pester.dev website.

View results

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://pester.dev.

View results

Use search filter ─BROKEN─ to highlight failures

Currently, the website pages/markdown files are missing front matter variables description and keywords which will be used as html meta tags.

Both variables should be added so the markdown looks similar to:

---
id: quick-start
title: Quick Start
sidebar_label: Quick Start
description: Some appropriate page-specific description
keywords:
  - Pester
  - Powershell
  - etc.
  - etc.
---

All,

I was thinking that perhaps I should add a version of my "Beyond Pester 101" and "Beyond Pester 102" talks into this docs repo. However before I start (as it would be a large piece of work) I'd like to make sure it would sit in the vision that the Pester team has for this Docs repo.

Does this sound like something the team would find useful?

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://pester.dev.

View results

Use search filter ─BROKEN─ to highlight failures

Hi Team,
As mentioned in https://pester.dev/docs/introduction/installation , the deletion of existing version needs to be done to install the new version. The code for deleting the current one works but the installation fails. There is some fault in the code with pester. Install-Module Pester -Force -SkipPublisherCheck used to work earlier, also the update-module pester, almost a month ago, now it says, pester is not installed using install-module and cannot be updated. Its so annoying. I currently have 3.4.0 version and need 4.10.0. Suggest me how to.Please reply.

After deletion happens through
*$module = "C:\Program Files\WindowsPowerShell\Modules\Pester"
takeown /F $module /A /R
icacls $module /reset
icacls $module /grant "S-1-5-32-544:F" /inheritance:d /T
Remove-Item -Path $module -Recurse -Force -Confirm:$false
Install-Module -Name Pester -Force

It gives me this error and results in not having pester of any version because it deletes existing one and doesn't install new version

Thank you.

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://pester.dev.

View results

Use search filter ─BROKEN─ to highlight failures

File changes

The generate-command-reference.ps1 script:

• only generates the .mdx files and the docusaurus.sidebar.js file found in this docs\command directory
• then replaces the existing content of above folder with the newly generated mdx files
• only mdx file changes will appear in the PR

The process

We already have a working process, it just needs some fine tuning IMO.

1. Do not move generate script out of the pester/docs repo
2. Update the generate script so it no longer uses a fixed Pester version but either:
   • uses latest Pester version (by default)
   • uses a specified Pester version if parameter is given (e.g. -PesterVersion)
3. Use that updated script to implement CI/CD

CI/CD

A solution was discussed earlier, something like:

1. pester/pester repo creates a new release
2. pester/pester release triggers a github action in the pester/docs repo
3. that pester/docs action uses the generate script to:
   • regenerate the mdx files using LATEST pester version
   • create a PR with the mdx file changes

This way everything stays as it is now with wesbite-previews etc. and.. no need to move pester-docs-related logic into the pester/pester repo.

Does that make sense?

Originally posted by @bravo-kernel in pester/Pester#1798 (comment)

The website pages currently contain a lot of migrated links in the following non-markdown-compatible (wiki-specific) format:

See the documentation for [[Invoke-Pester]].

These should all be updated to use valid markdown links similar to:

See the documentation for [Invoke-Pester](../commands/Invoke-Pester).

Why are the pester docs recommending a practice that almost nobody uses (not even Pester itself) of putting the test files in the source folder next to the function file? I assume this recommendation comes from writing tests for scripts vs. modules, but I don't know -- I can't find anyone that does that...

By far the most common practice is to create test folders...

• https://github.com/PowerShell/Crescendo/tree/master/Microsoft.PowerShell.Crescendo/test
• https://github.com/pester/Pester/tree/master/tst
• https://github.com/PowerShell/SecretManagement/tree/master/test
• https://github.com/PoshCode/ModuleBuilder/tree/main/Tests
• https://github.com/psake/psake/tree/master/tests

The Broken Link Checker found ⚰️ links on the pester.dev website.

View results

We might want to add a page showing the difference in output verbosity and the future stacktrace verbosity.

IIRC this is only mentioned quickly in VSCode + Diagnostic-level in Troubleshooting.

Website Contains Broken Links

Broken Links Checker found ⚰️ links on https://pester.dev.

View results...

To run locally:

npx broken-link-checker https://pester.dev --ordered --recursive

• current default logo found in src/static/img/logo.svg
• related code in docusaurus.config

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://pester.dev.

View results

Use search filter ─BROKEN─ to highlight failures

Once the website is live we will:

1. need to apply for Algolia fully indexed search
2. activate the search within Docusaurus

More information on Algolia DocSearch

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://pester.dev.

View results

Use search filter ─BROKEN─ to highlight failures

The Broken Link Checker found ⚰️ links on the pester.dev website.

View results

Website Contains Broken Links

Broken Links Checker found ⚰️ links on https://pester.dev.

View results...

To run locally:

npx broken-link-checker https://pester.dev --ordered --recursive

Now Pester v5 is released, documentation is out of date for all commands:
https://github.com/pester/Pester/releases/tag/5.0.0

All pages in the Command Reference are auto-generated using the Alt3.Docusaurus.Powershell module.

Because it uses the Get-Help documentation produced by Pester as input, it is important to implement some sort of mechanism to keep the pages in-sync with the Pester module releases. One idea talked about creating some sort of "webhook" that triggers this repo once a new Pester version is released.

Good to Know

Powershell used to generate the current command reference pages:

$pesterArgs = @{
    Module = "Pester"
    DocsFolder = "docs"
    SideBar = "commands"
    Exclude = @(
      "Get-MockDynamicParameter"
      "Invoke-Mock"
      "SafeGetCommand"
      "Set-DynamicParameterVariable"
    )
    MetaDescription = 'Help page for the Powershell Pester "%1" command'
    MetaKeywords = @(
        "Powershell"
        "Pester"
        "Help"
        "Documentation"
    )
    EditUrl = 'null' # prevents `Edit this Page` button
    AppendMarkdown = "## EDIT THIS PAGE`n`nThis page was auto-generated using Pester's comment based help. To edit the content of this page, change the corresponding help in the [pester/Pester](https://github.com/pester/pester) repository. See our [contribution guide](https://github.com/pester/docs#contributing) for more information."
}

New-DocusaurusHelp @pesterArgs -Verbose

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://pester.dev.

View results

Use search filter ─BROKEN─ to highlight failures

v5 is a massive breaking change. Anyone with a sizeable body of v4 tests will not be able to migrate all at once, and may not even own the ability to migrate completely. For migration to be possible for such people, they need to know how to run v5 for 1%, 10% or 90% of their tests, and still be able to run the remainder with v4.

Tips needed:

1. How to install both v4 and v5 side-by-side, such that v4 is the default version
2. How to annotate v5 tests so that v5 is used automatically when they are run
   • Should also mention how to annotate v4 tests for clarity, but recognize that it may be impossible to change some legacy content

A focus on this scenario will improve v5 adoption dramatically. (speaking from experience on breaking changes in general, and the lack of tools for dealing with the move to v5 has also been an inhibiting factor for me personally)

Website Contains Broken Links

Broken Links Checker found ⚰️ links on https://pester.dev.

View results...

To run locally:

npx broken-link-checker https://pester.dev --ordered --recursive

The Command Reference pages are not displaying multi-line examples correctly as can be seen in this example:

Info

1. This issue is NOT caused by this repo
2. Cause and additional information can be found at alt3/Docusaurus.Powershell#14
3. Could be be solved there as well but ideally through this PlatyPS issue
4. Requires help ❤️

These three slogans are still Docusaurus defaults and need to be updated.

Code found in src/pages/index.js

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://pester.dev.

View results

Use search filter ─BROKEN─ to highlight failures

Location

https://pester-docs.netlify.app/docs/usage/data-driven-tests

• Pester version: 5.2.2

General summary of the issue

I'm trying to take a working copy of code (e.g. code from the documentation) and run this locally to test and tweak to help me understand how the data driven aspects of Pester behave (sometimes long documentation is harder to understand than getting hands on with things). Without Get-Emoji.ps1 it's not possible to run any of this because the function doesn't exist (obviously!). Please could this file be added to the documentation to download so we can import it? Thank you.

The only place i've been able to find -skip mentioned was in the command reference which is unhelpful. I'm interested if I can leverage this in my test cases, but I'm unclear on how I would use it, the issue where it was added pester/Pester#1266 and suggested pester/Pester#442 don't really talk about a working usage of it.

The auto-generated Command Reference pages use the Get-Help information produced by Pester. PlatyPS is used to make the first conversion to markdown, Alt3.Docusaurus.Powershell then enriches the markdown so it becomes compatible with Docusaurus.

The Pester sources may contain Get-Help .LINK sections which are converted to External Links as shown below:

As you can see there are currently two issues, to be fixed in the Pester source file:

1. the link to the wiki is no longer valid
2. the second link uses a wiki-specific ref that is no longer valid

Another issue that might occur in the source files is this example taken from https://github.com/pester/Pester/blob/master/Functions/Mock.ps1:

.LINK
Assert-MockCalled
Assert-VerifiableMock
Describe
Context
It
about_Should
about_Mocking

which leads to this funky link in the browser:

Should be fixed by creating separate .LINK entities as per the specification. E.g.

.LINK
    Assert-MockCalled

.LINK
    Assert-VerifiableMock

.LINK
    Describe

.LINK
    Context

.LINK
    It

.LINK
    about_Should

.LINK
    about_Mocking

Some of the mapping value between legacy and v5 regarding the code coverage documentation are wrong in the following link https://github.com/pester/Pester#legacy-interface.

Should I create a PR in this repo or in the Pester one?