From b302201e8a43dd6250b4112eacc9e0140e197ec4 Mon Sep 17 00:00:00 2001 From: fadwen <110697945+fadwen@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:29:54 +0000 Subject: [PATCH] chore: sync Copilot and Claude Code standards from standards repo --- .claude/commands/powershell-standards/.keep | 2 + .../powershell-standards/code-analysis.md | 20 - .../powershell-standards/create-module.md | 20 - .../powershell-standards/create-test.md | 20 - .../powershell-standards/create-workflow.md | 20 - .../powershell-standards/new-function.md | 20 - .../optimize-performance.md | 20 - .../performance-analysis.md | 20 - .../powershell-standards/scaffold-project.md | 20 - .../powershell-standards/security-review.md | 20 - .../validate-standards.md | 20 - .claude/rules/powershell-standards/analyze.md | 11 - .../architecturedesign.md | 11 - .claude/rules/powershell-standards/cicd.md | 13 - .../rules/powershell-standards/comments.md | 10 - .../community-standards.md | 11 - .../copilot-instructions.md | 6 +- .../powershell-standards/errorsandlogs.md | 10 - .claude/rules/powershell-standards/module.md | 12 - .claude/rules/powershell-standards/pester.md | 10 - .claude/rules/powershell-standards/platyps.md | 11 - .../powershell-standards/powershell-cicd.md | 12 + .../powershell-error-handling.md | 11 + .../powershell-functions.md | 11 + .../powershell-standards/powershell-help.md | 11 + .../powershell-modules.md | 11 + .../powershell-standards/powershell-pester.md | 10 + .../powershell-platyps.md | 10 + .../powershell-pull-requests.md | 5 + .../powershell-standards/powershell-readme.md | 10 + .../powershell-security.md | 11 + .../powershell-standards/powershell-style.md | 12 + .../powershell-version.md | 5 +- .../powershell-standards/pull-requests.md | 6 - .claude/rules/powershell-standards/readme.md | 11 - .../securitycompliance.md | 11 - .../powershell-standards/style-enforcement.md | 10 - .github/copilot-instructions.md | 968 +++---------- .github/instructions/analyze.instructions.md | 104 -- .../architecturedesign.instructions.md | 213 --- .github/instructions/cicd.instructions.md | 372 ----- .github/instructions/comments.instructions.md | 303 ---- .../community-standards.instructions.md | 220 --- .../errorsandlogs.instructions.md | 399 ------ .github/instructions/futureTODO.md | 86 -- .github/instructions/module.instructions.md | 883 ------------ .../pester-supporting-docs/assertion-guide.md | 509 +++---- .../cicd-integration.md | 1237 +++++------------ .../custom-assertions.md | 379 +++-- .../integration-test-template.md | 375 ++--- .../mocking-patterns.md | 1041 ++++---------- .../performance-test-template.md | 425 +----- .../pester-configuration.md | 1007 ++++---------- .../security-test-template.md | 595 +++----- .../pester-supporting-docs/test-data-guide.md | 831 ++++------- .../pester-supporting-docs/test-execution.md | 964 +++---------- .../test-structure-guide.md | 454 +++--- .../unit-test-template.md | 417 +++--- .../pester-supporting-docs/v6-migration.md | 715 ++++------ .github/instructions/pester.instructions.md | 263 ---- .github/instructions/platyps.instructions.md | 454 ------ .../powershell-cicd.instructions.md | 206 +++ .../powershell-error-handling.instructions.md | 253 ++++ .../powershell-functions.instructions.md | 311 +++++ .../powershell-help.instructions.md | 160 +++ .../powershell-modules.instructions.md | 269 ++++ .../powershell-pester.instructions.md | 383 +++++ .../powershell-platyps.instructions.md | 312 +++++ .../powershell-pull-requests.instructions.md | 157 +++ .../powershell-readme.instructions.md | 72 + .../powershell-security.instructions.md | 140 ++ .../powershell-style.instructions.md | 276 ++++ .../powershell-version.instructions.md | 471 +++---- .../pull-requests.instructions.md | 153 -- .github/instructions/readme.instructions.md | 533 ------- .../securitycompliance.instructions.md | 746 ---------- .../style-enforcement.instructions.md | 95 -- .github/prompts/README.md | 17 + .github/prompts/code-analysis.prompt.md | 77 - .github/prompts/create-module.prompt.md | 38 - .github/prompts/create-test.prompt.md | 80 -- .github/prompts/create-workflow.prompt.md | 30 - .github/prompts/new-function.prompt.md | 38 - .../prompts/optimize-performance.prompt.md | 41 - .../prompts/performance-analysis.prompt.md | 56 - .github/prompts/scaffold-project.prompt.md | 28 - .github/prompts/security-review.prompt.md | 48 - .github/prompts/validate-standards.prompt.md | 42 - .../Examples/Basic-Function-Example.ps1 | 330 ++--- .../Configuration/DefaultConfiguration.psd1 | 142 +- .../Classes/ExampleClass.ps1 | 20 +- .../ModuleExample.psd1 | 33 +- .../ModuleExample.psm1 | 65 +- .../Private/Connect-ExampleService.ps1 | 53 +- .../Private/Get-ExampleServiceStatus.ps1 | 55 +- .../Public/Get-ExampleData.ps1 | 40 +- .../Module-Structure-Example/README.md | 188 ++- .../Tests/ModuleExample.Tests.ps1 | 323 ++--- .../docs/ModuleExample/Get-ExampleData.md | 86 +- .../docs/ModuleExample/ModuleExample.md | 6 +- .../en-US/ModuleExample-Help.xml | 95 +- .../en-US/about_ModuleExample.help.txt | 81 +- powershell-standards/Examples/README.md | 115 +- .../Basic-Function-Example.Tests.ps1 | 238 ++++ .../Testing-Examples/Basic-Function.Tests.ps1 | 181 --- 105 files changed, 6824 insertions(+), 13937 deletions(-) create mode 100644 .claude/commands/powershell-standards/.keep delete mode 100644 .claude/commands/powershell-standards/code-analysis.md delete mode 100644 .claude/commands/powershell-standards/create-module.md delete mode 100644 .claude/commands/powershell-standards/create-test.md delete mode 100644 .claude/commands/powershell-standards/create-workflow.md delete mode 100644 .claude/commands/powershell-standards/new-function.md delete mode 100644 .claude/commands/powershell-standards/optimize-performance.md delete mode 100644 .claude/commands/powershell-standards/performance-analysis.md delete mode 100644 .claude/commands/powershell-standards/scaffold-project.md delete mode 100644 .claude/commands/powershell-standards/security-review.md delete mode 100644 .claude/commands/powershell-standards/validate-standards.md delete mode 100644 .claude/rules/powershell-standards/analyze.md delete mode 100644 .claude/rules/powershell-standards/architecturedesign.md delete mode 100644 .claude/rules/powershell-standards/cicd.md delete mode 100644 .claude/rules/powershell-standards/comments.md delete mode 100644 .claude/rules/powershell-standards/community-standards.md delete mode 100644 .claude/rules/powershell-standards/errorsandlogs.md delete mode 100644 .claude/rules/powershell-standards/module.md delete mode 100644 .claude/rules/powershell-standards/pester.md delete mode 100644 .claude/rules/powershell-standards/platyps.md create mode 100644 .claude/rules/powershell-standards/powershell-cicd.md create mode 100644 .claude/rules/powershell-standards/powershell-error-handling.md create mode 100644 .claude/rules/powershell-standards/powershell-functions.md create mode 100644 .claude/rules/powershell-standards/powershell-help.md create mode 100644 .claude/rules/powershell-standards/powershell-modules.md create mode 100644 .claude/rules/powershell-standards/powershell-pester.md create mode 100644 .claude/rules/powershell-standards/powershell-platyps.md create mode 100644 .claude/rules/powershell-standards/powershell-pull-requests.md create mode 100644 .claude/rules/powershell-standards/powershell-readme.md create mode 100644 .claude/rules/powershell-standards/powershell-security.md create mode 100644 .claude/rules/powershell-standards/powershell-style.md delete mode 100644 .claude/rules/powershell-standards/pull-requests.md delete mode 100644 .claude/rules/powershell-standards/readme.md delete mode 100644 .claude/rules/powershell-standards/securitycompliance.md delete mode 100644 .claude/rules/powershell-standards/style-enforcement.md delete mode 100644 .github/instructions/analyze.instructions.md delete mode 100644 .github/instructions/architecturedesign.instructions.md delete mode 100644 .github/instructions/cicd.instructions.md delete mode 100644 .github/instructions/comments.instructions.md delete mode 100644 .github/instructions/community-standards.instructions.md delete mode 100644 .github/instructions/errorsandlogs.instructions.md delete mode 100644 .github/instructions/futureTODO.md delete mode 100644 .github/instructions/module.instructions.md delete mode 100644 .github/instructions/pester.instructions.md delete mode 100644 .github/instructions/platyps.instructions.md create mode 100644 .github/instructions/powershell-cicd.instructions.md create mode 100644 .github/instructions/powershell-error-handling.instructions.md create mode 100644 .github/instructions/powershell-functions.instructions.md create mode 100644 .github/instructions/powershell-help.instructions.md create mode 100644 .github/instructions/powershell-modules.instructions.md create mode 100644 .github/instructions/powershell-pester.instructions.md create mode 100644 .github/instructions/powershell-platyps.instructions.md create mode 100644 .github/instructions/powershell-pull-requests.instructions.md create mode 100644 .github/instructions/powershell-readme.instructions.md create mode 100644 .github/instructions/powershell-security.instructions.md create mode 100644 .github/instructions/powershell-style.instructions.md delete mode 100644 .github/instructions/pull-requests.instructions.md delete mode 100644 .github/instructions/readme.instructions.md delete mode 100644 .github/instructions/securitycompliance.instructions.md delete mode 100644 .github/instructions/style-enforcement.instructions.md create mode 100644 .github/prompts/README.md delete mode 100644 .github/prompts/code-analysis.prompt.md delete mode 100644 .github/prompts/create-module.prompt.md delete mode 100644 .github/prompts/create-test.prompt.md delete mode 100644 .github/prompts/create-workflow.prompt.md delete mode 100644 .github/prompts/new-function.prompt.md delete mode 100644 .github/prompts/optimize-performance.prompt.md delete mode 100644 .github/prompts/performance-analysis.prompt.md delete mode 100644 .github/prompts/scaffold-project.prompt.md delete mode 100644 .github/prompts/security-review.prompt.md delete mode 100644 .github/prompts/validate-standards.prompt.md create mode 100644 powershell-standards/Examples/Testing-Examples/Basic-Function-Example.Tests.ps1 delete mode 100644 powershell-standards/Examples/Testing-Examples/Basic-Function.Tests.ps1 diff --git a/.claude/commands/powershell-standards/.keep b/.claude/commands/powershell-standards/.keep new file mode 100644 index 0000000..ff5471a --- /dev/null +++ b/.claude/commands/powershell-standards/.keep @@ -0,0 +1,2 @@ +This folder is kept so that sync workflows written for earlier versions still find it. +The prompt files it mirrored were replaced by skills. diff --git a/.claude/commands/powershell-standards/code-analysis.md b/.claude/commands/powershell-standards/code-analysis.md deleted file mode 100644 index 4a2f7e7..0000000 --- a/.claude/commands/powershell-standards/code-analysis.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: 'Comprehensive code quality analysis with expert-reviewed standards' -argument-hint: '[file-or-code]' ---- - -Run the shared prompt in @.github/prompts/code-analysis.prompt.md. - -That file is written for GitHub Copilot Chat and is the only copy of the prompt. Apply it here as -follows: - -- Ignore its `agent` and `tools` frontmatter. -- `${input:NAME:...}` is a value to collect. Take it from the arguments below when they supply it, - otherwise ask before starting. The text after the name lists the choices or a placeholder, and a - final segment after another colon is the default. -- `${selection}` is the code the user selected or named in the arguments. `${fileBasename}` is the - file that code lives in, and `${workspaceFolderBasename}` is the repository folder name. -- If the contents of the prompt file are not shown above, read `.github/prompts/code-analysis.prompt.md` - before doing anything else. - -Arguments: $ARGUMENTS diff --git a/.claude/commands/powershell-standards/create-module.md b/.claude/commands/powershell-standards/create-module.md deleted file mode 100644 index 2bcf554..0000000 --- a/.claude/commands/powershell-standards/create-module.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: 'Generates complete PowerShell module structure' -argument-hint: '[moduleName] [purpose] [audience] [complexity]' ---- - -Run the shared prompt in @.github/prompts/create-module.prompt.md. - -That file is written for GitHub Copilot Chat and is the only copy of the prompt. Apply it here as -follows: - -- Ignore its `agent` and `tools` frontmatter. -- `${input:NAME:...}` is a value to collect. Take it from the arguments below when they supply it, - otherwise ask before starting. The text after the name lists the choices or a placeholder, and a - final segment after another colon is the default. -- `${selection}` is the code the user selected or named in the arguments. `${fileBasename}` is the - file that code lives in, and `${workspaceFolderBasename}` is the repository folder name. -- If the contents of the prompt file are not shown above, read `.github/prompts/create-module.prompt.md` - before doing anything else. - -Arguments: $ARGUMENTS diff --git a/.claude/commands/powershell-standards/create-test.md b/.claude/commands/powershell-standards/create-test.md deleted file mode 100644 index be314e7..0000000 --- a/.claude/commands/powershell-standards/create-test.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: 'Generate comprehensive tests following modern PowerShell patterns' -argument-hint: '[file-or-code] [testType] [coverage] [environment] [pesterVersion]' ---- - -Run the shared prompt in @.github/prompts/create-test.prompt.md. - -That file is written for GitHub Copilot Chat and is the only copy of the prompt. Apply it here as -follows: - -- Ignore its `agent` and `tools` frontmatter. -- `${input:NAME:...}` is a value to collect. Take it from the arguments below when they supply it, - otherwise ask before starting. The text after the name lists the choices or a placeholder, and a - final segment after another colon is the default. -- `${selection}` is the code the user selected or named in the arguments. `${fileBasename}` is the - file that code lives in, and `${workspaceFolderBasename}` is the repository folder name. -- If the contents of the prompt file are not shown above, read `.github/prompts/create-test.prompt.md` - before doing anything else. - -Arguments: $ARGUMENTS diff --git a/.claude/commands/powershell-standards/create-workflow.md b/.claude/commands/powershell-standards/create-workflow.md deleted file mode 100644 index c357971..0000000 --- a/.claude/commands/powershell-standards/create-workflow.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: 'Generates business workflow automation' -argument-hint: '[process] [trigger] [integrations] [errorHandling]' ---- - -Run the shared prompt in @.github/prompts/create-workflow.prompt.md. - -That file is written for GitHub Copilot Chat and is the only copy of the prompt. Apply it here as -follows: - -- Ignore its `agent` and `tools` frontmatter. -- `${input:NAME:...}` is a value to collect. Take it from the arguments below when they supply it, - otherwise ask before starting. The text after the name lists the choices or a placeholder, and a - final segment after another colon is the default. -- `${selection}` is the code the user selected or named in the arguments. `${fileBasename}` is the - file that code lives in, and `${workspaceFolderBasename}` is the repository folder name. -- If the contents of the prompt file are not shown above, read `.github/prompts/create-workflow.prompt.md` - before doing anything else. - -Arguments: $ARGUMENTS diff --git a/.claude/commands/powershell-standards/new-function.md b/.claude/commands/powershell-standards/new-function.md deleted file mode 100644 index b051f3b..0000000 --- a/.claude/commands/powershell-standards/new-function.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: 'Creates enterprise-standard PowerShell function with modern best practices' -argument-hint: '[functionName] [purpose] [parameters] [environment] [psVersion]' ---- - -Run the shared prompt in @.github/prompts/new-function.prompt.md. - -That file is written for GitHub Copilot Chat and is the only copy of the prompt. Apply it here as -follows: - -- Ignore its `agent` and `tools` frontmatter. -- `${input:NAME:...}` is a value to collect. Take it from the arguments below when they supply it, - otherwise ask before starting. The text after the name lists the choices or a placeholder, and a - final segment after another colon is the default. -- `${selection}` is the code the user selected or named in the arguments. `${fileBasename}` is the - file that code lives in, and `${workspaceFolderBasename}` is the repository folder name. -- If the contents of the prompt file are not shown above, read `.github/prompts/new-function.prompt.md` - before doing anything else. - -Arguments: $ARGUMENTS diff --git a/.claude/commands/powershell-standards/optimize-performance.md b/.claude/commands/powershell-standards/optimize-performance.md deleted file mode 100644 index 473e44a..0000000 --- a/.claude/commands/powershell-standards/optimize-performance.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: 'PowerShell performance optimization with specific targets' -argument-hint: '[file-or-code] [datasetSize] [performanceTarget] [environment] [criticality]' ---- - -Run the shared prompt in @.github/prompts/optimize-performance.prompt.md. - -That file is written for GitHub Copilot Chat and is the only copy of the prompt. Apply it here as -follows: - -- Ignore its `agent` and `tools` frontmatter. -- `${input:NAME:...}` is a value to collect. Take it from the arguments below when they supply it, - otherwise ask before starting. The text after the name lists the choices or a placeholder, and a - final segment after another colon is the default. -- `${selection}` is the code the user selected or named in the arguments. `${fileBasename}` is the - file that code lives in, and `${workspaceFolderBasename}` is the repository folder name. -- If the contents of the prompt file are not shown above, read `.github/prompts/optimize-performance.prompt.md` - before doing anything else. - -Arguments: $ARGUMENTS diff --git a/.claude/commands/powershell-standards/performance-analysis.md b/.claude/commands/powershell-standards/performance-analysis.md deleted file mode 100644 index c9cc603..0000000 --- a/.claude/commands/powershell-standards/performance-analysis.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: 'Detailed performance analysis and benchmarking' -argument-hint: '[file-or-code] [analysisScope] [metrics] [baseline] [target]' ---- - -Run the shared prompt in @.github/prompts/performance-analysis.prompt.md. - -That file is written for GitHub Copilot Chat and is the only copy of the prompt. Apply it here as -follows: - -- Ignore its `agent` and `tools` frontmatter. -- `${input:NAME:...}` is a value to collect. Take it from the arguments below when they supply it, - otherwise ask before starting. The text after the name lists the choices or a placeholder, and a - final segment after another colon is the default. -- `${selection}` is the code the user selected or named in the arguments. `${fileBasename}` is the - file that code lives in, and `${workspaceFolderBasename}` is the repository folder name. -- If the contents of the prompt file are not shown above, read `.github/prompts/performance-analysis.prompt.md` - before doing anything else. - -Arguments: $ARGUMENTS diff --git a/.claude/commands/powershell-standards/scaffold-project.md b/.claude/commands/powershell-standards/scaffold-project.md deleted file mode 100644 index d6b7f4a..0000000 --- a/.claude/commands/powershell-standards/scaffold-project.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: 'Creates complete project scaffold with CI/CD' -argument-hint: '[projectName] [projectType] [cicd] [deployment]' ---- - -Run the shared prompt in @.github/prompts/scaffold-project.prompt.md. - -That file is written for GitHub Copilot Chat and is the only copy of the prompt. Apply it here as -follows: - -- Ignore its `agent` and `tools` frontmatter. -- `${input:NAME:...}` is a value to collect. Take it from the arguments below when they supply it, - otherwise ask before starting. The text after the name lists the choices or a placeholder, and a - final segment after another colon is the default. -- `${selection}` is the code the user selected or named in the arguments. `${fileBasename}` is the - file that code lives in, and `${workspaceFolderBasename}` is the repository folder name. -- If the contents of the prompt file are not shown above, read `.github/prompts/scaffold-project.prompt.md` - before doing anything else. - -Arguments: $ARGUMENTS diff --git a/.claude/commands/powershell-standards/security-review.md b/.claude/commands/powershell-standards/security-review.md deleted file mode 100644 index e29c5ad..0000000 --- a/.claude/commands/powershell-standards/security-review.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: 'Security analysis with modern PowerShell patterns' -argument-hint: '[file-or-code] [complianceFramework] [environment]' ---- - -Run the shared prompt in @.github/prompts/security-review.prompt.md. - -That file is written for GitHub Copilot Chat and is the only copy of the prompt. Apply it here as -follows: - -- Ignore its `agent` and `tools` frontmatter. -- `${input:NAME:...}` is a value to collect. Take it from the arguments below when they supply it, - otherwise ask before starting. The text after the name lists the choices or a placeholder, and a - final segment after another colon is the default. -- `${selection}` is the code the user selected or named in the arguments. `${fileBasename}` is the - file that code lives in, and `${workspaceFolderBasename}` is the repository folder name. -- If the contents of the prompt file are not shown above, read `.github/prompts/security-review.prompt.md` - before doing anything else. - -Arguments: $ARGUMENTS diff --git a/.claude/commands/powershell-standards/validate-standards.md b/.claude/commands/powershell-standards/validate-standards.md deleted file mode 100644 index 3d0a611..0000000 --- a/.claude/commands/powershell-standards/validate-standards.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: 'Validates code against PowerShell community standards' -argument-hint: '[file-or-code]' ---- - -Run the shared prompt in @.github/prompts/validate-standards.prompt.md. - -That file is written for GitHub Copilot Chat and is the only copy of the prompt. Apply it here as -follows: - -- Ignore its `agent` and `tools` frontmatter. -- `${input:NAME:...}` is a value to collect. Take it from the arguments below when they supply it, - otherwise ask before starting. The text after the name lists the choices or a placeholder, and a - final segment after another colon is the default. -- `${selection}` is the code the user selected or named in the arguments. `${fileBasename}` is the - file that code lives in, and `${workspaceFolderBasename}` is the repository folder name. -- If the contents of the prompt file are not shown above, read `.github/prompts/validate-standards.prompt.md` - before doing anything else. - -Arguments: $ARGUMENTS diff --git a/.claude/rules/powershell-standards/analyze.md b/.claude/rules/powershell-standards/analyze.md deleted file mode 100644 index b3b3e44..0000000 --- a/.claude/rules/powershell-standards/analyze.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -paths: - - "**/*.ps1" - - "**/*.psm1" - - "**/*.psd1" ---- - -@../../../.github/instructions/analyze.instructions.md - -Source of this rule: `.github/instructions/analyze.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/architecturedesign.md b/.claude/rules/powershell-standards/architecturedesign.md deleted file mode 100644 index 760816c..0000000 --- a/.claude/rules/powershell-standards/architecturedesign.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -paths: - - "**/*.psm1" - - "**/module.json" - - "**/README.md" ---- - -@../../../.github/instructions/architecturedesign.instructions.md - -Source of this rule: `.github/instructions/architecturedesign.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/cicd.md b/.claude/rules/powershell-standards/cicd.md deleted file mode 100644 index fe2b59e..0000000 --- a/.claude/rules/powershell-standards/cicd.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -paths: - - "**/.github/workflows/*.yml" - - "**/.github/workflows/*.yaml" - - "**/azure-pipelines.yml" - - "**/build.ps1" - - "**/deploy.ps1" ---- - -@../../../.github/instructions/cicd.instructions.md - -Source of this rule: `.github/instructions/cicd.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/comments.md b/.claude/rules/powershell-standards/comments.md deleted file mode 100644 index 2cce02b..0000000 --- a/.claude/rules/powershell-standards/comments.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -paths: - - "**/*.ps1" - - "**/*.psm1" ---- - -@../../../.github/instructions/comments.instructions.md - -Source of this rule: `.github/instructions/comments.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/community-standards.md b/.claude/rules/powershell-standards/community-standards.md deleted file mode 100644 index 6652afb..0000000 --- a/.claude/rules/powershell-standards/community-standards.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -paths: - - "**/*.ps1" - - "**/*.psm1" - - "**/*.psd1" ---- - -@../../../.github/instructions/community-standards.instructions.md - -Source of this rule: `.github/instructions/community-standards.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/copilot-instructions.md b/.claude/rules/powershell-standards/copilot-instructions.md index 6c2e7b8..dbd4130 100644 --- a/.claude/rules/powershell-standards/copilot-instructions.md +++ b/.claude/rules/powershell-standards/copilot-instructions.md @@ -1,5 +1,5 @@ @../../../.github/copilot-instructions.md -Source of this rule: `.github/copilot-instructions.md`, the always-on standards GitHub Copilot applies to -every file. This rule has no `paths`, so Claude Code loads it at launch the same way. Relative links -inside it resolve from `.github/`. +Source of this rule: `.github/copilot-instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/errorsandlogs.md b/.claude/rules/powershell-standards/errorsandlogs.md deleted file mode 100644 index cf38818..0000000 --- a/.claude/rules/powershell-standards/errorsandlogs.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -paths: - - "**/*.ps1" - - "**/*.psm1" ---- - -@../../../.github/instructions/errorsandlogs.instructions.md - -Source of this rule: `.github/instructions/errorsandlogs.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/module.md b/.claude/rules/powershell-standards/module.md deleted file mode 100644 index f2998ff..0000000 --- a/.claude/rules/powershell-standards/module.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -paths: - - "**/*.psm1" - - "**/*.psd1" - - "**/Public/*.ps1" - - "**/Private/*.ps1" ---- - -@../../../.github/instructions/module.instructions.md - -Source of this rule: `.github/instructions/module.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/pester.md b/.claude/rules/powershell-standards/pester.md deleted file mode 100644 index 9978d24..0000000 --- a/.claude/rules/powershell-standards/pester.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -paths: - - "**/Tests/**/*.ps1" - - "**/*.Tests.ps1" ---- - -@../../../.github/instructions/pester.instructions.md - -Source of this rule: `.github/instructions/pester.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/platyps.md b/.claude/rules/powershell-standards/platyps.md deleted file mode 100644 index de21e5f..0000000 --- a/.claude/rules/powershell-standards/platyps.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -paths: - - "**/docs/**/*.md" - - "**/Public/*.ps1" - - "**/*.psd1" ---- - -@../../../.github/instructions/platyps.instructions.md - -Source of this rule: `.github/instructions/platyps.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/powershell-cicd.md b/.claude/rules/powershell-standards/powershell-cicd.md new file mode 100644 index 0000000..985757c --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-cicd.md @@ -0,0 +1,12 @@ +--- +paths: + - "**/.github/workflows/*.yml" + - "**/.github/workflows/*.yaml" + - "**/azure-pipelines.yml" +--- + +@../../../.github/instructions/powershell-cicd.instructions.md + +Source of this rule: `.github/instructions/powershell-cicd.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-error-handling.md b/.claude/rules/powershell-standards/powershell-error-handling.md new file mode 100644 index 0000000..a53eead --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-error-handling.md @@ -0,0 +1,11 @@ +--- +paths: + - "**/*.ps1" + - "**/*.psm1" +--- + +@../../../.github/instructions/powershell-error-handling.instructions.md + +Source of this rule: `.github/instructions/powershell-error-handling.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-functions.md b/.claude/rules/powershell-standards/powershell-functions.md new file mode 100644 index 0000000..8a594a9 --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-functions.md @@ -0,0 +1,11 @@ +--- +paths: + - "**/*.ps1" + - "**/*.psm1" +--- + +@../../../.github/instructions/powershell-functions.instructions.md + +Source of this rule: `.github/instructions/powershell-functions.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-help.md b/.claude/rules/powershell-standards/powershell-help.md new file mode 100644 index 0000000..1c7aee5 --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-help.md @@ -0,0 +1,11 @@ +--- +paths: + - "**/*.ps1" + - "**/*.psm1" +--- + +@../../../.github/instructions/powershell-help.instructions.md + +Source of this rule: `.github/instructions/powershell-help.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-modules.md b/.claude/rules/powershell-standards/powershell-modules.md new file mode 100644 index 0000000..cc81e36 --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-modules.md @@ -0,0 +1,11 @@ +--- +paths: + - "**/*.psm1" + - "**/*.psd1" +--- + +@../../../.github/instructions/powershell-modules.instructions.md + +Source of this rule: `.github/instructions/powershell-modules.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-pester.md b/.claude/rules/powershell-standards/powershell-pester.md new file mode 100644 index 0000000..07ff794 --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-pester.md @@ -0,0 +1,10 @@ +--- +paths: + - "**/*.Tests.ps1" +--- + +@../../../.github/instructions/powershell-pester.instructions.md + +Source of this rule: `.github/instructions/powershell-pester.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-platyps.md b/.claude/rules/powershell-standards/powershell-platyps.md new file mode 100644 index 0000000..cf59564 --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-platyps.md @@ -0,0 +1,10 @@ +--- +paths: + - "**/docs/**/*.md" +--- + +@../../../.github/instructions/powershell-platyps.instructions.md + +Source of this rule: `.github/instructions/powershell-platyps.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-pull-requests.md b/.claude/rules/powershell-standards/powershell-pull-requests.md new file mode 100644 index 0000000..78a4944 --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-pull-requests.md @@ -0,0 +1,5 @@ +@../../../.github/instructions/powershell-pull-requests.instructions.md + +Source of this rule: `.github/instructions/powershell-pull-requests.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-readme.md b/.claude/rules/powershell-standards/powershell-readme.md new file mode 100644 index 0000000..66e7043 --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-readme.md @@ -0,0 +1,10 @@ +--- +paths: + - "**/README.md" +--- + +@../../../.github/instructions/powershell-readme.instructions.md + +Source of this rule: `.github/instructions/powershell-readme.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-security.md b/.claude/rules/powershell-standards/powershell-security.md new file mode 100644 index 0000000..b2b5471 --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-security.md @@ -0,0 +1,11 @@ +--- +paths: + - "**/*.ps1" + - "**/*.psm1" +--- + +@../../../.github/instructions/powershell-security.instructions.md + +Source of this rule: `.github/instructions/powershell-security.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-style.md b/.claude/rules/powershell-standards/powershell-style.md new file mode 100644 index 0000000..56cfca0 --- /dev/null +++ b/.claude/rules/powershell-standards/powershell-style.md @@ -0,0 +1,12 @@ +--- +paths: + - "**/*.ps1" + - "**/*.psm1" + - "**/*.psd1" +--- + +@../../../.github/instructions/powershell-style.instructions.md + +Source of this rule: `.github/instructions/powershell-style.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/powershell-version.md b/.claude/rules/powershell-standards/powershell-version.md index cb07ded..274be64 100644 --- a/.claude/rules/powershell-standards/powershell-version.md +++ b/.claude/rules/powershell-standards/powershell-version.md @@ -7,5 +7,6 @@ paths: @../../../.github/instructions/powershell-version.instructions.md -Source of this rule: `.github/instructions/powershell-version.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. +Source of this rule: `.github/instructions/powershell-version.instructions.md`, which GitHub Copilot reads as well. +This file is generated by `Tools/Build-AgentInstructions.ps1`. Change the source under +`standards/` instead of editing it. diff --git a/.claude/rules/powershell-standards/pull-requests.md b/.claude/rules/powershell-standards/pull-requests.md deleted file mode 100644 index 3ac3368..0000000 --- a/.claude/rules/powershell-standards/pull-requests.md +++ /dev/null @@ -1,6 +0,0 @@ -@../../../.github/instructions/pull-requests.instructions.md - -Source of this rule: `.github/instructions/pull-requests.instructions.md` (shared with GitHub Copilot, -which applies it to every file through `applyTo: '**'`). This rule has no `paths`, so Claude Code loads -it at launch: opening a pull request does not always involve reading a file. Relative links inside it -resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/readme.md b/.claude/rules/powershell-standards/readme.md deleted file mode 100644 index cb004f1..0000000 --- a/.claude/rules/powershell-standards/readme.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -paths: - - "**/README.md" - - "**/readme.md" - - "**/Readme.md" ---- - -@../../../.github/instructions/readme.instructions.md - -Source of this rule: `.github/instructions/readme.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/securitycompliance.md b/.claude/rules/powershell-standards/securitycompliance.md deleted file mode 100644 index bc5a18f..0000000 --- a/.claude/rules/powershell-standards/securitycompliance.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -paths: - - "**/*.ps1" - - "**/*.psm1" - - "**/Security/**/*.ps1" ---- - -@../../../.github/instructions/securitycompliance.instructions.md - -Source of this rule: `.github/instructions/securitycompliance.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.claude/rules/powershell-standards/style-enforcement.md b/.claude/rules/powershell-standards/style-enforcement.md deleted file mode 100644 index d0474fc..0000000 --- a/.claude/rules/powershell-standards/style-enforcement.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -paths: - - "**/*.ps1" - - "**/*.psm1" ---- - -@../../../.github/instructions/style-enforcement.instructions.md - -Source of this rule: `.github/instructions/style-enforcement.instructions.md` (shared with GitHub Copilot, which -applies it through its `applyTo` glob). Relative links inside it resolve from `.github/instructions/`. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 279c6cc..52fce4a 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,781 +1,267 @@ -# PowerShell Copilot Instructions - -## 🎯 Core Principles - -You are assisting with enterprise PowerShell development that prioritizes security, maintainability, and performance. -Always follow these foundational principles: - -1. **Security by Design**: Implement comprehensive input validation and secure credential handling -2. **Correlation Tracking**: Include correlation IDs for audit trails and troubleshooting -3. **Error Resilience**: Implement robust error handling with structured logging -4. **Performance Awareness**: Write efficient code with appropriate optimization -5. **Community Standards**: Follow established PowerShell best practices and style guidelines -6. **Enterprise Integration**: Design for scalability and organizational compliance - -## 📋 Community Standards Integration - -### PowerShell Community Standards Compliance - -All code generation must comply with established PowerShell community best practices and style guidelines, incorporating -expert feedback for accuracy: - -#### Best Practices Enforcement - -- **Tool vs Controller Design**: Create reusable functions (tools) vs one-time automation scripts (controllers) -- **Modular Architecture**: Functions accept input via parameters, output to pipeline for maximum reusability -- **Error Handling Standards**: Use proper `$_` handling in catch blocks, appropriate null checking patterns -- **Performance Optimization**: Context-dependent string operations, test when it matters, use language features over - cmdlets -- **Security by Design**: Modern credential handling with `[PSCredential]::new()`, validate all inputs, sanitize data - -#### Style Guide Compliance - -- **Code Layout**: One True Brace Style (opening brace at end of line), 4-space indentation, 115-character line limit -- **Function Structure**: Advanced functions with CmdletBinding, appropriate parameter validation (no redundant - attributes) -- **Naming Conventions**: Approved PowerShell verbs only (use `Get-Verb`), full command names, explicit parameter names, - PascalCase -- **Documentation Standards**: Proper comment-based help format with opening `<#`, no maintenance-heavy versioning in - NOTES - -#### Anti-Patterns to Avoid - -- **Error Handling**: Don't use `$Error[0]` in catch blocks (use `$_`), don't force exceptions for simple existence - checks -- **Throw Behavior**: Be aware that `throw` statements can be silenced by `-ErrorAction SilentlyContinue` - use - `Write-Error -ErrorAction Stop` for proper termination when needed -- **Parameter Usage**: Don't pass parameters to functions without validating they have values, especially when - parameters might be empty strings or whitespace -- **Performance**: Don't use StringBuilder for small string operations (< 100 concatenations), don't use array appending - in large loops -- **Validation**: Don't add ValidateNotNullOrEmpty to mandatory parameters unless they'll be used in downstream function - calls where empty strings matter -- **Output**: Don't use misleading `[OutputType([PSCustomObject])]` declarations -- **Documentation**: Don't use broken comment-based help (missing `<#` opener) -- **Block Scoping**: Don't `return` from `begin` to stop a command. `return` ends the `begin` block and nothing - else; `process` still runs. A teardown that did this printed "cancelled" and deleted everything. Record the - decision in a variable and test it at the top of `process` -- **Confirmation Gates**: Don't rely on `Read-Host` or `ShouldContinue` to stop an unattended run. `Read-Host` - reads end-of-file in a non-interactive session and never matches the confirmation word; `ShouldContinue` hangs - a console and is refused in CI. Treat a session that cannot answer as a refusal, and require `-Force` for an - unattended destructive run -- **Parameter Shadowing**: Don't name a local after a parameter in any letter case. Variable names are - case-insensitive, so a body-level `$settings = @{}` silently overwrites `-Settings`. Inside a nested function - `$PSBoundParameters` is that function's own, so capture what it needs into a plain variable before defining it -- **WhatIf Reach**: Don't enumerate with `ForEach-Object -MemberName` in a command that supports `-WhatIf`; that - parameter set honours `ShouldProcess`, so the enumeration returns nothing under `-WhatIf`. Use a script block. - `$WhatIfPreference` is also inherited by every child scope, which is why a release rehearsal has to pin its - non-destructive steps; see - [module.instructions.md](./instructions/module.instructions.md#the-rehearsal-under--whatif) -- **Background Scope**: Don't read `$script:` state, or call the module's own functions, inside `Start-Job`, a - runspace worker, or a `ForEach-Object -Parallel` block. A job starts without this session's state and - functions, and a worker without its state; neither fails loudly. A seed that did this created 688 computers - with no prefix and silently created none of its 296 users. Pass values through `-ArgumentList`, `$using:`, or a - parameter, and remember that Pester mocks do not reach a worker either -- **Empty Collections**: Don't rely on a nested helper returning `@()`. PowerShell unrolls an empty array on - the way out of a function, so the caller receives `$null` and a splatted `[object[]]` parameter fails to - bind. Wrap the call site with `@(...)`, or return with `Write-Output -NoEnumerate` -- **Response Shapes**: Don't index response data with `['key']` or assume one shape. Graph SDK responses are - hashtables by default and PSObjects with `-OutputType PSObject`; `ConvertFrom-Json` is the reverse, and - `$psobject['key']` returns `$null` with no error. Read through one accessor that handles both; see - [module.instructions.md](./instructions/module.instructions.md#responses-that-arrive-as-hashtables-or-psobjects) - -### Script Development Guidelines - -- **Approved Verbs Only**: Use Microsoft's approved PowerShell verbs (`Get-Verb`) for ALL function names consistently -- **Version Compatibility**: Default target is **PowerShell 7.6 (LTS)**. Maintain Windows PowerShell 5.1 compatibility - only when the project must run on estates without pwsh installed — decide this deliberately, not by habit -- **Version Annotations**: Declare the target with `#requires -Version 7.6` at the script header. Never emit - `#requires -Version 7.0` — PowerShell 7.0–7.3 are retired, and 7.4/7.5 lose support on 10-Nov-2026 -- **Version-Dependent Features**: Before emitting a cmdlet or parameter added in 7.5 or 7.6, confirm the declared target - supports it — see [powershell-version.instructions.md](instructions/powershell-version.instructions.md) -- **Output Standards**: Avoid `Write-Host` except when colored console output is explicitly required - - Use `Write-Verbose`, `Write-Debug`, `Write-Information`, `Write-Warning`, or `Write-Error` instead - - Leverage pipeline output for data flow -- **Pipeline Efficiency**: Always design functions to work efficiently in the pipeline - -### Modern PowerShell Features - -- Use `[PSCredential]::new()` instead of `New-Object` for credential creation -- Use `Install-PSResource` / `Find-PSResource` (Microsoft.PowerShell.PSResourceGet, in-box since 7.4) over PowerShellGet - v2 `Install-Module` / `Find-Module` -- Call `Start-ThreadJob` unqualified — the module was renamed to `Microsoft.PowerShell.ThreadJob` in 7.6, so the old - `ThreadJob\` qualifier breaks -- Leverage current-version features when the declared target allows: `ConvertTo-CliXml`/`ConvertFrom-CliXml`, - `ConvertFrom-Json -DateKind`, `Test-Json -IgnoreComments` (7.5+); `Get-Command -ExcludeModule`, - `Get-Clipboard -Delimiter` (7.6+) -- Avoid redundant parameter validation (mandatory parameters are implicitly not null/empty) - -## 🛡️ Security Requirements - -### Input Validation +# PowerShell standards -```powershell -# Appropriate validation patterns -param( - [Parameter(Mandatory)] - [string]$ComputerName, # Mandatory implies not null/empty - - [Parameter()] - [ValidateNotNullOrEmpty()] # Explicit validation for optional params - [ValidatePattern('^[a-zA-Z0-9\-\.]+$')] - [string]$OptionalServer -) - -# Sanitize file paths to prevent traversal attacks -$safePath = Resolve-Path -Path $InputPath -ErrorAction Stop -if ($safePath.Path.Contains('..')) { - throw "Invalid path: Path traversal not allowed" -} -``` - -### Credential Management - -```powershell -# Modern credential creation (PowerShell 5+) -$credential = [PSCredential]::new($username, $securePassword) - -# Always use secure credential handling per community standards -$secureString = ConvertTo-SecureString $Password -AsPlainText -Force -``` +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. -### Security Scanning Patterns +These are the rules for writing and reviewing PowerShell in this repository. **MUST** and +**MUST NOT** are requirements. **SHOULD** is the default: depart from it only for a reason you state. -Avoid these patterns in production code: +## How to apply the rules -- Hardcoded passwords or API keys -- Plain text credential storage -- SQL injection vulnerabilities in dynamic queries -- Unvalidated user input in file paths or commands +- Apply them to code you write or change. Do not reformat or rewrite code the task does not touch. +- An explicit instruction from the user takes precedence. If following it breaks a MUST, say which + one. +- Do not invent facts: no made-up module names, version numbers, measurements, links, or authors. Ask, + or leave it out. +- When you can run commands, run PSScriptAnalyzer and the tests before you report the work as done, + and say what you ran. -### Security Logging +## Topic rules -```powershell -# Log security-relevant activities with correlation IDs -Write-Warning "Security event: $SecurityEventDescription - User: $env:USERNAME - Time: $(Get-Date)" -``` - -## 🔧 Function Template - -This template shows a **standalone function or a private module function**, where the comment block -is the only documentation. For a function exported from a module, the help content moves to PlatyPS -Markdown and the block collapses to two lines: - -```powershell -function Get-ExampleData { - <# - .EXTERNALHELP ModuleName-Help.xml - .SYNOPSIS - Brief description using approved verb-noun pattern - #> - [CmdletBinding(SupportsShouldProcess)] - # ... body identical to the template below -} -``` +The rules below are the ones that matter in almost every file. Each topic has a file with the +complete rules, the reasons, and examples: -See [PlatyPS Help Documentation](./instructions/platyps.instructions.md). Without the -`.EXTERNALHELP` line, comment-based help wins and the module's shipped MAML is ignored. Keep the -keyword **inside** the `<# #>` block — as a bare `#` comment preceded by ordinary prose it stops -being recognized, with no error and no warning. +| When the work involves | Read | +| --- | --- | +| Any `.ps1`, `.psm1`, or `.psd1` file | `.github/instructions/powershell-style.instructions.md` | +| Functions and parameters | `.github/instructions/powershell-functions.instructions.md` | +| Errors, strict mode, output streams | `.github/instructions/powershell-error-handling.instructions.md` | +| Secrets, credentials, untrusted input | `.github/instructions/powershell-security.instructions.md` | +| Comment-based help and comments | `.github/instructions/powershell-help.instructions.md` | +| Which PowerShell version a feature needs | `.github/instructions/powershell-version.instructions.md` | +| Module manifests, root modules, and releases | `.github/instructions/powershell-modules.instructions.md` | +| Pester tests | `.github/instructions/powershell-pester.instructions.md` | +| Help Markdown under `docs/` | `.github/instructions/powershell-platyps.instructions.md` | +| Workflows and build scripts | `.github/instructions/powershell-cicd.instructions.md` | +| `README.md` | `.github/instructions/powershell-readme.instructions.md` | +| Branches, commits, and pull requests | `.github/instructions/powershell-pull-requests.instructions.md` | + +GitHub Copilot and Claude Code load the matching file automatically when you work on such a file. If +your tooling does not, you MUST read the matching files before creating or changing the file. + +## Core rules + +### Version + +- **VER-01** Write for PowerShell 7.6 (LTS) unless the project declares another target. The + declaration is the project's `#requires -Version` lines and the `PowerShellVersion` and + `CompatiblePSEditions` keys of its module manifest. +- **VER-02** Write code that also runs on Windows PowerShell 5.1 only when the project declares it: + `PowerShellVersion = '5.1'`, `CompatiblePSEditions` containing `Desktop`, or + `#requires -Version 5.1`. +- **VER-04** Code MUST NOT use a command, parameter, operator, or type that the declared target does + not have. The feature tables in the PowerShell version rules list the ones that differ. +- **VER-06** Commands that exist only in Windows PowerShell MUST NOT be used in code that targets + PowerShell 7: use `Get-CimInstance` in place of `Get-WmiObject`, and `Get-WinEvent` in place of + `Get-EventLog`. + +### Style + +- **STY-02** Use One True Brace Style: an opening brace ends the line that starts the block, a closing + brace starts its own line, and `else`, `elseif`, `catch`, and `finally` follow that closing brace on + the same line. +- **STY-03** Lines SHOULD NOT exceed 115 characters. Shorten a long command with splatting, or break + the line after a pipe, comma, or operator. Backtick line continuation MUST NOT be used. +- **STY-06** Source MUST be ASCII unless a string literal needs another character: no emoji, + typographic quotes, or en and em dashes in code or comments. +- **STY-12** Name local variables in descriptive camelCase without a type prefix: `$retryCount`, not + `$RetryCount` or `$intRetryCount`. +- **STY-13** Automatic variables MUST NOT be assigned or reused as parameter, loop, or test-data + names. The ones most often hit are `$args`, `$input`, `$matches`, `$error`, `$event`, `$host`, + `$home`, `$pid`, `$profile`, `$sender`, `$this`, `$_`, and `$PSItem`. +- **STY-14** Call commands by their full name with named parameters. Aliases such as `gci`, `ls`, + `%`, `?`, and `where` MUST NOT be used. One leading positional argument is acceptable where it is + unambiguous, as in `Write-Verbose 'text'`. +- **STY-16** A local variable MUST NOT have the name of a parameter in any letter case. Variable names + are case-insensitive, so `$settings = @{}` replaces the value that was passed as `-Settings`. +- **STY-20** Put `$null` on the left of a comparison: `$null -eq $value`. +- **STY-21** Use single quotes for a string that needs no expansion and contains no single quote. In + an expandable string write `$($object.Property)` for member access, and `${name}` when a colon or + a name character follows the variable. +- **STY-32** Use `-LiteralPath` whenever the path names one specific item, and always for a path held + in a variable. `-Path` is for wildcard patterns. +- **STY-40** Build a collection by assigning the output of a loop or pipeline to a variable. An array + MUST NOT be grown with `+=` inside a loop. +- **STY-42** Wrap a command call in `@()` before the code reads `.Count` or an index from its result, + or passes the result to a parameter that needs a collection. + +### Functions + +- **FUN-01** Write every function as an advanced function, with `[CmdletBinding()]` and a `param()` + block. `$args` MUST NOT be used. +- **FUN-04** `return` in a `begin` block ends only that block; `process` and `end` still run. To stop + the command there, call `$PSCmdlet.ThrowTerminatingError()`, or set a variable and test it at the + top of `process`. +- **FUN-10** Declare `[OutputType()]` with the type the function emits. For a custom object, name the + type as a string and set `PSTypeName` on the object. `[OutputType([PSCustomObject])]` MUST NOT be + used. +- **FUN-11** Write each object to the pipeline as soon as it is ready. A function MUST NOT collect + its results in a list and return the list at the end. +- **FUN-12** Only intended output may reach the success stream. Discard a value returned by a method + or command that is called for its side effect, with `$null = ...` or `[void](...)`. +- **FUN-21** A parameter that accepts pipeline input MUST be handled in a `process` block. Declare it + as an array and loop over it there, so that pipeline input and a directly passed array behave the + same way. +- **FUN-25** A function that reduces its pipeline input to one result collects the input in `process` + and emits the result in `end`, so that piped input and an array argument give the same answer. +- **FUN-26** Read data that came from an API or a file through one accessor that handles both a + dictionary and an object. Index syntax (`$data['key']`) reads only a dictionary, and member syntax + (`$data.key`) can return a dictionary's own property instead of the data. +- **FUN-30** A function that changes state MUST declare `SupportsShouldProcess` and guard every change + with `$PSCmdlet.ShouldProcess()`. Add `ConfirmImpact = 'High'` when the change is destructive. +- **FUN-31** A read-only function, such as one with the verb `Get`, `Test`, or `Find`, MUST NOT + declare `SupportsShouldProcess`. + +### Errors + +- **ERR-01** A script that is run directly MUST set `Set-StrictMode -Version Latest` and + `$ErrorActionPreference = 'Stop'` immediately after its `param()` block. +- **ERR-02** Module code MUST NOT set `$ErrorActionPreference`, at module scope or inside a function. + A module sets `Set-StrictMode -Version Latest` once, at the top of its `.psm1`. +- **ERR-03** Code MUST run without errors under strict mode: assign a variable before reading it, test + for an optional property with `$object.PSObject.Properties['Name']`, test for a hashtable key with + `.ContainsKey()`, and wrap a result in `@()` before reading `.Count` or an index. +- **ERR-10** In an advanced function, put the work that can fail inside `try`, and end the function + on an unrecoverable failure by calling `$PSCmdlet.ThrowTerminatingError()` in `catch`. +- **ERR-11** `throw` and `Write-Error -ErrorAction Stop` MUST NOT be used in an advanced function. Use + `throw` only where `$PSCmdlet` does not exist: top-level script code, class methods, and plain + script blocks. +- **ERR-12** Inside `try`, pass `-ErrorAction Stop` to every command whose failure the `catch` must + see. A non-terminating error does not enter `catch`. +- **ERR-13** When one input item fails and the rest can still be processed, report the failure with + `$PSCmdlet.WriteError()` and continue with the next item. +- **ERR-15** Write output to the pipeline after the `try` block, not inside it. An error raised by a + command further down the pipeline is otherwise caught by this function's `catch`. +- **ERR-20** A `catch` block MUST NOT be empty and MUST NOT hide the error. To tolerate one expected + failure, catch that exception type and state the reason in a comment. +- **ERR-23** After running a native executable, test `$LASTEXITCODE` and fail when it reports an + error. A non-zero exit code does not raise a PowerShell error by default. + +### Security + +- **SEC-01** Secrets MUST NOT appear in source: no passwords, tokens, keys, or connection strings in + code, parameter defaults, comments, or example values. +- **SEC-03** Accept a credential as a `[PSCredential]` parameter carrying the + `[System.Management.Automation.Credential()]` attribute. A password MUST NOT be accepted as a + `[string]` parameter. +- **SEC-05** A function or an unattended script MUST NOT fall back to an interactive prompt + (`Get-Credential`, `Read-Host`) when a credential or value is missing. It fails with an error that + names what is missing. +- **SEC-06** Secrets and personal data MUST NOT be written to any stream, log, error message, or + file. This includes dumping `$PSBoundParameters` or a whole input object. +- **SEC-10** Commands MUST NOT be built from strings: no `Invoke-Expression`, and no + `[scriptblock]::Create()` on text that includes input. Pass arguments with splatting, or as an + array for a native executable. + +### Help + +- **DOC-01** Every function and every script has comment-based help with `.SYNOPSIS`, `.DESCRIPTION`, + one `.PARAMETER` for each parameter, at least one `.EXAMPLE`, `.INPUTS`, and `.OUTPUTS`. +- **DOC-02** In a function, the help block is the first thing inside the function body, before + `[CmdletBinding()]`. +- **DOC-05** Help MUST describe what the code does. Performance figures, compliance claims, and + behaviour that the code does not have MUST NOT be invented. If a fact is not known, leave it out. +- **DOC-07** Help MUST NOT contain a version number, a date, or a change history. An author name is + added only when the user supplies one. + +## Function template + +Copy this shape. It runs under strict mode on PowerShell 7.6 and Windows PowerShell 5.1, and its +tests are the test template in `.github/instructions/powershell-pester.instructions.md`. ```powershell -function Get-ExampleData { +function Get-ConfigValue { <# .SYNOPSIS - Brief description using approved verb-noun pattern + Gets named values from a JSON configuration file. .DESCRIPTION - Detailed explanation including: - - Business value and purpose - - Key functionality and features - - Dependencies and requirements - - Performance characteristics + Reads the JSON file once, then emits one object for each requested name. A name that is + not in the file is reported as a non-terminating error and the remaining names are still + processed. A file that cannot be read, or that does not contain a JSON object, is a + terminating error. + + .PARAMETER Path + Path of the JSON configuration file. Wildcard characters are not expanded. .PARAMETER Name - Description of mandatory parameter (implicitly validated as not null/empty) + One or more top-level property names to read. - .PARAMETER OptionalPath - Description of optional parameter with explicit validation + .EXAMPLE + Get-ConfigValue -Path './settings.json' -Name 'Region' + + Gets the Region value from settings.json. .EXAMPLE - PS> Get-ExampleData -Name "Value" + 'Region', 'Tier' | Get-ConfigValue -Path './settings.json' - DESCRIPTION: What this example demonstrates - OUTPUT: Expected output description - USE CASE: Business scenario where this is useful + Gets two values, taking the names from the pipeline. - .NOTES - Author: Jeffrey Stuhr - Blog: https://www.techbyjeff.net - LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/ + .INPUTS + System.String. You can pipe value names to this function. - TROUBLESHOOTING: - - For common issues: .\Troubleshooting\Common\Function-Name-Issues.md - - For performance: .\Troubleshooting\Performance\Optimization-Guide.md + .OUTPUTS + Example.ConfigValue. An object with Name, Value, and Path properties. #> - - [CmdletBinding(SupportsShouldProcess)] - [OutputType('ProcessedData')] # Use descriptive type name, not [PSCustomObject] + [CmdletBinding()] + [OutputType('Example.ConfigValue')] param( - [Parameter(Mandatory, ValueFromPipeline)] - [ValidateNotNullOrEmpty()] # Explicit validation even for mandatory params when used in downstream functions - [string]$Name, - - [Parameter()] - [ValidateNotNullOrEmpty()] - [string]$OptionalPath, + [Parameter(Mandatory)] + [string]$Path, - [Parameter()] - [string]$CorrelationId = [System.Guid]::NewGuid().ToString() + [Parameter(Mandatory, ValueFromPipeline)] + [string[]]$Name ) begin { - Write-EnterpriseLog -Level "INFO" -Message "Starting $($MyInvocation.MyCommand.Name)" -CorrelationId $CorrelationId - - # Load configuration - $config = Get-EnvironmentConfiguration - } - - process { try { - # Validate parameters before using in function calls (expert feedback Part 2) - if (-not $Name.Trim()) { - Write-Error "Name parameter cannot be empty or whitespace" -ErrorAction Stop - return - } - - if ($PSCmdlet.ShouldProcess($Name, "Process Data")) { - # Modern credential creation if needed - if ($needsCredential) { - $credential = [PSCredential]::new($username, $securePassword) - } - - # Context-appropriate string operations - if ($items.Count -lt 100) { - # Small operations - += is fine and readable - $summary = "Processing: $Name" - $summary += " at $(Get-Date)" - } else { - # Large operations - use StringBuilder - $sb = [System.Text.StringBuilder]::new() - foreach ($item in $items) { - [void]$sb.AppendLine("Processing: $item") - } - $summary = $sb.ToString() - } - - # Appropriate null checking for optional data - $optionalData = Get-OptionalData -Name $Name.Trim() -ErrorAction SilentlyContinue - if ($optionalData) { - # Process optional data - null check is valid here - Write-Verbose "Found optional data for $Name" - } - - # Return data with explicit type name for better tooling - $result = [PSCustomObject]@{ - PSTypeName = 'ProcessedData' - Name = $Name - ProcessedAt = Get-Date - CorrelationId = $CorrelationId - HasOptionalData = [bool]$optionalData - } - - Write-Output $result - } - } - catch { - # CORRECT: Use $_ not $Error[0] in catch blocks - $errorDetails = @{ - Message = $_.Exception.Message - Category = $_.CategoryInfo.Category - TargetObject = $_.TargetObject - CorrelationId = $CorrelationId - Function = $MyInvocation.MyCommand.Name - Line = $_.InvocationInfo.ScriptLineNumber - } - - Write-EnterpriseLog -Level "ERROR" -Message "Processing failed" -Details $errorDetails -CorrelationId $CorrelationId - - # Use Write-Error with -ErrorAction Stop instead of bare throw for proper error action handling - Write-Error "Failed to process $Name : $($_.Exception.Message)" -ErrorAction Stop + $fullPath = Convert-Path -LiteralPath $Path -ErrorAction Stop + $config = Get-Content -LiteralPath $fullPath -Raw -ErrorAction Stop | + ConvertFrom-Json -ErrorAction Stop + } catch { + $PSCmdlet.ThrowTerminatingError($_) } - } - - end { - Write-EnterpriseLog -Level "INFO" -Message "Completed $($MyInvocation.MyCommand.Name)" -CorrelationId $CorrelationId - } -} -``` - -## 🗂️ Mandatory File Organization - -All PowerShell projects must follow this standardized structure: - -```text -ProjectRoot/ -├── Public/ # Exported functions (tools for reuse) -│ └── Get-SomethingData.ps1 # Use approved verbs consistently -├── Private/ # Internal functions -│ └── Connect-InternalService.ps1 -├── Classes/ # PowerShell classes with explicit type names -│ └── CustomClass.ps1 -├── Tests/ # Pester test suite -│ ├── Unit/ -│ ├── Integration/ -│ └── Performance/ -├── docs/ # PlatyPS command help (Markdown source, committed) -│ └── ModuleName/ -├── en-US/ # Compiled MAML help, packaged with the module -│ └── ModuleName-Help.xml -├── Troubleshooting/ # Organized troubleshooting docs -│ ├── Common/ -│ ├── Security/ -│ ├── Performance/ -│ └── Integration/ -├── Documentation/ # Project documentation -│ ├── PowerShell-Best-Practices.md -│ └── PowerShell-Style-Guide.md -├── Configuration/ # Environment configs -└── README.md # Main documentation -``` - -**Critical**: All troubleshooting documentation must be organized in the `Troubleshooting/` folder with appropriate -subfolders for consistent reference. - -## 🚀 Performance Guidelines - -### Context-Dependent String Operations - -```powershell -# For small operations (< 100 concatenations), += is fine and more readable -if ($items.Count -lt 100) { - $output = "Processing started at: $(Get-Date)" - foreach ($item in $items) { - $output += "`nProcessing: $item" - } -} else { - # For large operations, use StringBuilder for performance - $sb = [System.Text.StringBuilder]::new() - [void]$sb.AppendLine("Processing started at: $(Get-Date)") - foreach ($item in $items) { - [void]$sb.AppendLine("Processing: $item") - } - $output = $sb.ToString() -} -``` - -### Array Accumulation (version-dependent — read this before flagging `+=`) - -```powershell -# ✅ Best on every version — assign the loop output directly, no per-iteration allocation -$results = foreach ($item in $collection) { - Get-ProcessedItem -Item $item -} - -# ✅ Also good: pipeline output -$results = $collection | ForEach-Object { Get-ProcessedItem -Item $_ } - -# ✅ When accumulation is genuinely conditional, use the generic List -$results = [System.Collections.Generic.List[object]]::new() -foreach ($item in $collection) { - if (Test-ItemRelevant -Item $item) { - $results.Add((Get-ProcessedItem -Item $item)) - } -} - -# ⚠️ `+=` — O(n²) on Windows PowerShell 5.1 and 7.4, but PowerShell 7.5 optimized it for -# object arrays, where it now outperforms List.Add(). Flag it only when the declared -# target includes 5.1/7.4, or when the loop is unbounded on any version. -$results = @() -foreach ($item in $collection) { $results += Get-ProcessedItem -Item $item } - -# ❌ Never generate ArrayList — non-generic, boxes values, forces [void] noise on every Add() -$results = [System.Collections.ArrayList]::new() -``` - -### Pipeline Optimization (Community Best Practice) - -```powershell -# Prefer pipeline operations over foreach loops for large datasets -$results = $largeCollection | - Where-Object { $_.Status -eq 'Active' } | - ForEach-Object { Process-Item $_ } | - Sort-Object Name - -# Use language features over cmdlets for performance -# Preferred: Where Status -eq Running -# Over: Where-Object { $_.Status -eq 'Running' } -``` - -## ⚠️ Error Handling Standards - -### Proper Error Handling Pattern - -```powershell -# Set appropriate error action preference -$ErrorActionPreference = 'Stop' - -try { - # Core operation with correlation tracking - $correlationId = [System.Guid]::NewGuid() - Write-Verbose "Operation started - CorrelationId: $correlationId" - - # Main logic here - $result = Invoke-Operation -CorrelationId $correlationId - Write-Verbose "Operation completed successfully - CorrelationId: $correlationId" - return $result -} -catch { - # CORRECT: Use $_ not $Error[0] in catch blocks - Write-Error "Operation failed: $($_.Exception.Message) - CorrelationId: $correlationId" - - # Log to troubleshooting system - $errorDetails = @{ - CorrelationId = $correlationId - Function = $MyInvocation.MyCommand.Name - ErrorMessage = $_.Exception.Message # Use $_ directly - StackTrace = $_.ScriptStackTrace - Timestamp = Get-Date - } - $errorDetails | ConvertTo-Json | Out-File ".\Troubleshooting\Logs\error-$correlationId.json" - - throw -} -finally { - # Cleanup resources following community disposal patterns - if ($resource -and $resource -is [System.IDisposable]) { - $resource.Dispose() - } -} -``` - -### Advanced Error Handling Considerations - -#### Throw Behavior with ErrorAction SilentlyContinue - -**Important**: Be aware that `throw` statements can be silenced by `-ErrorAction SilentlyContinue`, even though `throw` -creates terminating errors: - -```powershell -# ⚠️ This throw will be silenced and execution continues -function Test-ErrorHandling { - param([string]$Value) - - if (-not $Value) { - throw "Value is required" # This gets silenced with -ErrorAction SilentlyContinue - } - - Write-Output "Processing: $Value" -} - -# This will NOT stop execution as expected: -Test-ErrorHandling -Value "" -ErrorAction SilentlyContinue -Write-Output "This line will execute unexpectedly" - -# ✅ Better approach for validation that should never be silenced: -function Test-ErrorHandling { - param([string]$Value) - - if (-not $Value) { - # Use Write-Error with -ErrorAction Stop for proper termination - Write-Error "Value is required" -ErrorAction Stop - return # Explicit return as safety net - } - - Write-Output "Processing: $Value" -} -``` - -#### Parameter Validation Before Usage - -**Best Practice**: Always validate parameters have values before using them in function calls: - -```powershell -# ❌ Potential issue - passing potentially empty/null parameters -function Process-Data { - param( - [string]$ServerName, - [string]$DatabaseName - ) - - # This could fail if parameters are empty - $connection = Connect-Database -Server $ServerName -Database $DatabaseName -} - -# ✅ Proper validation before usage -function Process-Data { - param( - [Parameter(Mandatory)] - [ValidateNotNullOrEmpty()] - [string]$ServerName, - - [Parameter(Mandatory)] - [ValidateNotNullOrEmpty()] - [string]$DatabaseName - ) - - # Additional runtime validation for critical operations - if (-not $ServerName.Trim()) { - Write-Error "ServerName cannot be empty or whitespace" -ErrorAction Stop - return - } - - if (-not $DatabaseName.Trim()) { - Write-Error "DatabaseName cannot be empty or whitespace" -ErrorAction Stop - return - } - - # Now safe to use in function calls - $connection = Connect-Database -Server $ServerName.Trim() -Database $DatabaseName.Trim() -} -``` - -### Appropriate Null Checking vs Exception Handling - -```powershell -# VALID: Simple existence check for optional data -$optionalUser = Get-ADUser -Identity $username -ErrorAction SilentlyContinue -if ($optionalUser) { - # Process user if found - Write-Verbose "Found user: $($optionalUser.Name)" -} else { - Write-Verbose "User not found: $username" -} - -# ALSO VALID: Exception-based for critical operations -try { - $criticalUser = Get-ADUser -Identity $username -ErrorAction Stop - # Process critical user data -} catch { - Write-Error "Critical user lookup failed: $($_.Exception.Message)" - throw -} - -# Use null checks when you only care about existence -# Use try/catch when you need detailed error information or when failure should halt execution -``` - -## 🧪 Testing Standards - -### Minimum Testing Requirements - -- **Unit Tests**: Required for all public functions (minimum 80% coverage) -- **Integration Tests**: Required for external dependencies -- **Performance Tests**: Required for functions processing >100 items -- **Security Tests**: Required for credential handling and input validation - -### Pester Test Template - -Targets Pester 6.2+. See [Testing Framework](./instructions/pester.instructions.md) for the -full standards and [Assertion Guide](./instructions/pester-supporting-docs/assertion-guide.md) -for the `Should-*` reference. - -```powershell -#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } - -Describe "Get-ExampleData" -Tag "Unit" { - BeforeAll { - # Pester 6 discovers and runs one file at a time, so each file - # imports its own dependencies. - Import-Module $PSScriptRoot\..\ModuleName.psd1 -Force - - # Mock external dependencies following community patterns - Mock Write-Verbose { } - Mock Get-OptionalData { $MockResult } - } - - Context "Valid Input" { - # -ForEach data is injected as variables; no param() block needed. - # Never use 'Input' as a key - it collides with the automatic variable - # and the test data will not bind. - It "Should return expected result for " -ForEach @( - @{ TestValue = 'ValidValue1'; Expected = 'ExpectedResult1' } - @{ TestValue = 'ValidValue2'; Expected = 'ExpectedResult2' } - ) { - $result = Get-ExampleData -Name $TestValue - - $result | Should-HaveType ([PSCustomObject]) - $result.PSTypeName | Should-Be 'ProcessedData' - $result.Name | Should-Be $Expected + if ($config -isnot [System.Management.Automation.PSCustomObject]) { + $exception = [System.IO.InvalidDataException]::new("'$fullPath' does not contain a JSON object.") + $category = [System.Management.Automation.ErrorCategory]::InvalidData + $errorRecord = [System.Management.Automation.ErrorRecord]::new( + $exception, 'ConfigNotAnObject', $category, $fullPath) + $PSCmdlet.ThrowTerminatingError($errorRecord) } } - Context "Error Handling" { - It "Should handle errors correctly using proper error patterns" { - Mock Get-OptionalData { throw "Test error" } + process { + foreach ($item in $Name) { + $property = $config.PSObject.Properties[$item] + if ($null -eq $property) { + $message = "Configuration value '$item' was not found in '$fullPath'." + $exception = [System.Management.Automation.ItemNotFoundException]::new($message) + $category = [System.Management.Automation.ErrorCategory]::ObjectNotFound + $errorRecord = [System.Management.Automation.ErrorRecord]::new( + $exception, 'ConfigValueNotFound', $category, $item) + $PSCmdlet.WriteError($errorRecord) + continue + } - { Get-ExampleData -Name "TestValue" } | - Should-Throw -ExceptionMessage "*Test error*" + [PSCustomObject]@{ + PSTypeName = 'Example.ConfigValue' + Name = $property.Name + Value = $property.Value + Path = $fullPath + } } } } ``` -## 🏗️ Module Development Standards - -### Module Manifest Requirements +What the template shows: -```powershell -# ModuleName.psd1 -@{ - RootModule = 'ModuleName.psm1' - ModuleVersion = '1.0.0' # Semantic versioning - GUID = 'Generate-New-Guid' - Author = 'Jeffrey Stuhr' - Description = 'Clear description of module purpose and business value' - - # Target PowerShell 7.6 (LTS) for new modules. Use '5.1' + @('Desktop','Core') only when - # the module must run on Windows estates without pwsh installed. - PowerShellVersion = '7.6' - CompatiblePSEditions = @('Core') - - FunctionsToExport = @('Get-Something', 'Set-Something') # Explicit exports only - CmdletsToExport = @() - VariablesToExport = @() - AliasesToExport = @() - - RequiredModules = @( - @{ ModuleName = 'PSFramework'; ModuleVersion = '1.7.270' } - ) - - PrivateData = @{ - PSData = @{ - Tags = @('PowerShell', 'Enterprise', 'Automation') - ProjectUri = 'https://github.com/organization/module' - LicenseUri = 'https://github.com/organization/module/blob/main/LICENSE' - } - } -} -``` - -Before the first publish, read -[Releasing to the PowerShell Gallery](./instructions/module.instructions.md#releasing-to-the-powershell-gallery). -A Gallery version can never be deleted, so the publish stages an allowlist rather than the -repository root, the Gallery's metadata limits are measured locally, no URI key is left empty, and -the release script is written knowing that `-WhatIf` reaches every child scope it calls. - -## 🎯 Community Standards Integration - -### Automatic Validation - -All generated code must automatically comply with: - -- [ ] **Error Handling**: Use `$_` in catch blocks, appropriate null checking patterns, be aware of `throw` behavior - with ErrorAction -- [ ] **Parameter Validation**: Validate parameters before using in function calls, especially for empty/whitespace - values -- [ ] **Approved Verbs**: Only Microsoft-approved verbs from Get-Verb (consistently in ALL examples) -- [ ] **String Operations**: Context-appropriate choice between += and StringBuilder -- [ ] **Modern PowerShell**: Use `[PSCredential]::new()` instead of New-Object; `Install-PSResource` over - `Install-Module` -- [ ] **Version Targeting**: Declared `#requires -Version` / `PowerShellVersion` matches the features actually used, and - is 7.6 unless 5.1 support is a stated requirement -- [ ] **Output Types**: Use descriptive type names or custom classes, not misleading [PSCustomObject] -- [ ] **Documentation**: Proper comment-based help format with opening `<#` marker; exported module - functions instead carry `.EXTERNALHELP -Help.xml` with their content in PlatyPS - Markdown under `docs/` -- [ ] **Help Tooling**: `Microsoft.PowerShell.PlatyPS` 1.0.3+ only — never the retired `platyPS` - 0.14 cmdlets (`New-MarkdownHelp`, `New-ExternalHelp`, `Get-HelpPreview`) -- [ ] **Performance**: Loop output assigned directly where possible; no `ArrayList`; `+=` only where the target version - makes it safe -- [ ] **Error Termination**: Use `Write-Error -ErrorAction Stop` instead of bare `throw` when ErrorAction compliance is - needed - -## 🔍 Quality Standards - -### Code Review Checklist - -- ✅ Uses approved PowerShell verbs and follows community naming conventions consistently -- ✅ Implements proper error handling with `$_` usage and appropriate null checking -- ✅ Includes comprehensive help content — comment-based help for private and standalone functions, - PlatyPS Markdown plus `.EXTERNALHELP` for exported module functions -- ✅ Uses context-appropriate string operations and performance patterns -- ✅ Follows modern PowerShell practices (PSCredential constructor, appropriate validation) -- ✅ Includes appropriate Pester tests with community testing patterns -- ✅ Uses descriptive output types instead of misleading [PSCustomObject] declarations -- ✅ Organizes troubleshooting docs in `./Troubleshooting/` folder -- ✅ Maintains cross-platform compatibility considerations -- ✅ Uses semantic versioning for modules -- ✅ Implements structured logging for enterprise environments -- ✅ Avoids community-identified anti-patterns and outdated practices -- ✅ Implements correlation tracking -- ✅ Follows security best practices -- ✅ Includes appropriate performance optimizations -- ✅ Supports enterprise compliance requirements - -### Validation Commands - -Use these prompts for quality assurance: - -- `/validate-standards` - Check against community standards -- `/security-review` - Security and compliance analysis -- `/code-analysis` - Comprehensive quality review -- `/optimize-performance` - Performance optimization review - -## 📚 Comprehensive Reference Documentation - -### Quick Reference Links - -- **Community Standards**: Reference `.github/instructions/community-standards.instructions.md` -- **Style Guide**: Reference `.github/instructions/style-enforcement.instructions.md` -- **Troubleshooting**: Always organized in `./Troubleshooting/` folder structure -- **Testing**: Use Pester 6.2+ with comprehensive coverage requirements -- **Help Docs**: Use Microsoft.PowerShell.PlatyPS 1.0.3+ — Markdown in `docs/`, MAML in `en-US/` -- **Security**: Implement defense-in-depth with community-approved patterns -- **Performance**: Optimize using community-identified best practices and expert feedback - -### Detailed Guidance - -For specialized scenarios, reference these instruction files: - -- **Version Baseline**: [Target Versions and Breaking Changes](./instructions/powershell-version.instructions.md) -- **Security & Compliance**: [Security Guidelines](./instructions/securitycompliance.instructions.md) -- **Testing Standards**: [Testing Framework](./instructions/pester.instructions.md) -- **Architecture Design**: [Design Patterns](./instructions/architecturedesign.instructions.md) -- **Module Development**: [Module Standards](./instructions/module.instructions.md) -- **CI/CD Integration**: [Pipeline Setup](./instructions/cicd.instructions.md) -- **Error Handling**: [Logging Framework](./instructions/errorsandlogs.instructions.md) -- **Documentation**: [README Standards](./instructions/readme.instructions.md) -- **Code Analysis**: [Quality Standards](./instructions/analyze.instructions.md) -- **Comment Standards**: [Help Content Standards](./instructions/comments.instructions.md) -- **Help Generation**: [PlatyPS Documentation](./instructions/platyps.instructions.md) -- **Community Standards**: [Best Practices Integration](./instructions/community-standards.instructions.md) -- **Style Enforcement**: [Style Guide Compliance](./instructions/style-enforcement.instructions.md) - -### Worked Examples - -Prefer matching these over inventing a shape. Each is complete, runs, and passes the quality gates -described above: - -| Need | Example | -| --- | --- | -| A complete advanced function | [Basic-Function-Example.ps1](../powershell-standards/Examples/Basic-Function-Example.ps1) | -| Module layout and export boundary | [Module-Structure-Example](../powershell-standards/Examples/Module-Structure-Example/) | -| Pester 6 tests, including private functions | [Module-Structure-Example/Tests](../powershell-standards/Examples/Module-Structure-Example/Tests/) | -| Mocking CIM and typed parameters | [Testing-Examples](../powershell-standards/Examples/Testing-Examples/) | -| A module template to copy | [Templates/Powershell-Module](https://github.com/fadwen/ai-powershell-standards/tree/main/Templates/Powershell-Module) | - -[Test-QualityGates.ps1](https://github.com/fadwen/ai-powershell-standards/blob/main/Documentation/Anti-Patterns/Test-QualityGates.ps1) -is the exception: it intentionally violates these standards so the gates have something to catch. -Never use it as a model. It is not mirrored into consuming projects. - -### Implementation Documentation - -These live in the standards repository only and are not mirrored into consuming projects: - -- [Implementation Guide](https://github.com/fadwen/ai-powershell-standards/blob/main/Documentation/Implementation-Guide.md): - step-by-step setup and adoption -- [PowerShell Best Practices](https://github.com/fadwen/ai-powershell-standards/blob/main/Documentation/PowerShell-Best-Practices.md): - comprehensive community standards -- [Enterprise Extensions](https://github.com/fadwen/ai-powershell-standards/blob/main/Documentation/Enterprise-Extensions.md): - organizational customizations -- [Troubleshooting Guides](https://github.com/fadwen/ai-powershell-standards/tree/main/Troubleshooting): - organized problem-solving resources - ---- - -_This file provides core standards automatically applied by GitHub Copilot, integrating established -PowerShell community best practices with expert feedback corrections. For detailed guidance on -specific topics, reference the individual instruction files and comprehensive documentation -structure._ +- Help is the first thing in the body and covers every parameter, the input, and the output. +- `begin` does the work that must succeed once. Its `catch` ends the function with + `$PSCmdlet.ThrowTerminatingError($_)`, which keeps the original error. +- A problem the function detects itself becomes an `ErrorRecord` with its own ID and category. +- `process` handles each item. A missing item is reported with `$PSCmdlet.WriteError()` and the loop + continues, so the caller decides with `-ErrorAction` whether that stops the work. +- Each result is written to the pipeline as it is produced, with a named type, and outside any `try` + block. diff --git a/.github/instructions/analyze.instructions.md b/.github/instructions/analyze.instructions.md deleted file mode 100644 index a937358..0000000 --- a/.github/instructions/analyze.instructions.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -applyTo: "**/*.ps1,**/*.psm1,**/*.psd1" -description: 'Performs comprehensive PowerShell code analysis for quality, security, and performance' ---- - -# PowerShell Code Analysis - -Analyze the provided PowerShell code using enterprise-grade analysis standards. Perform a comprehensive review covering -code quality, security, performance, and compliance with organizational standards. - -## Analysis Framework - -Execute the following analysis components: - -### 1. Code Quality Assessment - -- **PSScriptAnalyzer Validation**: Check against all standard rules plus enterprise-specific rules -- **Best Practices Compliance**: Verify adherence to PowerShell development standards -- **Code Structure**: Evaluate function design, parameter validation, and pipeline efficiency -- **Documentation Quality**: Assess comment-based help completeness and accuracy - -### 2. Security Analysis - -- **Credential Leak Detection**: Scan for hardcoded passwords, API keys, or sensitive data -- **Input Validation**: Verify all user inputs are properly validated and sanitized -- **Path Traversal Protection**: Check for unsafe file path handling -- **Injection Prevention**: Identify potential code injection vulnerabilities - -### 3. Performance Evaluation - -- **Memory Usage**: Assess memory management and resource disposal -- **Pipeline Optimization**: Evaluate pipeline usage and efficiency -- **Scalability**: Review code for performance with large datasets -- **Algorithm Efficiency**: Identify optimization opportunities - -### 4. Compliance Verification - -- **PowerShell Standards**: Verify compliance with approved verbs and naming conventions -- **File Organization**: Check adherence to standardized folder structure -- **Testing Coverage**: Evaluate test completeness and quality -- **Error Handling**: Assess error handling patterns and correlation tracking - -## Required Output Format - -Provide analysis results in this structured format: - -### 🚨 Critical Issues (Must Fix) - -- List any critical security vulnerabilities or breaking errors -- Include specific line numbers and remediation steps - -### ⚠️ High Priority Issues - -- Security concerns that should be addressed before production -- Performance bottlenecks affecting scalability -- Standards violations impacting maintainability - -### 📋 Medium Priority Recommendations - -- Code quality improvements -- Performance optimizations -- Best practice adherence - -### 💡 Low Priority Suggestions - -- Style improvements -- Documentation enhancements -- Optional optimizations - -### 📊 Analysis Summary - -- Overall code quality score (1-100) -- Security risk level (Low/Medium/High/Critical) -- Performance rating (Poor/Fair/Good/Excellent) -- Standards compliance percentage - -## Specific Checks to Perform - -1. **Verify approved PowerShell verbs** are used for all functions -2. **Check for correlation IDs** in error handling and logging -3. **Validate parameter attributes** include proper validation -4. **Ensure troubleshooting documentation** references exist in `./Troubleshooting/` folder -5. **Confirm security practices** follow established patterns from copilot-instructions.md -6. **Review test coverage** and suggest missing test scenarios -7. **Check cross-platform compatibility** considerations - -## Remediation Guidance - -For each issue identified: - -- Provide specific fix recommendations with code examples -- Reference relevant troubleshooting documentation in `./Troubleshooting/` folder -- Suggest appropriate test cases to validate fixes -- Include performance impact assessment where applicable - -## Integration Notes - -- Flag any violations of the standardized file organization structure -- Identify missing components (tests, documentation, error handling) -- Suggest improvements for CI/CD pipeline integration -- Recommend security scanning tools integration points - -Focus on actionable feedback that improves code quality, security posture, and maintainability while ensuring compliance -with enterprise PowerShell development standards. diff --git a/.github/instructions/architecturedesign.instructions.md b/.github/instructions/architecturedesign.instructions.md deleted file mode 100644 index 5d4afba..0000000 --- a/.github/instructions/architecturedesign.instructions.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -applyTo: "**/*.psm1,**/module.json,**/README.md" -description: 'Designs enterprise-grade PowerShell architecture using proven design patterns and best practices' ---- - -# PowerShell Architecture and Design Assistant - -Help design scalable, maintainable PowerShell solutions using enterprise architecture patterns and design principles. -Provide comprehensive architectural guidance from initial design through implementation. - -## Architecture Assessment - -When reviewing or designing PowerShell solutions, evaluate and implement: - -### Core Architectural Principles - -- **Separation of Concerns**: Clear separation between business logic, data access, and presentation -- **Single Responsibility**: Each module and function serves a specific, well-defined purpose -- **Dependency Injection**: Loose coupling through dependency inversion patterns -- **Configuration-Driven Design**: Externalized configuration for flexibility -- **Event-Driven Architecture**: Asynchronous communication patterns -- **API-First Design**: Well-defined interfaces and contracts - -### Design Pattern Implementation - -Recommend and implement appropriate design patterns: - -#### Factory Pattern - -- Use for complex object creation scenarios -- Implement when multiple object types share common interfaces -- Provide configuration-driven object instantiation - -#### Strategy Pattern - -- Apply for algorithm selection and business rule variation -- Enable runtime behavior switching -- Support A/B testing and feature flags - -#### Observer Pattern - -- Implement for event-driven functionality -- Enable loose coupling between components -- Support monitoring and alerting scenarios - -#### Repository Pattern - -- Abstract data access layers -- Enable testability through mocking -- Support multiple data sources - -## Architecture Design Process - -### 1. Requirements Analysis - -Ask these key questions to understand the solution needs: - -- What is the primary business purpose and value? -- What are the performance and scalability requirements? -- What security and compliance requirements apply? -- What external systems need integration? -- What is the expected user base and usage patterns? - -### 2. Component Design - -For each major component, define: - -- **Purpose and Responsibilities**: Single, clear responsibility -- **Interface Contracts**: Input/output specifications -- **Dependencies**: External requirements and services -- **Error Handling**: Failure modes and recovery strategies -- **Performance Characteristics**: Expected load and response times - -### 3. Integration Architecture - -Design integration patterns for: - -- **REST API Integration**: HTTP client patterns with retry logic -- **Database Connectivity**: Connection pooling and transaction management -- **Message Queues**: Asynchronous processing patterns -- **File System Operations**: Secure file handling with proper permissions -- **External Service Dependencies**: Circuit breaker and timeout patterns - -### 4. Security Architecture - -Implement security-by-design principles: - -- **Input Validation**: Comprehensive sanitization at all entry points -- **Authentication/Authorization**: Role-based access control -- **Credential Management**: SecretManagement integration -- **Audit Logging**: Comprehensive security event tracking -- **Data Protection**: Encryption at rest and in transit - -## Implementation Guidance - -### Module Architecture - -Design PowerShell modules with: - -```text -ModuleName/ -├── Public/ # Exported functions -├── Private/ # Internal functions -├── Classes/ # PowerShell classes and types -├── Configuration/ # Config templates and schemas -├── Tests/ # Comprehensive test suite -└── Troubleshooting/ # Organized troubleshooting docs -``` - -### Class Design Patterns - -Implement PowerShell classes with: - -- Constructor overloads for different initialization scenarios -- Validation attributes for property constraints -- Interface-like abstract base classes for contracts -- Proper disposal patterns for resource management - -### Configuration Management - -Design hierarchical configuration systems: - -- Environment-specific configuration files -- Secure credential storage integration -- Configuration validation and schema enforcement -- Hot-reload capabilities where appropriate - -### Error Handling Architecture - -Implement comprehensive error handling: - -- Custom exception hierarchies for different error types -- Correlation ID tracking throughout the call stack -- Structured logging with appropriate detail levels -- Retry mechanisms with exponential backoff -- Circuit breaker patterns for external dependencies - -## Performance Architecture - -### Scalability Patterns - -- **Parallel Processing**: ForEach-Object -Parallel for PowerShell 7+. A parallel block, a runspace - worker, and a `Start-Job` body all start without the caller's `$script:` state; pass what they need - through `$using:`, a parameter, or `-ArgumentList`, and keep a contract test that refuses a `$script:` - read inside one. Measure before adopting: a cmdlet that keeps one session per process, such as the - RSAT `ActiveDirectory` module, fails under runspaces in ways a process per batch does not -- **Batch Processing**: Chunked operations for large datasets -- **Streaming**: Pipeline-based processing for memory efficiency -- **Caching**: Multi-level caching strategies -- **Connection Pooling**: Efficient resource utilization - -### Memory Management - -- Explicit disposal of IDisposable objects -- StringBuilder for string concatenation -- Proper COM object cleanup -- Garbage collection optimization - -## Output Deliverables - -Provide the following architectural artifacts: - -### 1. Architecture Diagram - -- Component relationships and dependencies -- Data flow patterns -- Integration points -- Security boundaries - -### 2. Design Document - -- Component specifications -- Interface definitions -- Security model -- Performance characteristics - -### 3. Implementation Roadmap - -- Development phases and milestones -- Dependency order for implementation -- Testing strategy -- Deployment approach - -### 4. Code Templates - -- Module structure scaffold -- Class design templates -- Configuration patterns -- Test frameworks - -## Quality Validation - -Ensure the architecture design meets: - -- **Maintainability**: Clear separation of concerns and documentation -- **Testability**: Dependency injection and mocking capabilities -- **Security**: Defense-in-depth and secure-by-design principles -- **Performance**: Scalability and efficiency requirements -- **Compliance**: Organizational standards and regulatory requirements - -## Integration Considerations - -Address enterprise integration requirements: - -- CI/CD pipeline compatibility -- Monitoring and alerting integration -- Log aggregation and analysis -- Configuration management systems -- Deployment automation -- Backup and disaster recovery - -When providing architecture guidance, always reference the established PowerShell development standards and ensure all -designs support the standardized troubleshooting documentation structure in `./Troubleshooting/` folders. diff --git a/.github/instructions/cicd.instructions.md b/.github/instructions/cicd.instructions.md deleted file mode 100644 index 256b0f1..0000000 --- a/.github/instructions/cicd.instructions.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -applyTo: "**/.github/workflows/*.yml,**/.github/workflows/*.yaml,**/azure-pipelines.yml,**/build.ps1,**/deploy.ps1" -description: 'Sets up comprehensive CI/CD pipelines for PowerShell projects with automated testing and deployment' ---- - -# PowerShell CI/CD Pipeline Configuration - -Create robust CI/CD pipelines for PowerShell projects with automated testing, quality gates, security scanning, and -deployment automation. Support multiple platforms while maintaining enterprise standards. - -## Pipeline Requirements Assessment - -First, determine the pipeline requirements: - -### Project Information Needed - -- **Platform Preference**: Azure DevOps, GitHub Actions, GitLab CI, or Jenkins -- **PowerShell Versions**: PowerShell 7.6 (LTS, default), or 5.1 + 7.6 when Windows PowerShell support is required. - Retire 7.4/7.5-only matrices before 10-Nov-2026, when both reach end of support -- **Target Environments**: Development, Testing, Staging, Production -- **Deployment Targets**: PowerShell Gallery, internal repositories, or direct deployment -- **Security Requirements**: Code signing, credential management, compliance scanning - -### Quality Gates to Implement - -- **Code Quality**: PSScriptAnalyzer validation with zero errors -- **Testing**: Minimum 80% code coverage with Pester tests -- **Security**: Credential scanning and vulnerability assessment -- **Performance**: Execution time and memory usage baselines -- **Documentation**: README and troubleshooting documentation validation -- **Help Docs**: PlatyPS Markdown structure valid, no placeholders, no drift against exported commands - -## Pipeline Configuration - -### Azure DevOps Pipeline - -Generate complete Azure DevOps YAML pipeline with: - -```yaml -# Key components to include: -stages: - - Build and Validate - - Security Scanning - - Package Creation - - Environment Deployments - - PowerShell Gallery Publishing -``` - -**Required Pipeline Features:** - -- Multi-stage pipeline with approval gates -- Parallel job execution for different PowerShell versions -- Artifact management and retention -- Environment-specific variable groups -- Integration with Azure Key Vault for secrets -- Automated rollback on deployment failure - -### GitHub Actions Workflow - -Create comprehensive GitHub Actions workflow including: - -```yaml -# Essential workflow components: -jobs: - - build-and-test (matrix strategy for PS versions) - - security-scan - - package-artifact - - deploy-environments - - publish-gallery -``` - -**Required Workflow Features:** - -- Matrix builds for PowerShell version compatibility -- Conditional execution based on branch and tags -- Secret management with GitHub Secrets -- Artifact upload and download between jobs -- Environment protection rules -- Integration with third-party security tools - -### Quality Gate Implementation - -#### Code Quality Validation - -```powershell -# PSScriptAnalyzer execution with enterprise rules -$analysisResults = Invoke-ScriptAnalyzer -Path . -Recurse -Settings PSGallery -if ($analysisResults) { - Write-Error "PSScriptAnalyzer issues found: $($analysisResults.Count)" - exit 1 -} -``` - -`-Settings` takes any of the presets PSScriptAnalyzer ships, so the formatting rules in -[style-enforcement.instructions.md](./style-enforcement.instructions.md) do not need a hand-written -settings file. `CodeFormattingOTBS` already configures them: - -```powershell -# One True Brace Style, 4-space indentation, operator and separator spacing, -# assignment alignment, and cmdlet casing - all built in -Invoke-ScriptAnalyzer -Path . -Recurse -Settings CodeFormattingOTBS -``` - -Run both when a team wants correctness and formatting checked together. The one documented rule no -preset covers is the 115-character line limit; add `PSAvoidLongLines` explicitly if it matters to -the team. - -Which presets to adopt is the consuming team's decision - these standards describe the practices, -not the audit configuration. - -#### Testing and Coverage - -```powershell -# Pester 6 test execution with coverage -Import-Module Pester -MinimumVersion 6.2.0 -Force - -$pesterConfig = New-PesterConfiguration -$pesterConfig.Run.Path = './Tests' -$pesterConfig.Run.PassThru = $true -$pesterConfig.CodeCoverage.Enabled = $true -$pesterConfig.CodeCoverage.Path = './Public/*.ps1', './Private/*.ps1' -# CoveragePercentTarget, not Threshold - CodeCoverage.Threshold does not exist -$pesterConfig.CodeCoverage.CoveragePercentTarget = 80 - -$result = Invoke-Pester -Configuration $pesterConfig - -# A file that fails discovery contributes 0 to FailedCount - check both -if ($result.FailedCount -gt 0 -or $result.FailedContainersCount -gt 0) { - Write-Error "Tests failed: $($result.FailedCount) test(s), $($result.FailedContainersCount) container(s)" - exit 1 -} - -# CoveragePercentTarget is the reported target; enforce the gate yourself -$coverage = [math]::Round($result.CodeCoverage.CoveragePercent, 2) -if ($coverage -lt 80) { - Write-Error "Code coverage $coverage% is below the 80% target" - exit 1 -} -``` - -See [Pester instructions](./pester.instructions.md) for the full testing standards. - -#### Security Scanning - -```powershell -# Credential and security scanning -$securityScan = Test-ScriptSecurity -Path . -RecursiveSearch -if ($securityScan.HighRiskFindings) { - Write-Error "Security vulnerabilities detected" - exit 1 -} -``` - -## Deployment Strategies - -### Environment Promotion - -Design deployment pipeline with: - -- **Development**: Automatic deployment on feature branch commits -- **Testing**: Automatic deployment on main branch commits -- **Staging**: Manual approval required, mirrors production -- **Production**: Requires multiple approvals and change management - -### Blue-Green Deployment - -Implement zero-downtime deployment strategy: - -- Deploy to inactive environment slot -- Run smoke tests and health checks -- Switch traffic to new deployment -- Keep previous version for rapid rollback - -### PowerShell Gallery Publishing - -Configure automated publishing with: - -- Semantic versioning based on commit messages -- Pre-release versions for development branches -- Release notes generation from changelog -- API key management through secure secret storage -- A release rehearsal, `Publish-Module.ps1 -WhatIf`, that stages the allowlisted package, imports it - in a fresh process, verifies exports and help, measures the Gallery's metadata limits, and stops - before the upload. Run it on every pull request; the tag-driven release re-runs it and publishes. -- The rules the rehearsal exists to enforce are in - [module.instructions.md](./module.instructions.md#releasing-to-the-powershell-gallery): never - publish the repository root, the `ReleaseNotes`, `Description` and tag limits, no empty URI keys, - and `$WhatIfPreference` reaching every child scope of the release script. - -## Security Integration - -### Code Signing - -Set up automated code signing: - -- Certificate management in secure storage -- Timestamp server configuration -- Validation of signature integrity -- Support for different certificate types per environment - -### Credential Management - -Implement secure credential handling: - -- Integration with Azure Key Vault or GitHub Secrets -- No hardcoded credentials in pipeline files -- Secure injection of credentials at runtime -- Audit logging of credential access - -### Vulnerability Scanning - -Configure security scanning tools: - -- Dependency vulnerability scanning -- Static code analysis for security issues -- Container scanning (if using containerized builds) -- Integration with security monitoring systems - -## Performance Monitoring - -### Build Performance - -Monitor and optimize: - -- Build execution time tracking -- Test execution duration monitoring -- Artifact size optimization -- Resource usage monitoring - -### Deployment Metrics - -Track deployment success: - -- Deployment frequency and duration -- Failure rates and root causes -- Mean time to recovery (MTTR) -- Change failure rate - -## Troubleshooting Integration - -### Pipeline Diagnostics - -Implement comprehensive logging: - -- Correlation IDs throughout pipeline execution -- Structured logging with appropriate detail levels -- Integration with centralized logging systems -- Error categorization and automated triage - -### Documentation Generation - -Automate troubleshooting documentation: - -- Generate pipeline status reports -- Create deployment summaries -- Update troubleshooting guides in `./Troubleshooting/` folder -- Maintain runbook documentation - -### Command Help Gate - -Command help is built and validated in the pipeline, not by hand. Full mechanics in -[platyps.instructions.md](./platyps.instructions.md). - -```powershell -# Pull request: validate the committed Markdown and fail on drift -#Requires -Modules @{ ModuleName = 'Microsoft.PowerShell.PlatyPS'; ModuleVersion = '1.0.3' } - -Import-Module ./ModuleName.psd1 -Force - -# 1. Structure -Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | - Where-Object Filetype -match 'CommandHelp' | - Test-MarkdownCommandHelp -Path {$_.FilePath} -DetailView - -# 2. No unfilled templates -$unfilled = Select-String -Path ./docs/ModuleName/*.md -Pattern '\{\{\s*Fill in' -List -if ($unfilled) { - Write-Error "Unfilled help placeholders in: $(($unfilled.Path | Split-Path -Leaf) -join ', ')" -ErrorAction Stop -} - -# 3. Drift - every exported command documented, nothing documented that is gone -$documented = (Get-ChildItem ./docs/ModuleName/*.md).BaseName | Where-Object { $_ -ne 'ModuleName' } -$exported = (Get-Module ModuleName).ExportedFunctions.Keys -$drift = @($exported | Where-Object { $_ -notin $documented }) + - @($documented | Where-Object { $_ -notin $exported }) -if ($drift) { - Write-Error "Help is out of sync with exported commands: $($drift -join ', ')" -ErrorAction Stop -} -``` - -The `package-artifact` job builds MAML into the module before packaging, so the published module -always ships current help: - -```powershell -Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | - Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - Export-MamlCommandHelp -OutputFolder ./maml -Force - -$cultureDir = Join-Path $ModuleOutputPath 'en-US' -New-Item -Path $cultureDir -ItemType Directory -Force | Out-Null -Copy-Item ./maml/ModuleName/ModuleName-Help.xml -Destination $cultureDir -Force -``` - -Install PlatyPS in the runner alongside the other build dependencies: - -```yaml -- name: Install build modules - shell: pwsh - run: | - Install-PSResource -Name Pester, PSScriptAnalyzer, Microsoft.PowerShell.PlatyPS -TrustRepository -``` - -## Configuration Templates - -Provide ready-to-use pipeline configurations for: - -### Basic PowerShell Module Pipeline - -- Simple module with unit tests -- PowerShell Gallery publishing -- Multi-version compatibility testing - -### Enterprise Application Pipeline - -- Complex multi-module solution -- Integration testing with external dependencies -- Security compliance validation -- Multi-environment deployment - -### Script Library Pipeline - -- Collection of standalone PowerShell scripts -- Individual script validation and testing -- Centralized distribution and versioning - -## Best Practices Implementation - -### Pipeline as Code - -- Version control all pipeline definitions -- Use templates and reusable components -- Implement proper change management -- Maintain pipeline documentation - -### Monitoring and Alerting - -- Pipeline execution monitoring -- Failure notification systems -- Performance trend analysis -- SLA tracking and reporting - -### Compliance and Governance - -- Audit trail maintenance -- Change approval workflows -- Security scanning integration -- Regulatory compliance validation - -## Output Deliverables - -Generate complete pipeline configuration including: - -1. **Pipeline Definition Files**: YAML/JSON configurations ready for deployment -2. **Environment Configuration**: Variable templates and secret management setup -3. **Quality Gate Scripts**: PowerShell scripts for validation and testing -4. **Deployment Scripts**: Automated deployment and rollback procedures -5. **Documentation**: Pipeline setup guide and troubleshooting procedures -6. **Monitoring Configuration**: Dashboards and alerting rules - -Ensure all generated configurations follow enterprise PowerShell development standards and integrate with the -established troubleshooting documentation structure in `./Troubleshooting/` folders. diff --git a/.github/instructions/comments.instructions.md b/.github/instructions/comments.instructions.md deleted file mode 100644 index 58c9c46..0000000 --- a/.github/instructions/comments.instructions.md +++ /dev/null @@ -1,303 +0,0 @@ ---- -applyTo: "**/*.ps1,**/*.psm1" -description: 'Defines help content standards for PowerShell functions - comment-based help and PlatyPS Markdown' ---- - -# PowerShell Help Content Standards - -Generate comprehensive, enterprise-grade help for PowerShell functions that serves as both technical -documentation and business communication. Create help that supports automatic README generation and provides full -`Get-Help` functionality. - -## Where Help Lives - -This file defines **what good help content contains**. Where that content is written depends on -whether the function is exported: - -| Function | Help lives in | Notes | -| --- | --- | --- | -| Exported (`Public/`) in a module | PlatyPS Markdown under `docs/ModuleName/` | The `.ps1` keeps only `# .EXTERNALHELP` plus a one-line `.SYNOPSIS` | -| Private (`Private/`) in a module | Full comment-based help in the `.ps1` | PlatyPS never sees these - the comment block is the only documentation | -| Standalone script or function | Full comment-based help in the `.ps1` | No module, no MAML, no PlatyPS | - -Every standard below — description structure, per-parameter content, three progressive examples, -enterprise notes — applies in all three cases. Only the file it is typed into changes. - -For the generation, update, and build mechanics, see -[platyps.instructions.md](./platyps.instructions.md). Do not add detail to a public function's -comment block: `.EXTERNALHELP` makes `Get-Help` ignore it, so the effort is invisible to users and -becomes a second copy that drifts. - -## Help Generation Requirements - -> **Worked example**: -> [Basic-Function-Example.ps1](../../powershell-standards/Examples/Basic-Function-Example.ps1) carries a -> complete help block in the form described here - synopsis, description, per-parameter text, -> multiple examples with expected output, and `.NOTES` with troubleshooting links but no change -> history. It is a standalone function, so the whole block lives in the `.ps1`. In a module, that -> same content is what belongs in the command's Markdown file. - -### Mandatory Sections - -Generate complete comment-based help including all required sections: - -#### .SYNOPSIS - -- Use approved PowerShell verbs (Get, Set, New, Remove, etc.) -- Maximum 80 characters -- Focus on primary action and business value -- Avoid technical jargon unless necessary - -#### .DESCRIPTION - -Structure with multiple audiences in mind: - -- **Core Functionality**: Primary purpose and key features -- **Business Value**: Why this function exists and organizational benefits -- **Use Cases**: Common scenarios and applications -- **Dependencies**: Required modules, permissions, and system requirements -- **Performance Considerations**: Expected execution time and resource usage -- **Side Effects**: Any system or environment changes - -#### .PARAMETER - -For each parameter, provide: - -- **Data Type**: Explicit .NET type with constraints -- **Mandatory Status**: Clear indication if required -- **Pipeline Support**: ByValue, ByPropertyName capabilities -- **Validation Rules**: Constraints, acceptable values, patterns -- **Business Context**: Why this parameter exists and when to use it -- **Examples**: Sample valid values and usage patterns - -#### .EXAMPLE - -Provide minimum three progressive examples: - -1. **Basic Usage**: Simplest functional example with expected output -2. **Advanced Scenario**: Multiple parameters with real-world context -3. **Pipeline Integration**: Shows integration with other PowerShell commands - -For each example include: - -- Clear description of the scenario -- Expected output or behavior -- Business use case or context -- Duration estimates where relevant - -#### .INPUTS/.OUTPUTS - -- Document .NET types for pipeline compatibility -- Describe object structure and properties -- Include usage guidance for returned objects -- Specify when different output types are returned - -#### .NOTES - -Comprehensive metadata including: - -- **Author Information**: Name, blog, LinkedIn -- **Security Considerations**: Permissions, data handling, compliance notes -- **Performance Characteristics**: Benchmarks and optimization notes -- **Troubleshooting References**: Links to documentation in `./Troubleshooting/` folder -- **Known Limitations**: Current constraints and workarounds - -#### .LINK - -Include relevant reference links: - -- Online documentation URLs -- Related function references -- Microsoft documentation links -- Troubleshooting guides in `./Troubleshooting/` folder -- Enterprise standards documentation - -## Help Content Standards - -### Business-Focused Language - -- Articulate clear business value in DESCRIPTION -- Use business scenarios in examples -- Explain ROI and organizational impact -- Reference compliance and governance benefits - -### Technical Accuracy - -- Validate all code examples are functional -- Ensure parameter descriptions match actual validation -- Verify .NET types are correct -- Test all usage examples before documenting - -### Enterprise Integration - -- Reference correlation ID usage for tracing -- Document integration with organizational systems -- Include security and compliance considerations -- Reference established troubleshooting procedures - -### Performance Documentation - -- Include typical execution times -- Document memory usage characteristics -- Specify scalability considerations -- Provide optimization recommendations - -## Enhanced Help Patterns - -### Complex Parameter Documentation - -```powershell -.PARAMETER ComputerName - [String[]] (Mandatory: Yes, Pipeline: ByValue, ByPropertyName) - - Specifies one or more target computer names for data collection. - - VALIDATION RULES: - - Must be valid computer names (NetBIOS or FQDN) - - Maximum 50 computers per execution - - Computers must be reachable via WinRM - - BUSINESS CONTEXT: - Used to target specific servers for monitoring. Consider grouping - servers by function (web servers, database servers) for meaningful reports. - - EXAMPLES: - - Single server: "SERVER01" - - Multiple servers: "SERVER01", "SERVER02", "SERVER03" - - Domain servers: "server01.contoso.com" -``` - -### Comprehensive Example Format - -```powershell -.EXAMPLE - PS> Get-ServerHealth -ComputerName "SERVER01" -IncludePerformance - - DESCRIPTION: Basic health check with performance metrics - OUTPUT: Health status object with CPU, memory, and disk information - DURATION: Approximately 30 seconds - USE CASE: Daily server health verification during morning checks - -.EXAMPLE - PS> Get-ADComputer -Filter "OperatingSystem -like '*Server*'" | - Select-Object -ExpandProperty Name | - Get-ServerHealth -Threshold 80 -ExportReport - - DESCRIPTION: Enterprise pipeline integration with Active Directory - OUTPUT: Health reports for all domain servers with alerting - BUSINESS CASE: Automated infrastructure monitoring and compliance reporting - INTEGRATION: Combines AD discovery with health monitoring -``` - -### Enterprise Notes Section - -```powershell -.NOTES - Author: Jeffrey Stuhr - Blog: https://www.techbyjeff.net - LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/ - PowerShell Version: 7.6 (LTS), or Windows PowerShell 5.1 - - No change history here - git records it, and a hand-maintained log in .NOTES - goes stale the first time someone forgets to update it. - - SECURITY CONSIDERATIONS: - - Requires local administrator privileges on target servers - - Uses WinRM for remote connectivity (ensure proper firewall configuration) - - Performance data may contain sensitive infrastructure information - - Credential handling follows secure PowerShell practices - - PERFORMANCE CHARACTERISTICS: - - Linear scaling: approximately 20-30 seconds per server - - Memory footprint: ~5MB per server in monitoring queue - - Network bandwidth: minimal (WMI query overhead only) - - TROUBLESHOOTING RESOURCES: - - Connectivity issues: .\Troubleshooting\Connectivity\WinRM-Configuration.md - - Performance problems: .\Troubleshooting\Performance\Large-Scale-Monitoring.md - - Security errors: .\Troubleshooting\Security\Admin-Rights-Setup.md - - COMPLIANCE NOTES: - - SOX compliance: Audit trail maintained in structured logs - - GDPR considerations: Performance data may contain system identifiers - - Data retention: Follows organizational policy (default: 90 days) -``` - -## Quality Validation - -### Content Verification Checklist - -Ensure generated help includes: - -- [ ] Business value clearly articulated in .DESCRIPTION -- [ ] All parameters documented with validation rules and business context -- [ ] Minimum 3 examples with progressive complexity -- [ ] Performance characteristics documented -- [ ] Security considerations comprehensive -- [ ] Troubleshooting references point to `./Troubleshooting/` folder -- [ ] No change history in .NOTES - version control already records it -- [ ] Cross-platform compatibility notes where applicable -- [ ] Content is in the right file: Markdown under `docs/` for exported functions, the `.ps1` comment - block for private functions and standalone scripts -- [ ] Public functions carry `.EXTERNALHELP -Help.xml` and no duplicated detail in the - comment block - -### Technical Accuracy Validation - -- [ ] All code examples tested and functional -- [ ] Parameter types and validation match function definition -- [ ] Output types accurately documented -- [ ] Links reference existing files and documentation -- [ ] Performance metrics realistic and measured - -## Integration Requirements - -### README Generation Support - -Structure help to support automatic README generation: - -- Clear section headings for extraction -- Business-focused language suitable for stakeholders -- Complete usage examples ready for documentation -- Integration scenarios for enterprise environments - -### Get-Help Compatibility - -Ensure full PowerShell Get-Help functionality: - -- All standard help sections properly formatted -- Parameter help accessible via Get-Help -Parameter -- Examples displayable via Get-Help -Examples -- Detailed help available via Get-Help -Detailed - -### Keyword to Markdown Mapping - -The sections above are named for comment-based help keywords. In PlatyPS Markdown they are headings. -The content requirements are identical; only the syntax differs: - -| Comment-based help | PlatyPS Markdown | -| --- | --- | -| `.SYNOPSIS` | `## SYNOPSIS` | -| `.DESCRIPTION` | `## DESCRIPTION` | -| `.PARAMETER Name` | `### -Name` under `## PARAMETERS` | -| `.EXAMPLE` | `### Example 1: ` under `## EXAMPLES` | -| `.INPUTS` / `.OUTPUTS` | `## INPUTS` / `## OUTPUTS` | -| `.NOTES` | `## NOTES` | -| `.LINK` | `## RELATED LINKS` | -| _(no equivalent)_ | `## ALIASES` - Markdown only; delete the section if the command has none | - -Parameter attribute tables, syntax blocks, and the common-parameter block are generated by PlatyPS -from the function definition. Never hand-write or hand-correct them in the Markdown — fix the -function signature and re-run `Update-MarkdownCommandHelp`. - -### Enterprise Standards Compliance - -- Reference established PowerShell development standards -- Include correlation ID usage examples -- Document integration with organizational monitoring systems -- Maintain consistency with troubleshooting documentation structure - -When generating help content, always follow the enterprise PowerShell development standards and ensure all -troubleshooting references point to properly organized documentation in the `./Troubleshooting/` folder structure. -Write that content into the PlatyPS Markdown for exported functions and into the comment block for -everything else - see [platyps.instructions.md](./platyps.instructions.md). diff --git a/.github/instructions/community-standards.instructions.md b/.github/instructions/community-standards.instructions.md deleted file mode 100644 index 06f2b19..0000000 --- a/.github/instructions/community-standards.instructions.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -applyTo: "**/*.ps1,**/*.psm1,**/*.psd1" -description: 'PowerShell community best practices and style guide integration' ---- - -# PowerShell Community Standards Integration - -Integrate established PowerShell community best practices and style guidelines into all code generation and analysis. - -## Best Practices Implementation - -### Tool Design Patterns - -```powershell -# Tools (reusable functions) - accept input via parameters, output to pipeline -function Get-ServerInfo { - [CmdletBinding()] - param( - [Parameter(Mandatory = $true, ValueFromPipeline = $true)] - [string[]]$ComputerName - ) - - process { - foreach ($computer in $ComputerName) { - # Return raw data for maximum reusability - [PSCustomObject]@{ - ComputerName = $computer - Status = Test-Connection $computer -Count 1 -Quiet - LastBootTime = (Get-CimInstance Win32_OperatingSystem -ComputerName $computer).LastBootUpTime - # Raw data, no formatting - } - } - } -} - -# Controllers (automation scripts) - can format data for specific purpose -$servers = Get-Content servers.txt -$results = $servers | Get-ServerInfo | Where-Object Status -eq $true -$results | Format-Table -AutoSize # Controller can format for display -``` - -### Error Handling Patterns - -```powershell -# Use -ErrorAction Stop for trappable exceptions -try { - $result = Get-Something -Parameter $value -ErrorAction Stop - - # Put entire transaction in try block, not just the risky part - Process-Result $result - Update-Database $result - Send-Notification "Success" - -} catch { - # Copy error immediately to avoid $Error[0] changes - $currentError = $Error[0] - - Write-Error "Operation failed: $($currentError.Exception.Message)" - # Include correlation ID for traceability - throw -} -``` - -### Performance Patterns - -```powershell -# Prefer language features over cmdlets for performance -# Instead of: Get-Service | Where-Object Status -eq 'Running' -# Use: Get-Service | Where Status -eq Running - -# Use StringBuilder for string concatenation -$sb = [System.Text.StringBuilder]::new() -foreach ($item in $collection) { - [void]$sb.AppendLine("Processing: $item") -} -$result = $sb.ToString() - -# Avoid appending to arrays in loops -$results = foreach ($item in $collection) { - Process-Item $item # Output to pipeline instead -} -``` - -## Style Guide Implementation - -### Code Layout Standards - -```powershell -# One True Brace Style - opening brace at end of line -function Test-Example { - [CmdletBinding()] - param( - [Parameter(Mandatory = $true)] - [string]$InputParameter - ) - - if ($condition -eq $true) { - Write-Output "Condition met" - } else { - Write-Output "Condition not met" - } -} - -# 4-space indentation, 115-character line limit -# Use splatting for long parameter lists instead of backticks -$splat = @{ - ComputerName = $servers - Credential = $credential - ScriptBlock = { Get-Process } - ThrottleLimit = 10 -} -Invoke-Command @splat -``` - -### Function Structure Standards - -```powershell -function Verb-Noun { - Verb-Noun -ParameterName "Value" - - Description of what this example demonstrates - - .NOTES - Author: Name - Version: 1.0.0 - Last Updated: Date - #> - - [CmdletBinding(SupportsShouldProcess = $true)] - [OutputType([PSCustomObject])] - param( - [Parameter(Mandatory = $true, ValueFromPipeline = $true)] - [ValidateNotNullOrEmpty()] - [string]$ParameterName - ) - - begin { - # Initialization code - } - - process { - # Main processing logic - if ($PSCmdlet.ShouldProcess($ParameterName, "Action")) { - # Implementation - } - } - - end { - # Cleanup code - } -} -``` - -### Naming Conventions - -```powershell -# Use full command names and parameter names - no aliases -Get-Process -Name "powershell" # Not: gps -n "powershell" - -# Use PascalCase for all public identifiers -$UserName = "john.doe" # Not: $username or $user_name -$ComputerList = @() # Not: $computerlist - -# Use approved PowerShell verbs -function Get-UserInfo { } # ✓ Approved verb -function Retrieve-UserInfo { } # ✗ Non-approved verb -``` - -### Security Implementation - -```powershell -# Always use PSCredential for credentials -param( - [Parameter(Mandatory = $true)] - [System.Management.Automation.PSCredential] - [System.Management.Automation.Credential()] - $Credential -) - -# Use SecureString for sensitive data -$securePassword = Read-Host -AsSecureString -Prompt "Enter password" - -# Never decrypt SecureString to plain text unless absolutely necessary -# If required, decrypt only during method call -$connection.SetCredential($credential.GetNetworkCredential()) -``` - -## Integration Requirements - -### Automatic Validation - -When generating or reviewing PowerShell code, always verify: - -- [ ] Uses approved PowerShell verbs from Get-Verb -- [ ] Follows One True Brace Style formatting -- [ ] Implements proper error handling with -ErrorAction Stop -- [ ] Uses full command and parameter names -- [ ] Includes comprehensive comment-based help -- [ ] Implements proper input validation -- [ ] Uses PascalCase for all identifiers -- [ ] Avoids performance anti-patterns (array appending, string concatenation) -- [ ] Implements secure credential handling - -### Quality Standards - -- Minimum 80% code coverage with Pester tests -- Zero PSScriptAnalyzer violations with default rules -- Complete comment-based help for all public functions -- Proper resource disposal for IDisposable objects -- Correlation ID tracking in error handling - -### Enterprise Extensions - -Extend community standards with enterprise requirements: - -- Structured logging with correlation IDs -- Integration with enterprise monitoring systems -- Compliance framework alignment (SOX, GDPR, HIPAA) -- Standardized troubleshooting documentation in ./Troubleshooting/ -- Security controls and audit trails diff --git a/.github/instructions/errorsandlogs.instructions.md b/.github/instructions/errorsandlogs.instructions.md deleted file mode 100644 index c364226..0000000 --- a/.github/instructions/errorsandlogs.instructions.md +++ /dev/null @@ -1,399 +0,0 @@ ---- -applyTo: "**/*.ps1,**/*.psm1" -description: 'Implements comprehensive error handling and structured logging for PowerShell solutions' ---- - -# PowerShell Error Handling and Logging Implementation - -Implement robust error handling and structured logging patterns for PowerShell code that ensure proper error management, -correlation tracking, and enterprise-grade diagnostic capabilities. - -> **Worked examples**: -> [Basic-Function-Example.ps1](../../powershell-standards/Examples/Basic-Function-Example.ps1) and -> [Get-ExampleData.ps1](../../powershell-standards/Examples/Module-Structure-Example/Public/Get-ExampleData.ps1) -> both generate a correlation ID once in `begin`, carry it through every message, use `$_` in the -> catch, and `continue` so one failed item does not abort the batch. Both failure paths are covered -> by tests. - -## Error Handling Implementation - -### Comprehensive Error Handling Pattern - -Generate error handling code following this enterprise pattern: - -```powershell -function Verb-Noun { - [CmdletBinding()] - param( - [Parameter(Mandatory = $true)] - [string]$InputParameter - ) - - # Initialize correlation tracking - $correlationId = [System.Guid]::NewGuid() - $ErrorActionPreference = 'Stop' - - try { - Write-Verbose "Starting operation - CorrelationId: $correlationId" - - # Main operation logic here - $result = Invoke-Operation -CorrelationId $correlationId - - Write-Verbose "Operation completed successfully - CorrelationId: $correlationId" - return $result - } - catch { - # Structured error logging - $errorDetails = @{ - CorrelationId = $correlationId - Function = $MyInvocation.MyCommand.Name - ErrorMessage = $_.Exception.Message - StackTrace = $_.ScriptStackTrace - Timestamp = Get-Date - InputParameters = $PSBoundParameters - } - - Write-Error "Operation failed: $($_.Exception.Message) - CorrelationId: $correlationId" - - # Log to troubleshooting system - $errorDetails | ConvertTo-Json | Out-File ".\Troubleshooting\Logs\error-$correlationId.json" - - throw - } - finally { - # Resource cleanup - if ($resource -and $resource -is [System.IDisposable]) { - $resource.Dispose() - } - } -} -``` - -### Custom Exception Classes - -Implement custom exception hierarchies for specific error scenarios: - -```powershell -# Base exception class -class BaseModuleException : System.Exception { - [string]$CorrelationId - [string]$Component - [string]$Operation - [hashtable]$Context - - BaseModuleException([string]$Message, [string]$Component, [string]$Operation) : base($Message) { - $this.CorrelationId = [System.Guid]::NewGuid().ToString() - $this.Component = $Component - $this.Operation = $Operation - $this.Context = @{} - } - - [void] AddContext([string]$Key, [object]$Value) { - $this.Context[$Key] = $Value - } -} - -# Specific exception types -class ValidationException : BaseModuleException { - [string]$ParameterName - [object]$ParameterValue - - ValidationException([string]$Message, [string]$ParameterName, [object]$ParameterValue) : base($Message, 'Validation', 'ParameterValidation') { - $this.ParameterName = $ParameterName - $this.ParameterValue = $ParameterValue - } -} -``` - -## Structured Logging Implementation - -### PSFramework Integration - -Set up comprehensive logging with PSFramework: - -```powershell -#requires -Module PSFramework - -# Initialize logging configuration -function Initialize-ModuleLogging { - param( - [string]$ModuleName = $MyInvocation.MyCommand.Module.Name, - [string]$LogLevel = 'Information', - [string]$LogPath = ".\Logs" - ) - - # Configure file logging - $fileLogPath = Join-Path $LogPath "$ModuleName-{0:yyyy-MM-dd}.log" - Set-PSFLoggingProvider -Name logfile -FilePath $fileLogPath -Enabled $true - - # Configure console logging - Set-PSFLoggingProvider -Name console -Enabled $true - - # Set logging level - Set-PSFConfig -FullName 'psframework.logging.maximumloglevel' -Value $LogLevel - - Write-PSFMessage -Level Host -Message "Logging initialized for module: $ModuleName" -} -``` - -### Structured Logging Patterns - -Implement consistent logging patterns throughout the code: - -```powershell -function Write-StructuredLog { - param( - [ValidateSet('Critical', 'Error', 'Warning', 'Information', 'Debug', 'Verbose')] - [string]$Level, - [string]$Message, - [string]$Component = 'Unknown', - [string]$Operation = 'Unknown', - [string]$CorrelationId = [System.Guid]::NewGuid().ToString(), - [hashtable]$Data = @{}, - [System.Management.Automation.ErrorRecord]$ErrorRecord - ) - - # Build comprehensive log context - $logContext = @{ - Component = $Component - Operation = $Operation - CorrelationId = $CorrelationId - MachineName = $env:COMPUTERNAME - UserName = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name - ProcessId = $PID - ThreadId = [System.Threading.Thread]::CurrentThread.ManagedThreadId - } - - # Add custom data - foreach ($key in $Data.Keys) { - $logContext["Data.$key"] = $Data[$key] - } - - # Add error information if present - if ($ErrorRecord) { - $logContext.ErrorType = $ErrorRecord.Exception.GetType().Name - $logContext.ErrorMessage = $ErrorRecord.Exception.Message - $logContext.ErrorStackTrace = $ErrorRecord.ScriptStackTrace - } - - # Write using PSFramework - Write-PSFMessage -Level $Level -Message $Message -Data $logContext -ErrorRecord $ErrorRecord -} -``` - -## Security Event Logging - -### Security-Specific Logging - -Implement specialized logging for security events: - -```powershell -function Write-SecurityLog { - param( - [ValidateSet('Authentication', 'Authorization', 'DataAccess', 'ConfigurationChange', 'SecurityViolation')] - [string]$SecurityEventType, - [string]$Message, - [ValidateSet('Success', 'Failure', 'Attempt')] - [string]$Outcome = 'Attempt', - [string]$TargetResource, - [string]$CorrelationId = [System.Guid]::NewGuid().ToString(), - [hashtable]$SecurityContext = @{}, - [string]$RiskLevel = 'Medium' - ) - - # Build security context (sanitize sensitive data) - $securityData = @{ - SecurityEventType = $SecurityEventType - Outcome = $Outcome - TargetResource = $TargetResource - RiskLevel = $RiskLevel - UserContext = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name - SessionId = [System.Diagnostics.Process]::GetCurrentProcess().SessionId - } - - # Add sanitized security context - foreach ($key in $SecurityContext.Keys) { - if ($key -notmatch '(password|secret|key|token|credential)') { - $securityData["Context.$key"] = $SecurityContext[$key] - } - } - - # Determine log level based on outcome and event type - $logLevel = switch ($Outcome) { - 'Failure' { if ($SecurityEventType -in @('Authentication', 'Authorization', 'SecurityViolation')) { 'Error' } else { 'Warning' } } - 'Success' { if ($SecurityEventType -eq 'SecurityViolation') { 'Warning' } else { 'Information' } } - default { 'Information' } - } - - Write-StructuredLog -Level $logLevel -Message $Message -Component 'Security' -Operation $SecurityEventType -CorrelationId $CorrelationId -Data $securityData -} -``` - -## Performance and Correlation Tracking - -### Performance Logging - -Track performance metrics with structured logging: - -```powershell -function Measure-OperationPerformance { - param( - [ScriptBlock]$Operation, - [string]$OperationName, - [string]$CorrelationId = [System.Guid]::NewGuid().ToString(), - [hashtable]$Metrics = @{} - ) - - $stopwatch = [System.Diagnostics.Stopwatch]::StartNew() - $memoryBefore = [System.GC]::GetTotalMemory($false) - - try { - Write-StructuredLog -Level Debug -Message "Starting performance measurement" -Component 'Performance' -Operation $OperationName -CorrelationId $CorrelationId - - $result = & $Operation - - $stopwatch.Stop() - $memoryAfter = [System.GC]::GetTotalMemory($false) - - # Calculate performance metrics - $performanceData = @{ - Duration = $stopwatch.Elapsed.TotalMilliseconds - MemoryUsed = $memoryAfter - $memoryBefore - MemoryUsedMB = [math]::Round(($memoryAfter - $memoryBefore) / 1MB, 2) - } - - # Add custom metrics - foreach ($key in $Metrics.Keys) { - $performanceData["Metric.$key"] = $Metrics[$key] - } - - Write-StructuredLog -Level Information -Message "Performance measurement completed" -Component 'Performance' -Operation $OperationName -CorrelationId $CorrelationId -Data $performanceData - - return $result - } - catch { - $stopwatch.Stop() - Write-StructuredLog -Level Error -Message "Performance measurement failed" -Component 'Performance' -Operation $OperationName -CorrelationId $CorrelationId -ErrorRecord $_ - throw - } -} -``` - -### Correlation ID Management - -Implement correlation tracking throughout the application: - -```powershell -# Global correlation context -$script:CorrelationContext = @{} - -function Start-Operation { - param( - [string]$OperationName, - [string]$ParentCorrelationId - ) - - $correlationId = [System.Guid]::NewGuid().ToString() - - $script:CorrelationContext[$correlationId] = @{ - OperationName = $OperationName - StartTime = Get-Date - ParentCorrelationId = $ParentCorrelationId - } - - Write-StructuredLog -Level Information -Message "Operation started" -Component 'OperationManager' -Operation $OperationName -CorrelationId $correlationId - - return $correlationId -} - -function Complete-Operation { - param( - [string]$CorrelationId, - [switch]$Success - ) - - if ($script:CorrelationContext.ContainsKey($CorrelationId)) { - $context = $script:CorrelationContext[$CorrelationId] - $duration = (Get-Date) - $context.StartTime - - $operationData = @{ - Duration = $duration.TotalMilliseconds - Success = $Success.IsPresent - } - - Write-StructuredLog -Level Information -Message "Operation completed" -Component 'OperationManager' -Operation $context.OperationName -CorrelationId $CorrelationId -Data $operationData - - $script:CorrelationContext.Remove($CorrelationId) - } -} -``` - -## Diagnostic and Troubleshooting Support - -### Diagnostic Data Export - -Generate comprehensive diagnostic information: - -```powershell -function Export-DiagnosticData { - param( - [string]$OutputPath = ".\Troubleshooting\Diagnostics", - [string]$CorrelationId = [System.Guid]::NewGuid().ToString(), - [int]$LogHistoryHours = 24 - ) - - # Create diagnostic package - $timestamp = Get-Date -Format 'yyyyMMdd-HHmmss' - $diagnosticPath = Join-Path $OutputPath "Diagnostic-$timestamp" - New-Item -Path $diagnosticPath -ItemType Directory -Force - - # Collect system information - $diagnosticData = @{ - SystemInfo = Get-ComputerInfo | Select-Object WindowsVersion, TotalPhysicalMemory - PowerShellInfo = $PSVersionTable - ModuleInfo = Get-Module | Select-Object Name, Version - RecentErrors = Get-PSFMessage | Where-Object Level -in @('Error', 'Critical') | Where-Object Timestamp -gt (Get-Date).AddHours(-$LogHistoryHours) - PerformanceCounters = Get-Counter '\Process(powershell)\Working Set' -ErrorAction SilentlyContinue - } - - # Export diagnostic data - $diagnosticData | ConvertTo-Json -Depth 10 | Out-File "$diagnosticPath\diagnostic-data.json" - - Write-StructuredLog -Level Information -Message "Diagnostic data exported" -Component 'Diagnostics' -Operation 'Export' -CorrelationId $CorrelationId -Data @{ - OutputPath = $diagnosticPath - DataPoints = $diagnosticData.Keys.Count - } - - return $diagnosticPath -} -``` - -## Implementation Requirements - -When implementing error handling and logging: - -### Required Components - -1. **Correlation ID tracking** throughout all operations -2. **Structured logging** with consistent format and context -3. **Custom exception classes** for specific error scenarios -4. **Performance measurement** for critical operations -5. **Security event logging** for audit and compliance -6. **Diagnostic data collection** for troubleshooting support - -### Integration Points - -- Reference troubleshooting documentation in `.\Troubleshooting\` folder -- Integrate with enterprise monitoring and alerting systems -- Support compliance and audit requirements -- Enable automated error analysis and trending - -### Quality Standards - -- All errors must include correlation IDs for traceability -- Security events must be logged with appropriate detail and protection -- Performance metrics must be captured for baseline establishment -- Diagnostic data must be comprehensive enough for remote troubleshooting - -Generate error handling and logging implementations that follow these enterprise patterns while maintaining consistency -with the established PowerShell development standards and troubleshooting documentation structure. diff --git a/.github/instructions/futureTODO.md b/.github/instructions/futureTODO.md deleted file mode 100644 index f6cc10c..0000000 --- a/.github/instructions/futureTODO.md +++ /dev/null @@ -1,86 +0,0 @@ -# Project-Specific Instruction Files (TODO) - -Examples of per-project `.instructions.md` files to place in specific project folders. -Each block below is the complete contents of one file, front matter included. - -## infrastructure-project.instructions.md - -````markdown ---- -applyTo: "**/*.ps1,**/*.psm1" ---- - -# Project-Specific PowerShell Standards - -## Infrastructure Automation Project Context - -This project focuses on enterprise infrastructure automation with these specific requirements: - -### Domain-Specific Patterns - -- **Server Management**: All functions must support bulk operations with progress reporting -- **Active Directory Integration**: Use specific organizational units: "OU=Servers,DC=contoso,DC=com" -- **Monitoring Integration**: Include SCOM integration hooks and custom performance counters -- **Change Management**: All infrastructure changes require approval workflow integration - -### Project-Specific Validation - -```powershell -# Server name validation for this environment -[ValidatePattern('^(WEB|DB|APP|DC)\d{2}$')] -[string]$ServerName - -# Environment validation -[ValidateSet('DEV', 'TEST', 'STAGE', 'PROD')] -[string]$Environment -``` - -### Required Error Codes - -- **E1001**: Server connectivity failure -- **E1002**: Active Directory operation failed -- **E1003**: SCOM integration error -- **E1004**: Change management approval required - -### Integration Requirements - -- **ServiceNow**: Include ticket correlation in all operations -- **SCOM**: Custom event logging for infrastructure changes -- **Email Notifications**: Use template system for consistent formatting -- **Database Logging**: Store all operations in AuditDB.InfrastructureOps table -```` - -## security-project.instructions.md - -````markdown ---- -applyTo: "**/*security*.ps1,**/*compliance*.ps1" ---- - -# Security & Compliance Project Standards - -This project handles sensitive security data and must meet SOX compliance requirements. - -## Mandatory Security Controls - -- **Data Classification**: All functions must handle data classification metadata -- **Audit Logging**: Every operation requires comprehensive audit trails -- **Encryption**: All data at rest and in transit must be encrypted -- **Access Controls**: Role-based access validation required - -## Compliance Framework Integration - -```powershell -# SOX compliance validation -function Invoke-SOXValidation { - param([string]$Operation, [string]$BusinessJustification) - # Implementation required for all financial data operations -} - -# GDPR consent verification -function Test-GDPRConsent { - param([string]$DataSubjectId, [string]$ProcessingPurpose) - # Required for all personal data processing -} -``` -```` diff --git a/.github/instructions/module.instructions.md b/.github/instructions/module.instructions.md deleted file mode 100644 index 3cd4a3f..0000000 --- a/.github/instructions/module.instructions.md +++ /dev/null @@ -1,883 +0,0 @@ ---- -applyTo: "**/*.psm1,**/*.psd1,**/Public/*.ps1,**/Private/*.ps1" -description: 'Creates enterprise-grade PowerShell modules with proper structure, security, and functionality' ---- - -# PowerShell Module Development Assistant - -Create comprehensive, enterprise-grade PowerShell modules that follow organizational standards, implement security best -practices, and provide scalable functionality for business operations. - -## Module Planning and Design - -### Initial Requirements Gathering - -Collect essential information for module development: - -#### Module Specifications - -- **Module Name**: Following PowerShell naming conventions (noun should be singular) -- **Primary Purpose**: Clear business value and functional scope -- **Target Audience**: System administrators, developers, end users, or automation systems -- **Functionality Scope**: Core features and capabilities to implement -- **Dependencies**: Required PowerShell modules and external systems -- **Security Requirements**: Authentication, authorization, and data protection needs -- **Performance Targets**: Expected load, scalability, and response time requirements - -#### Technical Requirements - -- **PowerShell Versions**: PowerShell 7.6 (LTS, default for new modules), or 5.1 + 7.6 when the module must run on - Windows estates without pwsh. Do not target 7.4/7.5 alone — both lose support 10-Nov-2026 -- **Platform Support**: Windows, Linux, macOS, or cross-platform -- **Integration Points**: External APIs, databases, file systems, or services -- **Deployment Method**: PowerShell Gallery, internal repository, or direct installation - -## Module Structure Generation - -> **Worked example**: -> [powershell-standards/Examples/Module-Structure-Example](../../powershell-standards/Examples/Module-Structure-Example/) -> is a small working module implementing everything in this section - the folder layout, the load -> order in `ModuleExample.psm1`, an explicit `FunctionsToExport`, a class used as a named output -> type, and a private helper that is never exported. Read it before generating a new module; prefer -> matching its shape over inventing one. - -### Standard Module Directory Structure - -Create the complete module structure following enterprise standards: - -```text -ModuleName/ -├── ModuleName.psd1 # Module manifest -├── ModuleName.psm1 # Root module file -├── Public/ # Exported functions -│ ├── Get-ModuleFunction.ps1 -│ ├── Set-ModuleConfiguration.ps1 -│ └── Invoke-ModuleProcess.ps1 -├── Private/ # Internal functions -│ ├── Test-InternalValidation.ps1 -│ └── Connect-InternalService.ps1 -├── Classes/ # PowerShell classes -│ ├── ModuleConfiguration.ps1 -│ └── ModuleException.ps1 -├── Data/ # Static data and configuration -│ ├── DefaultConfiguration.psd1 -│ └── ErrorCodes.psd1 -├── Tests/ # Comprehensive test suite -│ ├── Unit/ -│ ├── Integration/ -│ └── Performance/ -├── docs/ # PlatyPS command help - Markdown source, committed -│ └── ModuleName/ -│ ├── ModuleName.md # module page -│ └── Get-ModuleFunction.md # one file per exported command -├── en-US/ # Compiled help, packaged with the module -│ ├── ModuleName-Help.xml # built by Export-MamlCommandHelp - never hand-edited -│ └── about_ModuleName.help.txt # hand-written conceptual topic -├── Troubleshooting/ # Organized troubleshooting docs -│ ├── Common/ -│ ├── Security/ -│ ├── Performance/ -│ └── Integration/ -├── Documentation/ # Project documentation -├── Configuration/ # Environment configurations -├── Scripts/ # Utility scripts -└── README.md # Main documentation -``` - -`docs/` and `en-US/` are generated and maintained with **Microsoft.PowerShell.PlatyPS** — see -[platyps.instructions.md](./platyps.instructions.md). Every function in `Public/` must carry -`.EXTERNALHELP ModuleName-Help.xml`, or the shipped MAML is silently ignored in favour of the -comment block. - -### Module Manifest Creation - -Generate comprehensive module manifest (ModuleName.psd1). For a complete, valid manifest see -[ModuleExample.psd1](../../powershell-standards/Examples/Module-Structure-Example/ModuleExample.psd1) - -note that `FunctionsToExport` names each public function explicitly, which is what keeps private -helpers internal: - -```powershell -@{ - # Basic Module Information - RootModule = 'ModuleName.psm1' - ModuleVersion = '1.0.0' - GUID = '$(New-Guid)' - Author = 'Jeffrey Stuhr' - CompanyName = 'Organization Name' - Copyright = '(c) $(Get-Date -Format yyyy) Organization Name. All rights reserved.' - Description = 'Comprehensive description of module functionality and business value' - - # PowerShell Version Requirements - # Default to 7.6 (LTS). Switch to '5.1' + @('Desktop','Core') only when Windows PowerShell - # support is an explicit requirement — see instructions/powershell-version.instructions.md - PowerShellVersion = '7.6' - CompatiblePSEditions = @('Core') - - # Dependencies - RequiredModules = @( - @{ ModuleName = 'PSFramework'; ModuleVersion = '1.7.270' } - ) - - # Module Components - FunctionsToExport = @('Get-ModuleFunction', 'Set-ModuleConfiguration') - CmdletsToExport = @() - VariablesToExport = @() - AliasesToExport = @() - - # PowerShell Gallery Metadata - PrivateData = @{ - PSData = @{ - Tags = @('PowerShell', 'Enterprise', 'Automation', 'Management') - LicenseUri = 'https://github.com/organization/modulename/blob/main/LICENSE' - ProjectUri = 'https://github.com/organization/modulename' - # Omit IconUri when there is no icon. An empty string is not "no icon": NuGet - # aborts the pack with "IconUrl cannot be empty" and names neither file nor key. - IconUri = 'https://github.com/organization/modulename/raw/main/Assets/icon.png' - # The current release only, ending with a pointer to CHANGELOG.md. The Gallery - # refuses more than 10,600 characters, and only at upload. - ReleaseNotes = 'Initial release with core functionality' - RequireLicenseAcceptance = $false - } - } - - # Help Information - # Only set this if you actually publish an Updatable Help package to that location. - # Update-Help reports an error against a HelpInfoURI with no HelpInfo.xml behind it. - # Shipping MAML in en-US/ does not require this key. Omit it rather than setting it - # to '' - an empty value fails the pack the same way an empty IconUri does. - HelpInfoURI = 'https://docs.organization.com/powershell/modulename' -} -``` - -### Root Module Implementation - -Create optimized root module file (ModuleName.psm1). Load order matters: classes first, then private -functions, then public ones - see -[ModuleExample.psm1](../../powershell-standards/Examples/Module-Structure-Example/ModuleExample.psm1) for a -working loader. - -```powershell -# Match the manifest's PowerShellVersion. This template targets 7.6; use 5.1 only -# when the module is built for Windows PowerShell compatibility. -#Requires -Version 7.6 - -# Module initialization -$ModuleRoot = $PSScriptRoot -Write-Verbose "Initializing module: $($MyInvocation.MyCommand.Module.Name)" - -# Import module components in order -try { - # Load Classes first (dependencies for functions) - $classFiles = Get-ChildItem -Path "$ModuleRoot\Classes\*.ps1" -ErrorAction SilentlyContinue - foreach ($class in $classFiles) { - Write-Verbose "Loading class: $($class.Name)" - . $class.FullName - } - - # Load Private functions - $privateFunctions = Get-ChildItem -Path "$ModuleRoot\Private\*.ps1" -ErrorAction SilentlyContinue - foreach ($function in $privateFunctions) { - Write-Verbose "Loading private function: $($function.Name)" - . $function.FullName - } - - # Load Public functions - $publicFunctions = Get-ChildItem -Path "$ModuleRoot\Public\*.ps1" -ErrorAction SilentlyContinue - foreach ($function in $publicFunctions) { - Write-Verbose "Loading public function: $($function.Name)" - . $function.FullName - } - - # Load Data files - $script:ModuleConfiguration = Import-PowerShellDataFile -Path "$ModuleRoot\Data\DefaultConfiguration.psd1" -ErrorAction SilentlyContinue - - Write-Verbose "Module loaded successfully. Public functions: $($publicFunctions.Count), Private functions: $($privateFunctions.Count)" -} -catch { - Write-Error "Failed to load module components: $($_.Exception.Message)" - throw -} - -# Module cleanup on removal -$ExecutionContext.SessionState.Module.OnRemove = { - Write-Verbose "Cleaning up module: $($MyInvocation.MyCommand.Module.Name)" - # Clean up module variables and resources - Remove-Variable -Name ModuleConfiguration -Scope Script -ErrorAction SilentlyContinue -} -``` - -## Function Development - -### Public Function Template - -Generate public functions following enterprise standards: - -```powershell -function Verb-Noun { - <# - .SYNOPSIS - Brief description using approved PowerShell verb-noun pattern - - .DESCRIPTION - Comprehensive description including business value, functionality, - dependencies, and performance characteristics - - .PARAMETER ParameterName - [Type] (Mandatory: Yes/No, Pipeline: ByValue/ByPropertyName) - Detailed parameter description with validation rules and business context - - .EXAMPLE - PS> Verb-Noun -ParameterName "Value" - - DESCRIPTION: What this example demonstrates - OUTPUT: Expected output description - USE CASE: Business scenario - - .NOTES - Author: Jeffrey Stuhr - Version: 1.0.0 - Last Updated: $(Get-Date -Format 'yyyy-MM-dd') - - TROUBLESHOOTING: - - Common issues: .\Troubleshooting\Common\Function-Issues.md - - Performance: .\Troubleshooting\Performance\Optimization.md - #> - - [CmdletBinding(SupportsShouldProcess = $true)] - [OutputType([ExpectedOutputType])] - param( - [Parameter(Mandatory = $true, ValueFromPipeline = $true)] - [ValidateNotNullOrEmpty()] - [string]$ParameterName - ) - - begin { - $correlationId = [System.Guid]::NewGuid() - Write-Verbose "Starting $($MyInvocation.MyCommand.Name) - CorrelationId: $correlationId" - - # Initialize collections and validation - } - - process { - try { - if ($PSCmdlet.ShouldProcess($ParameterName, "Action Description")) { - # Core function logic with proper error handling - # Include correlation ID in all operations - } - } - catch { - Write-Error "Failed to process $ParameterName : $($_.Exception.Message)" -ErrorAction Stop - } - } - - end { - Write-Verbose "Completed $($MyInvocation.MyCommand.Name) - CorrelationId: $correlationId" - } -} -``` - -### Functions That Reduce Their Input to One Result - -`ValueFromPipeline` changes what `process` receives. Passed by parameter, a collection arrives in -`process` once, as one argument. Piped, PowerShell unrolls it and `process` runs once per element. A -function that reduces its input to a single result, such as folding a set of policy evaluations into -one outcome, gives a different answer on each path unless it handles both: by parameter it folds the -whole collection, piped it folds each element on its own and emits one wrong result per element. No -error is raised, and every result has the declared output type. - -For such a function: - -- Collect in `process` and fold in `end`. Elements arriving one at a time go into a `List[object]` - and the set is folded once the pipeline closes. -- Decide what a single element arriving alone means, and write that decision into the function. A - whole input that is itself one object (an envelope with a `value` property, a JSON string) is - folded as it arrives, so piping several whole inputs still yields one result each. -- Exclude `[string]` before any `IEnumerable` check. A string enumerates as characters. -- A hashtable is `IEnumerable` too, and is one object rather than a collection. - -```powershell -function ConvertTo-Outcome { - [CmdletBinding()] - [OutputType('Module.Outcome')] - param( - [Parameter(Mandatory, ValueFromPipeline)] - [AllowNull()] - [object]$InputObject - ) - - begin { - # Elements piped in one at a time are held here and folded together in end - $loose = [System.Collections.Generic.List[object]]::new() - } - - process { - # A lone element is a single object without the envelope's value property. A string is - # IEnumerable (of characters) and a hashtable is IEnumerable (of entries), so both are - # settled before the enumerable check. - $isLoneElement = $null -ne $InputObject -and $InputObject -isnot [string] -and - ($InputObject -is [hashtable] -or $InputObject -isnot [System.Collections.IEnumerable]) - if ($isLoneElement) { - if ($InputObject -is [hashtable]) { - $isLoneElement = -not $InputObject.ContainsKey('value') - } else { - $isLoneElement = -not $InputObject.PSObject.Properties['value'] - } - } - - if ($isLoneElement) { - $loose.Add($InputObject) - } else { - # A whole input arrived at once: a collection by parameter, an envelope, a JSON string - Get-FoldedOutcome -Response $InputObject - } - } - - end { - if ($loose.Count -gt 0) { - Get-FoldedOutcome -Response $loose.ToArray() - } - } -} -``` - -Test both paths. `-InputObject $collection` and `$collection | ConvertTo-Outcome` run different code -once the input is enumerable, and the piped test must pipe the shape the real upstream command -produces. A usage example in the README or in help is a test case until one exists that runs it as -written. See the [Unit Test Template](./pester-supporting-docs/unit-test-template.md). - -### Responses That Arrive as Hashtables or PSObjects - -The same JSON reaches a function in two shapes. `Invoke-MgGraphRequest` returns hashtables unless -`-OutputType PSObject` is passed; `ConvertFrom-Json` returns PSObjects unless `-AsHashtable` is -passed (PowerShell 7); a baseline or fixture read back from disk comes through `ConvertFrom-Json`. A -function that reads response data with one syntax is correct for one shape and silently wrong for -the other. Measured on PowerShell 7.6 and Windows PowerShell 5.1 alike: - -| Read | Hashtable | PSObject | -|---|---|---| -| `$response['value']` | the value | `$null` with no error; an error only under `Set-StrictMode` | -| `$response.value` | the value | the value | -| `$response.Count` | the key `Count` when one exists, otherwise the number of entries | the property when one exists, otherwise `1` | -| `$response.missing` | `$null` | `$null` | - -Index syntax reads only the hashtable. Member syntax reads both, but a key named like a hashtable -member (`Count`, `Keys`, `Values`) comes back as the hashtable's own property when the key is absent, -and a scalar's `Count` is `1`, so neither is `$null` when the data is missing. CaOutcome computed -Conditional Access outcomes from nulls, with no error, until every read of response data went -through one accessor: - -```powershell -function Get-ResponseProperty { - <# - .SYNOPSIS - Reads one property from response data in either shape it can arrive in. - - .DESCRIPTION - Private helper. Graph SDK responses are hashtables by default and PSObjects with - -OutputType PSObject; ConvertFrom-Json is the reverse. Indexing a PSObject with a key - returns $null with no error, so every read of anything that came from an API or a file - goes through this function. - #> - [CmdletBinding()] - [OutputType([object])] - param( - [Parameter(Mandatory)] - [AllowNull()] - [object]$InputObject, - - [Parameter(Mandatory)] - [string]$Name - ) - - if ($null -eq $InputObject) { - return $null - } - if ($InputObject -is [System.Collections.IDictionary]) { - if ($InputObject.Contains($Name)) { - return $InputObject[$Name] - } - return $null - } - $property = $InputObject.PSObject.Properties[$Name] - if ($property) { - return $property.Value - } - return $null -} -``` - -Use it for every read of anything that came from an API or a file. Like any function, it unrolls a -one-element collection on the way out, so wrap a read of a collection such as `value` in `@(...)` -before indexing or counting it. Test the public function with both shapes: the fixture parsed with -`ConvertFrom-Json`, and again with `ConvertFrom-Json -AsHashtable` or through the SDK's hashtable -form. Keep fixtures real: a recorded response with identifiers rewritten, because every shape defect -found this way came from a shape the API returned rather than one anybody imagined. - -### Class Development - -Create PowerShell classes with proper validation and methods. One constraint comes with the dot-source -loader above: **a class or enum defined in `Classes/` must not appear as a type constraint in any -`param()` block.** A type literal in a parameter attribute is resolved when the file is parsed, and a -dot-sourced file cannot see a class defined by a sibling file at that moment. Casts and `::new()` calls -in a function body are fine, because they resolve at run time. One `[ModuleConfiguration]$Config` -parameter breaks the import for every command in the module, not only the one that declares it. Take -`[object]` or `[PSCustomObject]` at the boundary and validate the type in the body, or build the module -into a single file whose classes precede the functions. - -```powershell -# Classes/ModuleConfiguration.ps1 -class ModuleConfiguration { - [ValidateNotNullOrEmpty()] - [string]$Environment - - [ValidateRange(1, 5)] - [int]$LogLevel = 3 - - [hashtable]$CustomSettings = @{} - - # Constructor with validation - ModuleConfiguration([string]$Environment) { - if ([string]::IsNullOrWhiteSpace($Environment)) { - throw [ArgumentNullException]::new('Environment') - } - $this.Environment = $Environment - } - - # Business logic methods - [bool] Validate() { - # Implement validation logic - return $true - } - - [hashtable] ToHashtable() { - return @{ - Environment = $this.Environment - LogLevel = $this.LogLevel - CustomSettings = $this.CustomSettings - } - } -} -``` - -## Security Implementation - -### Input Validation and Sanitization - -Implement comprehensive input validation: - -```powershell -function Protect-UserInput { - param( - [Parameter(Mandatory = $true)] - [string]$InputString, - [ValidateSet('ComputerName', 'FileName', 'UserName', 'General')] - [string]$InputType = 'General' - ) - - # Length validation - if ($InputString.Length -gt 1000) { - throw [ValidationException]::new("Input exceeds maximum length", "InputString", $InputString) - } - - # Type-specific validation - switch ($InputType) { - 'ComputerName' { - if ($InputString -notmatch '^[a-zA-Z0-9\-\.]+$') { - throw [ValidationException]::new("Invalid computer name format", "InputString", $InputString) - } - } - 'FileName' { - $invalidChars = [System.IO.Path]::GetInvalidFileNameChars() - foreach ($char in $invalidChars) { - if ($InputString.Contains($char)) { - throw [ValidationException]::new("Invalid file name character: $char", "InputString", $InputString) - } - } - } - } - - return $InputString.Trim() -} -``` - -### Credential Management Integration - -Implement secure credential handling: - -```powershell -function Get-ModuleCredential { - param( - [Parameter(Mandatory = $true)] - [string]$Name, - [string]$VaultName = 'DefaultVault' - ) - - try { - # Use SecretManagement for secure credential storage - $credential = Get-Secret -Name $Name -Vault $VaultName -AsPlainText:$false -ErrorAction Stop - return $credential - } - catch { - Write-Warning "Credential not found in vault, prompting user" - return Get-Credential -Message "Enter credentials for: $Name" - } -} -``` - -## Testing Framework Integration - -### Pester Test Structure - -Generate comprehensive test suites targeting **Pester 6.2+**: - -```powershell -# Tests/Unit/Public/Verb-Noun.Tests.ps1 -#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } - -BeforeAll { - # Pester 6 discovers and runs one file at a time - each file must be self-contained - $ModulePath = Join-Path $PSScriptRoot '..\..\..\..\ModuleName.psd1' - Import-Module $ModulePath -Force -} - -Describe "Verb-Noun" -Tag "Unit", "Public" { - Context "Parameter Validation" { - # -ForEach data is injected as variables - no param() block needed. - # Never name a key 'Input' - it collides with the automatic variable. - It "Should accept valid input: <TestValue>" -ForEach @( - @{ TestValue = 'ValidValue1' } - @{ TestValue = 'ValidValue2' } - ) { - # There is no Should-NotThrow - just call it; a throw fails the test - Verb-Noun -ParameterName $TestValue - } - - It "Should reject invalid input" { - { Verb-Noun -ParameterName $null } | Should-Throw - } - } - - Context "Functionality" { - BeforeEach { - Mock External-Dependency { "MockedResult" } - } - - It "Should return expected result" { - Verb-Noun -ParameterName "TestValue" | Should-NotBeNull - } - - It "Should call the dependency once" { - Verb-Noun -ParameterName "TestValue" - Should-Invoke External-Dependency -Times 1 -Exactly - } - } - - Context "Error Handling" { - It "Should handle errors gracefully" { - Mock External-Dependency { throw "Test Error" } - { Verb-Noun -ParameterName "TestValue" } | - Should-Throw -ExceptionMessage "*Test Error*" - } - } -} -``` - -Key Pester 6 points: `Should-*` assertions replace `Should -Be` for new tests, -`Assert-MockCalled` was removed in favour of `Should-Invoke`, and every file must import its own -dependencies. See -[Pester instructions](./pester.instructions.md) and the -[migration guide](./pester-supporting-docs/v6-migration.md). - -## Performance Optimization - -### Efficient Resource Management - -Implement performance best practices: - -```powershell -# Memory-efficient processing -function Process-LargeDataSet { - param( - [Parameter(ValueFromPipeline = $true)] - [object[]]$InputObject - ) - - begin { - # Initialize StringBuilder for efficient string operations - $sb = [System.Text.StringBuilder]::new() - $results = [System.Collections.Generic.List[object]]::new() - } - - process { - foreach ($item in $InputObject) { - # Process items in pipeline for memory efficiency - $processedItem = Process-Item $item - $results.Add($processedItem) - } - } - - end { - # Return results and cleanup - return $results.ToArray() - } -} -``` - -### Caching Implementation - -Add intelligent caching for improved performance: - -```powershell -# Module-level caching -$script:ModuleCache = @{} - -function Get-CachedResult { - param([string]$Key, [ScriptBlock]$Operation, [int]$ExpirationMinutes = 15) - - $cacheEntry = $script:ModuleCache[$Key] - if ($cacheEntry -and $cacheEntry.ExpirationTime -gt (Get-Date)) { - return $cacheEntry.Value - } - - # Execute operation and cache result - $result = & $Operation - $script:ModuleCache[$Key] = @{ - Value = $result - ExpirationTime = (Get-Date).AddMinutes($ExpirationMinutes) - } - - return $result -} -``` - -## Documentation and Troubleshooting - -### README Generation - -Create comprehensive README following enterprise standards: - -```markdown -# ModuleName - -## 📖 Overview -Clear business value and technical summary - -## 🚀 Quick Start -Copy-paste ready examples for immediate use - -## 📋 Prerequisites -System requirements, dependencies, and permissions - -## 🔧 Installation -Step-by-step installation instructions - -## 💡 Usage -Basic and advanced usage examples - -## 🔍 Troubleshooting -Reference to ./Troubleshooting/ folder organization - -## 📚 References -Links to additional documentation and resources -``` - -### Troubleshooting Documentation Structure - -Organize troubleshooting documentation in standardized folders: - -```text -Troubleshooting/ -├── Common/ -│ ├── Installation-Issues.md -│ ├── Function-Errors.md -│ └── Configuration-Problems.md -├── Security/ -│ ├── Credential-Management.md -│ └── Permission-Issues.md -├── Performance/ -│ ├── Memory-Usage.md -│ └── Slow-Execution.md -└── Integration/ - ├── API-Connection-Issues.md - └── External-Dependencies.md -``` - -## Releasing to the PowerShell Gallery - -A Gallery version is consumed the moment it uploads. It can be unlisted but never deleted, and the -`.nupkg` stays downloadable at its direct URL afterwards. Each rule below comes from a release of a -module built to these standards that passed every local gate and then shipped the wrong thing or -failed at the upload. - -### Stage an allowlist, never publish the repository root - -When the repository is the module root, `Publish-PSResource -Path .` packages the working tree: -`.git`, the tests and their fixtures, the build scripts, and anything else on disk. Measured on one -module: 313 files and 975 KB, all 213 files of `.git` among them, against 46 files and 507 KB for -the module itself. - -Publish from a staging folder that an allowlist fills. A new folder does not ship until it is named, -and the staged copy is imported in a fresh process and checked before anything uploads: - -```powershell -# Build/Publish-Module.ps1 - [CmdletBinding(SupportsShouldProcess)] with -WhatIf as the rehearsal -$shipFiles = 'ModuleName.psd1', 'ModuleName.psm1', 'README.md', 'CHANGELOG.md', 'LICENSE' -$shipFolders = 'Classes', 'Private', 'Public', 'en-US', 'Troubleshooting' - -# out/ is git-ignored. Every step but the publish is pinned -WhatIf:$false; see below for why. -$stage = Join-Path (Join-Path $PSScriptRoot '..\out') 'ModuleName' -if (Test-Path $stage) { - Remove-Item -Path $stage -Recurse -Force -WhatIf:$false -} -New-Item -Path $stage -ItemType Directory -Force -WhatIf:$false | Out-Null -foreach ($item in $shipFiles + $shipFolders) { - Copy-Item -Path (Join-Path $PSScriptRoot "..\$item") -Destination $stage -Recurse -WhatIf:$false -} - -# A fresh process proves the staged copy imports on its own and exports what the manifest says -$exported = pwsh -NoProfile -Command "Import-Module '$stage' -Force; (Get-Module ModuleName).ExportedFunctions.Keys" - -if ($PSCmdlet.ShouldProcess("ModuleName $($manifest.ModuleVersion)", 'Publish to PSGallery')) { - Publish-PSResource -Path $stage -Repository PSGallery -ApiKey $env:PSGALLERY_API_KEY -} -``` - -Pass the API key through an environment variable or a SecretManagement secret, never on the command -line of a workflow step, where it lands in the run log. - -### Metadata the Gallery refuses at upload - -Three fields carry a limit that is enforced only on upload, so every local gate passes until the -publish step returns 400: - -| Field | Limit | Whose limit | -| --- | --- | --- | -| `ReleaseNotes` | 10,600 characters | The Gallery's, stated in its error response | -| `Description` | 4,000 characters | NuGet's | -| Package tags | 4,000 characters | NuGet's, applied to the full tag list, not to the manifest's `Tags` key alone | - -The tag list the Gallery stores is the manifest's `Tags` plus what the publish adds: `PSModule`, a -`PSEdition_` tag per compatible edition, `PSIncludes_Function`, and `PSFunction_` and `PSCommand_` -for every exported function. A module with 27 commands carries 61 tags and about 1,900 characters, -so each new command costs about twice its name and a module that keeps adding commands reaches the -limit without its `Tags` key changing. - -`ReleaseNotes` grows the same way when every release prepends its paragraph and none removes one. -Two modules built to these standards were refused at 11,319 and 12,699 characters, each after every -other gate had passed and the tag had been pushed. Keep the current release's notes in the manifest -and end them with a pointer to `CHANGELOG.md`, which ships in the package and already holds the -history. - -Measure all three in the release rehearsal and in a contract test, so a pull request fails rather -than the tag-driven release: - -```powershell -$manifest = Import-PowerShellDataFile -Path ./ModuleName.psd1 -$module = Get-Module -Name ModuleName # the staged copy -$tags = @($manifest.PrivateData.PSData.Tags) + 'PSModule' + 'PSIncludes_Function' + - @($manifest.CompatiblePSEditions | ForEach-Object { "PSEdition_$_" }) + - @($module.ExportedFunctions.Keys | ForEach-Object { "PSFunction_$_"; "PSCommand_$_" }) - -$limits = @{ - Description = @{ Length = $manifest.Description.Length; Limit = 4000 } - Tags = @{ Length = ($tags -join ' ').Length; Limit = 4000 } - ReleaseNotes = @{ Length = $manifest.PrivateData.PSData.ReleaseNotes.Length; Limit = 10600 } -} -foreach ($field in $limits.Keys) { - $measured = $limits[$field] - if ($measured.Length -gt $measured.Limit) { - $message = "The manifest's $field is $($measured.Length) characters; " + - "the Gallery accepts at most $($measured.Limit)" - Write-Error $message -ErrorAction Stop - } -} -``` - -A module that exports cmdlets or DSC resources gains further automatic tags (`PSCmdlet_`, -`PSDscResource_`); build the list the way the publish does for what the module ships. - -### Omit a URI key rather than leaving it empty - -`IconUri = ''` is not "no icon". The nuspec writer emits an empty `<iconUrl>` and NuGet aborts the -pack with `IconUrl cannot be empty`, naming neither the manifest nor the key. `HelpInfoURI = ''` -fails the same way. Leave the key out until there is a value, and have the rehearsal check for an -empty one. Setting `IconUri` has no visible effect on the Gallery in any case: the package page -renders the default PowerShell logo and does not fetch the icon. - -### The rehearsal under `-WhatIf` - -`-WhatIf` sets `$WhatIfPreference`, and preference variables are inherited by every child scope: -the cmdlets a script calls and the scripts it calls. In a release script that declares -`SupportsShouldProcess`, `-WhatIf` therefore reaches the staging `Copy-Item`, the help build's -`Export-MamlCommandHelp`, and everything else downstream, not only the publish. The rehearsal then -copies nothing and compiles nothing, and either fails on the empty folder or passes while having -verified nothing. One module's release broke this way twice. - -- Only the publish is gated by `ShouldProcess`. Every other step is pinned `-WhatIf:$false` or runs - with the preference cleared. When adding a step, decide whether it is destructive; if not, pin it. -- A called script that declares `[CmdletBinding()]` without `SupportsShouldProcess` has no `-WhatIf` - parameter to pin. Save and clear the preference around the call: - - ```powershell - $savedWhatIf = $WhatIfPreference - $WhatIfPreference = $false - try { - & (Join-Path $PSScriptRoot 'Build-Help.ps1') - } finally { - $WhatIfPreference = $savedWhatIf - } - ``` - -- Test `-WhatIf` in combination with the script's other switches, not each alone. Both failures - above survived testing because `-WhatIf` and `-SkipHelpBuild` had only ever been exercised - separately. -- A stale local intermediate (a `maml/` left by an earlier run) hides a step that now produces - nothing. Rehearse from a clean checkout, or delete the intermediate first. - -### Tag-driven release - -The release workflow runs on `git tag v<ModuleVersion> && git push origin v<ModuleVersion>`, -re-runs every gate, refuses a tag that disagrees with the manifest's `ModuleVersion`, stages, -verifies, and publishes. When the upload fails for a reason the rehearsal did not measure, nothing -has been consumed: fix the manifest, move the tag to the new merge commit, and release under the same -number. - -## Quality Assurance Requirements - -### Pre-Release Checklist - -Ensure module meets all quality standards: - -- [ ] All public functions have a PlatyPS Markdown file under `docs/` with no `{{ Fill in` - placeholders remaining; all private functions have comprehensive comment-based help -- [ ] All public functions carry `.EXTERNALHELP ModuleName-Help.xml` -- [ ] MAML built to `en-US/ModuleName-Help.xml` and `Get-Help` verified against the packaged module -- [ ] Pester tests achieve minimum 80% code coverage -- [ ] PSScriptAnalyzer validation passes with no errors -- [ ] Security validation completed (no credential leaks) -- [ ] Performance benchmarks established -- [ ] Cross-platform compatibility tested (if applicable) -- [ ] Documentation complete and accurate -- [ ] Troubleshooting guides organized in proper folder structure - -### PowerShell Gallery Preparation - -Prepare module for publication: - -- [ ] Module manifest includes all required metadata, and no URI key is set to an empty string -- [ ] License file included and referenced -- [ ] README provides clear installation and usage instructions -- [ ] `ReleaseNotes` covers the current release and points to `CHANGELOG.md` for the rest -- [ ] `Description`, the full tag list and `ReleaseNotes` are measured against the Gallery's limits - in the rehearsal and in a contract test -- [ ] The publish stages an allowlist into a git-ignored folder; `Publish-PSResource` is never - pointed at the repository root -- [ ] `Publish-Module.ps1 -WhatIf` stages, imports and verifies the package with every - non-destructive step pinned against the inherited preference, and has been run together with - the script's other switches -- [ ] Version follows semantic versioning principles -- [ ] Dependencies clearly documented and available - -Generate comprehensive PowerShell modules that follow all enterprise standards, implement proper security controls, -include comprehensive testing, and provide excellent documentation with organized troubleshooting resources in the -`./Troubleshooting/` folder structure. diff --git a/.github/instructions/pester-supporting-docs/assertion-guide.md b/.github/instructions/pester-supporting-docs/assertion-guide.md index e25e92c..47053be 100644 --- a/.github/instructions/pester-supporting-docs/assertion-guide.md +++ b/.github/instructions/pester-supporting-docs/assertion-guide.md @@ -1,119 +1,109 @@ # Pester 6 Assertion Guide -Targets **Pester 6.2+**. - -Pester 6 ships a new family of `Should-*` assertions (dash, no space) alongside the classic -`Should -Be` operator. Both work. This guide covers which to use and how they differ. - -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. +Reference for the `Should-*` assertions. The rules are TST-10 to TST-17 in the +[Pester rules](../powershell-pester.instructions.md); this guide holds the detail behind them. Every +statement about behaviour was checked by running it on Pester 6.2.0. ## Which Syntax To Use -| Situation | Syntax | -| --- | --- | -| New test files | `Should-*` (preferred) | -| Editing an existing `Should -Be` file | Keep the file's existing style; do not mix within a file | -| Repo-wide migration not yet done | Leave `Should.DisableV5 = $false` (the default) | - -Do not set `Should.DisableV5 = $true` until every test file in the repository has been migrated. -That switch makes any use of `Should -Be` throw. +Pester 6 has two assertion styles: the `Should-*` commands (`Should-Be`) and the classic operator +(`Should -Be`). TST-10 decides between them: `Should-*` in a new file, the existing style in an +existing file, never both in one file. -## Why The New Syntax +Setting `Should.DisableV5 = $true` makes every classic assertion fail with +`Pester Should -Be syntax is disabled`. Leave it at its default until no test file uses that style. -The classic `Should` routes `-Be`, `-BeExactly`, `-Contain` and friends through one command. The -left side is always unwrapped by the pipeline and failure messages have to guess intent. The -`Should-*` assertions are specialized and type-aware: +## What The Should-* Assertions Change -- Failure messages are precise (a short string diff points a caret at the first differing character - and a long one prints every differing region with line numbers; collection comparisons point at - the first differing index). -- `$Expected` drives the comparison type, so `1 | Should-Be $true` compares as booleans. -- Type-specific switches live where they belong (`Should-BeString -IgnoreWhitespace`). -- `$null`, empty collections, and single-item arrays behave consistently. -- The set is **open** - see [Custom Assertion Guide](./custom-assertions.md) to add your own. +- Each assertion does one job, so its options are its own (`Should-BeString -IgnoreWhitespace`) and + its failure message is specific: a caret under the first differing character of a string, a line + diff for a long string, the missing and extra values of a collection. +- `-Expected` decides how the values are compared. `1 | Should-Be $true` and `'1' | Should-Be 1` both + pass, so assert the type as well when the type matters. +- A value assertion refuses a collection as `-Expected`. `Should-Be -Expected @(1, 2)` is an error + that names `Should-BeCollection`. +- The set can be extended. See the [custom assertion guide](./custom-assertions.md). -## Pipeline vs. -Actual +## Pipeline Or -Actual -The actual value comes from the pipeline or from `-Actual`: +The value under test comes from the pipeline or from `-Actual`: ```powershell 1 | Should-Be -Expected 1 Should-Be -Actual 1 -Expected 1 ``` -The pipeline **unwraps** its input. A _value_ assertion sees `1` and `@(1)` identically, and `@()` -as `$null`. A _collection_ assertion sees the same input as `@(1)` and `@()`. +The pipeline unrolls its input, and the two kinds of assertion read the result differently: -Use `-Actual` when the exact value or the concrete collection type matters: - -```powershell -# Value assertions - all pass -1 | Should-Be -Expected 1 -@(1) | Should-Be -Expected 1 -$null | Should-Be -Expected $null +| Piped input | A value assertion sees | A collection assertion sees | +| --- | --- | --- | +| `1` or `@(1)` | `1` | one item | +| `@()` | `$null` | no items | +| `$null` | `$null` | one item, which is `$null` | +| `1, 2, 3` | one `[Object[]]`, and the failure message says so | three items | +| `[int[]](1, 2)` | `[Object[]]`; the element type is lost | two items | -# Collection assertions -1, 2, 3 | Should-BeCollection @(1, 2, 3) -@() | Should-BeCollection @() +Pass the value with `-Actual` when its exact type matters: -# -Actual preserves the original type; piping would re-collect as [Object[]] +```powershell Should-HaveType -Actual ([int[]](1, 2)) -Expected ([int[]]) ``` -When unwrapping causes a failure, the message explains what the pipeline did and points back to -`-Actual`, so this is never a silent surprise. +When a value assertion fails on a piped collection, the message ends with a hint that explains what +the pipeline did and points to `-Actual`. -## Migration Map: Should -Be to Should-* +## Migration Map: Should -Be To Should-* -| Classic (v5) | New (v6) | Notes | +| Classic | Pester 6 | Notes | | --- | --- | --- | | `Should -Be $x` | `Should-Be $x` | | | `Should -Not -Be $x` | `Should-NotBe $x` | | | `Should -BeExactly $x` | `Should-BeString $x -CaseSensitive` | For strings | -| `Should -BeOfType [T]` | `Should-HaveType ([T])` | Name changed | +| `Should -BeOfType [T]` | `Should-HaveType ([T])` | Not with `[PSCustomObject]`; see Types | | `Should -Not -BeOfType [T]` | `Should-NotHaveType ([T])` | | | `Should -Match 'regex'` | `Should-MatchString 'regex'` | | | `Should -Not -Match 'regex'` | `Should-NotMatchString 'regex'` | | | `Should -BeLike 'pat*'` | `Should-BeLikeString 'pat*'` | | -| `Should -BeTrue` / `-BeFalse` | `Should-BeTrue` / `Should-BeFalse` | Strict `[bool]` | -| `Should -BeNullOrEmpty` | `Should-BeNull` / `Should-BeEmptyString` / `Should-BeFalsy` | **No single equivalent** - pick by intent | -| `Should -Not -BeNullOrEmpty` | `Should-NotBeNull` / `Should-NotBeEmptyString` / `Should-BeTruthy` | Same, pick by intent | +| `Should -BeTrue` / `-BeFalse` | `Should-BeTrue` / `Should-BeFalse` | Only a real `[bool]` passes | +| `Should -BeNullOrEmpty` | `Should-BeNull`, `Should-BeEmptyString`, or `Should-BeFalsy` | No single equivalent | +| `Should -Not -BeNullOrEmpty` | `Should-NotBeNull`, `Should-NotBeEmptyString`, or `Should-BeTruthy` | No single equivalent | | `Should -BeGreaterThan $x` | `Should-BeGreaterThan $x` | | | `Should -BeLessThan $x` | `Should-BeLessThan $x` | | | `Should -BeGreaterOrEqual $x` | `Should-BeGreaterThanOrEqual $x` | Name changed | | `Should -BeLessOrEqual $x` | `Should-BeLessThanOrEqual $x` | Name changed | -| `Should -Contain $item` | `Should-ContainCollection @($item)` | Now an ordered sub-collection check | +| `Should -Contain $item` | `Should-ContainCollection $item` | | +| `$item \| Should -BeIn $list` | `$list \| Should-ContainCollection $item` | The list is piped | | `Should -HaveCount 3` | `Should-BeCollection -Count 3` | | -| `Should -Throw '*msg*'` | `Should-Throw -ExceptionMessage 'msg'` | See exceptions below | +| `Should -Throw '*msg*'` | `Should-Throw -ExceptionMessage '*msg*'` | Both need the wildcards | | `Should -Invoke Cmd` | `Should-Invoke Cmd` | | | `Should -Not -Invoke Cmd` | `Should-NotInvoke Cmd` | | | `Should -InvokeVerifiable` | `Should-Invoke -Verifiable` | | | `Should -HaveParameter Name` | `Should-HaveParameter -ParameterName Name` | | -| `Should -BeIn @(...)` | `Should-Any { $_ -eq $actual }` or keep classic | No direct 1:1 | -| `Should -Exist` | Keep classic `Should -Exist` | No `Should-*` equivalent; gained `-LiteralPath` in v6 | +| `$path \| Should -Exist` | `Test-Path -LiteralPath $path \| Should-BeTrue` | There is no `Should-Exist` | -`Should -BeNullOrEmpty` has no single replacement on purpose - it conflated three different -questions. Choose the one you actually mean: +`Should -BeNullOrEmpty` asked three questions at once. Choose the one that is meant: ```powershell -$result.Error | Should-BeNull # is it $null? -$result.Name | Should-BeEmptyString # is it ''? -$result.Items | Should-BeFalsy # $null, '', 0, $false, or @() +$result.Error | Should-BeNull +$result.Name | Should-BeEmptyString +$result.Items | Should-BeFalsy ``` +`Should-BeFalsy` passes for `$null`, `''`, `0`, `$false`, and `@()`. `'' | Should-BeNull` fails, and +so does `$null | Should-BeEmptyString`. + ## The Four Families | Family | Examples | Use for | | --- | --- | --- | -| Value - generic | `Should-Be`, `Should-NotBe`, `Should-BeGreaterThan`, `Should-BeSame`, `Should-BeNull`, `Should-HaveType` | A single value, compared like the PowerShell operators | -| Value - type specific | `Should-BeString`, `Should-MatchString`, `Should-BeLikeString`, `Should-BeTrue`/`False`, `Should-BeFalsy`/`Truthy`, `Should-BeBefore`/`After`, `Should-BeFasterThan`/`SlowerThan` | A value of known type, with type-specific options | -| Collection - generic | `Should-BeCollection`, `Should-ContainCollection`, `Should-NotContainCollection` | Whole-collection comparison, or an ordered sub-collection | -| Collection - combinator | `Should-All`, `Should-Any` | A condition across every / any item | +| Value, generic | `Should-Be`, `Should-NotBe`, `Should-BeGreaterThan`, `Should-BeSame`, `Should-BeNull`, `Should-HaveType` | One value, compared the way the PowerShell operators compare | +| Value, typed | `Should-BeString`, `Should-MatchString`, `Should-BeLikeString`, `Should-BeTrue`, `Should-BeFalsy`, `Should-BeBefore`, `Should-BeFasterThan` | One value of a known type, with options for that type | +| Collection, generic | `Should-BeCollection`, `Should-ContainCollection`, `Should-NotContainCollection` | The same items in any order, or a sub-collection in order | +| Collection, combinator | `Should-All`, `Should-Any` | A condition on every item, or on at least one | -Plus dedicated assertions for exceptions (`Should-Throw`), mocks (`Should-Invoke`, -`Should-NotInvoke`), command metadata (`Should-HaveParameter`), hashtable shape -(`Should-BeHashtable`), and deep comparison (`Should-BeEquivalent`). +There are also assertions for errors (`Should-Throw`), mocks (`Should-Invoke`, `Should-NotInvoke`), +command metadata (`Should-HaveParameter`), hashtables (`Should-BeHashtable`), and deep comparison +(`Should-BeEquivalent`). ## Common Patterns @@ -121,291 +111,316 @@ Plus dedicated assertions for exceptions (`Should-Throw`), mocks (`Should-Invoke ```powershell ' hello ' | Should-BeString 'hello' -TrimWhitespace -'Hello' | Should-BeString 'hello' -CaseSensitive # fails, caret marks the first difference -'a b' | Should-BeString 'a b' -IgnoreWhitespace -$name | Should-MatchString '^[A-Z][a-z]+$' -$path | Should-BeLikeString 'C:\Temp\*' +'a b' | Should-BeString 'a b' -IgnoreWhitespace +'Hello' | Should-BeString 'Hello' -CaseSensitive +$name | Should-MatchString '^[A-Z][a-z]+$' +$path | Should-BeLikeString '*.json' ``` -Use `-NormalizeLineEnding` whenever the actual value came off disk. It treats `` `n `` and `` `r`n `` -as equal, which is the difference between a test that passes everywhere and one that fails on -whichever platform did not write the fixture: +`Should-Be`, `Should-BeString`, and `Should-BeLikeString` ignore case. `Should-BeString` and +`Should-BeLikeString` take `-CaseSensitive`. + +Use `-NormalizeLineEnding` when the actual value was read from a file. It treats `` `n `` and +`` `r`n `` as equal, so the test does not depend on the platform that wrote the file: ```powershell -"a`r`nb" | Should-BeString "a`nb" -NormalizeLineEnding -Get-Content $path -Raw | Should-BeString $expected -NormalizeLineEnding +Get-Content -LiteralPath $reportPath -Raw | Should-BeString $expected -NormalizeLineEnding ``` -`Should-NotBeString` takes both `-TrimWhitespace` and `-NormalizeLineEnding`, and its `-Expected` is -mandatory. +`Should-NotBeString` takes the same switches, and its `-Expected` is mandatory. -#### Long strings get a real diff +#### Long Strings -From 6.2, when either string is longer than 10 lines or 120 characters, a failing `Should-BeString` -prints every region that differs with context, instead of a caret under the first difference. -Expected line numbers are on the left and actual on the right, so the output stays readable when -lines were added or removed and the two sides stop lining up: +A failing `Should-BeString` prints a line diff in place of the caret when the strings have more than +one line and either more than 10 lines or more than 120 characters. Expected line numbers are on the +left and actual on the right: ```text Expected strings to be the same, but they were different. -Expected length: 860 -Actual length: 834 -Expected 30 line(s), actual 30 line(s). -2 regions differ. +Expected length: 309 +Actual length: 296 +Expected 11 line(s), actual 11 line(s). +1 region differs. + 3 3 | line 3 of the expected text 4 4 | line 4 of the expected text 5 | - line 5 of the expected text 5 | + line 5 CHANGED 6 6 | line 6 of the expected text - ... - 17 | - line 17 of the expected text - 17 | + line 17 CHANGED + 7 7 | line 7 of the expected text ``` -Only the differing lines are expanded, so a tab or trailing space shows up without the unchanged -context turning into escape codes. This is the assertion to use for snapshot tests, rendered -templates, and generated configuration files - pair it with `-NormalizeLineEnding`. Short strings -keep the caret. +This makes `Should-BeString` the assertion for rendered templates and generated files. `Should-Be` +on the same strings prints both in full. -### Booleans and null +### Booleans And Null ```powershell -$true | Should-BeTrue -$result | Should-NotBeNull -$result.Error | Should-BeNull -$result.Items | Should-BeTruthy +$result.IsReady | Should-BeTrue +$result.Error | Should-BeNull +$result.Name | Should-NotBeEmptyString ``` +`Should-BeTrue` and `Should-BeFalse` pass only for a `[bool]`: `1 | Should-BeTrue` fails. Use +`Should-BeTruthy` and `Should-BeFalsy` when any value that PowerShell converts to that Boolean will +do. + +An empty array reaches a value assertion as `$null`, so `@() | Should-BeNull` passes and +`@() | Should-NotBeNull` fails. To assert that a command returned something, assert the count +(TST-12). + ### Types ```powershell -$result | Should-HaveType ([pscustomobject]) -$result.Retries | Should-HaveType ([int]) -$result | Should-NotHaveType ([hashtable]) +$result | Should-HaveType 'ModuleName.Thing' +$result.RetryCount | Should-HaveType ([int]) +$result | Should-NotHaveType ([hashtable]) ``` -`Should-HaveType` honors `PSTypeNames`, so an object decorated with a synthetic type name - the usual -way a module brands its output - asserts against that name directly: +A string argument is matched against the object's type and against its `PSTypeName`, so a custom +object is asserted by the name its function gives it (TST-13). Related facts: + +- `Should-HaveType ([PSCustomObject])` passes for every piped value, including `5`. For an object + that carries no type name, such as the output of `ConvertFrom-Json`, pass the full name as a + string: `Should-HaveType 'System.Management.Automation.PSCustomObject'` fails for a number, a + string, and a hashtable. +- `PSTypeName` is not a property. `$result.PSTypeName` is `$null`; the name is + `$result.PSObject.TypeNames[0]`. +- A piped array arrives as `[Object[]]`. Assert a typed array with `-Actual`, as shown under + "Pipeline Or -Actual". + +### Collections ```powershell -$session | Should-HaveType 'MyModule.Session' +$names | Should-BeCollection @('alpha', 'beta') +$names | Should-BeCollection -Count 2 +$names | Should-All { $_ -like '*a' } +$names | Should-Any { $_ -eq 'beta' } +$names | Should-ContainCollection @('alpha', 'beta') +$names | Should-ContainCollection @('beta', 'alpha') -IgnoreOrder +$names | Should-NotContainCollection @('gamma') ``` -That is the assertion to reach for when a module's formatting or a `ValidateScript` depends on the -type name, and it beats asserting on `$session.PSTypeNames[0]` as a string. +The Pester rules list the results that matter most: `Should-BeCollection` does not compare order, +and `Should-All` fails on an empty input. In addition: -### Collections +| Assertion | Behaviour | +| --- | --- | +| `1, 1, 2 \| Should-BeCollection @(1, 2, 2)` | Fails. Each value must occur the same number of times. | +| `1, 2, 3 \| Should-BeCollection @(1, 2)` | Fails. The counts differ. | +| `$null \| Should-BeCollection -Count 0` | Fails. `$null` is one item. Pipe `@()` for an empty collection. | +| `'a' \| Should-BeCollection -Count 1` | Passes. | +| `'a', 'b', 'c' \| Should-ContainCollection @('a', 'c')` | Passes. The items must appear in this order; gaps are allowed. | +| `'a', 'b', 'c' \| Should-ContainCollection @('c', 'a')` | Fails. It passes with `-IgnoreOrder`. | + +To assert order, assert the count and then each element (TST-14). For a list of strings, one +assertion on the joined text also shows the whole sequence when it fails: ```powershell -1, 2, 3 | Should-BeCollection @(1, 2, 3) -1, 2, 3 | Should-BeCollection -Count 3 -1, 2, 3 | Should-All { $_ -gt 0 } -1, 2, 3 | Should-Any { $_ -gt 2 } -@('a', 'b', 'c') | Should-ContainCollection @('a', 'c') # ordered sub-collection, gaps allowed +$result | Should-BeCollection -Count 2 +$result[0].Name | Should-Be 'beta' +$result[1].Name | Should-Be 'alpha' + +$calls -join ', ' | Should-Be 'Connect, Query, Disconnect' ``` -`Should-ContainCollection` is order-sensitive by default. When the source genuinely has no defined -order - a hashtable's keys, a directory listing, a set of exported command names - assert with -`-IgnoreOrder` rather than sorting both sides at the call site: +The script block of `Should-All` may contain assertions. When one fails, the message of `Should-All` +includes its reason: ```powershell -1, 2, 3 | Should-ContainCollection @(3, 1) -IgnoreOrder -$module.ExportedFunctions.Keys | Should-ContainCollection @('Get-Thing', 'Set-Thing') -IgnoreOrder +$results | Should-All { $_.State | Should-Be 'ready' } ``` -### Exceptions +Use `-IgnoreOrder` on `Should-ContainCollection` when the source has no defined order, such as the +keys of a hashtable. + +### Errors -`Should-Throw` takes the scriptblock from the pipeline (or `-ScriptBlock`) and matches on message, -type, or error id: +`Should-Throw` takes the script block from the pipeline and can match the message, the type, or the +error ID: ```powershell { throw 'kaboom' } | Should-Throw -ExceptionMessage 'kaboom' +{ throw 'the disk is full' } | Should-Throw -ExceptionMessage '*disk*' -{ Get-Thing -Id $null } | - Should-Throw -ExceptionType ([System.ArgumentNullException]) +{ Get-Thing -Name 'alpha' -ErrorAction Stop } | + Should-Throw -ExceptionType ([System.InvalidOperationException]) -{ Get-Thing -Id 'bad' } | - Should-Throw -FullyQualifiedErrorId 'InvalidId,Get-Thing' - -# Non-terminating errors need the switch -{ Get-Thing -Id 'bad' } | Should-Throw -AllowNonTerminatingError +{ Get-Thing -Name 'alpha' -ErrorAction Stop } | + Should-Throw -FullyQualifiedErrorId 'ThingReadFailed,Get-Thing' ``` -`-ExceptionMessage` matches with wildcards, so `'kaboom'` matches the whole message and -`'*kaboom*'` matches a substring. This differs from classic `Should -Throw '*kaboom*'`, where the -leading wildcard was almost always required. +- `-ExceptionMessage` and `-FullyQualifiedErrorId` compare with `-like` against the whole value, + ignoring case. Without wildcards the pattern must equal the whole message, and `'ThingReadFailed'` + does not match `'ThingReadFailed,Get-Thing'`. Write `'*disk*'` or `'ThingReadFailed*'` for a + partial match. The classic `Should -Throw 'text'` compares the same way. +- `-ExceptionType` passes for that type or a type derived from it. It compares the outer exception: + a failure inside a .NET method call arrives as a `MethodInvocationException`. +- `-Because` is named only. The positional arguments are the message, the error ID, and the type, + in that order. +- `Should-Throw` returns the error record, so a test can assert more about it: + +```powershell +$failure = { Export-Thing -Thing $things -LiteralPath $missingPath } | + Should-Throw -ExceptionType ([System.Management.Automation.MethodInvocationException]) + +$failure.Exception.InnerException | Should-HaveType ([System.IO.DirectoryNotFoundException]) +``` -Because the match is `-like`, the characters `[ ] * ?` in the expected message are **wildcards, not -literals**. A message containing brackets fails against itself unless you escape them: +Because the match is `-like`, the characters `[ ] * ?` in the expected message are wildcards. A +message that contains brackets does not match itself until they are escaped: ```powershell { throw 'value is [1]' } | Should-Throw -ExceptionMessage 'value is `[1]' -{ throw 'value is [1]' } | - Should-Throw -ExceptionMessage ([System.Management.Automation.WildcardPattern]::Escape('value is [1]')) + +$pattern = [System.Management.Automation.WildcardPattern]::Escape('value is [1]') +{ throw 'value is [1]' } | Should-Throw -ExceptionMessage $pattern ``` -Pester detects this specific case - when the two messages differ only in those characters the -failure says so, rather than printing two strings that look identical. `Should-Throw -Because` is -named-only; it cannot be passed positionally. +When the two messages differ only in those characters, the failure message says so. -There is no `Should-NotThrow`. Call the code directly - an unhandled exception fails the test: +#### Code That Must Not Fail + +There is no `Should-NotThrow` (TST-16). Call the command in the test, with `-ErrorAction Stop`: ```powershell -It 'accepts a valid id' { - Get-Thing -Id 'valid' # no assertion needed; a throw fails the test +It 'Accepts a name with a hyphen' { + $null = Get-Thing -Name 'alpha-2' -ErrorAction Stop } ``` -### Mocks +Any error then fails the test. Without `-ErrorAction Stop`, a non-terminating error is only written +to the error stream and the test still passes. -```powershell -Should-Invoke Send-Email -Times 2 -Exactly -ParameterFilter { $To -eq 'alice@example.com' } -Should-NotInvoke Remove-Item -Should-Invoke -Verifiable -``` +#### Non-Terminating Errors -When a mock assertion fails, Pester 6 prints the recorded invocation history and marks which calls -matched the `-ParameterFilter` with `[*]`: +`Should-Throw` runs the script block with `$ErrorActionPreference` set to `Stop`. The result depends +on where the error comes from: -```text -[-] emails alice exactly twice - Expected Send-Email to be called 2 times exactly, but was called 1 times - Performed invocations: - [*] Send-Email -To 'alice@example.com' -Subject 'Welcome' from Order.Tests.ps1:7 - [ ] Send-Email -To 'bob@example.com' -Subject 'Receipt' from Order.Tests.ps1:7 -``` +| Source of the non-terminating error | `Should-Throw` | +| --- | --- | +| A cmdlet, such as `Get-Item` on a missing path | Passes | +| A function defined in the test file | Passes | +| A function in a module | Fails. A module does not see that preference. | +| A function in a module, called with `-ErrorAction Stop` | Passes | + +`-AllowNonTerminatingError` does not help here. It runs the script block with `Continue`, so +non-terminating errors are let through and only a terminating error passes. + +For module code, follow TST-17: merge the error stream and count the records. To test that the error +stops the caller on request, pass `-ErrorAction Stop` inside the script block. -### Command metadata +### Mocks ```powershell -Get-Command Get-Thing | Should-HaveParameter -ParameterName Name -Type ([string[]]) -Mandatory -Get-Command Get-Thing | Should-HaveParameter -ParameterName Path -DefaultValue '.' -Get-Command Get-Thing | Should-NotHaveParameter -ParameterName Force +Should-Invoke -CommandName Invoke-RestMethod -ModuleName ModuleName -Times 1 -Exactly +Should-NotInvoke -CommandName Remove-Item -ModuleName ModuleName +Should-Invoke -Verifiable ``` -### Time and duration +The [mocking guide](./mocking-patterns.md) covers parameter filters, scopes, and the invocation +history that a failed assertion prints. + +### Command Metadata ```powershell -{ Invoke-Thing } | Should-BeFasterThan '100ms' -{ Invoke-Thing } | Should-BeSlowerThan '10ms' -[datetime]::Now.AddMinutes(11) | Should-BeAfter 10minutes -Ago -$record.Created | Should-BeBefore ([datetime]::Now) +Get-Command -Name Get-Thing | Should-HaveParameter -ParameterName Name -Type ([string[]]) -Mandatory +Get-Command -Name Get-Thing | Should-HaveParameter -ParameterName Path -DefaultValue '.' +Get-Command -Name Get-Thing | Should-NotHaveParameter -ParameterName Force ``` -`Should-BeFasterThan` replaces hand-rolled `Measure-Command` plus `Should -BeLessThan` and avoids -the TimeSpan-vs-double comparison mistakes that pattern invites. Its `-Expected` is mandatory, as is -`Should-BeSlowerThan`'s - a bare `Should-BeFasterThan` no longer binds to a silent default. - -Both take a `[scriptblock]` to measure or a `[timespan]` to compare, and nothing else. From 6.2 -anything else **throws**: +### Time And Duration ```powershell -{ Invoke-Thing } | Should-BeFasterThan 1s # measures the scriptblock -(Invoke-Thing) | Should-BeFasterThan 1s # 6.1: passed without measuring anything. 6.2: throws -# Expected a [scriptblock] to measure or a [timespan] to compare, but got [string] 'result'. +{ Get-ThingSummary -Thing $things } | Should-BeFasterThan '100ms' +{ Start-Sleep -Milliseconds 50 } | Should-BeSlowerThan '10ms' +$record.Created | Should-BeBefore ([datetime]::Now) +$record.Created | Should-BeAfter 10minutes -Ago ``` -On 6.1 a string, a number, or `$null` fell through the assertion and the test passed having asserted -nothing. A performance test that starts failing on 6.2 with that message was never measuring. +- `Should-BeFasterThan` and `Should-BeSlowerThan` measure a piped script block, or compare a piped + `[timespan]`. Any other input is an error: + `Expected a [scriptblock] to measure or a [timespan] to compare, but got [string] 'result'.` Pipe + the script block, not its result. +- `-Expected` is mandatory. It is a `[timespan]` or a number with a unit: `ms`, `s`, `m`, `h`, `d`, + `w`, or a longer form such as `'1.5hours'`. +- The failure message contains the measured time. +- `Should-BeLessThan` cannot compare a `[timespan]` with a number; it stops with + `Could not compare`. Compare `$elapsed.TotalMilliseconds` with a number, or a `[timespan]` with a + `[timespan]`. +- `-Ago`, `-FromNow`, and `-Now` compare with the current time. When the code under test reads the + clock, mock `Get-Date` instead (TST-31). -### Deep object comparison +### Deep Object Comparison -`Should-BeEquivalent` walks nested properties, hashtables, dictionaries, and collections and emits -a property-by-property diff. Use it for whole API responses or configuration objects: +`Should-BeEquivalent` compares nested properties, hashtables, and collections, and prints the +differences by property. Use it for a whole response or configuration object: ```powershell -$user | Should-BeEquivalent ([pscustomobject]@{ - Name = 'Jakub' - Age = 31 - Address = [pscustomobject]@{ City = 'Prague'; Country = 'CZ' } - Roles = @('admin', 'user') -}) +$expected = [PSCustomObject]@{ + Name = 'Jakub' + Age = 31 + Address = [PSCustomObject]@{ City = 'Prague'; Country = 'CZ' } + Roles = @('admin', 'user') +} + +$user | Should-BeEquivalent $expected ``` -The comparison is **strict and symmetric** by default - an extra property on the actual object -fails. Compare like with like (object to object, hashtable to hashtable). Two options relax it: +By default every property must be present on both sides: an extra property on the actual object +fails, and so does a missing one. Two options relax that: ```powershell -# Assert a subset: properties absent from $expected are never looked at -$user | Should-BeEquivalent ([pscustomobject]@{ Name = 'Jakub' }) -ExcludePathsNotOnExpected +# Properties that $expected does not have are not compared. +$user | Should-BeEquivalent ([PSCustomObject]@{ Name = 'Jakub' }) -ExcludePathsNotOnExpected -# Full comparison except volatile fields; dot-notation reaches nested members +# Everything is compared except the named paths. A dot reaches a nested property. $actual | Should-BeEquivalent $expected -ExcludePath 'Id', 'Metadata.Timestamp' - -# Non-recursive equality when that is all you need -$actual | Should-BeEquivalent $expected -Comparator Equality ``` -Prefer `-ExcludePathsNotOnExpected` over listing every field you do not care about. It keeps tests -focused and resilient: a new field on the object under test will not break an assertion that never -claimed to care about it. +What it does not check: -## Writing Your Own +- The order of a collection. `@(1, 2, 3) | Should-BeEquivalent @(3, 2, 1)` passes, and so does a + property that holds the same items in another order. +- The type of a value. A property that holds `1` is equivalent to one that holds `'1'`. -The `Should-*` family is open for extension. Declare a function, call `New-ShouldAssertion` inside -it, and the result collects pipeline input, formats values, and fails through the same path a -built-in assertion uses - so soft assertions and mock parameter filters work with no extra effort: +Compare like with like: an object is not equivalent to a hashtable that has the same keys. -```powershell -function Assert-BeValidSemVer { - [CmdletBinding()] - param ( - [Parameter(Position = 0, ValueFromPipeline)] $Actual, - [string] $Because - ) - - $assert = New-ShouldAssertion -Caller $PSCmdlet -Actual $Actual -Buffer $Input - $Actual = $assert.Actual() - - $parsed = $null - if (-not [version]::TryParse($Actual, [ref] $parsed) -or $parsed.Build -lt 0) { - $assert.Fail( - 'Expected a Major.Minor.Patch version,<because> but got <actual>.', - @{ Because = $Because }) - } -} - -Set-Alias -Name Should-BeValidSemVer -Value Assert-BeValidSemVer -``` - -Reach for this only when the same non-trivial check recurs across files **and** naming the offending -value is the point. See [Custom Assertion Guide](./custom-assertions.md) for the full treatment - -`-As` modes, message tokens, the `Assert-` verb packaging rule, and how to test the assertion itself. +## Writing Your Own -This replaces `Add-ShouldOperator` for new work. That mechanism still exists for the classic `Should` -syntax, but it is a different shape and the runspace caps out at 32 operators. +A custom assertion is a function that calls `New-ShouldAssertion`. It gets the same input handling, +formatting, and failure path as the built-in assertions. Write one only when the same check recurs +in several test files and the built-in failure message cannot name what went wrong. The +[custom assertion guide](./custom-assertions.md) has the details. ## Soft Assertions -Both syntaxes honor `Should.ErrorAction = 'Continue'`, which collects every failure in an `It` -instead of stopping at the first: +With `Should.ErrorAction = 'Continue'`, a failed assertion is recorded and the test goes on, so one +`It` reports every failure: ```powershell -$config = New-PesterConfiguration -$config.Should.ErrorAction = 'Continue' +$configuration = New-PesterConfiguration +$configuration.Should.ErrorAction = 'Continue' ``` ```powershell -It 'has the expected shape' { +It 'Returns the expected user' { $user.Name | Should-Be 'Jakub' - $user.Age | Should-Be 31 + $user.Age | Should-Be 31 $user.City | Should-Be 'Prague' } ``` -All three run and every failure is reported at the end of the test. Use this for shape assertions -on a single object. Keep the default `'Stop'` elsewhere, so a failed precondition does not cascade -into a wall of downstream noise. - -## Assertion Selection Guidelines - -- Assert on the narrowest thing that proves the behavior. `Should-Be 'Active'` beats - `Should-NotBeNull`. -- Prefer `Should-BeEquivalent -ExcludePathsNotOnExpected` over a run of six property assertions. -- Use `Should-HaveType` rather than asserting on `.GetType().Name` as a string. -- Use `-Because` to record intent on non-obvious assertions: - `$retries | Should-Be 3 -Because 'the transient-failure policy caps retries at 3'`. -- Do not assert on the text of a message you also control and change often; assert on the error - type or id instead. -- Write a [custom assertion](./custom-assertions.md) only when the same domain rule is asserted in - several files and the built-in failure message cannot name what went wrong. +A single assertion can opt in with `-ErrorAction Continue`. Keep the default, `Stop`, for assertions +that later lines depend on, such as a count before an index. + +## Choosing An Assertion + +- Assert the narrowest fact that proves the behaviour. `Should-Be 'Active'` is better than + `Should-NotBeNull` (TST-11). +- Assert the count before reading an element by index (TST-12). +- Prefer one `Should-BeEquivalent -ExcludePathsNotOnExpected` to a run of property assertions, and + add index assertions when order matters. +- Assert an error by its type or error ID. A message that the code owns changes more often. +- Use `-Because` to record the reason for a value that is not obvious: + `$retryCount | Should-Be 3 -Because 'the retry policy stops after three attempts'`. diff --git a/.github/instructions/pester-supporting-docs/cicd-integration.md b/.github/instructions/pester-supporting-docs/cicd-integration.md index 98269aa..a661e43 100644 --- a/.github/instructions/pester-supporting-docs/cicd-integration.md +++ b/.github/instructions/pester-supporting-docs/cicd-integration.md @@ -1,988 +1,427 @@ # CI/CD Integration Guide -Targets **Pester 6.2+**. Pester 6 supports **Windows PowerShell 5.1** and **PowerShell 7.4+** only - -support for PowerShell 3, 4, 6, and early/unsupported 7.x was removed, so drop `7.2` and `7.3` from -existing test matrices. - -**Matrix targets (verified 2026-08-01):** build against **PowerShell 7.6 (LTS)**. PowerShell 7.4 and -7.5 both reach end of support on **10-Nov-2026** - keep them in the matrix only while you still -support consumers on those versions, and plan their removal. See -[powershell-version.instructions.md](../powershell-version.instructions.md). - -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. - -## Job Design for Pester 6 - -Three facts shape the pipeline: - -1. **Coverage and parallel pull against each other.** Pester 6.0 refused to combine them at all; - 6.1 merges coverage across workers but forces slower breakpoint-based collection to do it. Either - way, run a fast parallel job without coverage for feedback and a separate sequential job with the - profiler for the gate. -2. **Discovery failures do not appear in `FailedCount`.** A file that fails discovery contributes - zero failed tests. Every gate must also check `FailedContainersCount`, and a cheap discovery-only - job should run first. -3. **Pester 6.0 and 6.1 do not import on PowerShell 7.4.0 to 7.4.5.** Their `net8.0` assembly - referenced a newer `System.Management.Automation` than those releases carry, so `Import-Module` - failed with `Cannot convert "PesterConfigurationDeserializer" from String to Type`. 6.2 fixed it. - Hosted runners ship the latest 7.4.x, so this bites self-hosted agents and pinned container - images - pin Pester at 6.2.0 or newer wherever a 7.4 leg remains. - -```text -validate (discovery-only, fast) - | - +--> test-parallel (no coverage, fast feedback) - +--> test-coverage (sequential, coverage gate) - +--> test-ps51 (Windows PowerShell 5.1; parallel works here too from 6.2) -``` +This guide shows how to run Pester in a pipeline so that the build fails when it should. It supports +the CI rules in [powershell-cicd.instructions.md](../powershell-cicd.instructions.md) and rules +TST-40 to TST-42 in [powershell-pester.instructions.md](../powershell-pester.instructions.md). -## GitHub Actions Integration +The gate script was run on Pester 6.2.0 under PowerShell 7.6 and Windows PowerShell 5.1. The +pipeline definitions are well-formed, and the GitHub Actions and Azure Pipelines keywords were +checked against their documentation, but none of the pipelines was run on a CI service. -### Complete GitHub Actions Workflow +## What the Pipeline Must Do -```yaml -name: PowerShell Testing +- Install PSScriptAnalyzer and Pester at fixed versions (CIC-02). +- Run both on every pull request, and fail when either reports a problem (CIC-01). +- Fail when no tests ran, when the Pester result is not `Passed`, and when coverage is below + 80 percent (TST-40, TST-42). +- Run on PowerShell 7.6. Add a Windows PowerShell 5.1 job only when the project declares 5.1 support + (CIC-03). +- Leave out every PowerShell version that is past its end-of-support date (CIC-04). PowerShell 7.4 + and 7.5 reached it on 10-Nov-2026; see + [powershell-version.instructions.md](../powershell-version.instructions.md). -on: - push: - branches: [ main, develop ] - pull_request: - branches: [ main ] - schedule: - - cron: '0 2 * * *' # Daily at 2 AM +Three facts about Pester 6.2.0 shape the gate: -env: - POWERSHELL_TELEMETRY_OPTOUT: 1 - PESTER_VERSION: '6.2.0' +1. A failed run does not always have a failed test. A failing `AfterAll` leaves `FailedCount` at 0 + and sets `FailedBlocksCount`. A file that fails discovery sets only `FailedContainersCount`. The + property that covers every case is `Result`. The table is in + [Test Execution Guide](./test-execution.md#what-a-failure-looks-like). +2. A run whose files contain no tests has the result `Passed`, and a run that finds no test file + returns nothing. The gate therefore tests for `$null` and for `TotalCount`. +3. `CodeCoverage.CoveragePercentTarget` does not fail a run. The script compares the percentage. -jobs: - # Fast structural check. Catches the Pester 6 breakages - empty -ForEach, files - # that cannot be discovered independently, a wrong-typed configuration value - - # without running a single test. - validate: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v7 - - - name: Install Pester - shell: pwsh - run: | - Install-PSResource Pester -Version "[$env:PESTER_VERSION,)" -Scope CurrentUser -TrustRepository - - - name: Discovery-only pass - shell: pwsh - run: | - $config = New-PesterConfiguration - $config.Run.Path = './Tests' - $config.Run.SkipRun = $true - $config.Run.PassThru = $true - $config.Output.CIFormat = 'GithubActions' - - $result = Invoke-Pester -Configuration $config - - if ($result.FailedContainersCount -gt 0) { - $result.FailedContainers | ForEach-Object { - Write-Host "::error file=$($_.Item)::Discovery failed: $($_.ErrorRecord.Exception.Message)" - } - throw "$($result.FailedContainersCount) file(s) failed discovery" - } - Write-Host "Discovered $($result.TotalCount) tests across $($result.Containers.Count) files" - - - name: Verify every test is tagged - shell: pwsh - run: | - $config = New-PesterConfiguration - $config.Run.Path = './Tests' - $config.Filter.Tag = 'None' # reserved value: tests with NO tags - $config.Run.SkipRun = $true - $config.Run.PassThru = $true - $config.Output.Verbosity = 'None' - - $result = Invoke-Pester -Configuration $config - - # ShouldRun marks what Filter.Tag selected. TotalCount ignores the filter - it counts - # everything discovered, so it would fail every non-empty suite - and PassedCount only - # counts untagged tests that ran AND passed, which under Run.SkipRun is never any. - $untagged = @($result.Tests | Where-Object ShouldRun) - if ($untagged.Count -gt 0) { - $untagged | ForEach-Object { - Write-Host "::error::Untagged test: $($_.ExpandedPath)" - } - throw "$($untagged.Count) test(s) have no tag" - } +## The Gate Script - test: - needs: validate - runs-on: ${{ matrix.os }} - strategy: - fail-fast: false - matrix: - # Pester 6 supports Windows PowerShell 5.1 and PowerShell 7.4+ only. - # ubuntu/macos runners ship PowerShell 7.4+; windows-latest has both. - os: [windows-latest, ubuntu-latest, macos-latest] - shell: [pwsh] - include: - # Windows PowerShell 5.1 - Run.Parallel works here from Pester 6.2 - - os: windows-latest - shell: powershell - - steps: - - uses: actions/checkout@v7 - - - name: Cache PowerShell Modules - uses: actions/cache@v4 - with: - path: | - ~/.local/share/powershell/Modules - ~/Documents/PowerShell/Modules - ~/Documents/WindowsPowerShell/Modules - key: ${{ runner.os }}-pester-${{ env.PESTER_VERSION }}-${{ hashFiles('**/*.psd1') }} - restore-keys: | - ${{ runner.os }}-pester-${{ env.PESTER_VERSION }}- - - - name: Install Dependencies - shell: ${{ matrix.shell }} - run: | - # Install-PSResource is in-box on PowerShell 7.4+; Windows PowerShell 5.1 needs PowerShellGet. - if (Get-Command Install-PSResource -ErrorAction SilentlyContinue) { - Install-PSResource Pester -Version "[$env:PESTER_VERSION,)" -Scope CurrentUser -TrustRepository - Install-PSResource PSScriptAnalyzer -Scope CurrentUser -TrustRepository - } - else { - Set-PSRepository PSGallery -InstallationPolicy Trusted - Install-Module Pester -MinimumVersion $env:PESTER_VERSION -Force -Scope CurrentUser - Install-Module PSScriptAnalyzer -Force -Scope CurrentUser - } +Keep the logic in one script that the pipeline and a developer both call. The test folder is held in +one place, the `TestRoot` parameter. - - name: Run PSScriptAnalyzer - shell: ${{ matrix.shell }} - run: | - $analysisResults = Invoke-ScriptAnalyzer -Path . -Recurse -Settings PSGallery - if ($analysisResults) { - $analysisResults | Format-Table -AutoSize - throw "PSScriptAnalyzer found $($analysisResults.Count) issues" - } - - # Fast feedback: parallel, no coverage. From Pester 6.2 the parallel runner - # works on Windows PowerShell 5.1 too; 6.0 and 6.1 fell back to sequential there. - - name: Run Unit Tests - shell: ${{ matrix.shell }} - run: | - Import-Module Pester -MinimumVersion 6.2.0 -Force - - $config = New-PesterConfiguration - $config.Run.Path = './Tests/Unit' - $config.Run.PassThru = $true - $config.Run.Parallel = $true - $config.TestResult.Enabled = $true - $config.TestResult.OutputFormat = 'NUnitXml' - $config.TestResult.OutputPath = './TestResults.xml' - $config.Output.Verbosity = 'Detailed' - $config.Output.CIFormat = 'GithubActions' - - $result = Invoke-Pester -Configuration $config - - # Check BOTH - a file that fails discovery contributes 0 to FailedCount - if ($result.FailedCount -gt 0 -or $result.FailedContainersCount -gt 0) { - throw "Unit tests failed: $($result.FailedCount) test failure(s), $($result.FailedContainersCount) container failure(s)" - } +```powershell +#requires -Version 7.6 - - name: Run Integration Tests - shell: ${{ matrix.shell }} - run: | - Import-Module Pester -MinimumVersion 6.2.0 -Force - - $config = New-PesterConfiguration - $config.Run.Path = './Tests/Integration' - $config.Run.PassThru = $true - # Integration tests share external resources - never parallel - $config.Run.Parallel = $false - $config.Filter.Tag = 'Integration' - $config.TestResult.Enabled = $true - $config.TestResult.OutputFormat = 'NUnitXml' - $config.TestResult.OutputPath = './IntegrationResults.xml' - $config.Output.CIFormat = 'GithubActions' - - $result = Invoke-Pester -Configuration $config - - if ($result.FailedCount -gt 0) { - Write-Warning "Integration tests failed: $($result.FailedCount) failures" - # Don't fail the build for integration test failures - } +<# +.SYNOPSIS +Runs the Pester tests and fails when the quality gate is not met. - - name: Upload Test Results - uses: actions/upload-artifact@v7 - if: always() - with: - name: test-results-${{ matrix.os }}-${{ matrix.shell }} - path: | - TestResults.xml - IntegrationResults.xml - - # Coverage runs sequentially so it can use the fast profiler tracer. Pester 6.1 - # does support coverage under Run.Parallel, but forces breakpoint mode to do it. - coverage: - needs: validate - runs-on: windows-latest - steps: - - uses: actions/checkout@v7 - - - name: Install Pester - shell: pwsh - run: | - Install-PSResource Pester -Version "[$env:PESTER_VERSION,)" -Scope CurrentUser -TrustRepository - - - name: Run Tests with Coverage - shell: pwsh - run: | - Import-Module Pester -MinimumVersion 6.2.0 -Force - - $config = New-PesterConfiguration - $config.Run.Path = './Tests/Unit' - $config.Run.PassThru = $true - # Sequential job, so it is the one that runs shuffled: a fresh seed each run, printed - # at the start and named below when the run fails - $config.Run.Shuffle = $true - $config.CodeCoverage.Enabled = $true - $config.CodeCoverage.Path = './Public/*.ps1', './Private/*.ps1' - # Profiler-based coverage is the v6 default and far faster than breakpoints - $config.CodeCoverage.UseBreakpoints = $false - $config.CodeCoverage.OutputFormat = 'JaCoCo' - $config.CodeCoverage.OutputPath = './coverage.xml' - # CoveragePercentTarget is the REPORTED target - it does not fail the run. - # There is no CodeCoverage.Threshold setting. - $config.CodeCoverage.CoveragePercentTarget = 80 - $config.Output.CIFormat = 'GithubActions' - - $result = Invoke-Pester -Configuration $config - - if ($result.FailedCount -gt 0 -or $result.FailedContainersCount -gt 0) { - $seed = $result.Configuration.Run.ShuffleSeed.Value - throw "Tests failed: $($result.FailedCount) test(s), $($result.FailedContainersCount) container(s). Replay with Run.ShuffleSeed = $seed" - } +.DESCRIPTION +Runs every test under the test root with code coverage, and writes a test result report and a +coverage report. Throws when no tests ran, when the Pester result is not 'Passed', or when code +coverage is below 80 percent. - # Enforce the coverage gate yourself - $actual = [math]::Round($result.CodeCoverage.CoveragePercent, 2) - $target = $result.CodeCoverage.CoveragePercentTarget +.PARAMETER TestRoot +Folder that contains the test files. The default is the Tests folder of the repository. - "## Code Coverage`n`n**$actual%** (target $target%)" | - Out-File $env:GITHUB_STEP_SUMMARY -Append +.PARAMETER OutputPath +Folder that receives testResults.xml and coverage.xml. The default is the out folder of the +repository. - if ($actual -lt $target) { - $result.CodeCoverage.CommandsMissed | Group-Object File | ForEach-Object { - Write-Host "::warning file=$($_.Name)::$($_.Count) uncovered commands" - } - throw "Code coverage $actual% is below the $target% target" - } +.PARAMETER TestResultFormat +Format of the test result report. - - name: Upload Coverage - uses: actions/upload-artifact@v7 - if: always() - with: - name: coverage - path: coverage.xml - - - name: Upload Coverage to Codecov - uses: codecov/codecov-action@v5 - with: - files: ./coverage.xml - flags: powershell - env: - CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} - - security-scan: - needs: validate - runs-on: windows-latest - steps: - - name: Checkout Repository - uses: actions/checkout@v7 - - - name: Install Dependencies - shell: pwsh - run: | - # Install-PSResource is in-box on PowerShell 7.4+; Windows PowerShell 5.1 needs PowerShellGet. - if (Get-Command Install-PSResource -ErrorAction SilentlyContinue) { - Install-PSResource Pester -Version "[$env:PESTER_VERSION,)" -Scope CurrentUser -TrustRepository - Install-PSResource PSScriptAnalyzer -Scope CurrentUser -TrustRepository - } - else { - Set-PSRepository PSGallery -InstallationPolicy Trusted - Install-Module Pester -MinimumVersion $env:PESTER_VERSION -Force -Scope CurrentUser - Install-Module PSScriptAnalyzer -Force -Scope CurrentUser - } +.PARAMETER CoverageFormat +Format of the coverage report. - - name: Run Security Tests - shell: pwsh - run: | - Import-Module Pester -MinimumVersion 6.2.0 -Force - - $config = New-PesterConfiguration - $config.Run.Path = './Tests/Security' - $config.Filter.Tag = 'Security' - $config.Run.PassThru = $true - $config.TestResult.Enabled = $true - $config.TestResult.OutputPath = './SecurityResults.xml' - $config.Output.CIFormat = 'GithubActions' - - $result = Invoke-Pester -Configuration $config - - # A security suite that discovers zero tests must fail the build. - # Attack-pattern data built in BeforeAll instead of BeforeDiscovery - # silently collapses the suite - see security-test-template.md. - if ($result.TotalCount -eq 0) { - throw "Security suite discovered no tests - check BeforeDiscovery data" - } +.EXAMPLE +./build/Invoke-Tests.ps1 - if ($result.FailedCount -gt 0 -or $result.FailedContainersCount -gt 0) { - throw "Security tests failed: $($result.FailedCount) critical issue(s) found" - } +Runs the tests of the repository and applies the gate. - - name: Run Credential Scan - shell: pwsh - run: | - # Custom credential scanning - $credentialPatterns = @( - '(?i)(password|pwd|pass)\s*[:=]\s*["\'''][^"\''\s]{8,}' - '(?i)(api[_-]?key|apikey)\s*[:=]\s*["\''']?[a-zA-Z0-9]{20,}' - '(?i)(secret|token)\s*[:=]\s*["\''']?[a-zA-Z0-9]{16,}' - ) - - $issues = @() - Get-ChildItem -Recurse -Include *.ps1, *.psm1, *.psd1 | ForEach-Object { - $content = Get-Content $_.FullName -Raw - foreach ($pattern in $credentialPatterns) { - if ($content -match $pattern) { - $issues += "Potential credential leak in $($_.FullName): $($matches[0])" - } - } - } +.EXAMPLE +./build/Invoke-Tests.ps1 -TestResultFormat JUnitXml -CoverageFormat Cobertura - if ($issues) { - $issues | ForEach-Object { Write-Warning $_ } - throw "Credential leaks detected: $($issues.Count) issues" - } +Writes the reports in the formats that GitLab CI reads. - performance-baseline: - needs: validate - runs-on: windows-latest - steps: - - name: Checkout Repository - uses: actions/checkout@v7 - - - name: Install Dependencies - shell: pwsh - run: | - Install-PSResource Pester -Version "[$env:PESTER_VERSION,)" -Scope CurrentUser -TrustRepository - - - name: Run Performance Tests - shell: pwsh - run: | - Import-Module Pester -MinimumVersion 6.2.0 -Force - - $config = New-PesterConfiguration - $config.Run.Path = './Tests/Performance' - $config.Filter.Tag = 'Performance' - $config.Run.PassThru = $true - # Never parallel, and never with coverage - both distort the measurement - $config.Run.Parallel = $false - $config.CodeCoverage.Enabled = $false - $config.TestResult.Enabled = $true - $config.TestResult.OutputPath = './PerformanceResults.xml' - - $result = Invoke-Pester -Configuration $config - - # Performance tests generate warnings, not failures - if ($result.FailedCount -gt 0) { - Write-Warning "Performance regression detected: $($result.FailedCount) tests exceeded baseline" - } +.INPUTS +None. This script does not accept pipeline input. - - name: Store Performance Metrics - shell: pwsh - run: | - # Store performance metrics for trending - $metrics = @{ - timestamp = Get-Date - commit = "${{ github.sha }}" - branch = "${{ github.ref_name }}" - performance_results = "Performance test results would be parsed here" - } +.OUTPUTS +None. The script throws when the gate is not met. +#> +[CmdletBinding()] +param( + [string]$TestRoot, - $metrics | ConvertTo-Json | Out-File performance-metrics.json + [string]$OutputPath, - - name: Upload Performance Results - uses: actions/upload-artifact@v7 - with: - name: performance-results - path: | - PerformanceResults.xml - performance-metrics.json -``` + [ValidateSet('NUnitXml', 'NUnit3', 'JUnitXml')] + [string]$TestResultFormat = 'NUnitXml', -### GitHub Actions Notes + [ValidateSet('JaCoCo', 'Cobertura')] + [string]$CoverageFormat = 'JaCoCo' +) -- `actions/setup-powershell` is not an official action. GitHub-hosted runners ship a supported - PowerShell 7 preinstalled (`shell: pwsh`), and `windows-latest` also has Windows PowerShell 5.1 - (`shell: powershell`). Select the shell rather than installing a version. If your gate requires a - specific release (for example 7.6 for `Join-Path` multi-segment or `Get-Command -ExcludeModule`), - assert it rather than assuming the runner image: - `if ($PSVersionTable.PSVersion -lt [version]'7.6') { throw "Need PowerShell 7.6+, got $($PSVersionTable.PSVersion)" }` -- `::set-output` was disabled by GitHub in 2023. Write to `$GITHUB_OUTPUT` instead: - `"name=value" | Out-File $env:GITHUB_OUTPUT -Append`. -- `$config.Output.CIFormat = 'GithubActions'` makes Pester emit `::error` and `::warning` - annotations that surface failures inline on the PR diff. `Auto` detects this, but setting it - explicitly is clearer. -- Use `fail-fast: false` so one platform's failure does not cancel the others - you want the full - picture of which platforms broke. +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' -## Azure DevOps Integration +$repositoryRoot = Split-Path -Path $PSScriptRoot -Parent +if (-not $TestRoot) { + $TestRoot = Join-Path -Path $repositoryRoot -ChildPath 'Tests' +} +if (-not $OutputPath) { + $OutputPath = Join-Path -Path $repositoryRoot -ChildPath 'out' +} +$null = New-Item -Path $OutputPath -ItemType Directory -Force + +Import-Module -Name Pester -RequiredVersion 6.2.0 + +$configuration = New-PesterConfiguration +$configuration.Run.Path = $TestRoot +$configuration.Run.RepoRoot = $repositoryRoot +$configuration.Run.PassThru = $true +$configuration.Run.Shuffle = $true +$configuration.CodeCoverage.Enabled = $true +$configuration.CodeCoverage.Path = @( + Join-Path -Path $repositoryRoot -ChildPath 'Public' + Join-Path -Path $repositoryRoot -ChildPath 'Private' +) +$configuration.CodeCoverage.OutputFormat = $CoverageFormat +$configuration.CodeCoverage.OutputPath = Join-Path -Path $OutputPath -ChildPath 'coverage.xml' +$configuration.TestResult.Enabled = $true +$configuration.TestResult.OutputFormat = $TestResultFormat +$configuration.TestResult.OutputPath = Join-Path -Path $OutputPath -ChildPath 'testResults.xml' -### Azure Pipelines YAML +$result = Invoke-Pester -Configuration $configuration -```yaml -# azure-pipelines.yml -trigger: - branches: - include: - - main - - develop - paths: - exclude: - - README.md - - docs/* +if ($null -eq $result -or $result.TotalCount -eq 0) { + throw 'Pester ran no tests.' +} -pr: - branches: - include: - - main - paths: - exclude: - - README.md - - docs/* - -schedules: -- cron: "0 2 * * *" - displayName: Daily Build - branches: - include: - - main - -variables: - POWERSHELL_TELEMETRY_OPTOUT: 1 - -stages: -- stage: Test - displayName: 'Testing Stage' - jobs: - - job: TestWindows - displayName: 'Test on Windows' - pool: - vmImage: 'windows-latest' - strategy: - matrix: - PS5: - powershellVersion: '5.1' - PS7: - powershellVersion: '7.x' - steps: - - task: PowerShell@2 - displayName: 'Install Dependencies' - inputs: - targetType: 'inline' - script: | - Set-PSRepository PSGallery -InstallationPolicy Trusted - Install-Module Pester -MinimumVersion 6.2.0 -Force -Scope CurrentUser - Install-Module PSScriptAnalyzer -Force -Scope CurrentUser - pwsh: $(powershellVersion -eq '7.x') - - - task: PowerShell@2 - displayName: 'Run PSScriptAnalyzer' - inputs: - targetType: 'inline' - script: | - $results = Invoke-ScriptAnalyzer -Path . -Recurse -Settings PSGallery - if ($results) { - $results | Format-Table -AutoSize - Write-Host "##vso[task.logissue type=error]PSScriptAnalyzer found $($results.Count) issues" - exit 1 - } - pwsh: $(powershellVersion -eq '7.x') - - - task: PowerShell@2 - displayName: 'Run Tests' - inputs: - targetType: 'inline' - script: | - Import-Module Pester -MinimumVersion 6.2.0 -Force - - $config = New-PesterConfiguration - $config.Run.Path = './Tests' - $config.Run.PassThru = $true - $config.CodeCoverage.Enabled = $true - $config.CodeCoverage.Path = './Public/*.ps1', './Private/*.ps1' - $config.CodeCoverage.OutputFormat = 'JaCoCo' - $config.CodeCoverage.OutputPath = '$(Agent.TempDirectory)/coverage.xml' - $config.CodeCoverage.CoveragePercentTarget = 80 - $config.TestResult.Enabled = $true - $config.TestResult.OutputFormat = 'NUnitXml' - $config.TestResult.OutputPath = '$(Agent.TempDirectory)/TestResults.xml' - $config.Output.CIFormat = 'AzureDevops' - - $result = Invoke-Pester -Configuration $config - - Write-Host "##vso[task.setvariable variable=TotalTests]$($result.TotalCount)" - Write-Host "##vso[task.setvariable variable=PassedTests]$($result.PassedCount)" - Write-Host "##vso[task.setvariable variable=FailedTests]$($result.FailedCount)" - - # Pester 5/6 property is CoveragePercent. CoveredPercent is the - # Pester 4 name and returns $null silently. - if ($result.CodeCoverage) { - Write-Host "##vso[task.setvariable variable=CodeCoverage]$($result.CodeCoverage.CoveragePercent)" - } +if ($result.Result -ne 'Passed') { + $counts = $result.FailedCount, $result.FailedBlocksCount, $result.FailedContainersCount + $summary = 'Failed tests: {0}. Failed blocks: {1}. Failed files: {2}.' -f $counts + $seed = $result.Configuration.Run.ShuffleSeed.Value + throw "Pester result is '$($result.Result)'. $summary Replay with Run.ShuffleSeed = $seed." +} - # A file that fails discovery contributes 0 to FailedCount - check both - if ($result.FailedContainersCount -gt 0) { - $result.FailedContainers | ForEach-Object { - Write-Host "##vso[task.logissue type=error]Discovery failed: $($_.Item)" - } - exit 1 - } +$coverage = [math]::Round($result.CodeCoverage.CoveragePercent, 2) +if ($coverage -lt 80) { + throw "Code coverage is $coverage percent. The minimum is 80." +} +``` - if ($result.FailedCount -gt 0) { - Write-Host "##vso[task.logissue type=error]$($result.FailedCount) tests failed" - exit 1 - } - pwsh: $(powershellVersion -eq '7.x') - - - task: PublishTestResults@2 - displayName: 'Publish Test Results' - condition: always() - inputs: - testResultsFormat: 'NUnit' - testResultsFiles: '$(Agent.TempDirectory)/TestResults.xml' - testRunTitle: 'PowerShell Tests - $(Agent.OS) - PS$(powershellVersion)' - - # PublishCodeCoverageResults@1 is deprecated; @2 takes summaryFileLocation - # directly and infers the format. - - task: PublishCodeCoverageResults@2 - displayName: 'Publish Code Coverage' - condition: always() - inputs: - summaryFileLocation: '$(Agent.TempDirectory)/coverage.xml' - - - job: TestLinux - displayName: 'Test on Linux' - pool: - vmImage: 'ubuntu-latest' - steps: - - task: PowerShell@2 - displayName: 'Install Dependencies' - inputs: - targetType: 'inline' - script: | - Install-PSResource Pester -Version '[6.2.0,)' -Scope CurrentUser -TrustRepository - pwsh: true - - - task: PowerShell@2 - displayName: 'Run Cross-Platform Tests' - inputs: - targetType: 'inline' - script: | - $config = New-PesterConfiguration - $config.Run.Path = './Tests/Unit' - $config.Filter.Tag = 'CrossPlatform' - $config.Run.PassThru = $true - $config.TestResult.Enabled = $true - $config.TestResult.OutputPath = '$(Agent.TempDirectory)/LinuxTestResults.xml' - - $result = Invoke-Pester -Configuration $config - - if ($result.FailedCount -gt 0) { - Write-Host "##vso[task.logissue type=error]Cross-platform tests failed: $($result.FailedCount) failures" - exit 1 - } - pwsh: true - -- stage: Security - displayName: 'Security Scanning' - dependsOn: Test - condition: succeeded() - jobs: - - job: SecurityScan - displayName: 'Security Analysis' - pool: - vmImage: 'windows-latest' - steps: - - task: PowerShell@2 - displayName: 'Security Tests' - inputs: - targetType: 'inline' - script: | - Install-PSResource Pester -Version '[6.2.0,)' -Scope CurrentUser -TrustRepository - - $config = New-PesterConfiguration - $config.Run.Path = './Tests/Security' - $config.Filter.Tag = 'Security' - $config.Run.PassThru = $true - - $result = Invoke-Pester -Configuration $config - - if ($result.FailedCount -gt 0) { - Write-Host "##vso[task.logissue type=error]Security tests failed: $($result.FailedCount) critical issues" - exit 1 - } +Notes on the script: -- stage: Deploy - displayName: 'Deployment' - dependsOn: - - Test - - Security - condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')) - jobs: - - deployment: DeployProduction - displayName: 'Deploy to PowerShell Gallery' - environment: 'Production' - strategy: - runOnce: - deploy: - steps: - - task: PowerShell@2 - displayName: 'Publish to PowerShell Gallery' - inputs: - targetType: 'inline' - script: | - # Publish logic here - Write-Host "Publishing to PowerShell Gallery..." -``` +- It is the gate from the testing rules, with reports and parameters added. The three checks are + the same, in the same order. +- Every path comes from `$PSScriptRoot`, so the script works from any current location. +- `Run.RepoRoot` is set, so shared setup files are found even in a checkout that has no `.git` + folder; see [Pester Configuration Guide](./pester-configuration.md#runreporoot). +- `Run.Throw` and `Run.Exit` are left off. Either would end the script inside `Invoke-Pester` when a + test fails, before the script can report the counts, and neither reports a run without tests. +- When no test file exists under the test root, `Invoke-Pester` writes an error and returns nothing. + The error does not always stop the script, because the preference set in a script does not reach + the functions of a module. The test for `$null` turns the missing result into a failure. +- In a project that declares Windows PowerShell 5.1 support, change the first line to + `#requires -Version 5.1`. The script uses nothing newer. -## Jenkins Integration +To enforce tags in CI (TST-04), add the check for untagged tests from +[Pester Test Structure Guide](./test-structure-guide.md#finding-untagged-tests) before the run. -### Jenkinsfile +## GitHub Actions -```groovy -pipeline { - agent none +```yaml +name: Quality gates - environment { - POWERSHELL_TELEMETRY_OPTOUT = '1' - } +on: + pull_request: + branches: [main] - stages { - stage('Test') { - parallel { - stage('Windows PowerShell 5.1') { - agent { label 'windows' } - steps { - powershell ''' - Set-PSRepository PSGallery -InstallationPolicy Trusted - Install-Module Pester -MinimumVersion 6.2.0 -Force -Scope CurrentUser - - $config = New-PesterConfiguration - $config.Run.Path = './Tests' - $config.Run.PassThru = $true - $config.TestResult.Enabled = $true - $config.TestResult.OutputPath = './TestResults.xml' - - $result = Invoke-Pester -Configuration $config - - if ($result.FailedCount -gt 0) { - exit 1 - } - ''' - } - post { - always { - publishTestResults testResultsPattern: 'TestResults.xml' - } - } - } - - stage('PowerShell 7.x') { - agent { label 'pwsh' } - steps { - pwsh ''' - Install-PSResource Pester -Version '[6.2.0,)' -Scope CurrentUser -TrustRepository - - ./Invoke-Tests.ps1 -TestType All -Environment CI -CodeCoverage - ''' - } - post { - always { - publishTestResults testResultsPattern: 'Tests/Results/*.xml' - publishCoverage adapters: [jacocoAdapter('Tests/Results/Coverage*.xml')] - } - } - } - } - } +permissions: + contents: read - stage('Security Scan') { - agent { label 'windows' } - steps { - powershell ''' - ./Invoke-Tests.ps1 -TestType Security -Environment CI - ''' - } - } +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - name: Install build tools + shell: pwsh + run: | + $ErrorActionPreference = 'Stop' + Install-PSResource -Name PSScriptAnalyzer -Version 1.25.0 -TrustRepository + Install-PSResource -Name Pester -Version 6.2.0 -TrustRepository + + - name: Run PSScriptAnalyzer + shell: pwsh + run: | + $ErrorActionPreference = 'Stop' + $findings = @(Invoke-ScriptAnalyzer -Path . -Recurse -Severity Error, Warning) + $findings | Format-Table -Property Severity, RuleName, ScriptName, Line -AutoSize + if ($findings.Count -gt 0) { + throw "PSScriptAnalyzer reported $($findings.Count) finding(s)." + } - stage('Deploy') { - when { - branch 'main' - allOf { - environment name: 'BUILD_STATUS', value: 'SUCCESS' - } - } - agent { label 'windows' } - steps { - powershell ''' - # Deployment logic - Write-Host "Deploying to PowerShell Gallery..." - ''' - } - } - } + - name: Run Pester + shell: pwsh + run: ./build/Invoke-Tests.ps1 - post { - always { - emailext ( - to: '${DEFAULT_RECIPIENTS}', - subject: '${PROJECT_NAME} - Build ${BUILD_NUMBER} - ${BUILD_STATUS}', - body: '''${PROJECT_NAME} - Build ${BUILD_NUMBER} - ${BUILD_STATUS} - - Test Results: - Total Tests: ${TEST_COUNTS,var="total"} - Failed Tests: ${TEST_COUNTS,var="fail"} - Passed Tests: ${TEST_COUNTS,var="pass"} - Skipped Tests: ${TEST_COUNTS,var="skip"} - - Build URL: ${BUILD_URL} - ''' - ) - } - } -} + - name: Upload reports + if: always() + uses: actions/upload-artifact@v7 + with: + name: test-reports + path: out/ ``` -## GitLab CI Integration +Use `runs-on: windows-latest` when the code is Windows-only. -### .gitlab-ci.yml +Each action is referenced by a release tag (CIC-09). A full commit ID is the stricter choice; look +the ID up and write the tag after it in a comment. -```yaml -stages: - - test - - security - - deploy - -variables: - POWERSHELL_TELEMETRY_OPTOUT: "1" - -.powershell_template: &powershell_template - before_script: - - Set-PSRepository PSGallery -InstallationPolicy Trusted - - Install-Module Pester -MinimumVersion 6.2.0 -Force -Scope CurrentUser - -# GitLab needs JUnit for test results and Cobertura for coverage. Pester 6 -# supports both natively - set TestResult.OutputFormat = 'JUnitXml' and -# CodeCoverage.OutputFormat = 'Cobertura' in PesterConfiguration.CI.psd1. -# -# Container images: the `mcr.microsoft.com/powershell` images are DEPRECATED. PowerShell now -# ships inside the .NET SDK images - `mcr.microsoft.com/dotnet/sdk:10.0` carries PowerShell 7.6 -# (.NET 10 LTS). Microsoft publishes these for development and testing only; build and maintain -# your own image for production pipelines. -test:windows: - stage: test - image: mcr.microsoft.com/dotnet/sdk:10.0-windowsservercore-ltsc2022 - <<: *powershell_template - script: - - ./Invoke-Tests.ps1 -TestType Unit -Environment CI -CodeCoverage - artifacts: - reports: - junit: Tests/Results/TestResults*.xml - coverage_report: - coverage_format: cobertura - path: Tests/Results/Coverage*.xml - paths: - - Tests/Results/ - expire_in: 1 week - coverage: '/Code Coverage: (\d+\.?\d*)%/' +The gate script requires PowerShell 7.6 through its `#requires` line, so the job fails with a clear +message on a runner image that has an older version. -test:linux: - stage: test - image: mcr.microsoft.com/dotnet/sdk:10.0 - <<: *powershell_template - script: - # Parallel is safe here - no coverage on this job - - pwsh -Command "./Invoke-Tests.ps1 -TestType Unit -Tag CrossPlatform -Environment CI -Parallel" - artifacts: - reports: - junit: Tests/Results/TestResults*.xml +Pester detects GitHub Actions and writes each failed test as an `::error::` command, which GitHub +shows as an annotation on the run. No option has to be set for this. -security: - stage: security - image: mcr.microsoft.com/dotnet/sdk:10.0-windowsservercore-ltsc2022 - <<: *powershell_template - script: - - ./Invoke-Tests.ps1 -TestType Security -Environment CI - allow_failure: false +### Windows PowerShell 5.1 Job -deploy: - stage: deploy - image: mcr.microsoft.com/dotnet/sdk:10.0-windowsservercore-ltsc2022 - script: - - Write-Host "Deploying to PowerShell Gallery..." - only: - - main - when: manual -``` +Add this job only when the project declares Windows PowerShell 5.1 support (CIC-03). It goes under +`jobs:` beside the `test` job. -## CI/CD Best Practices +```yaml + test-windows-powershell: + runs-on: windows-latest + steps: + - uses: actions/checkout@v7 -### Environment Variables + - name: Install Pester + shell: powershell + run: | + $ErrorActionPreference = 'Stop' + Install-Module -Name Pester -RequiredVersion 6.2.0 -Scope CurrentUser -Force -SkipPublisherCheck -```powershell -# Common environment variables for CI/CD -$env:POWERSHELL_TELEMETRY_OPTOUT = '1' -$env:PESTER_CI_MODE = 'true' -$env:CODE_COVERAGE_ENABLED = 'true' -$env:TEST_RESULTS_PATH = './Tests/Results' + - name: Run Pester + shell: powershell + run: ./build/Invoke-Tests.ps1 ``` -### Parallel Test Execution +`Install-Module` is used here because PSResourceGet is not part of Windows PowerShell 5.1 (VER-08). +Windows PowerShell ships with Pester 3.4.0, which has a different publisher, so the installation +needs `-SkipPublisherCheck`. -Pester 6 has a built-in parallel runner. `Run.Container` is for _parametrizing_ files, not for -parallelism - the old snippet using multiple containers ran sequentially. +## Azure Pipelines -```powershell -# Actual parallel execution: one file per runspace, on 5.1 and 7 alike from 6.2 -$config = New-PesterConfiguration -$config.Run.Path = './Tests/Unit' -$config.Run.Parallel = $true -$config.Run.ParallelThrottleLimit = 4 # 0 (default) uses all processors -``` +```yaml +trigger: + branches: + include: + - main -Parametrized containers still work, and they parallelize too: +pr: + branches: + include: + - main + +pool: + vmImage: ubuntu-latest + +steps: + - task: PowerShell@2 + displayName: Install build tools + inputs: + targetType: inline + pwsh: true + script: | + $ErrorActionPreference = 'Stop' + Install-PSResource -Name PSScriptAnalyzer -Version 1.25.0 -TrustRepository + Install-PSResource -Name Pester -Version 6.2.0 -TrustRepository + + - task: PowerShell@2 + displayName: Run PSScriptAnalyzer + inputs: + targetType: inline + pwsh: true + script: | + $ErrorActionPreference = 'Stop' + $findings = @(Invoke-ScriptAnalyzer -Path . -Recurse -Severity Error, Warning) + $findings | Format-Table -Property Severity, RuleName, ScriptName, Line -AutoSize + if ($findings.Count -gt 0) { + throw "PSScriptAnalyzer reported $($findings.Count) finding(s)." + } -```powershell -$config.Run.Container = @( - New-PesterContainer -Path './Tests/Unit' -Data @{ Environment = 'CI' } -) -$config.Run.Parallel = $true # each file's -Data reaches its worker intact + - task: PowerShell@2 + displayName: Run Pester + inputs: + targetType: filePath + filePath: build/Invoke-Tests.ps1 + pwsh: true + + - task: PublishTestResults@2 + displayName: Publish test results + condition: always() + inputs: + testResultsFormat: NUnit + testResultsFiles: out/testResults.xml + + - task: PublishCodeCoverageResults@2 + displayName: Publish code coverage + condition: always() + inputs: + summaryFileLocation: out/coverage.xml ``` -**Coverage under parallel changed in 6.1.** Pester 6.0 collected no coverage in a parallel run; 6.1 -merges it across workers, but forces slower breakpoint-based collection to do it. Splitting into two -jobs is still the better default - a parallel job without coverage for feedback, and a sequential -job with the profiler for the gate - but measure before assuming either is faster. +`pwsh: true` runs the step in PowerShell 7. On a Windows agent, `pwsh: false` runs it in Windows +PowerShell 5.1; use that only in a job for a project that declares 5.1 support. -Each worker starts from a **clean runspace**, so every test file must be self-contained. Provide -shared bootstrap through `Pester.BeforeContainer.ps1` files, which Pester dot-sources before every -container - from 6.2, every one from `Run.RepoRoot` down to the test file's folder, outermost first. -Put run-time setup in a `BeforeAll`; top-level code in the file runs at discovery only: +Pester detects Azure Pipelines and writes failures as logging commands. No option has to be set for +this. -```powershell -# Pester.BeforeContainer.ps1, at the repository root -BeforeAll { - . "$PSScriptRoot/Tests/TestHelpers/Bootstrap.ps1" -} -``` +## Other CI Systems -The `Run.BeforeContainer` option was removed in 6.1 - a CI job that still sets it now throws. In CI -also set `Run.RepoRoot` explicitly. From 6.2 an unset root is resolved from the session's current -location (6.1 used the .NET process working directory), but a checkout without a `.git` directory, -or a run launched from outside the repository, still lands on the wrong root and finds no setup file: +The pattern is the same everywhere: install the pinned tools, call the gate script, and publish the +reports that the script wrote. A step fails when the script throws. -```powershell -$config.Run.RepoRoot = $env:GITHUB_WORKSPACE # or the equivalent for your CI system +GitLab CI reads JUnit test results and Cobertura coverage: + +```yaml +test: + stage: test + # An image that contains PowerShell 7.6. + image: registry.example.com/build/powershell:7.6 + script: + - pwsh -NoProfile -Command "Install-PSResource -Name Pester -Version 6.2.0 -TrustRepository" + - pwsh -NoProfile -File ./build/Invoke-Tests.ps1 -TestResultFormat JUnitXml -CoverageFormat Cobertura + artifacts: + when: always + reports: + junit: out/testResults.xml + coverage_report: + coverage_format: cobertura + path: out/coverage.xml ``` -A parallel worker that died used to drop its file from the results without a trace. From 6.2 the run -throws naming the missing files, and a worker that throws no longer aborts the remaining files when -the job runs with `$ErrorActionPreference = 'Stop'`. +Jenkins reads JUnit test results with the `junit` step: -Verify isolation before enabling parallel in CI - if a file only passes as part of a full run, it is -not self-contained: +```groovy +pipeline { + agent { label 'pwsh' } -```powershell -Get-ChildItem ./Tests/Unit -Recurse -Filter *.Tests.ps1 | ForEach-Object { - $r = Invoke-Pester -Path $_.FullName -PassThru -Output None - if ($r.FailedCount -gt 0 -or $r.FailedContainersCount -gt 0) { - Write-Warning "Not self-contained: $($_.FullName)" + stages { + stage('Test') { + steps { + pwsh 'Install-PSResource -Name Pester -Version 6.2.0 -TrustRepository' + pwsh './build/Invoke-Tests.ps1 -TestResultFormat JUnitXml' + } + } } -} -``` - -### Artifact Management -```powershell -# Standardized artifact collection -$artifacts = @{ - TestResults = './Tests/Results/TestResults*.xml' - CodeCoverage = './Tests/Results/Coverage*.xml' - PerformanceMetrics = './Tests/Results/Performance*.json' - SecurityReports = './Tests/Results/Security*.xml' + post { + always { + junit 'out/testResults.xml' + } + } } ``` -### Report Format by Platform +For a container image, Microsoft's documentation states that the .NET SDK images contain PowerShell +and that they are meant for development and testing. Check which PowerShell version an image +contains before you rely on it; the `#requires` line of the gate script fails the job when the +version is too old. -| Platform | Test results | Coverage | +## Report Formats + +| CI system | Test result format | Coverage format | | --- | --- | --- | -| GitHub Actions (`dorny/test-reporter`) | `NUnitXml` | `JaCoCo` | -| Azure DevOps (`PublishTestResults@2`) | `NUnitXml` | `JaCoCo` | +| GitHub Actions | Any. The reports are uploaded as an artifact. | Any | +| Azure Pipelines | `NUnitXml`, published with `PublishTestResults@2` | `JaCoCo` or `Cobertura`, published with `PublishCodeCoverageResults@2` | | GitLab CI | `JUnitXml` | `Cobertura` | -| Jenkins (JUnit plugin) | `JUnitXml` | `JaCoCo` | -| Codecov | any | `JaCoCo` or `Cobertura` | +| Jenkins | `JUnitXml`, published with the `junit` step | `JaCoCo` or `Cobertura`, depending on the plugin | -`Cobertura` and `NUnit3` are new in Pester 6. `CoverageGutters` was **removed** - all coverage output -is now repo-root-relative, so plain `JaCoCo` works with the Coverage Gutters extension. +Pester writes one test result format for each run. To write a second one, convert the result object +with `Export-NUnitReport` or `Export-JUnitReport`; see +[Pester Configuration Guide](./pester-configuration.md#test-results). -Coverage paths are relative to `CodeCoverage.ReportRoot`, which defaults to `Run.RepoRoot` (found -from the `.git` directory). If your CI checks out to a subdirectory and paths do not line up in the -report, set `ReportRoot` explicitly. +Paths inside a coverage report are relative to `CodeCoverage.ReportRoot`, which defaults to +`Run.RepoRoot`. Set `ReportRoot` when the CI system expects paths relative to another folder. -`TestResult` writes one format per run. For two, convert the result object afterwards: +## Failing Correctly -```powershell -$config.Run.PassThru = $true -$result = Invoke-Pester -Configuration $config -Export-NUnitReport -Result $result -Path './Tests/Results/NUnit.xml' -Export-JUnitReport -Result $result -Path './Tests/Results/JUnit.xml' -``` +A pipeline script fails by throwing, with `$ErrorActionPreference = 'Stop'` set at the top (CIC-05). -### CI Gate Checklist +```powershell +# Compliant +if ($null -eq $result -or $result.TotalCount -eq 0) { + throw 'Pester ran no tests.' +} -A Pester 6 gate must check more than `FailedCount`: +# Non-compliant: Write-Error ends the script under 'Stop', so the exit statement is never reached, +# and without 'Stop' the pattern depends on every caller checking the exit code. +if ($result.FailedCount -gt 0) { + Write-Error "$($result.FailedCount) test(s) failed." + exit 1 +} +``` -```powershell -$result = Invoke-Pester -Configuration $config +Do not turn a failure into a warning to keep a build green. A pull request pipeline fails when +Pester reports a problem (CIC-01). Tests that need resources a pull request build does not have, +such as integration tests against a live service, belong in a separate workflow that also fails when +they fail. -# 1. Test failures -if ($result.FailedCount -gt 0) { throw "$($result.FailedCount) test(s) failed" } +`Invoke-Pester` sets `$LASTEXITCODE` to the number of failures. Do not reset it before the script +has thrown for the failure it carried (CIC-05). -# 2. Discovery/container failures - these contribute 0 to FailedCount. -# Without this check, whole files can silently never run. -if ($result.FailedContainersCount -gt 0) { throw "$($result.FailedContainersCount) file(s) failed discovery" } +## Parallel Runs and Coverage in CI -# 3. Zero tests discovered - a suite that tests nothing must not report success -if ($result.TotalCount -eq 0) { throw 'No tests were discovered' } +`Run.Parallel` is experimental, so the gate script does not use it. When a project chooses to use +it, keep the coverage gate in a sequential job: a parallel run measures coverage with the slower +breakpoint method. Put the parallel run in a second job without coverage. Details are in +[Test Execution Guide](./test-execution.md#parallel-test-execution). -# 4. Coverage target - CoveragePercentTarget does not fail the run on its own -if ($result.CodeCoverage) { - $actual = [math]::Round($result.CodeCoverage.CoveragePercent, 2) - $target = $result.CodeCoverage.CoveragePercentTarget - if ($actual -lt $target) { throw "Coverage $actual% below $target% target" } -} -``` +## Settings Files in CI -Items 2 and 3 are the ones a Pester 5 pipeline will not have, and they are exactly how a v6 upgrade -turns green while running fewer tests than before. +When the gate script loads Pester settings from a `.psd1` file, a misspelled key only produces a +warning. Fail the build on it with `GetUnknownKeys()`; see +[Pester Configuration Guide](./pester-configuration.md#checking-what-was-loaded). -From 6.2 the configuration is part of the gate too. A wrong-typed value - `'true'` as a string in a -`psd1`, say - throws when the configuration is built, and a key that matches no option is reported -once by `Invoke-Pester` as `WARNING: Ignoring configuration keys ...`. A warning does not fail a job, -so check the list before the run: +## Checklist -```powershell -$unknown = @($config.GetUnknownKeys()) -if ($unknown.Count -gt 0) { throw "Configuration keys that match no option: $($unknown -join ', ')" } -``` +- Tool versions are pinned: Pester 6.2.0 and PSScriptAnalyzer 1.25.0. +- The pipeline calls one gate script, and the script tests for no tests, for `Result`, and for + coverage. +- Every action is referenced by a release tag or a full commit ID (CIC-09). +- The test folder is named in one place. +- Every script sets `$ErrorActionPreference = 'Stop'` and fails by throwing. +- The workflow has an explicit `permissions` block with the least access it needs (CIC-07). +- No secret is written in the workflow or printed to the log (CIC-06). +- No job targets a PowerShell version that is past its end-of-support date. diff --git a/.github/instructions/pester-supporting-docs/custom-assertions.md b/.github/instructions/pester-supporting-docs/custom-assertions.md index da08b17..eafb377 100644 --- a/.github/instructions/pester-supporting-docs/custom-assertions.md +++ b/.github/instructions/pester-supporting-docs/custom-assertions.md @@ -1,206 +1,205 @@ # Custom Assertion Guide -Requires **Pester 6.2+**. `New-ShouldAssertion` does not exist in 6.0.x. +How to add an assertion to the `Should-*` family with `New-ShouldAssertion`. That command was added +in Pester 6.1 and does not exist in 6.0. Every statement about behaviour was checked by running it +on Pester 6.2.0. The built-in assertions are described in the [assertion guide](./assertion-guide.md). -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. - -In Pester 6.0 the `Should-*` family was a closed set - extending it meant dropping back to the v5 -`Add-ShouldOperator` mechanism, a different shape that caps out at 32 operators. Pester 6.1 opens the -family up: write an ordinary function, call `New-ShouldAssertion` inside it, and the result behaves -exactly like a built-in assertion. +The older mechanism, `Add-ShouldOperator`, extends only the classic `Should -Be` syntax and stops at +32 operators. Use `New-ShouldAssertion` for new work. ## When To Write One -Write a custom assertion when the same non-trivial check appears across several test files and the -built-in failure message cannot explain it. The bar is the failure message: if a custom assertion -does not produce a better one than `Should-BeTrue` plus `-Because`, it is not worth the indirection. +Write a custom assertion when the same check appears in several test files and a built-in failure +message cannot explain what went wrong. If it does not produce a better message than `Should-BeTrue` +with `-Because`, it is not worth having. | Situation | Do this | | --- | --- | -| One test needs a bespoke check | Plain PowerShell plus `Should-Be` | -| A property-by-property object shape check | `Should-BeEquivalent -ExcludePathsNotOnExpected` | -| A condition across every item | `Should-All { ... }` | -| A domain rule repeated across files, where naming the violating item is the point | Custom assertion | +| One test needs a special check | Plain PowerShell and `Should-Be` | +| The shape of an object | `Should-BeEquivalent -ExcludePathsNotOnExpected` | +| A condition on every item | `Should-All { ... }` | +| A project rule checked in many files, where the message must name the item that breaks it | Custom assertion | -A custom assertion inherits all of the shared machinery for free: pipeline input collection, Pester's -value formatting, the diagnostic hint when a collection is piped into a value assertion, soft -assertions via `Should.ErrorAction = 'Continue'`, and use inside a mock `-ParameterFilter`. +A custom assertion gets what the built-in ones have: input from the pipeline or from `-Actual`, +Pester's value formatting, the hint about piped collections, soft assertions, and use inside a mock +`-ParameterFilter`. ## The Shape +The functions in this guide omit comment-based help to stay short. A real one carries it. + ```powershell function Assert-BeValidSemVer { [CmdletBinding()] - param ( - [Parameter(Position = 0, ValueFromPipeline)] $Actual, - [string] $Because + param( + [Parameter(Position = 0, ValueFromPipeline)] + [object]$Actual, + + [string]$Because ) $assert = New-ShouldAssertion -Caller $PSCmdlet -Actual $Actual -Buffer $Input $Actual = $assert.Actual() - $parsed = $null - if (-not [version]::TryParse($Actual, [ref] $parsed) -or $parsed.Build -lt 0) { + $version = $null + $isVersion = [version]::TryParse($Actual, [ref]$version) + if (-not $isVersion -or $version.Build -lt 0 -or $version.Revision -ge 0) { $assert.Fail( 'Expected a Major.Minor.Patch version,<because> but got <actual>.', @{ Because = $Because }) } } + Set-Alias -Name Should-BeValidSemVer -Value Assert-BeValidSemVer ``` ```powershell -'1.2.3' | Should-BeValidSemVer # passes -$manifest.ModuleVersion | Should-BeValidSemVer -Because 'the module is published to a gallery' -# Expected a Major.Minor.Patch version, because the module is published to a gallery, but got '1.0'. +'1.2.3' | Should-BeValidSemVer +$manifest.ModuleVersion | Should-BeValidSemVer -Because 'the module is published to a gallery' +``` + +```text +Expected a Major.Minor.Patch version, because the module is published to a gallery, but got '1.0'. ``` Three rules cover most of it: -1. **Call `New-ShouldAssertion` once, at the top**, passing the assertion's own `$PSCmdlet`, - its `-Actual` value, and `$Input`. Pass all three even when one is usually empty - `-Actual` is - `$null` for a piped call and `$Input` is empty for an `-Actual` call, and the helper resolves - which one was used. -2. **Read the value back through `$assert.Actual()`**, never from `$Actual` directly. That is what - applies the pipeline-collection rules and preserves shapes a bare read would flatten. -3. **A pass is implicit.** Return without calling `Fail()`. There is nothing to signal success with. +1. Call `New-ShouldAssertion` once, at the top, with the function's own `$PSCmdlet`, its `-Actual` + value, and `$Input`. Pass all three every time: `-Actual` is `$null` for a piped call, `$Input` is + empty for an `-Actual` call, and the helper works out which was used. +2. Read the value from `$assert.Actual()`, not from `$Actual`. That applies the same input handling + as the built-in assertions. +3. A pass is implicit. Return without calling `Fail()`. + +This is the one place where a function reads the automatic variable `$Input`. It is read, never +assigned. + +### No Process Block -Do not add a `process` block. The assertion body must run as an `end` block - the default when a -function declares no named blocks - because `$Input` only holds the whole pipeline there. Pester's -own examples write `end { ... }` explicitly; both forms are equivalent. +Do not add a `process` block, even though the parameter takes pipeline input. The body must run +once, in the `end` block, which is where a function body runs when it names no blocks. `$Input` +holds the whole pipeline only there. -A `process` block does not error, which is what makes it worth calling out. It quietly changes the -assertion's semantics: the body runs **once per piped item** instead of once for the pipeline, so -the assertion inspects items individually rather than as one value the way every built-in -`Should-*` does. The diagnostic hint also becomes nonsense, because it describes a collection that -the assertion never saw: +A `process` block causes no error. It changes what the assertion does: the body runs once for each +piped item, and the hint describes a collection that the assertion never saw. ```powershell 'ok', 'bad' | Should-BeOk ``` ```text -# end block (correct) - invoked once, "Expected ok but got @('ok', 'bad')." -# process block (wrong) - invoked twice, "Expected ok but got 'bad'." -# and the hint claims the collection was "re-collected into a single [string]" +Body in the end block: runs once. Expected ok but got @('ok', 'bad'). +Body in a process block: runs twice. Expected ok but got 'bad'. ``` -If you want per-item semantics, that is what `Should-All` is for. +For a check on each item, use `Should-All`. ### Parameter Positions -6.1 aligned `-Actual` across every built-in assertion, and custom assertions should match so they -read the same at a call site. `-Actual` always takes `ValueFromPipeline`; its position depends on -whether the assertion has a comparand: +Match the built-in assertions, so that a custom assertion reads the same way at a call site. +`-Actual` always accepts pipeline input. Its position depends on whether there is an expected value: -| Assertion shape | `-Expected` | `-Actual` | Built-in example | +| Shape | `-Expected` | `-Actual` | Built-in examples | | --- | --- | --- | --- | -| Single-subject - nothing to compare against | none | `Position = 0` | `Should-BeNull`, `Should-BeTrue`, `Should-BeHashtable` | -| Two-subject - a positional comparand | `Position = 0`, mandatory | `Position = 1` | `Should-Be`, `Should-BeString`, `Should-HaveType` | +| Nothing to compare with | none | `Position = 0` | `Should-BeNull`, `Should-BeTrue`, `Should-BeHashtable` | +| An expected value | `Position = 0`, mandatory | `Position = 1` | `Should-Be`, `Should-BeString`, `Should-HaveType` | -Verify against the installed version rather than trusting a doc, including this one: - -```powershell -Get-Command -Syntax Should-BeHashtable -``` +`Get-Command -Syntax Should-BeHashtable` shows the positions of any assertion. ## Collecting The Input: -As -`-As` selects both how the piped input is collected and how the diagnostic hint is worded when the -assertion fails. +`-As` selects how piped input is collected and which hint is added to a failure. -| `-As` | Input handling | Use for | -| --- | --- | --- | -| `Scalar` (default) | Unrolls a single piped value | A value assertion, like `Should-Be` | -| `ExactType` | Unrolls, preserving the concrete type | A value assertion that inspects the type | -| `Collection` | Keeps the input as a collection | A whole-collection assertion, like `Should-BeCollection` | -| `CollectionItems` | Keeps the input as a collection, hints about items | An assertion that reports on individual items | -| `None` | No unrolling, no input hint | A structural comparison, like `Should-BeEquivalent` | +| `-As` | A single piped item | Hint added when | Use for | +| --- | --- | --- | --- | +| `Scalar` (default) | Unrolled | A collection was piped and inspected as one value | A value assertion, like `Should-Be` | +| `ExactType` | Unrolled | A typed collection was piped and lost its type | A type assertion, like `Should-HaveType` | +| `Collection` | Kept as a one-item array | A single value, `$null`, or a dictionary was given | A whole-collection assertion, like `Should-BeCollection` | +| `CollectionItems` | Kept as a one-item array | A dictionary was given | An item-by-item assertion, like `Should-All` | +| `None` | Unrolled | Never | A structural comparison, like `Should-BeEquivalent` | + +Several piped items reach the assertion as an `[Object[]]` in every mode. ```powershell function Assert-HaveTag { [CmdletBinding()] - param ( - [Parameter(Position = 1, ValueFromPipeline)] $Actual, - [Parameter(Position = 0, Mandatory)] [string] $Expected, - [string] $Because + param( + [Parameter(Position = 1, ValueFromPipeline)] + [object]$Actual, + + [Parameter(Position = 0, Mandatory)] + [string]$Expected, + + [string]$Because ) $assert = New-ShouldAssertion -Caller $PSCmdlet -Actual $Actual -Buffer $Input -As Collection - $Actual = $assert.Actual() + $blocks = $assert.Actual() - $missing = @($Actual | Where-Object { $_.Tag -notcontains $Expected }) - if (0 -lt $missing.Count) { + $untagged = @($blocks | Where-Object { $_.Tag -notcontains $Expected }) + if ($untagged.Count -gt 0) { $assert.Fail( 'Expected every block to be tagged <expected>,<because> but <Untagged> were not.', - @{ Expected = $Expected; Because = $Because; Untagged = $missing.Name }) + @{ Expected = $Expected; Because = $Because; Untagged = $untagged.Name }) } } + Set-Alias -Name Should-HaveTag -Value Assert-HaveTag ``` ```powershell -$result.Blocks | Should-HaveTag 'Unit' -Because 'the tagging audit depends on it' -# Expected every block to be tagged 'Unit', because the tagging audit depends on it, -# but @('Connectivity', 'Retry') were not. +$blocks | Should-HaveTag 'Unit' -Because 'the tagging audit depends on it' ``` -Naming the violating items is the whole reason to write this instead of -`$result.Blocks | Should-All { $_.Tag -contains 'Unit' }`. +```text +Expected every block to be tagged 'Unit', because the tagging audit depends on it, but +@('Connectivity', 'Retry') were not. +``` + +Naming the items that break the rule is the reason to write this in place of +`$blocks | Should-All { $_.Tag -contains 'Unit' }`. ## The Failure Message -`Fail(message)` or `Fail(message, data)`. The message is a template; `data` is a hashtable. +Call `Fail(message)` or `Fail(message, data)`. The message is a template and `data` is a hashtable. -Four keys in `data` are **reserved** and are not turned into tokens: +Four keys of `data` have a fixed meaning: | Key | Effect | | --- | --- | | `Expected` | Fills `<expected>` and `<expectedType>` | -| `Actual` | Fills `<actual>` and `<actualType>`; defaults to the collected input when omitted | -| `Because` | Fills `<because>`, formatted as `, because <text>` (empty when `-Because` was not passed) | -| `Hint` | Replaces the default input hint, printed as `Hint: <text>` after a blank line | - -Every other key becomes a `<key>` token. - -| Token | Renders | -| --- | --- | -| `<expected>` | `data.Expected`, through Pester's formatter | -| `<actual>` | `data.Actual`, or the collected input | -| `<expectedType>` / `<actualType>` | The short type name, e.g. `[string]` | -| `<because>` | `, because <text>`, or nothing | -| `<YourKey>` | `data.YourKey`, through Pester's formatter | - -**`<because>` is only filled when you pass `Because` in the data.** Declaring a `-Because` parameter -is not enough - the value has to be threaded through: - -```powershell -$assert.Fail('Expected <expected>,<because> but got <actual>.', @{ Expected = $Expected; Because = $Because }) -``` +| `Actual` | Fills `<actual>` and `<actualType>`. When omitted, the collected input is used. | +| `Because` | Fills `<because>` with a space, `because <text>`, and a comma. With no text it fills it with nothing. | +| `Hint` | Replaces the default hint. It is printed after a blank line as `Hint: <text>`. | -**Custom tokens are case-sensitive and must match the hashtable key exactly.** A key of `Untagged` -fills `<Untagged>`; `<untagged>` is left in the message as literal text. Only the built-in tokens are -lowercase. The failure is silent - the raw token ships in the message - so read the message once when -you write the assertion. +Every other key fills the token of the same name, such as `<Untagged>`. Values are formatted the way +Pester formats them: a string in quotes, a collection as `@(...)`, a type name as `[int]`. -Write the comma before `<because>` rather than inside it, as the examples do. When `-Because` is -absent the token renders as nothing and the sentence still reads correctly. +- `<because>` is filled only when `Because` is in `data`. Declaring a `-Because` parameter is not + enough; pass its value on, as both functions above do. +- Write the comma before `<because>`, as in `Expected <expected>,<because> but got <actual>.` The + sentence then reads correctly with and without a reason. +- A token for a custom key must match the key's case. With the key `Untagged`, `<Untagged>` is + filled and `<untagged>` stays in the message as written. A token with no key also stays as + written, and nothing reports it, so read the message once when writing the assertion. ### Hint -Use the `Hint` key when the assertion knows something more specific than the generic input hint: +Add the `Hint` key when the assertion knows something more useful than the default hint: ```powershell $assert.Fail( 'Expected at most 5 characters,<because> but <actual> has <Length>.', - @{ Because = $Because; Length = $Actual.Length - Hint = 'Rename the function rather than abbreviating the noun.' }) + @{ + Because = $Because + Length = $Actual.Length + Hint = 'Rename the function rather than abbreviating the noun.' + }) ``` -Left alone, the default hint covers the common shape mistake: +Without that key, the default hint covers the usual mistake with piped input: ```text Expected a Major.Minor.Patch version, but got @('1.2.3', '2.0.0'). @@ -211,150 +210,144 @@ value. To assert on a collection use Should-BeCollection or Should-BeEquivalent; single value pass it as the -Actual argument instead of piping it, e.g. -Actual $value. ``` -## Other Members On $assert +## Other Members Of $assert | Member | Purpose | | --- | --- | | `Actual()` | The collected value to assert on | -| `Fail(message [, data [, pretty]])` | Report a failure; `pretty` formats values across multiple lines | +| `Fail(message)`, `Fail(message, data)`, `Fail(message, data, pretty)` | Report a failure. `pretty` is a Boolean that formats values over several lines. | | `EnsureScalar(expected)` | Returns `expected`, or throws when it is a collection | -| `Format(value)` | Formats a value the way Pester does in messages | -| `IsCollection(value)` | Whether a value is treated as a collection | -| `Hint()` | The default input hint, for assertions that inspect it before failing | +| `Format(value)` | Formats a value as Pester does in messages | +| `IsCollection(value)` | Whether Pester treats the value as a collection | +| `Hint()` | The default hint, or `$null` | -`EnsureScalar` guards the **expected** side of an assertion that only makes sense against one value. -Call it before comparing: +`EnsureScalar` guards the expected side of an assertion that makes sense for one value only. Call it +before comparing: ```powershell $Expected = $assert.EnsureScalar($Expected) ``` ```text -5 | Should-BeUnder @(1, 2) -# You provided a collection to the -Expected parameter. Using a collection on the -Expected side is -# not allowed by this assertion, because it leads to unexpected behavior. To compare collections use -# Should-BeCollection, or a more specialized collection assertion such as Should-Any or Should-All. +You provided a collection to the -Expected parameter. Using a collection on the -Expected side is +not allowed by Assert-BeUnder, because it leads to unexpected behavior. To compare collections use +Should-BeCollection, or a more specialized collection assertion such as Should-Any or Should-All. ``` -Guard the actual side too when the check does arithmetic or calls a type-specific method. Pester's -hint appears on a `Fail()`, so an assertion that crashes on `@(1, 3) % 2` before reaching `Fail()` -produces a raw PowerShell error instead. Test the type first and fail properly. - -## Packaging: Name It Assert-, Export It As Should- +The message names the function, not the alias it was called through. -`Should` is not an approved PowerShell verb. A module that exports `Should-*` functions makes -`Import-Module` print the unapproved-verb warning to every consumer. An explicit `FunctionsToExport` -in the manifest does not suppress it, and `-DisableNameChecking` only moves the problem onto your -users. +Guard the actual side as well when the check uses an operator or a method that fails on a +collection. Such a failure is an ordinary PowerShell error, raised before `Fail()` is reached, and it +carries no hint. Test the value first and call `Fail()`. -Name the function with the approved `Assert` verb and export a `Should-*` alias. Aliases are not -verb-checked: +## Packaging: Name It Assert-, Export A Should- Alias -```powershell -function Assert-BeValidSemVer { ... } +`Should` is not an approved verb. A module that exports a function named `Should-*` makes +`Import-Module` warn about unapproved verbs, on PowerShell 7 and Windows PowerShell 5.1, and listing +the function in `FunctionsToExport` does not prevent the warning. -Set-Alias -Name Should-BeValidSemVer -Value Assert-BeValidSemVer -Export-ModuleMember -Function Assert-BeValidSemVer -Alias Should-BeValidSemVer -``` +Name the function with the approved verb `Assert` and export a `Should-*` alias. Aliases are not +checked: ```powershell -# TestHelpers/Assertions.psd1 +# Tests/TestHelpers/Assertions.psd1 @{ - RootModule = 'Assertions.psm1' + RootModule = 'Assertions.psm1' + ModuleVersion = '1.0.0' FunctionsToExport = @('Assert-BeValidSemVer', 'Assert-HaveTag') - AliasesToExport = @('Should-BeValidSemVer', 'Should-HaveTag') + CmdletsToExport = @() + AliasesToExport = @('Should-BeValidSemVer', 'Should-HaveTag') } ``` -Nothing in Pester keys off the assertion's name - it all keys off the `$PSCmdlet` passed as -`-Caller` - so the assertion behaves identically when called through the alias. +The root module holds the functions and the `Set-Alias` lines shown above. Pester works from the +`$PSCmdlet` passed as `-Caller`, not from the name of the command, so the assertion behaves the same +when it is called through the alias. -This only applies to modules. A test file that defines or dot-sources a `Should-*` function directly -needs none of it. +Use the same names when a test file defines the function itself. No warning appears there, but +STY-10 asks for an approved verb in every function name. ## Where To Put Them -Custom assertions are shared test infrastructure, so they follow the same rule as every other -discovery-time dependency: **each test file loads its own.** See -[Test Structure Guide](./test-structure-guide.md). +Custom assertions are test helpers, and each test file loads the helpers it uses (TST-02). The +[test structure guide](./test-structure-guide.md) describes the folder layout. ```text Tests/ TestHelpers/ Assertions.psd1 Assertions.psm1 - Assertions.Tests.ps1 # the assertions are code; test them + Assertions.Tests.ps1 Unit/ ``` ```powershell +# In Tests/Unit/Get-Thing.Tests.ps1 BeforeAll { - Import-Module "$PSScriptRoot/../TestHelpers/Assertions.psd1" -Force - Import-Module "$PSScriptRoot/../../MyModule.psd1" -Force + $testRoot = Split-Path -Path $PSScriptRoot -Parent + $helperFolder = Join-Path -Path $testRoot -ChildPath 'TestHelpers' + Import-Module -Name (Join-Path -Path $helperFolder -ChildPath 'Assertions.psd1') -Force } ``` -For a repository-wide set, import them from a `Pester.BeforeContainer.ps1` at the repository root, -which Pester dot-sources before every container. Put the import in a `BeforeAll`: from 6.2 the -file's top-level code runs at discovery only, and while a module import happens to survive into the -run phase (module state is session-wide), a dot-sourced function does not: - -```powershell -# Pester.BeforeContainer.ps1, at the repository root -BeforeAll { - Import-Module "$PSScriptRoot/Tests/TestHelpers/Assertions.psd1" -Force -} -``` - -The chain of setup files starts at `Run.RepoRoot` - see -[Pester Configuration Guide](./pester-configuration.md). +To load them for every test file, put the same import in a `BeforeAll` block of +`Pester.BeforeContainer.ps1` in the repository root. It must be inside `BeforeAll`: top-level code in +that file runs during discovery only. The [configuration guide](./pester-configuration.md) describes +`Run.RepoRoot`, where Pester starts looking for that file. Pester marks the setup file as +experimental; the import in each test file's own `BeforeAll` needs no such file. ## Test The Assertion Itself -An assertion that cannot fail is worse than no assertion, and this is exactly the failure mode -custom assertions invite. Cover the pass, the fail, and the message: +An assertion that cannot fail is worse than none. Cover the pass, the failure, and the message: ```powershell -Describe 'Should-BeValidSemVer' -Tag 'Unit', 'TestHelpers' { - It 'passes on <_>' -ForEach '1.2.3', '0.0.1', '10.20.30' { - $_ | Should-BeValidSemVer +#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } + +BeforeAll { + Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath 'Assertions.psd1') -Force +} + +Describe 'Should-BeValidSemVer' -Tag 'Unit' { + It 'Passes for <Version>' -ForEach @( + @{ Version = '1.2.3' } + @{ Version = '0.0.1' } + @{ Version = '10.20.30' } + ) { + $Version | Should-BeValidSemVer } - It 'fails on <_>' -ForEach '1.0', 'v1.2.3', 'not-a-version' { - { $_ | Should-BeValidSemVer } | Should-Throw + It 'Fails for <Version>' -ForEach @( + @{ Version = '1.0' } + @{ Version = 'v1.2.3' } + @{ Version = '1.2.3.4' } + ) { + { $Version | Should-BeValidSemVer } | + Should-Throw -ExceptionMessage 'Expected a Major.Minor.Patch version*' } - It 'names the offending value and the reason' { - try { - '1.0' | Should-BeValidSemVer -Because 'the module is published' - throw 'the assertion did not fail' - } - catch [Exception] { - $_.Exception.Message | - Should-BeString "Expected a Major.Minor.Patch version, because the module is published, but got '1.0'." - } + It 'Names the value and the reason in the message' { + $failure = { '1.0' | Should-BeValidSemVer -Because 'the module is published' } | Should-Throw + + $expected = "Expected a Major.Minor.Patch version, because the module is published, but got '1.0'." + $failure.Exception.Message | Should-BeString $expected } } ``` -The third test is the one that catches an unexpanded `<key>` token, which no amount of pass/fail -coverage will. +The message pattern in the second test matters. A bare `Should-Throw` would also pass if the +assertion could not be found. The third test is the one that catches a token that was not filled. ## Soft Assertions And Mock Filters -Both work with no extra code, because `Fail()` goes through the shared failure path: +Both work without extra code, because `Fail()` uses the same failure path as the built-in +assertions. With `Should.ErrorAction = 'Continue'`, a failed custom assertion is recorded and the +test goes on. -```powershell -$config.Should.ErrorAction = 'Continue' # collects every failure in the It, custom ones included -``` +Inside a `-ParameterFilter`, a passing assertion emits `$true`, so the filter matches. A failing one +ends the test with the assertion's own message: ```powershell -Should-Invoke Publish-Module -Times 1 -ParameterFilter { - $Version | Should-BeValidSemVer - $true +Should-Invoke -CommandName Publish-Module -ModuleName ModuleName -Times 1 -Exactly -ParameterFilter { + $RequiredVersion | Should-BeValidSemVer } ``` - -Inside a `-ParameterFilter` a passing assertion emits `$true` on its own pipeline, so the filter -matches; a failing one throws out of the filter. The trailing `$true` keeps the filter's result -explicit when the assertion is not the last statement. diff --git a/.github/instructions/pester-supporting-docs/integration-test-template.md b/.github/instructions/pester-supporting-docs/integration-test-template.md index 69cf641..81d263a 100644 --- a/.github/instructions/pester-supporting-docs/integration-test-template.md +++ b/.github/instructions/pester-supporting-docs/integration-test-template.md @@ -1,316 +1,177 @@ # Integration Test Template -Targets **Pester 6.2+**. Uses the `Should-*` assertion syntax - see -[Assertion Guide](./assertion-guide.md). +An integration test file: the module runs against the real file system and a real service, with +nothing mocked. The rules it follows are in the [Pester rules](../powershell-pester.instructions.md). +The file below passes on Pester 6.2.0 under PowerShell 7.6 and Windows PowerShell 5.1, with the +service configured and without it. -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. +## The Code Under Test -## Standard Integration Test Structure +The template tests the module `ModuleName` from the [unit test template](./unit-test-template.md). +The test file is in the `Tests` folder directly under the module root. -Use this template for integration tests that validate component interactions: +- `Export-Thing -Thing <object[]> -LiteralPath <string>` writes the things to a JSON file as UTF-8 + without a byte order mark. The file holds a `savedAt` time and a `things` array. The function + supports `-WhatIf`. +- `Get-Thing -Name <string[]> -ServiceUri <uri>` reads things from the service at that address. + +The address of a test instance of the service comes from the environment variable +`THING_SERVICE_URI`. + +## The Test File ```powershell #Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } -# Integration tests touch shared external resources - databases, ports, live endpoints - -# so they must not run concurrently with other files. #pester:no-parallel -BeforeAll { - # Import module under test. Each file is self-contained in Pester 6. - $ModulePath = Join-Path $PSScriptRoot '..\..\ModuleName.psd1' - Import-Module $ModulePath -Force - - # Set up test environment - $TestEnvironment = @{ - DatabaseConnection = $env:TEST_DATABASE_CONNECTION - APIEndpoint = $env:TEST_API_ENDPOINT - TempDirectory = Join-Path $env:TEMP "IntegrationTests" - TestDataPath = Join-Path $PSScriptRoot "..\TestData" - } - - # Create test resources - if (-not (Test-Path $TestEnvironment.TempDirectory)) { - New-Item -Path $TestEnvironment.TempDirectory -ItemType Directory -Force - } - - # Load test configuration - $TestConfig = Import-PowerShellDataFile (Join-Path $TestEnvironment.TestDataPath "integration-config.psd1") +BeforeDiscovery { + $serviceIsMissing = [string]::IsNullOrEmpty($env:THING_SERVICE_URI) } -AfterAll { - # Cleanup test resources - if (Test-Path $TestEnvironment.TempDirectory) { - Remove-Item -Path $TestEnvironment.TempDirectory -Recurse -Force - } - - # Cleanup test data - if ($TestConfig.CleanupRequired) { - Invoke-TestCleanup -Configuration $TestConfig +BeforeAll { + $moduleRoot = Split-Path -Path $PSScriptRoot -Parent + if (-not (Get-Module -Name ModuleName)) { + Import-Module -Name (Join-Path -Path $moduleRoot -ChildPath 'ModuleName.psd1') } } -Describe "Integration Tests" -Tag "Integration", "EndToEnd" { - Context "End-to-End Workflow" { - It "Should complete full business process" { - # Execute complete workflow - $result = Invoke-CompleteWorkflow -Configuration $TestEnvironment - - # Validate end-to-end results - $result.Success | Should-BeTrue - $result.ProcessedItems | Should-BeGreaterThan 0 - $result.Errors | Should-BeCollection @() - $result.ExecutionTime | Should-BeLessThan ([TimeSpan]::FromMinutes(5)) - } - - It "Should handle partial failures gracefully" { - # Inject controlled failures - $testData = Get-TestData -Type 'PartialFailure' - - $result = Invoke-CompleteWorkflow -Configuration $TestEnvironment -TestData $testData - - # Should complete with warnings - $result.Success | Should-BeTrue - $result.Warnings | Should-NotBeNull - $result.ProcessedItems | Should-BeGreaterThan 0 - } - - It "Should maintain data consistency across components" { - $testId = [System.Guid]::NewGuid().ToString() - - # Create data in first component - New-TestEntity -Id $testId -Data @{ Name = 'IntegrationTest'; Value = 'TestValue' } | - Should-BeEquivalent ([PSCustomObject]@{ Success = $true }) -ExcludePathsNotOnExpected - - # Retrieve from second component - Get-TestEntity -Id $testId | Should-BeEquivalent ([PSCustomObject]@{ - Name = 'IntegrationTest' - Value = 'TestValue' - }) -ExcludePathsNotOnExpected - - # Update through third component - (Set-TestEntity -Id $testId -Value 'UpdatedValue').Success | Should-BeTrue - - # Verify consistency - (Get-TestEntity -Id $testId).Value | Should-Be 'UpdatedValue' - } +Describe 'Export-Thing with the real file system' -Tag 'Integration' { + BeforeAll { + $things = @( + [PSCustomObject]@{ PSTypeName = 'ModuleName.Thing'; Name = 'alpha'; State = 'ready' } + [PSCustomObject]@{ PSTypeName = 'ModuleName.Thing'; Name = 'beta'; State = 'stopped' } + ) } - Context "External Service Dependencies" { - BeforeEach { - # Verify test environment connectivity - $connectivityTest = Test-ExternalServiceConnectivity -Endpoint $TestEnvironment.APIEndpoint - if (-not $connectivityTest.Success) { - Set-ItResult -Skipped -Because "External service not available: $($connectivityTest.Error)" - } - } + It 'Writes a file that reads back as the same things' { + $exportPath = Join-Path -Path $TestDrive -ChildPath 'things.json' - It "Should handle external service integration" { - # Test with real external services (controlled test environment) - $serviceResult = Test-ExternalServiceIntegration -Endpoint $TestEnvironment.APIEndpoint + $things | Export-Thing -LiteralPath $exportPath - $serviceResult.Connected | Should-BeTrue - $serviceResult.ResponseTime | Should-BeLessThan 5000 - $serviceResult.DataExchanged | Should-BeTrue + $document = Get-Content -LiteralPath $exportPath -Raw | ConvertFrom-Json + $expected = [PSCustomObject]@{ + things = @( + [PSCustomObject]@{ name = 'alpha'; state = 'ready' } + [PSCustomObject]@{ name = 'beta'; state = 'stopped' } + ) } + $document | Should-BeEquivalent $expected -ExcludePath 'savedAt' + } - It "Should retry on transient failures" { - # Simulate transient failure scenario - $retryResult = Invoke-ServiceWithRetry -Endpoint $TestEnvironment.APIEndpoint -MaxRetries 3 - - $retryResult.Success | Should-BeTrue - $retryResult.AttemptCount | Should-BeGreaterThan 1 - $retryResult.AttemptCount | Should-BeLessThanOrEqual 3 -Because 'MaxRetries caps attempts at 3' - } + It 'Writes UTF-8 without a byte order mark' { + $exportPath = Join-Path -Path $TestDrive -ChildPath 'encoding.json' - It "Should circuit break on persistent failures" { - # Test circuit breaker pattern - $circuitResult = Invoke-ServiceWithCircuitBreaker -Endpoint 'http://invalid-endpoint.test' + $things | Export-Thing -LiteralPath $exportPath - $circuitResult.CircuitOpen | Should-BeTrue - $circuitResult.ExecutionTime | Should-BeLessThan ([TimeSpan]::FromSeconds(10)) - } + # 123 is the opening brace. A byte order mark would put 239 first. + $bytes = [System.IO.File]::ReadAllBytes($exportPath) + $bytes.Count | Should-BeGreaterThan 0 + $bytes[0] | Should-Be 123 } - Context "Data Persistence" { - It "Should persist data correctly across sessions" { - $testData = @{ - Name = 'IntegrationTest' - Value = 'TestValue' - Timestamp = Get-Date - ComplexData = @{ - NestedProperty = 'NestedValue' - ArrayProperty = @(1, 2, 3) - } - } - - # Save data - $saveResult = Save-TestData -Data $testData -Connection $TestEnvironment.DatabaseConnection - $saveResult.Success | Should-BeTrue - $saveResult.RecordId | Should-NotBeNull - - # Retrieve data in new session - $retrievedData = Get-TestData -Id $saveResult.RecordId -Connection $TestEnvironment.DatabaseConnection - - # Verify data integrity. One deep comparison beats four property assertions and - # reports a property-by-property diff when the round trip loses something. - # Timestamp is excluded because storage may re-quantize it. - $retrievedData | Should-BeEquivalent $testData -ExcludePath 'Timestamp' - } - - It "Should handle concurrent data access" { - $testId = [System.Guid]::NewGuid().ToString() + It 'Writes nothing when -WhatIf is passed' { + $exportPath = Join-Path -Path $TestDrive -ChildPath 'whatif.json' - # Create concurrent operations - $jobs = 1..5 | ForEach-Object { - Start-Job -ScriptBlock { - param($TestId, $WorkerId) + $things | Export-Thing -LiteralPath $exportPath -WhatIf - # Simulate concurrent data access - Set-TestData -Id $TestId -Worker $WorkerId -Value "Worker$WorkerId-$(Get-Date -Format 'HHmmss')" - } -ArgumentList $testId, $_ - } - - # Wait for completion - $results = $jobs | Wait-Job | Receive-Job - $jobs | Remove-Job + Test-Path -LiteralPath $exportPath | Should-BeFalse + } - # Verify no data corruption - Get-TestData -Id $testId | Should-NotBeNull - $results | Should-BeCollection -Count 5 - } + It 'Throws when the folder does not exist' { + $missingFolder = Join-Path -Path $TestDrive -ChildPath 'missing' + $exportPath = Join-Path -Path $missingFolder -ChildPath 'things.json' - It "Should maintain referential integrity" { - # Create parent record - $parentId = [System.Guid]::NewGuid().ToString() - (New-TestParent -Id $parentId -Name 'TestParent').Success | Should-BeTrue + $failure = { $things | Export-Thing -LiteralPath $exportPath } | + Should-Throw -ExceptionType ([System.Management.Automation.MethodInvocationException]) - # Create child records - 1..3 | ForEach-Object { - (New-TestChild -ParentId $parentId -Name "TestChild$_").Success | Should-BeTrue - } + $failure.Exception.InnerException | Should-HaveType ([System.IO.DirectoryNotFoundException]) + } +} - # Verify relationships - $children = Get-TestChildren -ParentId $parentId - $children | Should-BeCollection -Count 3 - $children | Should-All { $_.ParentId -eq $parentId } +Describe 'Get-Thing with the real service' -Tag 'Integration' -Skip:$serviceIsMissing { + BeforeAll { + $serviceUri = $env:THING_SERVICE_URI + } - # Test cascade operations - (Remove-TestParent -Id $parentId -Cascade).Success | Should-BeTrue + It 'Reads a thing that exists' { + $result = @(Get-Thing -Name 'alpha' -ServiceUri $serviceUri) - # Verify cascade worked - Get-TestChildren -ParentId $parentId | Should-BeCollection @() - } + $result | Should-BeCollection -Count 1 + $result[0] | Should-HaveType 'ModuleName.Thing' + $result[0].Name | Should-Be 'alpha' } - Context "Cross-Platform Compatibility" { - # Pester 6 supports Windows PowerShell 5.1 and PowerShell 7.4+ only. - It "Should work on Windows PowerShell 5.1" -Skip:($PSVersionTable.PSVersion.Major -ne 5) { - $result = Invoke-CrossPlatformFunction -Platform 'Windows' -PowerShellVersion '5.1' - $result.Success | Should-BeTrue - $result.Platform | Should-Be 'Windows' - } - - It "Should work on PowerShell 7.4+" -Skip:($PSVersionTable.PSVersion -lt [version]'7.4') { - $result = Invoke-CrossPlatformFunction -Platform $PSVersionTable.Platform -PowerShellVersion $PSVersionTable.PSVersion - $result.Success | Should-BeTrue - $result.CrossPlatformFeatures | Should-BeTrue - } + It 'Reports a thing that does not exist as one non-terminating error' { + $output = Get-Thing -Name 'no-such-thing' -ServiceUri $serviceUri 2>&1 + $errors = @($output | Where-Object { $_ -is [System.Management.Automation.ErrorRecord] }) - It "Should handle path separators correctly" { - $testPath = Join-Path 'parent' 'child' 'file.txt' - $result = Test-PathHandling -Path $testPath - - $result.Success | Should-BeTrue - $result.NormalizedPath | Should-NotBeNull - - # Verify platform-specific path handling. - # $IsWindows is undefined on Windows PowerShell 5.1, which is always Windows. - $onWindows = $PSVersionTable.PSVersion.Major -eq 5 -or $IsWindows - if ($onWindows) { - $result.NormalizedPath | Should-MatchString '\\' - } else { - $result.NormalizedPath | Should-MatchString '/' - } - } + $output | Should-BeCollection -Count 1 + $errors | Should-BeCollection -Count 1 + $errors[0].FullyQualifiedErrorId | Should-Be 'ThingReadFailed,Get-Thing' } } ``` -## Pester 6 Notes for Integration Tests - -### Opt out of parallel execution +## What The Template Shows -Integration tests hold shared external resources - a database, a fixed port, a live endpoint. Two -files touching the same resource concurrently will produce flaky, hard-to-diagnose failures. Put -`#pester:no-parallel` at the top of every integration test file. Those files run serially in the -parent session while unit test files run in parallel. +### Real Files Go In The Test Drive -### `Set-ItResult -Pending` is gone - -Use `-Skipped` (with `-Because`) or `-Inconclusive`: - -```powershell -BeforeEach { - $connectivity = Test-ExternalServiceConnectivity -Endpoint $TestEnvironment.APIEndpoint - if (-not $connectivity.Success) { - Set-ItResult -Skipped -Because "External service not available: $($connectivity.Error)" - } -} -``` +Every file is created under `$TestDrive` (TST-03). Pester creates that folder for the test file and +removes it afterwards, so the tests need no cleanup code and cannot leave files behind. Anything +else that a test changes, such as an environment variable or a record in the service, must be +restored in `AfterAll` or `AfterEach` (TST-31). -### Environment-driven test cases must not be empty +### A Missing Environment Is Skipped At Discovery -An integration suite that builds `-ForEach` from environment configuration will **fail discovery** -in Pester 6 if that configuration is missing, rather than silently running zero tests. This is -usually what you want. Where an empty set is legitimate, be explicit: +`-Skip:` takes a value that is known during discovery, so it is computed in `BeforeDiscovery`. The +tests of a skipped block are reported as `Skipped`, and the block's `BeforeAll` does not run. -```powershell -It "Should reach <Endpoint>" -ForEach $configuredEndpoints -AllowNullOrEmptyForEach { - Test-Endpoint -Uri $Endpoint | Should-BeTrue -} -``` +Skip only for an environment that is not configured. When the address is set and the service does +not answer, the tests must fail; a skip there would hide the outage. A test can still mark itself at +run time with `Set-ItResult -Skipped -Because '<reason>'` or `Set-ItResult -Inconclusive`, from the +`It` block or from `BeforeEach`. `Set-ItResult -Pending` was removed in Pester 6. -### Prefer `Should-BeEquivalent` for round trips +Tag the `Describe` blocks `Integration` (TST-04), so that a run can leave them out with +`Filter.ExcludeTag`. -Persistence and API tests compare whole objects. One `Should-BeEquivalent` with `-ExcludePath` for -volatile fields (generated ids, timestamps) gives a property-by-property diff, where a run of -individual property assertions only tells you about the first mismatch. +### Test Cases From The Environment -## Integration Test Guidelines +A `-ForEach` list that is built from configuration is empty when the configuration is missing, and +Pester 6 then stops discovery of the file instead of running no tests. That is usually the right +outcome. The unit test template shows `-AllowNullOrEmptyForEach` for the case where an empty list is +legitimate. -### Test Environment Setup +### Whole Objects Are Compared With Should-BeEquivalent -- Use environment variables for configuration -- Create isolated test resources -- Verify external service availability -- Clean up resources after tests +One `Should-BeEquivalent` reports every property that differs after a round trip. `-ExcludePath` +leaves out a value that changes on every run, here `savedAt`. `Should-BeEquivalent` does not compare +the order of a collection; add index assertions after a count when order is part of the contract. -### End-to-End Testing +### A .NET Failure Arrives Wrapped -- Test complete business workflows -- Validate component interactions -- Verify data flow and consistency -- Test error propagation and recovery +`Export-Thing` writes with `[System.IO.File]::WriteAllText()` and passes a failure on with +`$PSCmdlet.ThrowTerminatingError($_)`. `Should-Throw -ExceptionType` compares the outer exception, +which is a `MethodInvocationException`. The test asserts that type and then reads the original +exception from the error record that `Should-Throw` returns. -### External Dependencies +### The File Does Not Run In Parallel -- Use real services in controlled environment -- Test connectivity and error handling -- Validate retry and circuit breaker patterns -- Mock only when real services unavailable +The comment `#pester:no-parallel` keeps the file out of the worker runspaces when a run sets +`Run.Parallel`; such files run one after another in the main session. It has no effect otherwise. +`Run.Parallel` is experimental and off by default. Mark a file this way when it uses a resource that +two files cannot share, such as a fixed port or a record in a test service. -### Data Persistence Testing +### Both Editions -- Test CRUD operations -- Verify data integrity and consistency -- Test concurrent access scenarios -- Validate referential integrity +The file runs unchanged on Windows PowerShell 5.1 because it avoids what differs there: -### Cross-Platform Considerations +- Each `Join-Path` call has one child path. `Join-Path 'a' 'b' 'c'` is an error on 5.1; nest the + calls. +- `$IsWindows` does not exist on 5.1, and reading it under strict mode is an error. Test + `$PSVersionTable.PSEdition -eq 'Desktop' -or $IsWindows`, which reads it only on PowerShell 7. +- The byte order mark is asserted from the bytes of the file, not from the encoding name, because + `-Encoding utf8` means different things on the two editions (STY-33). -- Test on multiple PowerShell versions -- Verify path handling differences -- Test platform-specific features -- Use conditional test execution +To limit a test to one edition, pass a discovery-time condition such as +`-Skip:($PSVersionTable.PSEdition -ne 'Core')`. diff --git a/.github/instructions/pester-supporting-docs/mocking-patterns.md b/.github/instructions/pester-supporting-docs/mocking-patterns.md index 75a6e18..59e7219 100644 --- a/.github/instructions/pester-supporting-docs/mocking-patterns.md +++ b/.github/instructions/pester-supporting-docs/mocking-patterns.md @@ -1,939 +1,406 @@ # Mocking Patterns Guide -Targets **Pester 6.2+**. +Patterns for `Mock`, `Should-Invoke`, and `InModuleScope`. The rules are TST-20 to TST-22 in the +[Pester rules](../powershell-pester.instructions.md); this guide holds the detail behind them. Every +statement about behaviour was checked by running it on Pester 6.2.0. -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. +The examples use the module from the Pester rules: `ModuleName`, whose public function `Get-Thing` +calls `Invoke-RestMethod`. -## What Changed in Pester 6 +## What Changed In Pester 6 -### `Assert-MockCalled` and `Assert-VerifiableMock` were removed +### Assert-MockCalled And Assert-VerifiableMock Were Removed -Both commands are **gone**. Calling them fails with a command-not-found error. - -| Removed | Replacement (classic) | Replacement (v6 syntax) | +| Removed | Classic replacement | Pester 6 replacement | | --- | --- | --- | | `Assert-MockCalled Cmd -Times 1 -Exactly` | `Should -Invoke Cmd -Times 1 -Exactly` | `Should-Invoke Cmd -Times 1 -Exactly` | | `Assert-MockCalled Cmd -Times 0` | `Should -Not -Invoke Cmd` | `Should-NotInvoke Cmd` | | `Assert-VerifiableMock` | `Should -InvokeVerifiable` | `Should-Invoke -Verifiable` | -The parameters carry over unchanged: `-Times`, `-Exactly`, `-ParameterFilter`, `-ExclusiveFilter`, +The parameters are the same: `-Times`, `-Exactly`, `-ParameterFilter`, `-ExclusiveFilter`, `-ModuleName`, `-Scope`. -### Fall-through to the real command was removed - -A mock whose `-ParameterFilter` does not match **no longer quietly calls the real command**. This -made mocks unpredictable and hid missing cases. Define every case you need explicitly: - -```powershell -# Pester 5: unmatched calls silently hit the real Get-Content. Pester 6: they hit this mock. -Mock Get-Content { 'default content' } -ModuleName ModuleName -Mock Get-Content { 'special content' } -ParameterFilter { $Path -like '*special*' } -ModuleName ModuleName -``` - -If a test relied on fall-through, add an explicit default mock, or scope the mock more narrowly so -the real command is genuinely not intercepted. - -### Failed mock assertions print the invocation history +### A Call That Matches No Mock Is An Error -When a `Should -Invoke` / `Should-Invoke` assertion fails, Pester prints every recorded call and -marks whether it matched your `-ParameterFilter` - `[*]` for matched, `[ ]` for not: +In Pester 5, a call that matched none of a command's parameter filters ran the real command. In +Pester 6 it fails the test: ```text -[-] emails alice exactly twice - Expected Send-Email to be called 2 times exactly, but was called 1 times - Performed invocations: - [*] Send-Email -To 'alice@example.com' -Subject 'Welcome' from Order.Tests.ps1:7 - [ ] Send-Email -To 'bob@example.com' -Subject 'Receipt' from Order.Tests.ps1:7 +No mock for command 'Get-Content' matched the call: none of the parameter filters matched, and there +is no default mock to fall back to. Add a default mock (e.g. `Mock Get-Content { ... }`) or adjust an +existing -ParameterFilter. ``` -You no longer need `Write-Host` debugging to work out why a parameter filter did not match. - -### Dynamic parameters are handled more robustly - -Aliases are matched in `-ParameterFilter`, and mocking falls back gracefully when a command cannot -produce dynamic parameters. - -### Mocking inside a module - -A mock declared in a test file replaces the command for callers in that file. To replace a function -that a _module's_ code calls - typically a private helper - declare the mock inside -`InModuleScope`, where the module's internal scope is visible: +The message goes on to list each filter and the parameters of the call. Declare a mock without a +filter for the calls that the filtered mocks do not cover. The order of the declarations does not +matter: ```powershell -InModuleScope MyModule { - Mock Get-ServiceStatus { throw 'service unreachable' } - - # Get-Data is public; Get-ServiceStatus is private and never exported - 'Billing', 'Identity' | Get-Data -ErrorAction SilentlyContinue -} +Mock -CommandName Get-Content -ModuleName ModuleName -MockWith { 'default content' } +Mock -CommandName Get-Content -ModuleName ModuleName -ParameterFilter { + $LiteralPath -like '*special*' +} -MockWith { 'special content' } ``` -Worked instance: -[Module-Structure-Example/Tests](../../../powershell-standards/Examples/Module-Structure-Example/Tests/) -mocks a private function this way to exercise a per-item failure path. +### A Failed Assertion Prints The Calls -## Global Mocks (Experimental) - -New in Pester 6.1, off by default. - -Scoping is the part of mocking that most often goes wrong, and it fails quietly. A mock applies to -calls from the scope that declared it, or from the one module named by `-ModuleName`. A call that -originates anywhere else reaches the **real command**. When the code under test calls a helper module -that calls `Invoke-WebRequest`, mocking `Invoke-WebRequest` in the test file does nothing, the test -still hits the network, and nothing announces it. - -`Mock.Global` makes a mock reach the command wherever it is called, from any module or script in the -runspace: +When `Should-Invoke` or `Should-NotInvoke` fails, the message lists every recorded call. `[*]` marks +a call that matched the `-ParameterFilter`: -```powershell -$config = New-PesterConfiguration -$config.Mock.Global = $true +```text +Expected Get-ServiceStatus in module ModuleName to be called 2 times exactly, but was called 1 time +Performed invocations: + [*] Get-ServiceStatus -Name 'alice' from C:\Repo\Tests\Get-Data.Tests.ps1:65 + [ ] Get-ServiceStatus -Name 'bob' from C:\Repo\Tests\Get-Data.Tests.ps1:65 ``` -The mock itself is written exactly as before - one declaration now covers every caller: +### A Parameter Filter Can Use An Alias -```powershell -Mock Invoke-WebRequest { '<html />' } +A filter may name a parameter by one of its aliases. A call to `Get-Content -LiteralPath` matches +`-ParameterFilter { $PSPath -like '*settings*' }`. -Get-Data # a function in another module that calls Invoke-WebRequest -Should-Invoke Invoke-WebRequest -Times 1 -``` - -### What Changes +## Where A Mock Applies -| | Default | `Mock.Global = $true` | -| --- | --- | --- | -| Reach | The declaring scope, or the module named by `-ModuleName` | Every module and script in the runspace | -| `-ModuleName` | Selects the scope the mock applies to | A hint used only to resolve the command | -| Lifetime | Removed when the declaring block ends | Unchanged | -| Nested Pester runs | Not visible | Not visible - the mock is tied to the run that created it | +A mock replaces a command for one caller (TST-21): -Because `-ModuleName` stops being a scope, existing mocks keep working unchanged. The one behavior -that can move is a mocked command called from a module you did **not** name: that call used to reach -the real command and now gets the mock. That is the change to look for when turning the option on - -in most suites it is also the bug the option exists to prevent. +| Declaration | Calls that reach the mock | +| --- | --- | +| `Mock -CommandName Get-Content` | Calls made from the test file. A call inside a module runs the real command. | +| `Mock -CommandName Get-Content -ModuleName ModuleName` | Calls made inside `ModuleName`, by public and private functions. | -### Guarding Against A Command Running For Real +- `-ModuleName` also works when the command is a private function of that module. Without it, Pester + reports `Could not find Command`. +- A second module that calls the same command needs its own mock with its own `-ModuleName`. +- Give `Should-Invoke` and `Should-NotInvoke` the same `-ModuleName` as the mock. -The clearest use is proving a destructive or outbound command is never genuinely invoked, without -enumerating every module that might reach it: +Use `InModuleScope` to call a private function directly. The script block runs inside the module, +where the test's variables do not exist, so pass values in with `-Parameters`: ```powershell -# Fail loudly on any real network call, from anywhere in the suite -Mock Invoke-RestMethod { throw 'blocked: unmocked network call' } -``` +It 'Appends the path of the thing to the service address' { + $expected = 'https://things.example.test/api/things/alpha' -A guard narrowed with `-ParameterFilter` needs one more piece. **`Mock.Global` does not reinstate -fall-through** - the Pester 6 removal described above still applies, so a call that matches no filter -does not reach the real command, it fails: + InModuleScope -ModuleName ModuleName -Parameters @{ expected = $expected } -ScriptBlock { + $result = Get-ThingUri -ServiceUri 'https://things.example.test/' -Name 'alpha' -```text -No mock for command 'Remove-Item' matched the call: none of the parameter filters matched, and there -is no default mock to fall back to. Add a default mock (e.g. `Mock Remove-Item { ... }`) or adjust an -existing -ParameterFilter. + $result.AbsoluteUri | Should-Be $expected + } +} ``` -Declare the allowed case explicitly alongside the guard: +### How Long A Mock Lasts -```powershell -# Any delete outside TestDrive fails the test, wherever it was called from -Mock Remove-Item { throw "blocked: Remove-Item outside TestDrive ($Path)" } ` - -ParameterFilter { $Path -notlike "$TestDrive*" } +A mock lasts until the block that declared it ends, and Pester then restores the command. No cleanup +code is needed. -# Required: the calls the guard permits still need a mock to land on -Mock Remove-Item { } -``` - -This is the same rule as everywhere else in Pester 6 - every case a mock is expected to handle must -be declared - and it is easy to miss when writing a guard, because the guard reads as though it only -concerns the calls it names. +| Declared in | Applies to | +| --- | --- | +| An `It` block | That test. It takes precedence over a mock of the same command from an outer block. | +| `BeforeEach` | Each test of the block, declared again before every test. | +| `BeforeAll` of a `Describe` or `Context` | Every test in that block. | +| `BeforeAll` at the top of the file | Every test in the file. | -### Why The Guard Needs Both Pieces +`Should-Invoke` counts the calls made in the current `It` block, wherever the mock was declared, so +one test does not see the calls of another. `-Scope Describe` widens the count to the enclosing +`Describe` block. -Run the same guard against a call made from inside another module, with and without the option, and -the two failure modes are opposite: +A mock never reaches another test file. Pester 6 discovers and runs one file, then the next, and +removes a file's mocks when the file ends. -| | Filter matches (blocked path) | Filter does not match (allowed path) | -| --- | --- | --- | -| `Mock.Global = $false` | **Guard never fires.** The mock does not cover the module, so the real command runs | Real command runs | -| `Mock.Global = $true` | Guard throws, as intended | **Unmatched-mock error.** Not fall-through | +### Mocks And Setup Blocks -The left column is the reason to turn `Mock.Global` on: without it a guard aimed at "any code under -test" silently does not apply to the module callers it was written for, and a destructive command -runs for real while the test still passes. +A `BeforeAll` in a `Context` runs before any `BeforeEach`. A mock defined in the parent's +`BeforeEach` is therefore not active while that `BeforeAll` runs, and the command it calls runs for +real. Define a mock that setup code depends on in an enclosing `BeforeAll` (TST-23). -The right column is the reason the guard still needs a default mock. Turning the option on converts -the permitted calls from "reach the real command" into "error", so a guard that looked complete -before now fails on traffic it was never meant to block. +`Should-Invoke` counts the calls made inside the current `It`. A call made in `BeforeAll` is outside +every `It`, so assert it with `-Scope Context`. Both were measured on Pester 6.2.0; the Pester rules +show a complete example. -The apparent fall-through with the option off is not fall-through at all - it is the mock failing to -reach that caller. Nothing restores Pester 5's fall-through behavior; `Mock.Global` is the only -setting in the `Mock` configuration section. +## Patterns -### Calling the Real Command From Inside a Mock +### An Answer That Depends On The Arguments -When the permitted calls must genuinely run, the default mock has to invoke the original command. -Capture it with `Get-Command` in a `BeforeAll` - **before** the mock is defined, or `Get-Command` -resolves to the mock - and call it with `&`, forwarding the automatic `$PesterBoundParameters` -hashtable that Pester exposes inside a `-MockWith` body: +Declare one filtered mock for each case. A default mock that throws turns an unexpected call into a +clear failure: ```powershell BeforeAll { - $originalRemoveItem = Get-Command Remove-Item -CommandType Cmdlet -} - -It 'deletes inside TestDrive and blocks everything else' { - Mock Remove-Item { throw "blocked: Remove-Item outside TestDrive ($Path)" } ` - -ParameterFilter { $Path -notlike "$TestDrive*" } - - # The permitted calls really delete - Mock Remove-Item { & $originalRemoveItem @PesterBoundParameters } - - # ... + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { + throw "Unexpected request: $Uri" + } + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -ParameterFilter { + $Uri.AbsolutePath -eq '/api/things/alpha' + } -MockWith { + [PSCustomObject]@{ name = 'alpha'; state = 'ready' } + } + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -ParameterFilter { + $Uri.AbsolutePath -eq '/api/things/beta' + } -MockWith { + [PSCustomObject]@{ name = 'beta'; state = 'stopped' } + } } ``` -`$PesterBoundParameters` is the hashtable of parameters the caller bound, so splatting it forwards -the call unchanged. This is the supported way to wrap rather than replace a command - decorating its -output, counting calls while keeping real behavior, or letting a filtered subset through. - -`$PSBoundParameters` is **not** the equivalent inside a mock body and does not carry the caller's -arguments; use `$PesterBoundParameters`. - -### Status - -`Mock.Global` is experimental and may change. The Pester team has said it wants this to become the -default in v7 and is collecting reports either way - including "turned it on, nothing changed" - -through the [Pester issue tracker](https://github.com/pester/Pester/issues). +The parameters of the mocked command are variables inside `-MockWith` and `-ParameterFilter`. A +`param()` block is not needed. Return objects with the shape and types of the real command's output, +so that the code under test reads them the way it reads the real thing. -Configure it per run rather than per file: there is no file-level directive to opt in or out, so a -suite either runs with global mocks or it does not. +### A Dependency That Fails -## Advanced Mocking Strategies - -### Context-Aware Mocking - -Create sophisticated mocks that respond differently based on parameters: +Throw the exception type that the real dependency throws, and assert what the function does with it: ```powershell -BeforeAll { - # API endpoint mocking with different responses - Mock Invoke-RestMethod { - param($Uri, $Method, $Body, $Headers) - - switch -Regex ($Uri) { - '/api/users/\d+$' { - if ($Method -eq 'GET') { - return @{ - Id = 123 - Name = 'Test User' - Email = 'test@example.com' - Status = 'Active' - } - } - elseif ($Method -eq 'PUT') { - $userData = $Body | ConvertFrom-Json - return @{ - Id = 123 - Name = $userData.Name - Email = $userData.Email - Status = 'Updated' - LastModified = Get-Date - } - } - elseif ($Method -eq 'DELETE') { - return @{ Success = $true; Message = 'User deleted' } - } - } - '/api/users$' { - if ($Method -eq 'GET') { - return @{ - Users = @( - @{ Id = 1; Name = 'User 1'; Status = 'Active' } - @{ Id = 2; Name = 'User 2'; Status = 'Inactive' } - ) - TotalCount = 2 - Page = 1 - } - } - elseif ($Method -eq 'POST') { - $newUser = $Body | ConvertFrom-Json - return @{ - Id = 999 - Name = $newUser.Name - Email = $newUser.Email - Status = 'Created' - CreatedDate = Get-Date - } - } - } - '/api/health' { - return @{ Status = 'Healthy'; Timestamp = Get-Date; Version = '1.0.0' } - } - default { - throw [System.Net.WebException]::new("Not Found: $Uri", [System.Net.WebExceptionStatus]::ProtocolError) - } - } - } -ModuleName ModuleName +It 'Reports a service timeout as a read error' { + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { + throw [System.TimeoutException]::new('The service did not answer.') + } + + { Get-Thing -Name 'alpha' -ErrorAction Stop } | + Should-Throw -FullyQualifiedErrorId 'ThingReadFailed,Get-Thing' } ``` -### Database Connection Mocking +### The Clock -Mock database operations with realistic behavior: +Code that calls `Get-Date` gives a different result on every run. Fix the time (TST-31): ```powershell -BeforeAll { - # Mock database connection with state management - $script:MockDatabase = @{ - Connected = $false - TransactionActive = $false - Data = @{ - Users = @() - Products = @() - } - } +It 'Reports the age of the report in days' { + Mock -CommandName Get-Date -ModuleName ModuleName -MockWith { [datetime]::new(2024, 1, 31) } - Mock Connect-Database { - param($ConnectionString, $Credential) - - if ($ConnectionString -match 'invalid') { - throw [System.Data.SqlClient.SqlException]::new('Invalid connection string') - } - - if ($Credential -and $Credential.UserName -eq 'invaliduser') { - throw [System.Data.SqlClient.SqlException]::new('Login failed for user') - } - - $script:MockDatabase.Connected = $true - return @{ - ConnectionId = [System.Guid]::NewGuid() - ServerVersion = '14.0.3048' - Database = 'TestDB' - State = 'Open' - } - } -ModuleName ModuleName - - Mock Invoke-DatabaseQuery { - param($Query, $Parameters = @{}) - - if (-not $script:MockDatabase.Connected) { - throw [System.InvalidOperationException]::new('Database connection not established') - } - - # Parse simple SQL queries - switch -Regex ($Query) { - 'SELECT.*FROM Users' { - if ($Query -match 'WHERE Id = @Id') { - $userId = $Parameters.Id - return $script:MockDatabase.Data.Users | Where-Object { $_.Id -eq $userId } - } - return $script:MockDatabase.Data.Users - } - 'INSERT INTO Users' { - $newUser = @{ - Id = ($script:MockDatabase.Data.Users.Count + 1) - Name = $Parameters.Name - Email = $Parameters.Email - CreatedDate = Get-Date - } - $script:MockDatabase.Data.Users += $newUser - return @{ RowsAffected = 1; Identity = $newUser.Id } - } - 'UPDATE Users' { - $user = $script:MockDatabase.Data.Users | Where-Object { $_.Id -eq $Parameters.Id } - if ($user) { - $user.Name = $Parameters.Name ?? $user.Name - $user.Email = $Parameters.Email ?? $user.Email - $user.ModifiedDate = Get-Date - return @{ RowsAffected = 1 } - } - return @{ RowsAffected = 0 } - } - 'DELETE FROM Users' { - $originalCount = $script:MockDatabase.Data.Users.Count - $script:MockDatabase.Data.Users = $script:MockDatabase.Data.Users | Where-Object { $_.Id -ne $Parameters.Id } - return @{ RowsAffected = $originalCount - $script:MockDatabase.Data.Users.Count } - } - default { - throw [System.Data.SqlClient.SqlException]::new("Invalid SQL syntax: $Query") - } - } - } -ModuleName ModuleName - - Mock Start-DatabaseTransaction { - if (-not $script:MockDatabase.Connected) { - throw [System.InvalidOperationException]::new('Database connection not established') - } - $script:MockDatabase.TransactionActive = $true - return @{ TransactionId = [System.Guid]::NewGuid() } - } -ModuleName ModuleName - - Mock Commit-DatabaseTransaction { - $script:MockDatabase.TransactionActive = $false - } -ModuleName ModuleName - - Mock Rollback-DatabaseTransaction { - $script:MockDatabase.TransactionActive = $false - # In a real mock, you might restore previous state here - } -ModuleName ModuleName + Get-ReportAge -Created ([datetime]::new(2024, 1, 1)) | Should-Be 30 } ``` -### File System Mocking +### The File System -Mock file system operations with realistic behavior: +Prefer real files in `$TestDrive` to mocks of `Get-Content`, `Test-Path`, and `Set-Content` (TST-03). +The test then exercises the real provider, and Pester removes the files. Mock a file command only +for a condition that cannot be staged, such as a read that is denied: ```powershell -BeforeAll { - # Mock file system with in-memory storage - $script:MockFileSystem = @{ - Files = @{} - Directories = @('C:\', 'C:\Temp\', 'C:\Windows\') +It 'Reports a settings file that cannot be read' { + Mock -CommandName Get-Content -ModuleName ModuleName -MockWith { + throw [System.UnauthorizedAccessException]::new('Access to the path is denied.') } - Mock Test-Path { - param($Path) - - $normalizedPath = $Path.Replace('/', '\').TrimEnd('\') - - # Check if it's a file - if ($script:MockFileSystem.Files.ContainsKey($normalizedPath)) { - return $true - } - - # Check if it's a directory - return $script:MockFileSystem.Directories -contains "$normalizedPath\" - } -ModuleName ModuleName - - Mock Get-Content { - param($Path, $Raw, $Encoding = 'UTF8') - - $normalizedPath = $Path.Replace('/', '\') - - if (-not $script:MockFileSystem.Files.ContainsKey($normalizedPath)) { - throw [System.IO.FileNotFoundException]::new("File not found: $Path") - } - - $content = $script:MockFileSystem.Files[$normalizedPath] - - if ($Raw) { - return $content - } else { - return $content -split "`r?`n" - } - } -ModuleName ModuleName - - Mock Set-Content { - param($Path, $Value, $Encoding = 'UTF8') - - $normalizedPath = $Path.Replace('/', '\') - $directory = Split-Path $normalizedPath -Parent - - # Ensure directory exists - if ($directory -and -not ($script:MockFileSystem.Directories -contains "$directory\")) { - throw [System.IO.DirectoryNotFoundException]::new("Directory not found: $directory") - } - - $script:MockFileSystem.Files[$normalizedPath] = $Value -join "`r`n" - return @{ Length = $script:MockFileSystem.Files[$normalizedPath].Length } - } -ModuleName ModuleName - - Mock New-Item { - param($Path, $ItemType, $Force) - - $normalizedPath = $Path.Replace('/', '\') - - if ($ItemType -eq 'Directory') { - if (-not ($script:MockFileSystem.Directories -contains "$normalizedPath\")) { - $script:MockFileSystem.Directories += "$normalizedPath\" - } - return @{ FullName = $normalizedPath; PSIsContainer = $true } - } else { - $script:MockFileSystem.Files[$normalizedPath] = '' - return @{ FullName = $normalizedPath; PSIsContainer = $false } - } - } -ModuleName ModuleName - - Mock Remove-Item { - param($Path, $Recurse, $Force) - - $normalizedPath = $Path.Replace('/', '\') - - # Remove file - if ($script:MockFileSystem.Files.ContainsKey($normalizedPath)) { - $script:MockFileSystem.Files.Remove($normalizedPath) - return - } - - # Remove directory - $directoryPath = "$normalizedPath\" - if ($script:MockFileSystem.Directories -contains $directoryPath) { - if ($Recurse) { - # Remove all files and subdirectories - $filesToRemove = $script:MockFileSystem.Files.Keys | Where-Object { $_.StartsWith($normalizedPath) } - foreach ($file in $filesToRemove) { - $script:MockFileSystem.Files.Remove($file) - } - - $dirsToRemove = $script:MockFileSystem.Directories | Where-Object { $_.StartsWith($directoryPath) } - foreach ($dir in $dirsToRemove) { - $script:MockFileSystem.Directories = $script:MockFileSystem.Directories | Where-Object { $_ -ne $dir } - } - } - $script:MockFileSystem.Directories = $script:MockFileSystem.Directories | Where-Object { $_ -ne $directoryPath } - } - } -ModuleName ModuleName + { Read-Setting -LiteralPath (Join-Path -Path $TestDrive -ChildPath 'settings.json') } | + Should-Throw -ExceptionType ([System.UnauthorizedAccessException]) } ``` -### Network Service Mocking +### A Native Executable -Mock network operations with failure simulation: +An executable is mocked by its name, and it must be installed where the tests run, because Pester +cannot mock a command that it cannot find. The function under test reads `$LASTEXITCODE` (ERR-23), +so the mock sets it. It must write to PowerShell's own variable in the global scope; a plain +assignment stays inside the mock: ```powershell -BeforeAll { - # Mock network services with failure simulation - Mock Test-NetConnection { - param($ComputerName, $Port = 80, $InformationLevel = 'Detailed') - - # Simulate different network conditions - switch ($ComputerName) { - 'unreachable.test' { - return @{ - ComputerName = $ComputerName - RemoteAddress = $null - PingSucceeded = $false - TcpTestSucceeded = $false - } - } - 'slow.test' { - Start-Sleep -Milliseconds 2000 # Simulate slow connection - return @{ - ComputerName = $ComputerName - RemoteAddress = '192.168.1.100' - PingSucceeded = $true - TcpTestSucceeded = $true - PingReplyDetails = @{ RoundtripTime = 2000 } - } - } - { $_ -match '\.local$' } { - return @{ - ComputerName = $ComputerName - RemoteAddress = '192.168.1.50' - PingSucceeded = $true - TcpTestSucceeded = $true - PingReplyDetails = @{ RoundtripTime = 15 } - } - } - default { - return @{ - ComputerName = $ComputerName - RemoteAddress = '8.8.8.8' - PingSucceeded = $true - TcpTestSucceeded = $true - PingReplyDetails = @{ RoundtripTime = 45 } - } - } - } - } -ModuleName ModuleName - - Mock Invoke-WebRequest { - param($Uri, $Method = 'GET', $Body, $Headers = @{}, $TimeoutSec = 30) - - # Simulate different response scenarios - switch -Regex ($Uri) { - 'timeout\.test' { - Start-Sleep -Seconds ($TimeoutSec + 1) - throw [System.Net.WebException]::new('The operation has timed out', [System.Net.WebExceptionStatus]::Timeout) - } - 'server-error\.test' { - throw [System.Net.WebException]::new('The remote server returned an error: (500) Internal Server Error', [System.Net.WebExceptionStatus]::ProtocolError) - } - 'not-found\.test' { - throw [System.Net.WebException]::new('The remote server returned an error: (404) Not Found', [System.Net.WebExceptionStatus]::ProtocolError) - } - 'auth\.test' { - if (-not $Headers.ContainsKey('Authorization')) { - throw [System.Net.WebException]::new('The remote server returned an error: (401) Unauthorized', [System.Net.WebExceptionStatus]::ProtocolError) - } - # Return success response - return @{ - StatusCode = 200 - StatusDescription = 'OK' - Content = '{"authenticated": true, "user": "testuser"}' - Headers = @{ 'Content-Type' = 'application/json' } - } - } - default { - # Return successful response - $responseContent = switch ($Method) { - 'GET' { '{"data": "sample response"}' } - 'POST' { '{"id": 12345, "status": "created"}' } - 'PUT' { '{"id": 12345, "status": "updated"}' } - 'DELETE' { '{"status": "deleted"}' } - default { '{"status": "ok"}' } - } - - return @{ - StatusCode = 200 - StatusDescription = 'OK' - Content = $responseContent - Headers = @{ 'Content-Type' = 'application/json' } - } - } - } - } -ModuleName ModuleName -} -``` +It 'Throws when git reports an error' { + Mock -CommandName git -ModuleName ModuleName -MockWith { + $global:LASTEXITCODE = 128 + } -### External Command Mocking + { Get-RepositoryStatus } | + Should-Throw -FullyQualifiedErrorId 'GitStatusFailed,Get-RepositoryStatus' +} -Mock external executable commands: +It 'Returns the changed files' { + Mock -CommandName git -ModuleName ModuleName -MockWith { + $global:LASTEXITCODE = 0 + ' M README.md' + } -```powershell -BeforeAll { - # Mock external commands with different exit codes - Mock Start-Process { - param($FilePath, $ArgumentList, $Wait, $PassThru, $RedirectStandardOutput, $RedirectStandardError) - - $command = $FilePath - $args = $ArgumentList -join ' ' - - # Simulate different command behaviors - switch -Regex ("$command $args") { - 'git status' { - $output = @" -On branch main -Your branch is up to date with 'origin/main'. - -Changes not staged for commit: - (use "git add <file>..." to update what will be committed) - (use "git checkout -- <file>..." to discard changes in working directory) - - modified: src/module.ps1 - -no changes added to commit (use "git add" or "git commit -a") -"@ - if ($RedirectStandardOutput) { - $output | Out-File $RedirectStandardOutput - } - return @{ ExitCode = 0; ProcessName = 'git' } - } - 'git clone.*invalid-repo' { - $error = "fatal: repository 'invalid-repo' does not exist" - if ($RedirectStandardError) { - $error | Out-File $RedirectStandardError - } - return @{ ExitCode = 128; ProcessName = 'git' } - } - 'docker ps' { - $output = @" -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -abc123def456 nginx "/docker-entrypoint.…" 2 hours ago Up 2 hours 80/tcp web-server -def456ghi789 redis "docker-entrypoint.s…" 2 hours ago Up 2 hours 6379/tcp redis-cache -"@ - if ($RedirectStandardOutput) { - $output | Out-File $RedirectStandardOutput - } - return @{ ExitCode = 0; ProcessName = 'docker' } - } - 'powershell.*-File.*test-script' { - # Simulate script execution - if ($args -match 'fail') { - return @{ ExitCode = 1; ProcessName = 'powershell' } - } - return @{ ExitCode = 0; ProcessName = 'powershell' } - } - default { - # Unknown command - return @{ ExitCode = 127; ProcessName = $command } - } - } - } -ModuleName ModuleName - - # Mock Windows services - Mock Get-Service { - param($Name, $ComputerName = $env:COMPUTERNAME) - - $mockServices = @{ - 'Spooler' = @{ Name = 'Spooler'; Status = 'Running'; StartType = 'Automatic' } - 'BITS' = @{ Name = 'BITS'; Status = 'Running'; StartType = 'Manual' } - 'Fax' = @{ Name = 'Fax'; Status = 'Stopped'; StartType = 'Manual' } - 'InvalidService' = $null - } - - if ($Name) { - $service = $mockServices[$Name] - if ($service) { - return [PSCustomObject]$service - } else { - throw [Microsoft.PowerShell.Commands.ServiceCommandException]::new("Cannot find any service with service name '$Name'.") - } - } else { - return $mockServices.Values | Where-Object { $_ -ne $null } | ForEach-Object { [PSCustomObject]$_ } - } - } -ModuleName ModuleName + Get-RepositoryStatus | Should-Be ' M README.md' } ``` -## Mock Validation Patterns +Set the exit code in every mock of an executable, the successful ones too. The variable keeps the +value that the previous test left in it. -### Parameter Filter Testing +### Running The Real Command From A Mock -Validate that mocks are called with correct parameters: +To count the calls to a command that should still do its work, or to run the real command for some +calls only, capture the command before the test and call it with the parameters of the mocked call. +Pester provides those as `$PesterBoundParameters`: ```powershell -Context "Mock Parameter Validation" { - It "Should call API with correct parameters" { - $testData = @{ Name = 'Test'; Value = 'Data' } - - Function-Name -Data $testData -Endpoint 'https://api.test.com' - - Should-Invoke Invoke-RestMethod -Times 1 -Exactly -ModuleName ModuleName -ParameterFilter { - $Uri -eq 'https://api.test.com' -and - $Method -eq 'POST' -and - ($Body | ConvertFrom-Json).Name -eq 'Test' - } - } - - It "Should handle multiple calls with different parameters" { - $endpoints = @('https://api1.test.com', 'https://api2.test.com') - - foreach ($endpoint in $endpoints) { - Function-Name -Endpoint $endpoint - } - - Should-Invoke Invoke-RestMethod -Times 2 -Exactly -ModuleName ModuleName - Should-Invoke Invoke-RestMethod -Times 1 -Exactly -ModuleName ModuleName -ParameterFilter { - $Uri -eq 'https://api1.test.com' - } - Should-Invoke Invoke-RestMethod -Times 1 -Exactly -ModuleName ModuleName -ParameterFilter { - $Uri -eq 'https://api2.test.com' - } - } - - It "Should not call the destructive command in WhatIf mode" { - Function-Name -Path 'C:\Temp\file.txt' -WhatIf +BeforeAll { + $realGetContent = Get-Command -Name Get-Content -CommandType Cmdlet + $settingPath = Join-Path -Path $TestDrive -ChildPath 'settings.txt' + Set-Content -LiteralPath $settingPath -Value 'region=westeurope' -Encoding ascii +} - Should-NotInvoke Remove-Item -ModuleName ModuleName +It 'Reads the settings file once' { + Mock -CommandName Get-Content -ModuleName ModuleName -MockWith { + & $realGetContent @PesterBoundParameters } - It "Should call the API only for allowed endpoints" { - Function-Name -Endpoint 'https://api1.test.com' + Read-Setting -LiteralPath $settingPath | Should-BeString 'region=westeurope' -TrimWhitespace - # -ExclusiveFilter fails if ANY recorded call does not match the filter - Should-Invoke Invoke-RestMethod -ModuleName ModuleName -ExclusiveFilter { - $Uri -like 'https://api1.*' - } - } + Should-Invoke -CommandName Get-Content -ModuleName ModuleName -Times 1 -Exactly } ``` -Note the parameter shape: `-Times 1 -Exactly`, not `-Exactly 1`. `-Exactly` is a switch that changes -`-Times` from "at least" to "exactly". `Should-Invoke Cmd -Exactly 1` binds `1` positionally to -`-Times` and happens to work, but writing it out is clearer and matches the classic syntax. +- `$PSBoundParameters` is empty inside `-MockWith`. Use `$PesterBoundParameters`. +- Pass `-CommandType` to `Get-Command`. Once a mock exists, `Get-Command -Name Get-Content` returns + the alias that Pester created for the mock. -### Asserting a Mock Was Not Called +## Asserting Calls -`Should-NotInvoke` replaces `Should -Not -Invoke` and `Assert-MockCalled -Times 0`. This is the -assertion most often missing from error-handling tests - proving the failure path stopped before the -destructive call is usually more valuable than proving it threw: +### Parameters Of A Call ```powershell -It "Should not write results when validation fails" { - Mock Write-Result { } -ModuleName ModuleName - - { Function-Name -ParameterName '' } | Should-Throw +It 'Sends one GET request for each name' { + $null = Get-Thing -Name 'alpha', 'beta' - Should-NotInvoke Write-Result -ModuleName ModuleName + $alphaRequest = @{ + CommandName = 'Invoke-RestMethod' + ModuleName = 'ModuleName' + ParameterFilter = { $Method -eq 'Get' -and $Uri.AbsolutePath -eq '/api/things/alpha' } + } + Should-Invoke -CommandName Invoke-RestMethod -ModuleName ModuleName -Times 2 -Exactly + Should-Invoke @alphaRequest -Times 1 -Exactly } ``` -### Mock Call Sequence Validation - -Ensure mocks are called in the correct order: +- `-Times 1` alone means at least once. Add `-Exactly` (TST-22). Without `-Times`, `Should-Invoke` + passes for one call or more. +- `-ExclusiveFilter` passes only when every recorded call matches the filter. Use it to prove that + nothing else was requested: ```powershell -Context "Mock Call Sequence" { - BeforeEach { - $script:CallSequence = @() - - Mock Connect-Database { - $script:CallSequence += 'Connect' - return @{ Connected = $true } - } -ModuleName ModuleName - - Mock Start-DatabaseTransaction { - $script:CallSequence += 'StartTransaction' - return @{ TransactionId = '12345' } - } -ModuleName ModuleName - - Mock Invoke-DatabaseQuery { - $script:CallSequence += 'Query' - return @{ Success = $true } - } -ModuleName ModuleName - - Mock Commit-DatabaseTransaction { - $script:CallSequence += 'Commit' - } -ModuleName ModuleName - - Mock Disconnect-Database { - $script:CallSequence += 'Disconnect' - } -ModuleName ModuleName - } - - It "Should call database operations in correct sequence" { - Function-Name -DatabaseOperation 'UpdateUser' - - # Should-BeCollection compares item by item and reports the first differing index - $script:CallSequence | - Should-BeCollection @('Connect', 'StartTransaction', 'Query', 'Commit', 'Disconnect') - } +Should-Invoke -CommandName Invoke-RestMethod -ModuleName ModuleName -ExclusiveFilter { + $Uri.Host -eq 'things.example.test' } ``` -`Should-BeCollection` is the right assertion here rather than `Should-Be`: it compares element by -element and names the index that diverged, instead of dumping two flattened strings at you. +### A Command That Must Not Run -## Mock Best Practices +`Should-NotInvoke` shows that a failure path stopped before the call that changes something. That is +often worth more than showing that the function threw: -### Isolated Mock Scope +```powershell +It 'Does not call the service when the name is not valid' { + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { } -Keep mocks isolated between tests: + { Remove-Thing -Name '../alpha' -Confirm:$false } | + Should-Throw -FullyQualifiedErrorId 'ParameterArgumentValidationError,Remove-Thing' -```powershell -Describe "Function Tests" { - Context "Success Scenarios" { - BeforeEach { - Mock External-Service { return @{ Success = $true } } -ModuleName ModuleName - } + Should-NotInvoke -CommandName Invoke-RestMethod -ModuleName ModuleName +} - # Tests using success mock - } +It 'Does not call the service when -WhatIf is passed' { + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { } - Context "Failure Scenarios" { - BeforeEach { - Mock External-Service { throw 'Service unavailable' } -ModuleName ModuleName - } + Remove-Thing -Name 'alpha' -WhatIf - # Tests using failure mock - } + Should-NotInvoke -CommandName Invoke-RestMethod -ModuleName ModuleName } ``` -Each `Context` gets its own `BeforeEach`. From 6.2 a block may also hold several `BeforeEach` -blocks, run in declaration order, so a second group of mocks can be its own block rather than -merged into the first. Separate `Context` blocks remain the better split when the two groups serve -different tests; 6.0 and 6.1 throw on a second `BeforeEach` in the _same_ block. +### The Order Of Calls -### Mocks and Setup Blocks Run at Different Times - -A `BeforeEach` runs before each `It`. A `BeforeAll` in a child `Context` runs once, before the first -`It` in that `Context`, which is before any `BeforeEach` has run. A mock defined in the parent's -`BeforeEach` is therefore not active while the child's `BeforeAll` executes, and a command the setup -calls runs for real, or fails as unmocked, with nothing pointing at the mock one block up. Define a -mock that setup code depends on in an enclosing `BeforeAll`; keep `BeforeEach` for mocks that only -the tests themselves call. - -`Should-Invoke` counts calls made in the current `It` by default. A call made in `BeforeAll` is -outside every `It`, so the assertion reports zero invocations even though the command ran. Assert -it with `-Scope Context` (or `-Scope Describe`), which counts every call made inside that block, -its setup included: +Record the calls in a list that the mocks add to, then assert the count and each position. +`Should-BeCollection @('Connect', 'Query')` cannot do this: it passes for the same items in any +order (TST-14). ```powershell -Describe 'Get-ServerHealth' -Tag 'Unit' { - BeforeAll { - # Defined here so the Context's BeforeAll below can rely on it - Mock Get-CimInstance { [PSCustomObject]@{ FreePhysicalMemory = 4GB } } -ModuleName ModuleName - } - - Context 'A server queried once for the whole Context' { - BeforeAll { - # Runs before any BeforeEach; only mocks from enclosing BeforeAll blocks are active here - $script:Health = Get-ServerHealth -ComputerName 'SERVER01' - } - - It 'Queried the server once' { - # The default scope is this It, where nothing was called; the call lives in BeforeAll - Should-Invoke Get-CimInstance -ModuleName ModuleName -Times 1 -Exactly -Scope Context - } - } +It 'Connects before it queries and disconnects last' { + $calls = [System.Collections.Generic.List[string]]::new() + Mock -CommandName Connect-Database -ModuleName ModuleName -MockWith { $calls.Add('Connect') } + Mock -CommandName Invoke-DatabaseQuery -ModuleName ModuleName -MockWith { $calls.Add('Query') } + Mock -CommandName Disconnect-Database -ModuleName ModuleName -MockWith { $calls.Add('Disconnect') } + + Update-Record -Id 42 + + $calls | Should-BeCollection -Count 3 + $calls[0] | Should-Be 'Connect' + $calls[1] | Should-Be 'Query' + $calls[2] | Should-Be 'Disconnect' } ``` -### Mocks Do Not Cross Files +`$calls -join ', ' | Should-Be 'Connect, Query, Disconnect'` asserts the same thing in one line, and +its failure message shows the whole sequence. -Pester 6 discovers and runs one file at a time, and under `Run.Parallel` each file gets its own -runspace. A mock defined in one test file is never visible to another. Define every mock a file -needs inside that file. For mock setup shared across many files, dot-source a shared mock factory -from a `Pester.BeforeContainer.ps1` - inside its `BeforeAll`, because from 6.2 top-level code in -that file runs at discovery only and a function it defined would be gone by the time a test calls -it. `Mock` itself must still be called inside a `Describe`/`Context`/`BeforeAll` scope: +## Shared Mocks + +Each test file declares the mocks it needs (TST-02). When many files need the same set, put it in a +function and load that function from `Pester.BeforeContainer.ps1`, the setup file that Pester runs +for every test file below its folder: ```powershell -# TestHelpers/MockFactory.ps1 - dot-sourced from Pester.BeforeContainer.ps1 -function Set-StandardExternalMock { - param([string]$ModuleName) - Mock Invoke-RestMethod { @{ Status = 'Healthy' } } -ModuleName $ModuleName - Mock Write-Verbose { } -ModuleName $ModuleName +# Tests/TestHelpers/MockFactory.ps1 +function Set-ServiceMock { + [CmdletBinding()] + param( + [Parameter(Mandatory)] + [string]$ModuleName + ) + + Mock -CommandName Invoke-RestMethod -ModuleName $ModuleName -MockWith { + [PSCustomObject]@{ status = 'healthy' } + } } ``` ```powershell -# Pester.BeforeContainer.ps1, at the repository root +# Pester.BeforeContainer.ps1, in the repository root BeforeAll { - . "$PSScriptRoot/Tests/TestHelpers/MockFactory.ps1" + $helperFolder = Join-Path -Path (Join-Path -Path $PSScriptRoot -ChildPath 'Tests') -ChildPath 'TestHelpers' + . (Join-Path -Path $helperFolder -ChildPath 'MockFactory.ps1') } ``` ```powershell -# In each test file +# In a test file BeforeAll { - Set-StandardExternalMock -ModuleName ModuleName + Set-ServiceMock -ModuleName ModuleName } ``` -### Realistic Mock Data - -Use realistic data structures in mocks: +- The dot-sourcing must be inside `BeforeAll`. Top-level code in `Pester.BeforeContainer.ps1` runs + during discovery only, so a function defined there no longer exists when the tests run. +- The mock belongs to the block that calls the function, as if the block had declared it. +- Pester's source marks `Pester.BeforeContainer.ps1` as experimental. -```powershell -BeforeAll { - # Load realistic test data - $script:TestUsers = @( - @{ Id = 1; Name = 'John Doe'; Email = 'john.doe@example.com'; Department = 'IT'; Active = $true } - @{ Id = 2; Name = 'Jane Smith'; Email = 'jane.smith@example.com'; Department = 'HR'; Active = $true } - @{ Id = 3; Name = 'Bob Johnson'; Email = 'bob.johnson@example.com'; Department = 'Finance'; Active = $false } - ) +## Global Mocks (Experimental) - Mock Get-ADUser { - param($Identity, $Properties) +`Mock.Global` is off by default, and the Pester rules say not to enable an experimental option +unless the user asks. When it is on, a mock reaches the command from every module and script, not +from one caller: - $user = $script:TestUsers | Where-Object { $_.Name -eq $Identity -or $_.Id -eq $Identity } - if ($user) { - return [PSCustomObject]$user - } else { - throw [Microsoft.ActiveDirectory.Management.ADIdentityNotFoundException]::new("User '$Identity' not found") - } - } -ModuleName ModuleName -} +```powershell +$configuration = New-PesterConfiguration +$configuration.Mock.Global = $true ``` -### Mock Cleanup +| | Default | `Mock.Global = $true` | +| --- | --- | --- | +| Reach of a mock | The test file, or the module named by `-ModuleName` | Every module and script | +| `-ModuleName` | Selects the caller that the mock applies to | Still accepted; it no longer limits the mock | +| A call that matches no filter | Error, as described above | Error, as described above | -Ensure proper mock cleanup: +Its use is a guard: a mock that fails the test when any code, in any module, runs a command for +real. A guard that has a filter needs a default mock beside it, because the calls that the guard +permits must still match something: ```powershell -AfterEach { - # Reset mock state if needed - $script:MockDatabase = @{ - Connected = $false - Data = @{} +BeforeAll { + Mock -CommandName Remove-Item -ParameterFilter { + $target = if ($LiteralPath) { $LiteralPath } else { $Path } + $target -notlike "$TestDrive*" + } -MockWith { + throw 'Remove-Item was called outside the test drive.' } - - # Clear any temporary files created by mocks - Get-ChildItem -Path $env:TEMP -Filter "MockTest*" | Remove-Item -Force -ErrorAction SilentlyContinue + Mock -CommandName Remove-Item -MockWith { } } ``` + +The filter reads both path parameters, because the code under test may use either. With the option +off, the same two mocks apply to calls from the test file only. A module that calls `Remove-Item` +runs the real command, and the guard never fires. To let the permitted calls delete for real, make +the default mock call the real command as shown under "Running The Real Command From A Mock". diff --git a/.github/instructions/pester-supporting-docs/performance-test-template.md b/.github/instructions/pester-supporting-docs/performance-test-template.md index a7efc2c..d99c75b 100644 --- a/.github/instructions/pester-supporting-docs/performance-test-template.md +++ b/.github/instructions/pester-supporting-docs/performance-test-template.md @@ -1,402 +1,119 @@ # Performance Test Template -Targets **Pester 6.2+**. Uses the `Should-*` assertion syntax - see -[Assertion Guide](./assertion-guide.md). +A test file for a function that has a stated performance requirement. Write one only for such a +function (TST-43), and take the limits from the requirement; the figures below are placeholders. +The rules are in the [Pester rules](../powershell-pester.instructions.md). The file below passes on +Pester 6.2.0 under PowerShell 7.6 and Windows PowerShell 5.1. -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. +## The Code Under Test -## Standard Performance Test Structure +The template tests the module `ModuleName` from the [unit test template](./unit-test-template.md). +`Get-ThingSummary -Thing <object[]>` reads each thing once and emits one object for each state, with +the number of things in that state. -Use this template for performance benchmarking and regression detection: +## The Test File ```powershell #Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } -# Performance measurement is meaningless when other test files are competing for the -# CPU. This directive keeps the file on the serial path even when Run.Parallel is set. #pester:no-parallel BeforeAll { - # Import module under test. Each file is self-contained in Pester 6. - $ModulePath = Join-Path $PSScriptRoot '..\..\ModuleName.psd1' - Import-Module $ModulePath -Force - - # Performance test configuration - $PerformanceConfig = @{ - BaselineDataSize = 100 - ScaleTestDataSize = 1000 - MaxExecutionTime = [TimeSpan]::FromSeconds(30) - MaxMemoryUsageMB = 100 - WarmupIterations = 3 - TestIterations = 5 - } - - # Load performance baselines - $BaselinePath = Join-Path $PSScriptRoot "..\TestData\performance-baselines.psd1" - if (Test-Path $BaselinePath) { - $PerformanceBaselines = Import-PowerShellDataFile $BaselinePath - } else { - $PerformanceBaselines = @{} + $moduleRoot = Split-Path -Path $PSScriptRoot -Parent + if (-not (Get-Module -Name ModuleName)) { + Import-Module -Name (Join-Path -Path $moduleRoot -ChildPath 'ModuleName.psd1') } -} - -Describe "Performance Tests" -Tag "Performance", "Benchmark" { - Context "Execution Time Baselines" { - BeforeEach { - # Warm up the function - 1..$PerformanceConfig.WarmupIterations | ForEach-Object { - Function-Name -ParameterName 'WarmupValue' | Out-Null - } - - # Force garbage collection for consistent baseline - [System.GC]::Collect() - [System.GC]::WaitForPendingFinalizers() - } - - It "Should process a single item faster than the baseline" { - # Should-BeFasterThan takes the scriptblock and a duration string or TimeSpan, - # and reports the measured time in the failure message. - { Function-Name -ParameterName 'SingleItem' } | Should-BeFasterThan '1s' - } - - It "Should process single item within baseline across iterations" { - $baseline = if ($PerformanceBaselines.SingleItemBaseline) { - $PerformanceBaselines.SingleItemBaseline - } else { - [TimeSpan]::FromSeconds(1) - } - $measurements = @() - - # Run multiple iterations for accurate measurement - 1..$PerformanceConfig.TestIterations | ForEach-Object { - $executionTime = Measure-Command { - Function-Name -ParameterName 'SingleItem' - } - $measurements += $executionTime.TotalMilliseconds - } - - $averageMs = ($measurements | Measure-Object -Average).Average - $maxMs = ($measurements | Measure-Object -Maximum).Maximum - - # Compare like with like - milliseconds against milliseconds. Comparing a - # TimeSpan against a raw number silently coerces and gives nonsense results. - $averageMs | Should-BeLessThan $baseline.TotalMilliseconds - $maxMs | Should-BeLessThan ($baseline.TotalMilliseconds * 1.5) ` - -Because 'peak may exceed the average baseline by up to 50%' - } - - It "Should scale efficiently with data volume" { - $baselineItems = 1..$PerformanceConfig.BaselineDataSize - $scaledItems = 1..$PerformanceConfig.ScaleTestDataSize - - # Measure baseline performance - $baselineTime = Measure-Command { - Function-Name -ParameterName $baselineItems - } - - # Measure scaled performance - $scaledTime = Measure-Command { - Function-Name -ParameterName $scaledItems - } - - # Calculate scaling efficiency - $dataScaleFactor = $PerformanceConfig.ScaleTestDataSize / $PerformanceConfig.BaselineDataSize - $timeScaleFactor = $scaledTime.TotalMilliseconds / $baselineTime.TotalMilliseconds - - # Should scale sub-linearly due to optimizations - $scalingEfficiency = $timeScaleFactor / $dataScaleFactor - $scalingEfficiency | Should-BeLessThan 1.5 -Because 'processing should scale sub-linearly' - } - - It "Should complete large datasets within time limit" { - $largeDataset = 1..5000 - $result = $null - # Do not put assertions inside Measure-Command - the assertion cost lands in - # the measurement, and a failure there reports a confusing location. - $executionTime = Measure-Command { - $result = Function-Name -ParameterName $largeDataset - } - - $result | Should-BeCollection -Count 5000 - $executionTime.TotalMilliseconds | - Should-BeLessThan $PerformanceConfig.MaxExecutionTime.TotalMilliseconds - } - - It "Should maintain consistent performance across iterations" { - $iterations = 10 - $measurements = @() - - 1..$iterations | ForEach-Object { - $time = Measure-Command { - Function-Name -ParameterName (1..100) - } - $measurements += $time.TotalMilliseconds - } - - # Calculate coefficient of variation (CV) - $average = ($measurements | Measure-Object -Average).Average - $stdDev = [Math]::Sqrt((($measurements | ForEach-Object { ($_ - $average) * ($_ - $average) }) | Measure-Object -Sum).Sum / $iterations) - $cv = $stdDev / $average - - # CV should be less than 20% for consistent performance - $cv | Should-BeLessThan 0.20 -Because 'execution time should be stable across runs' - } + $largeInput = foreach ($index in 1..20000) { + $state = if ($index % 3 -eq 0) { 'failed' } elseif ($index % 2 -eq 0) { 'stopped' } else { 'ready' } + [PSCustomObject]@{ Name = "thing-$index"; State = $state } } + $smallInput = $largeInput | Select-Object -First 2000 - Context "Memory Usage" { - It "Should maintain reasonable memory footprint" { - $beforeMemory = [System.GC]::GetTotalMemory($true) - - Function-Name -ParameterName (1..$PerformanceConfig.ScaleTestDataSize) - - $afterMemory = [System.GC]::GetTotalMemory($false) # Don't force GC yet - $memoryUsedMB = ($afterMemory - $beforeMemory) / 1MB - - $memoryUsedMB | Should-BeLessThan $PerformanceConfig.MaxMemoryUsageMB - } - - It "Should release memory after completion" { - $beforeMemory = [System.GC]::GetTotalMemory($true) - - Function-Name -ParameterName (1..$PerformanceConfig.ScaleTestDataSize) - - # Force garbage collection - [System.GC]::Collect() - [System.GC]::WaitForPendingFinalizers() - [System.GC]::Collect() - - $afterMemory = [System.GC]::GetTotalMemory($true) - $memoryDifference = [Math]::Abs($afterMemory - $beforeMemory) / 1MB - - # Should release most memory (allow 10MB tolerance) - $memoryDifference | Should-BeLessThan 10 -Because 'the function should not retain allocations' - } - - It "Should not have memory leaks with repeated calls" { - $initialMemory = [System.GC]::GetTotalMemory($true) - $memoryMeasurements = @() - - # Execute function multiple times - 1..20 | ForEach-Object { - Function-Name -ParameterName (1..100) - - # Measure memory every 5 iterations - if ($_ % 5 -eq 0) { - [System.GC]::Collect() - $currentMemory = [System.GC]::GetTotalMemory($true) - $memoryMeasurements += ($currentMemory - $initialMemory) / 1MB - } - } - - # Memory usage should not continuously increase - $firstMeasurement = $memoryMeasurements[0] - $lastMeasurement = $memoryMeasurements[-1] - $memoryGrowth = $lastMeasurement - $firstMeasurement + # The first call pays for module loading and compilation, so it is made before any measurement. + $null = Get-ThingSummary -Thing $smallInput +} - # Allow maximum 5MB growth over 20 iterations - $memoryGrowth | Should-BeLessThan 5 -Because 'repeated calls must not leak' - } +Describe 'Get-ThingSummary performance' -Tag 'Performance' { + It 'Summarizes 2,000 things in less than one second' { + { Get-ThingSummary -Thing $smallInput } | Should-BeFasterThan '1s' } - Context "Throughput and Scalability" { - It "Should achieve minimum throughput requirements" { - $testData = 1..1000 - $requiredThroughput = 50 # items per second - $results = $null - - $executionTime = Measure-Command { - $results = Function-Name -ParameterName $testData - } - - $results | Should-BeCollection -Count 1000 - - $actualThroughput = 1000 / $executionTime.TotalSeconds - $actualThroughput | Should-BeGreaterThan $requiredThroughput + It 'Summarizes 20,000 things correctly in less than five seconds' { + $elapsed = Measure-Command { + $result = @(Get-ThingSummary -Thing $largeInput) } - It "Should handle concurrent execution efficiently" { - $concurrentJobs = 1..5 | ForEach-Object { - Start-Job -ScriptBlock { - param($ModulePath, $JobId) - - Import-Module $ModulePath -Force - - $startTime = Get-Date - $result = Function-Name -ParameterName (1..200) - $endTime = Get-Date - - return @{ - JobId = $JobId - ItemsProcessed = $result.Count - ExecutionTime = ($endTime - $startTime).TotalMilliseconds - Success = $result.Count -eq 200 - } - } -ArgumentList $ModulePath, $_ - } - - # Wait for all jobs to complete - $results = $concurrentJobs | Wait-Job | Receive-Job - $concurrentJobs | Remove-Job - - # Verify all jobs completed successfully - $results | Should-All { $_.Success } - $results | Should-All { $_.ItemsProcessed -eq 200 } - $results | Should-All { $_.ExecutionTime -lt 30000 } # 30 seconds max - - # Verify concurrent execution didn't significantly degrade performance - $averageConcurrentTime = ($results.ExecutionTime | Measure-Object -Average).Average - $serialTime = Measure-Command { Function-Name -ParameterName (1..200) } - - # Concurrent execution should not be more than 2x slower per job - $averageConcurrentTime | Should-BeLessThan ($serialTime.TotalMilliseconds * 2) - } + $result | Should-BeCollection -Count 3 + ($result | Measure-Object -Property Count -Sum).Sum | Should-Be 20000 + $elapsed.TotalMilliseconds | Should-BeLessThan 5000 } - Context "Resource Utilization" { - It "Should efficiently use CPU resources" { - $cpuCounter = Get-Counter "\Process(powershell*)\% Processor Time" -ErrorAction SilentlyContinue - - if ($cpuCounter) { - $beforeCpu = $cpuCounter.CounterSamples | Where-Object { $_.InstanceName -like "*$PID*" } | Select-Object -First 1 -ExpandProperty CookedValue - - Function-Name -ParameterName (1..1000) - - Start-Sleep -Seconds 1 # Allow CPU counter to update - $afterCpu = (Get-Counter "\Process(powershell*)\% Processor Time").CounterSamples | Where-Object { $_.InstanceName -like "*$PID*" } | Select-Object -First 1 -ExpandProperty CookedValue - - # CPU usage should be reasonable (less than 80% for single-threaded operation) - $cpuUsage = $afterCpu - $beforeCpu - $cpuUsage | Should-BeLessThan 80 - } else { - Set-ItResult -Skipped -Because "CPU performance counters not available" - } + It 'Takes less than 30 times as long for 10 times the input' { + $smallRuns = foreach ($run in 1..5) { + (Measure-Command { $null = Get-ThingSummary -Thing $smallInput }).TotalMilliseconds } - - It "Should not create excessive temporary files" { - $tempFilesBefore = @(Get-ChildItem -Path $env:TEMP -File | Where-Object { $_.LastWriteTime -gt (Get-Date).AddMinutes(-5) }) - - Function-Name -ParameterName (1..500) - - $tempFilesAfter = @(Get-ChildItem -Path $env:TEMP -File | Where-Object { $_.LastWriteTime -gt (Get-Date).AddMinutes(-5) }) - - $newTempFiles = $tempFilesAfter.Count - $tempFilesBefore.Count - - # Should not create more than 5 temporary files - $newTempFiles | Should-BeLessThanOrEqual 5 + $largeRuns = foreach ($run in 1..5) { + (Measure-Command { $null = Get-ThingSummary -Thing $largeInput }).TotalMilliseconds } - } -} + $smallBest = ($smallRuns | Measure-Object -Minimum).Minimum + $largeBest = ($largeRuns | Measure-Object -Minimum).Minimum -AfterAll { - # Save performance metrics for baseline comparison - $resultsPath = Join-Path $PSScriptRoot "..\Results\performance-results-$(Get-Date -Format 'yyyyMMdd-HHmmss').json" - - $performanceMetrics = @{ - TestDate = Get-Date - PowerShellVersion = $PSVersionTable.PSVersion - Platform = $PSVersionTable.Platform - # Add specific metrics from test execution + # A floor of one millisecond keeps timer resolution from deciding the ratio. + $ratio = $largeBest / [math]::Max($smallBest, 1) + $ratio | Should-BeLessThan 30 -Because 'the summary reads each thing once' } - - $performanceMetrics | ConvertTo-Json -Depth 10 | Out-File $resultsPath } ``` -## Pester 6 Notes for Performance Tests +## What The Template Shows -### Always opt out of parallel execution +### A Time Limit -Put `#pester:no-parallel` at the top of every performance test file. Timing measurements taken while -other test files compete for CPU are noise. Opted-out files run serially in the parent session while -other files run in parallel, so you keep the speedup elsewhere without corrupting the benchmarks. +`Should-BeFasterThan` measures the piped script block and puts the measured time in the failure +message. Use it for a plain limit. Pipe the script block, not its result: any input other than a +script block or a `[timespan]` is an error. -Belt and braces: also keep `Run.Parallel = $false` in `PesterConfiguration.Performance.psd1`. +Use `Measure-Command` when the test needs the number itself, for a ratio or for the best of several +runs, or when it must also assert the result of the measured call. -### Use `Should-BeFasterThan` for simple time limits +### Assertions Stay Outside The Measurement -```powershell -{ Function-Name -ParameterName 'x' } | Should-BeFasterThan '250ms' -{ Function-Name -ParameterName 'x' } | Should-BeSlowerThan '10ms' -``` - -It accepts a duration string (`'250ms'`, `'2s'`) or a `TimeSpan`, measures the scriptblock, and puts -the actual measured time in the failure message. Prefer it over `Measure-Command` plus a comparison -for single-shot limits. Keep `Measure-Command` where you need the measurement itself for ratios, -averages, or coefficient-of-variation math. +An assertion inside `Measure-Command` adds its own time to the figure. The second test assigns the +result inside the measured block, where the variable stays visible afterwards, and asserts after +the measurement. Asserting the result also proves that the fast call did the work. -Pipe the **scriptblock**, not its result. From 6.2 both assertions throw when handed anything other -than a `[scriptblock]` or a `[timespan]`; on 6.1 a string, number, or `$null` slipped through and -the test passed without measuring. A limit that starts failing on 6.2 with -`Expected a [scriptblock] to measure or a [timespan] to compare` was never a limit. +### Like Is Compared With Like -### Compare like with like - -The most common bug in hand-rolled performance assertions is comparing a `TimeSpan` against a raw -number: +`Should-BeLessThan` cannot compare a `[timespan]` with a number. It stops with `Could not compare`: ```powershell -# WRONG - TimeSpan vs. double; the comparison does not mean what it looks like -$elapsed | Should-BeLessThan ($baseline.TotalMilliseconds * 1.5) +# Non-compliant: a TimeSpan compared with a number +$elapsed | Should-BeLessThan 5000 -# RIGHT - both sides in milliseconds -$elapsed.TotalMilliseconds | Should-BeLessThan ($baseline.TotalMilliseconds * 1.5) +# Compliant: milliseconds compared with milliseconds +$elapsed.TotalMilliseconds | Should-BeLessThan 5000 -# ALSO RIGHT - both sides TimeSpan -$elapsed | Should-BeLessThan ([TimeSpan]::FromMilliseconds($baseline.TotalMilliseconds * 1.5)) +# Compliant: a TimeSpan compared with a TimeSpan +$elapsed | Should-BeLessThan ([timespan]::FromSeconds(5)) ``` -Pester 6's type-aware assertions make the mismatch visible in the failure message, but the fix is to -not write it in the first place. - -### Keep assertions out of `Measure-Command` - -An assertion inside the measured scriptblock adds its own cost to the measurement, and a failure -there reports a confusing location. Capture the result, measure, then assert. - -### Never enable coverage on a performance job - -Coverage instruments exactly the thing you are measuring, so the numbers stop meaning anything. - -Pester 6.0 refused to combine coverage with `Run.Parallel` at all, falling back to sequential with a -warning. 6.1 does collect coverage across parallel workers - but it forces breakpoint-based -collection to do it, which is heavier per file than the default profiler tracer. Either way, a -performance job should run sequentially with coverage off. - -## Performance Test Guidelines - -### Baseline Establishment - -- Warm up functions before measurement -- Run multiple iterations for accuracy -- Force garbage collection for consistency -- Establish realistic performance targets - -### Memory Testing - -- Measure memory usage during execution -- Verify memory release after completion -- Test for memory leaks with repeated calls -- Monitor garbage collection patterns - -### Scalability Testing +### Measurements Are Made Stable -- Test with increasing data sizes -- Measure throughput and response time -- Validate concurrent execution performance -- Test resource utilization limits +- The input is built once in `BeforeAll`, and one call is made before any measurement. +- A ratio uses the best of several runs. A single run can include a garbage collection or another + process taking the processor. +- Limits leave room for a slower machine. A limit close to the usual time makes the test fail at + random, and a test that fails at random gets ignored. -### Regression Detection +### The File Does Not Run In Parallel -- Compare against historical baselines -- Track performance trends over time -- Alert on significant performance degradation -- Maintain performance metrics database +Timings taken while other test files use the processor are noise. The comment `#pester:no-parallel` +keeps the file in the main session, one file at a time, when a run sets `Run.Parallel`. That option +is experimental and off by default. -### Resource Monitoring +### Coverage Is Off -- Monitor CPU utilization -- Track temporary file creation -- Measure network usage (if applicable) -- Validate resource cleanup +Do not enable code coverage in a run that measures time. Coverage instruments the code that is being +measured. Tag the `Describe` block `Performance` (TST-04), and run these tests in their own job with +`Filter.Tag`, without `CodeCoverage.Enabled`. diff --git a/.github/instructions/pester-supporting-docs/pester-configuration.md b/.github/instructions/pester-supporting-docs/pester-configuration.md index 96b7cd8..775eaa2 100644 --- a/.github/instructions/pester-supporting-docs/pester-configuration.md +++ b/.github/instructions/pester-supporting-docs/pester-configuration.md @@ -1,832 +1,389 @@ # Pester Configuration Guide -Targets **Pester 6.2+**. All settings below were verified against the `PesterConfiguration` object. +This guide lists the options of the Pester configuration object and explains the ones that are +easy to get wrong. It supports the testing rules in +[powershell-pester.instructions.md](../powershell-pester.instructions.md). The option names, +defaults, and behaviour were read from the configuration object of Pester 6.2.0 and checked by +running it. `Get-Help about_PesterConfiguration` shows the same list on the installed version. -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. - -## Standard Pester Configuration - -Use this standardized configuration for consistent test execution: +## Creating a Configuration ```powershell -# PesterConfiguration.psd1 -@{ - Run = @{ - Path = @('./Tests/Unit', './Tests/Integration') - ExcludePath = @() - PassThru = $true - Throw = $true - SkipRun = $false - - # Pester 6: empty -ForEach fails discovery. Keep on; opt out per test with - # -AllowNullOrEmptyForEach where an empty set is legitimately expected. - FailOnNullOrEmptyForEach = $true - - # None | Run | Container | Block - SkipRemainingOnFailure = 'None' - - # EXPERIMENTAL. Off by default. See "Parallel Execution" below. - Parallel = $false - ParallelThrottleLimit = 0 - - # EXPERIMENTAL and off by default, but turn it on in CI. See "Shuffled Test Order" below. - Shuffle = $false - ShuffleSeed = 0 # 0 picks a new seed per run and prints it - } - - Output = @{ - Verbosity = 'Detailed' - StackTraceVerbosity = 'Filtered' # None | FirstLine | Filtered | Full - CIFormat = 'Auto' # Auto | AzureDevops | GithubActions - CILogLevel = 'Error' - CIDebugOutput = 'Auto' # Auto | None - surface verbose/debug on CI debug runs - RenderMode = 'Auto' # Auto | Ansi | ConsoleColor | Plaintext - ShowTags = $false # append [Tags: ...] to each output line - } - - Mock = @{ - # EXPERIMENTAL. Off by default. See "Global Mocks" below. - Global = $false - } - - CodeCoverage = @{ - Enabled = $true - Path = @('./Public/*.ps1', './Private/*.ps1', './Classes/*.ps1') - OutputFormat = 'JaCoCo' # JaCoCo | Cobertura - OutputPath = './Tests/Results/Coverage.xml' - OutputEncoding = 'UTF8' - CoveragePercentTarget = 80 # NOT "Threshold" - that setting does not exist - UseBreakpoints = $false # $false = profiler-based (v6 default, much faster) - SingleHitBreakpoints = $true - ExcludeTests = $true # keep test files out of the coverage numbers - RecursePaths = $true - ReportRoot = '' # defaults to Run.RepoRoot - } - - TestResult = @{ - Enabled = $true - OutputFormat = 'NUnitXml' # NUnitXml | NUnit2.5 | NUnit3 | JUnitXml - OutputPath = './Tests/Results/TestResults.xml' - OutputEncoding = 'UTF8' - TestSuiteName = 'PowerShell Tests' - } +$configuration = New-PesterConfiguration +$configuration.Run.Path = Join-Path -Path $PSScriptRoot -ChildPath 'Tests' +$configuration.Run.PassThru = $true +$configuration.Output.Verbosity = 'Detailed' - Should = @{ - ErrorAction = 'Stop' # 'Continue' enables soft assertions - DisableV5 = $false # $true makes `Should -Be` throw - } - - Debug = @{ - ShowFullErrors = $false - WriteDebugMessages = $false - WriteDebugMessagesFrom = @() - ShowNavigationMarkers = $false - ShowStartMarkers = $false # v6: marks when each test starts - ReturnRawResultObject = $false - } - - Filter = @{ - Tag = @() - ExcludeTag = @() - Line = @() - ExcludeLine = @() - FullName = @() - } -} +$result = Invoke-Pester -Configuration $configuration ``` -### Settings That Do Not Exist - -These appear in older guidance and in a lot of blog posts. They are not real. From 6.2 -`Invoke-Pester` warns `Ignoring configuration keys '...', there are no such options` when a hashtable -carries one; before 6.2 they were silently ignored: - -| Not a setting | Use instead | -| --- | --- | -| `CodeCoverage.Threshold` | `CodeCoverage.CoveragePercentTarget` | -| `CodeCoverage.PerFileThreshold` | No equivalent - enforce per-file in your own gate | -| `CodeCoverage.ExcludePath` | `Run.ExcludePath`, or narrow `CodeCoverage.Path` | -| `TestResult.OutputFormat = 'VSTest'` | `NUnitXml`, `NUnit2.5`, `NUnit3`, or `JUnitXml` | -| `CodeCoverage.OutputFormat = 'CoverageGutters'` | `JaCoCo` - removed in v6, see below | - -`CoveragePercentTarget` sets the target Pester reports against. It does **not** fail the run on its -own - enforce the gate yourself: +Each option is an object with the properties `Value`, `Default`, `IsModified`, and `Description`. +Assign to the option itself, and read the setting from `.Value`: ```powershell -$result = Invoke-Pester -Configuration $config -$covered = $result.CodeCoverage.CoveragePercent -if ($covered -lt $config.CodeCoverage.CoveragePercentTarget.Value) { - throw "Code coverage $([math]::Round($covered, 2))% is below the $($config.CodeCoverage.CoveragePercentTarget.Value)% target" -} +$configuration.CodeCoverage.CoveragePercentTarget = 80 +$target = $configuration.CodeCoverage.CoveragePercentTarget.Value ``` -### Auto-Enable Behavior - -In Pester 6, `TestResult` and `CodeCoverage` **auto-enable** when you set any of their non-default -options. You can no longer silently configure a report that never gets written. Setting -`CodeCoverage.Path` is enough to turn coverage on. - -## Environment-Specific Configurations - -### Development Configuration +`Invoke-Pester` also has a short form for simple runs. Its parameters are `-Path`, `-ExcludePath`, +`-TagFilter`, `-ExcludeTagFilter`, `-FullNameFilter`, `-Output`, `-PassThru`, `-Container`, and +`-CI`. Use a configuration object for anything else. The Pester 4 parameters such as `-Script` and +`-EnableExit` do not exist in Pester 6. -```powershell -# PesterConfiguration.Development.psd1 -@{ - Run = @{ - Path = @('./Tests/Unit') - PassThru = $true - } +### Loading Settings From a File - Output = @{ - Verbosity = 'Detailed' - } - - CodeCoverage = @{ - Enabled = $true - CoveragePercentTarget = 70 # Lower target for development - } -} -``` - -### CI/CD Configuration +`New-PesterConfiguration -Hashtable` accepts a hashtable that contains only the options to change, +so settings can be kept in a `.psd1` file: ```powershell -# PesterConfiguration.CI.psd1 +# build/PesterConfiguration.psd1 @{ Run = @{ - Path = @('./Tests/Unit', './Tests/Integration', './Tests/Security') PassThru = $true - Throw = $true - Exit = $true - } - - Output = @{ - Verbosity = 'Normal' - CIFormat = 'GithubActions' # or 'AzureDevops' - RenderMode = 'Ansi' } CodeCoverage = @{ - Enabled = $true + Enabled = $true CoveragePercentTarget = 80 - OutputFormat = 'JaCoCo' - OutputPath = './Tests/Results/Coverage.xml' } TestResult = @{ - Enabled = $true + Enabled = $true OutputFormat = 'NUnitXml' - OutputPath = './Tests/Results/TestResults.xml' } } ``` -### Performance Testing Configuration +Paths in a configuration are relative to the current location, which a build script does not +control. Keep paths out of the file and set them in the script from `$PSScriptRoot`: ```powershell -# PesterConfiguration.Performance.psd1 -@{ - Run = @{ - Path = @('./Tests/Performance') - PassThru = $true - - # Performance tests must not share the box with other work - Parallel = $false - } - - Output = @{ - Verbosity = 'Minimal' - } - - Filter = @{ - Tag = @('Performance', 'Benchmark') - } - - TestResult = @{ - Enabled = $true - OutputPath = './Tests/Results/PerformanceResults.xml' - } -} -``` - -## Parallel Execution (Experimental) - -Pester 6 can run test **files** concurrently, one file per runspace. From 6.2 the workers run on a -runspace pool, which Windows PowerShell 5.1 and PowerShell 7 both have; 6.0 and 6.1 used -`ForEach-Object -Parallel` and so ran sequentially on 5.1. +$repositoryRoot = Split-Path -Path $PSScriptRoot -Parent +$settingsPath = Join-Path -Path $PSScriptRoot -ChildPath 'PesterConfiguration.psd1' +$settings = Import-PowerShellDataFile -LiteralPath $settingsPath -```powershell -$config = New-PesterConfiguration -$config.Run.Path = './Tests/Unit' -$config.Run.Parallel = $true -$config.Run.ParallelThrottleLimit = 4 # 0 (default) uses all processors -Invoke-Pester -Configuration $config -``` - -**Requirements**: file-based containers (`Run.Path`, or `New-PesterContainer -Path` including -parametrized files built with `-Data`). - -**Falls back to a sequential run with a warning** when: - -- Using in-memory `ScriptBlock` containers -- `Run.SkipRemainingOnFailure = 'Run'` -- Running on Windows PowerShell 5.1 with Pester 6.0 or 6.1 - -If every file opts out with `#pester:no-parallel` the run is simply sequential, with no warning - -there is nothing left to parallelize. - -**A lost file is an error** from 6.2. A worker that died before returning its result used to vanish -from the run - not failed, not skipped, simply absent, and the run looked green with one file fewer. -The run now compares results to the files it sent and throws naming the missing ones. A worker that -throws is reported with `Write-Error` and the remaining files still report, even under -`$ErrorActionPreference = 'Stop'`, which used to abort the loop at the first failing file. - -**Code coverage works under parallel** as of 6.1: each worker measures the same locations and the -parent merges the per-location hits into one report. The cost is that coverage in a parallel run is -forced onto **breakpoint mode**, because the profiler-based tracer keeps its state in a -process-global static and is not concurrency-safe. `CodeCoverage.UseBreakpoints = $false` is ignored -for the parallel path. Breakpoint coverage is substantially slower per file, so parallel plus -coverage is not automatically faster than sequential plus the profiler - measure before adopting it. - -**Opting a file out** with a comment directive parsed like `#requires` (matched only inside real -comment tokens, never inside strings): - -```powershell -#pester:no-parallel -Describe 'integration that must not share the box' { -} +$configuration = New-PesterConfiguration -Hashtable $settings +$configuration.Run.Path = Join-Path -Path $repositoryRoot -ChildPath 'Tests' +$configuration.Run.RepoRoot = $repositoryRoot +$configuration.CodeCoverage.Path = @( + Join-Path -Path $repositoryRoot -ChildPath 'Public' + Join-Path -Path $repositoryRoot -ChildPath 'Private' +) ``` -Opted-out files run in the parent session on the normal serial path, with shared session state and -live output, while other files run in parallel. - -Console output, the `TestResult` report, and IDE adapters behave the same in both modes - only the -concurrency differs. The run's total `Duration` becomes the orchestrator's elapsed time rather than -the sum of the files, and per-phase run totals (user, framework, discovery) are blank - that -breakdown is still reported on each container. - -Treat this as opt-in and experimental. The directive name, config shape, and behavior may still -change. +To use different settings for one kind of run, load the same file and then assign the options that +differ. The coverage figure that CI enforces is 80 percent (TST-40); do not keep a second, lower +figure for other runs. -### Shared Per-File Setup +### Checking What Was Loaded -Pester dot-sources every **`Pester.BeforeContainer.ps1`** it finds between `Run.RepoRoot` and the -test file's own folder before that file is discovered and run, outermost first, in both serial and -parallel runs. This matters most under parallel, where each worker starts from a clean runspace. +Pester 6.2.0 checks a hashtable in three ways, at three different times. -The file follows the same rule as a test file. Top-level code runs during **discovery** only - use it -for what `-ForEach` data or `BeforeDiscovery` needs. Anything the tests need at **run** time goes in -a `BeforeAll`: +A value of the wrong type throws when the configuration is created. This happens most often with a +Boolean written as a string in a `.psd1` or JSON file: ```powershell -# Pester.BeforeContainer.ps1, at the repository root -BeforeAll { - Import-Module "$PSScriptRoot/Tests/TestHelpers/Assertions.psd1" -Force - . "$PSScriptRoot/Tests/TestHelpers/Bootstrap.ps1" -} +New-PesterConfiguration -Hashtable @{ Run = @{ Parallel = 'yes' } } +# Error: Run.Parallel expects a bool, but got the string 'yes'. ``` -Before 6.2 the file had no `BeforeAll` and everything sat at top level. That shape silently stops -working on 6.2: a function or variable dot-sourced at top level is gone by the time a test runs -(verified - `CommandNotFoundException` for the helper, `$null` for the variable), and only an -`Import-Module` happens to survive because module state is session-wide. Wrap it. - -Because it is a real file it always exposes a stable `$PSScriptRoot` and `$PSCommandPath`, so -relative paths have something reliable to anchor against. The files run before **every** container, -so what they do must be safe to run more than once. - -> **Removed in 6.1**: the `Run.BeforeContainer` configuration option. 6.0 shipped both the option -> and the convention file; the option had no file to anchor relative paths against, so it was -> dropped and the convention file kept. Assigning `$config.Run.BeforeContainer` now throws -> `The property 'BeforeContainer' cannot be found on this object`. Move the scriptblock's body into -> a `BeforeAll` in `Pester.BeforeContainer.ps1` at the repository root. +An `int` is accepted for a decimal option, and a key whose value is `$null` is treated as not set. -### Folder-Scoped Setup (6.2+) - -One file at the root was all 6.1 used. From 6.2 the chain follows the folder structure, so unit and -integration tests can each carry their own setup without repeating it in every test file: +A key that matches no option does not throw. `Invoke-Pester` writes one warning for all of them: ```text -reporoot/Pester.BeforeContainer.ps1 <- applies to everything -reporoot/Tests/Pester.BeforeContainer.ps1 <- Tests/ and below -reporoot/Tests/Unit/Pester.BeforeContainer.ps1 <- Tests/Unit only -reporoot/Tests/Integration/Pester.BeforeContainer.ps1 <- Tests/Integration only +WARNING: Ignoring configuration keys 'Nonsense', 'Run.Paralel', there are no such options. Check +the spelling, 'Get-Help about_PesterConfiguration' lists all the options. ``` -```powershell -# reporoot/Tests/Unit/Pester.BeforeContainer.ps1 -BeforeAll { $script:Db = 'in-memory' } - -# reporoot/Tests/Integration/Pester.BeforeContainer.ps1 -BeforeAll { $script:Db = 'real-sql' } -``` - -The files are dot-sourced into the container's own scope, not the run session state, so a file in -`Tests/Integration` never sees what `Tests/Unit` set up, whichever runs first. A folder opts out of -everything above it with a directive, the same meaning `root = true` has in an `.editorconfig`: +A warning does not fail a build. Read the same list from the object and throw: ```powershell -# reporoot/Tests/Docs/Pester.BeforeContainer.ps1 -#pester:no-inherit -BeforeAll { Import-Module "$PSScriptRoot/../../Source/ModuleName.psd1" } -``` +$configuration = New-PesterConfiguration -Hashtable $settings -Each container records which setup files applied to it, outermost first, as `BeforeContainerFile` -on the result object - the folder tree cannot show a `#pester:no-inherit`, but this can: - -```powershell -$result = Invoke-Pester -Path ./Tests -PassThru -foreach ($container in $result.Containers) { - $container.Item.Name - $container.BeforeContainerFile | ForEach-Object { " $_" } +$unknownKeys = @($configuration.GetUnknownKeys()) +if ($unknownKeys.Count -gt 0) { + throw "Configuration keys that match no option: $($unknownKeys -join ', ')" } ``` -`Run.SkipRun` applies the chain too, so a discovery-only pass sees the same `-ForEach` data a real -run does. - -### Run.RepoRoot Decides Where the Chain Starts - -The chain starts at `Run.RepoRoot`, and nothing above it is looked at. Be explicit in any script or -CI job: - -```powershell -$config.Run.RepoRoot = $PSScriptRoot -``` +A value that has the right type but is not one of the allowed words is reported when the run +starts. `Invoke-Pester` writes an error such as +`TestResult.OutputFormat must be 'NUnitXml', 'NUnit2.5', 'NUnit3' or 'JUnitXml', but it was 'VSTest'` +and returns no result. Test the result for `$null`, as the CI gate does. + +Before 6.2 a misspelled key and a value of the wrong type were both ignored without a message. + +## Option Reference + +### Run + +| Option | Default | Meaning | +| --- | --- | --- | +| `Run.Path` | `.` | Folders or files to search for tests. Wildcards are allowed. | +| `Run.ExcludePath` | empty | Folders or files to leave out. Each entry is compared with full paths; see [Pester Test Structure Guide](./test-structure-guide.md#hidden-folders-and-excluded-paths). | +| `Run.ScriptBlock` | empty | Script blocks that contain tests. | +| `Run.Container` | empty | Containers made by `New-PesterContainer`, used to pass data to a test file. | +| `Run.TestExtension` | `.Tests.ps1` | Suffix that identifies a test file. | +| `Run.PassThru` | `$false` | Return the result object. | +| `Run.SkipRun` | `$false` | Discover the tests but do not run them. | +| `Run.Throw` | `$false` | Throw when the run fails. | +| `Run.Exit` | `$false` | End the process with a non-zero exit code when the run fails. | +| `Run.SkipRemainingOnFailure` | `None` | What to skip after the first failure: `None`, `Block`, `Container`, or `Run`. | +| `Run.FailOnNullOrEmptyForEach` | `$true` | Fail discovery when `-ForEach` receives `$null` or an empty array. | +| `Run.RepoRoot` | found when the run starts | Experimental. Where the search for setup files starts; see [Run.RepoRoot](#runreporoot). | +| `Run.Parallel` | `$false` | Experimental. Run test files at the same time. | +| `Run.ParallelThrottleLimit` | `0` | Experimental. Number of files to run at once; `0` uses every processor. | +| `Run.Shuffle` | `$false` | Experimental. Run files, blocks, and tests in a random order. | +| `Run.ShuffleSeed` | `0` | Experimental. Seed for the order; `0` picks a new seed for each run. | + +`Run.Throw` and `Run.Exit` stop the script inside `Invoke-Pester` when the run fails, so the +statements after it, such as a coverage check, do not run. The CI gate in the testing rules leaves +both off, sets `Run.PassThru`, and inspects the result itself. Neither option reports a run that +found no tests: measured on 6.2.0, a file without tests gives the result `Passed` with `Run.Throw` +set. + +`Invoke-Pester` always sets `$LASTEXITCODE`: to the number of failed tests, blocks, and files, or to +`-1` when Pester itself fails, for example because no test file was found. + +### Filter + +| Option | Default | Meaning | +| --- | --- | --- | +| `Filter.Tag` | empty | Run tests that have any of these tags. `None` selects tests without a tag. | +| `Filter.ExcludeTag` | empty | Leave out tests that have any of these tags. `None` leaves out tests without a tag. | +| `Filter.FullName` | empty | Run tests whose full name matches a wildcard pattern, for example `*Get-Thing*`. | +| `Filter.Line` | empty | Run the test or block that starts at a line, written as `<full path>:<line>`. | +| `Filter.ExcludeLine` | empty | Leave out the test or block that starts at a line. It takes precedence over `Filter.Line`. | + +Several tags in `Filter.Tag` select a test that has any one of them, not a test that has all of +them. The reserved value `None` is explained in +[Pester Test Structure Guide](./test-structure-guide.md#the-reserved-tag-none). + +### CodeCoverage + +| Option | Default | Meaning | +| --- | --- | --- | +| `CodeCoverage.Enabled` | `$false` | Measure coverage. | +| `CodeCoverage.Path` | empty | Folders or files to measure. When empty, `Run.Path` is used. | +| `CodeCoverage.ExcludeTests` | `$true` | Leave test files out of the figures. | +| `CodeCoverage.RecursePaths` | `$true` | Search the folders in `CodeCoverage.Path` recursively. | +| `CodeCoverage.CoveragePercentTarget` | `75` | The figure that Pester reports against. It does not fail the run. | +| `CodeCoverage.OutputFormat` | `JaCoCo` | Report format: `JaCoCo` or `Cobertura`. | +| `CodeCoverage.OutputPath` | `coverage.xml` | Report file. | +| `CodeCoverage.OutputEncoding` | `UTF8` | Encoding of the report file. | +| `CodeCoverage.ReportRoot` | not set | Folder that paths in the report are relative to. When not set, `Run.RepoRoot` is used. | +| `CodeCoverage.UseBreakpoints` | `$false` | `$false` measures with the profiler-based tracer; `$true` sets a breakpoint on every command. | +| `CodeCoverage.SingleHitBreakpoints` | `$true` | Remove a breakpoint after its first hit. Applies only to breakpoint mode. | + +### TestResult + +| Option | Default | Meaning | +| --- | --- | --- | +| `TestResult.Enabled` | `$false` | Write a test result report. | +| `TestResult.OutputFormat` | `NUnitXml` | Report format: `NUnitXml`, `NUnit2.5`, `NUnit3`, or `JUnitXml`. | +| `TestResult.OutputPath` | `testResults.xml` | Report file. | +| `TestResult.OutputEncoding` | `UTF8` | Encoding of the report file. | +| `TestResult.TestSuiteName` | `Pester` | Name of the root test suite in the report. | + +### Output + +| Option | Default | Meaning | +| --- | --- | --- | +| `Output.Verbosity` | `Normal` | `None`, `Normal`, `Detailed`, or `Diagnostic`. | +| `Output.StackTraceVerbosity` | `Filtered` | `None`, `FirstLine`, `Filtered`, or `Full`. `Filtered` hides Pester's own frames. | +| `Output.CIFormat` | `Auto` | Format of failures in a build log: `None`, `Auto`, `AzureDevops`, or `GithubActions`. | +| `Output.CILogLevel` | `Error` | Level that failures are logged at in a build log: `Error` or `Warning`. | +| `Output.CIDebugOutput` | `Auto` | `Auto` shows verbose and debug output when the CI system runs in debug mode; `None` does not. | +| `Output.RenderMode` | `Auto` | `Auto`, `Ansi`, `ConsoleColor`, or `Plaintext`. | +| `Output.ShowTags` | `$false` | Add the tags of each block and test to its output line. | + +### Should, Mock, TestDrive, and TestRegistry + +| Option | Default | Meaning | +| --- | --- | --- | +| `Should.ErrorAction` | `Stop` | `Stop` ends the test at the first failed assertion. `Continue` runs the rest of the test and reports every failed assertion. | +| `Should.DisableV5` | `$false` | `$true` makes the `Should -Be` style fail. | +| `Mock.Global` | `$false` | Experimental. Every mock applies to calls from any module or script. | +| `TestDrive.Enabled` | `$true` | Provide `$TestDrive`. | +| `TestRegistry.Enabled` | `$true` | Provide the `TestRegistry:` drive on Windows. | + +Do not set `Should.DisableV5` while any test file still uses the `Should -Be` style. With the option +on, such an assertion fails with `Pester Should -Be syntax is disabled`. + +### Debug + +| Option | Default | Meaning | +| --- | --- | --- | +| `Debug.WriteDebugMessages` | `$false` | Write Pester's debug messages. | +| `Debug.WriteDebugMessagesFrom` | `Discovery`, `Skip`, `Mock`, `CodeCoverage` | Sources of the debug messages. Wildcards are allowed. | +| `Debug.ShowNavigationMarkers` | `$false` | Write the path after every block and test. | +| `Debug.ShowStartMarkers` | `$false` | Write a line when each test starts. | +| `Debug.ShowFullErrors` | `$false` | Deprecated. Use `Output.StackTraceVerbosity = 'Full'`. | +| `Debug.ReturnRawResultObject` | `$false` | For the development of Pester only. | + +## Options and Values That Do Not Exist + +These names appear in older guidance. On Pester 6.2.0 a key from the first table is reported as an +unknown key, and a value from the second table is rejected when the run starts. + +| Not an option | Use instead | +| --- | --- | +| `CodeCoverage.Threshold` | `CodeCoverage.CoveragePercentTarget`, with the check in the gate script | +| `CodeCoverage.PerFileThreshold` | No option. Compute it in the gate script from `CodeCoverage.CommandsMissed`. | +| `CodeCoverage.ExcludePath` | Narrow `CodeCoverage.Path` | +| `Run.BeforeContainer` | A `Pester.BeforeContainer.ps1` file; see [Pester Test Structure Guide](./test-structure-guide.md#shared-setup-files) | -`Run.RepoRoot` defaults to the nearest ancestor directory containing `.git`, falling back to the -starting directory when no `.git` is found. Where that search starts changed in 6.2: +| Not a value | Use instead | +| --- | --- | +| `TestResult.OutputFormat = 'VSTest'` | `NUnitXml`, `NUnit2.5`, `NUnit3`, or `JUnitXml` | +| `CodeCoverage.OutputFormat = 'CoverageGutters'` | `JaCoCo` | +| `Output.Verbosity = 'Minimal'` | `Normal`. Pester accepts `Minimal` and changes it to `Normal`. | -- `New-PesterConfiguration` still resolves the default from - `[System.IO.Directory]::GetCurrentDirectory()`, the .NET process working directory, which - `Set-Location` does not update. That is the value you see on the object. -- `Invoke-Pester` then re-resolves it from the session's current location (`$PWD`) - **only when - you did not set it**. On 6.1 the run used the process directory, so a session that started - elsewhere and then changed into the repository found no setup file, with nothing to say why. +## Reports Turn On by Themselves -```powershell -Set-Location $repo -(New-PesterConfiguration).Run.RepoRoot.Value # still the directory the process started in -$result = Invoke-Pester -Configuration $config # 6.2 resolves $repo here; 6.1 used the process directory -$result.Configuration.Run.RepoRoot.Value # what the run actually used -``` +Setting any option of `CodeCoverage` or `TestResult` to a value other than its default turns that +section on for the run, even when `Enabled` still reads `$false` on the object. Measured on 6.2.0: +setting only `CodeCoverage.Path` wrote `coverage.xml`, and setting only `TestResult.OutputFormat` +wrote `testResults.xml`. -It is never derived from `Run.Path`, so pointing Pester at a test directory in another repository -does not move it. When the two diverge the bootstrap silently does not run, and every test that -depended on it fails with `CommandNotFoundException` rather than anything naming the real cause. +Set `Enabled` explicitly anyway. It states the intent, and it is what a reader looks for. -This does **not** replace per-file setup. Each file must still be able to be discovered on its own; -see [Pester 6 Migration Guide](./v6-migration.md). +## Run.RepoRoot -## Shuffled Test Order (Experimental) +`Run.RepoRoot` is the folder where Pester starts to look for `Pester.BeforeContainer.ps1` files, and +the default for `CodeCoverage.ReportRoot`. Pester marks the option as experimental. The setup files +themselves are described in +[Pester Test Structure Guide](./test-structure-guide.md#shared-setup-files). -New in 6.1. `Run.Shuffle` reorders the test files, and the blocks and tests inside them, so a suite -that quietly depends on declaration order fails instead of passing by luck. +When the option is not set, `Invoke-Pester` finds the root when the run starts: it searches upwards +from the current location (`$PWD`) for a folder that contains `.git`, and uses the current location +when it finds none. It never derives the root from `Run.Path`. Measured on 6.2.0 with a setup file +at the repository root: -```powershell -$config = New-PesterConfiguration -$config.Run.Path = './Tests/Unit' -$config.Run.Shuffle = $true -Invoke-Pester -Configuration $config -``` +| Current location when the run starts | Root that the run used | Setup file applied | +| --- | --- | --- | +| The repository root, or a folder inside it | The repository root | Yes | +| An unrelated folder | That folder | No | +| A folder inside a checkout that has no `.git` folder | That folder | No, unless the setup file is in that folder or below | -Items are reordered only **within their own level** - a test never leaves its `Context`, and a -`Context` never leaves its `Describe`. The tree keeps its shape; only sibling order changes. +Nothing is written when a setup file is not found. The tests then fail with +`CommandNotFoundException` or read `$null`, which does not point at the cause. -The run picks a seed, prints it at the start, and records it on the result object: +Two details make this harder to see: -```text -Shuffling execution order using seed 852659930. Set 'Run.ShuffleSeed = 852659930' to repeat this order. -``` +- `New-PesterConfiguration` fills in a value before the run, from the working directory of the + process, which `Set-Location` does not change. The object can therefore show a different folder + from the one the run uses. The folder that was used is in + `$result.Configuration.Run.RepoRoot.Value`. +- Pester 6.1 used the working directory of the process for the run as well. -```powershell -$config.Run.ShuffleSeed = 852659930 # replay the exact order that failed -``` +Set the option in every script and CI job, from a path that does not depend on the current location: ```powershell -# after a PassThru run, the seed that was actually used -$result.Configuration.Run.ShuffleSeed.Value +$configuration.Run.RepoRoot = Split-Path -Path $PSScriptRoot -Parent ``` -`ShuffleSeed` defaults to `0`, which means "pick a new one each run". Capture the printed seed from -a failing CI log before re-running, or the order is gone. +## Code Coverage -A file whose blocks genuinely must run in sequence opts out with a comment directive, parsed like -`#requires` and like `#pester:no-parallel`: +### What Is Measured -```powershell -#pester:no-shuffle -Describe 'ordered migration steps' -Tag 'Integration' { -} -``` - -Opting out is an admission of order dependence, so treat a `#pester:no-shuffle` file the same way as -a `#pester:no-parallel` one - fine for a genuinely sequential integration script, a smell in a unit -test file. +Pester counts commands, not lines. `CodeCoverage.CoveragePercent` on the result is +`CommandsExecutedCount` divided by `CommandsAnalyzedCount`, as a percentage. The commands that did +not run are in `CodeCoverage.CommandsMissed`, each with its file and line. -The option is experimental and may change. Enabling it changes only ordering, never which tests run -or how they are filtered. +`CodeCoverage.Path` takes folders or files. With `CodeCoverage.ExcludeTests` at its default, files +that match `Run.TestExtension` are left out of the figures. -### Run It in CI +### The Target Is Not a Gate -Turn shuffling on in the CI unit-test job, with a fresh seed each run and the seed named in the -failure message. The first shuffled run of one 1,300-test suite failed three tests under seed 1 that -file order had always hidden: each wrote into a folder an earlier test in the same file had created. -Two other seeds passed. The same suite later moved to importing the module once per run instead of -in every file, which makes state visible across files; the shuffled run is what keeps that trade -honest, because a test that passes only after a fresh import fails there with a seed to replay. +`CodeCoverage.CoveragePercentTarget` changes what Pester prints and writes to the report. Measured +on 6.2.0, a run with 60 percent coverage and a target of 99 has the result `Passed`. The script +compares the figure itself (TST-40): ```powershell -$config = New-PesterConfiguration -$config.Run.Path = './Tests/Unit' -$config.Run.PassThru = $true -$config.Run.Shuffle = $true # ShuffleSeed stays 0: a new seed each run, printed at the start +$result = Invoke-Pester -Configuration $configuration -$result = Invoke-Pester -Configuration $config - -if ($result.FailedCount -gt 0 -or $result.FailedContainersCount -gt 0) { - $seed = $result.Configuration.Run.ShuffleSeed.Value - throw "Tests failed: $($result.FailedCount) test(s), $($result.FailedContainersCount) container(s). " + - "Replay this order with Run.ShuffleSeed = $seed" +$coverage = [math]::Round($result.CodeCoverage.CoveragePercent, 2) +if ($coverage -lt 80) { + throw "Code coverage is $coverage percent. The minimum is 80." } ``` -Document the replay command in the tests README, so whoever reads the failing log knows what to do -with the number. - -## Global Mocks (Experimental) - -New in 6.1. Normally a mock applies to calls from the scope that defined it, or from the single -module named by `-ModuleName`. `Mock.Global` makes every mock apply to calls of that command from -**any module or script in the runspace**: - -```powershell -$config = New-PesterConfiguration -$config.Mock.Global = $true -``` +### Profiler and Breakpoints -Mocks are written exactly as before - see -[Mocking Patterns Guide](./mocking-patterns.md#global-mocks-experimental) for what changes in -practice. With the option on, `-ModuleName` becomes a hint used to resolve the command rather than a -scope, so existing mocks keep working. Mocks are still removed when the block that defined them -ends, and are tied to the run that created them, so they cannot leak into a nested Pester-in-Pester -run. +By default Pester 6 measures coverage with a profiler-based tracer. Pester 5 set a breakpoint on +every command by default. `CodeCoverage.UseBreakpoints = $true` selects the breakpoint method. -The option is experimental and may change; the Pester team has stated an intent to make it the -default in v7. +A parallel run always measures with breakpoints, whatever the option says; see +[Test Execution Guide](./test-execution.md#coverage-in-a-parallel-run). -## Dynamic Configuration Loading +### Report Format and Paths -### Configuration Loader Function +`JaCoCo` is the default format and `Cobertura` is the alternative. The `CoverageGutters` format of +Pester 5 was removed. -```powershell -function Get-PesterConfiguration { - [CmdletBinding()] - param( - [ValidateSet('Development', 'CI', 'Performance', 'Security', 'Integration')] - [string]$Environment = 'Development', - [string]$ConfigPath = './Tests' - ) - - # Load base configuration - $baseConfigPath = Join-Path $ConfigPath "PesterConfiguration.psd1" - $baseConfig = Import-PowerShellDataFile $baseConfigPath - - # Load environment-specific overrides - $envConfigPath = Join-Path $ConfigPath "PesterConfiguration.$Environment.psd1" - if (Test-Path $envConfigPath) { - $envConfig = Import-PowerShellDataFile $envConfigPath - - # Merge configurations (environment overrides base) - $mergedConfig = Merge-HashTable $baseConfig $envConfig - } else { - $mergedConfig = $baseConfig - } +Paths in the report are relative to `CodeCoverage.ReportRoot`, which defaults to `Run.RepoRoot`. +Measured on 6.2.0 for the file `C/src/Code.ps1` in a repository: the JaCoCo package is `C/src` by +default and `src` with `ReportRoot` set to the folder `C`. Set `ReportRoot` when the tool that reads +the report expects paths relative to another folder. - # Create Pester configuration object - return New-PesterConfiguration -Hashtable $mergedConfig -} +## Output -function Merge-HashTable { - param( - [hashtable]$Base, - [hashtable]$Override - ) +`Output.Verbosity` has four values. `Normal` prints one line for each test file and the failures, +`Detailed` prints every block and test, and `Diagnostic` adds Pester's debug messages. - $result = $Base.Clone() +`Output.CIFormat = 'Auto'` detects Azure Pipelines (`TF_BUILD`) and GitHub Actions +(`GITHUB_ACTIONS`) from their environment variables. In GitHub Actions a failed test is written as +an `::error::` command followed by a group that holds the message. `Output.CILogLevel = 'Warning'` +writes failures as warnings instead. - foreach ($key in $Override.Keys) { - if ($result.ContainsKey($key) -and $result[$key] -is [hashtable] -and $Override[$key] -is [hashtable]) { - $result[$key] = Merge-HashTable $result[$key] $Override[$key] - } else { - $result[$key] = $Override[$key] - } - } +`Output.CIDebugOutput = 'Auto'` shows verbose and debug output when the pipeline runs with +`System.Debug` set in Azure Pipelines, or with step debug logging on in GitHub Actions. - return $result -} -``` - -From 6.2 the configuration checks what it is handed. A value of the wrong type throws while the -configuration is built - which bites first with `psd1` and JSON files, where a boolean written in -quotes arrives as a string: - -```powershell -New-PesterConfiguration -Hashtable @{ Run = @{ Parallel = 'yes' } } -# Error: "Run.Parallel expects a bool, but got the string 'yes'." -``` - -An `int` where a `decimal` is expected is still accepted, and a key present with a `$null` value -still means "not set". A key that matches no option is collected rather than thrown on, because a -hashtable may carry keys meant for something else, and `Invoke-Pester` warns about all of them once: +`Output.ShowTags` helps to see why a tag filter selected a test: ```text -WARNING: Ignoring configuration keys 'Nonsense', 'Run.Paralel', there are no such options. - Check the spelling, 'Get-Help about_PesterConfiguration' lists all the options. -``` - -A warning is easy to lose in CI output. Read the same list off the object and fail before the run: - -```powershell -$config = New-PesterConfiguration -Hashtable $mergedConfig -$unknown = @($config.GetUnknownKeys()) -if ($unknown.Count -gt 0) { - throw "Configuration keys that match no option: $($unknown -join ', ')" -} -``` - -Before 6.2 both cases were silent - a misspelled key or a wrong-typed value simply did not apply, -and the only defence was reading the value back off the object. - -## Test Filtering Configuration - -### Tag-Based Filtering - -```powershell -# Filter by test type -$config.Filter.Tag = @('Unit') # Only unit tests -$config.Filter.Tag = @('Integration') # Only integration tests -$config.Filter.Tag = @('Security') # Only security tests - -# Filter by priority -$config.Filter.Tag = @('Critical') # Only critical tests -$config.Filter.ExcludeTag = @('Slow') # Exclude slow tests - -# Combined filtering -$config.Filter.Tag = @('Unit', 'Public') # Unit tests for public functions only -``` - -### The Reserved `None` Tag Value - -Pester 6 reserves `None` (case-insensitive) as a filter value meaning **tests that have no tag** on -themselves or any parent block: - -```powershell -$config.Filter.Tag = @('None') # only untagged tests - use to audit tagging coverage -$config.Filter.ExcludeTag = @('None') # skip untagged tests, run only tagged ones -$config.Filter.Tag = @('None', 'Acceptance') # untagged tests plus Acceptance -``` - -Never use `None` as a literal tag name. If an existing suite does, rename it - filtering by it now -also selects every untagged test. - -### Path-Based Filtering - -```powershell -# Test specific modules -$config.Run.Path = @('./Tests/Unit/Public/Get-*.Tests.ps1') - -# Test specific areas -$config.Run.Path = @('./Tests/Unit/Authentication', './Tests/Unit/Authorization') -``` - -### Excluding Paths - -Pester 6 discovers test files inside **hidden and dot-prefixed folders** (file search uses -`Get-ChildItem -Force`). Version-control metadata folders (`.git`, `.svn`, `.hg`) are still ignored. -Exclude anything else you do not want picked up: - -```powershell -$config.Run.ExcludePath = @( - './.build/**', - './.config/**', - './Tests/Fixtures/**' -) -``` - -## Code Coverage Configuration - -### Coverage Paths - -```powershell -$config.CodeCoverage.Path = @( - './Public/*.ps1', # All public functions - './Private/*.ps1', # All private functions - './Classes/*.ps1', # All class files - './Modules/*/Public/*.ps1' # Multi-module support -) -``` - -There is no `CodeCoverage.ExcludePath`. Narrow `CodeCoverage.Path` instead, and rely on -`CodeCoverage.ExcludeTests = $true` (the default) to keep `*.Tests.ps1` files out of the numbers. - -### Profiler vs. Breakpoint Coverage - -Pester 6 uses the Profiler's tracer by default instead of setting a breakpoint on every command. -This is dramatically faster on large code bases. The old behavior is still available: - -```powershell -$config.CodeCoverage.UseBreakpoints = $true # only if you depend on breakpoint-based numbers -``` - -A parallel run overrides this and always uses breakpoints - see -[Parallel Execution](#parallel-execution-experimental) above. - -### Output Formats and Report Root - -```powershell -$config.CodeCoverage.OutputFormat = 'JaCoCo' # default -$config.CodeCoverage.OutputFormat = 'Cobertura' # for GitLab, Codecov, and similar -``` - -`CoverageGutters` was **removed** in v6. It only existed to produce repo-root-relative paths, and -now _all_ coverage output is relative to the repository root, so plain `JaCoCo` works with the -Coverage Gutters extension. - -Paths are relative to `CodeCoverage.ReportRoot`, which defaults to `Run.RepoRoot` (found from the -nearest `.git` directory, falling back to the working directory). Override it when the repo layout -does not match what your CI tool expects: - -```powershell -$config.CodeCoverage.ReportRoot = "$PSScriptRoot/.." -``` - -## Output Configuration - -### Verbosity Levels - -```powershell -$config.Output.Verbosity = 'None' # No output -$config.Output.Verbosity = 'Minimal' # Only summary -$config.Output.Verbosity = 'Normal' # Standard output (default) -$config.Output.Verbosity = 'Detailed' # Verbose output with test details -$config.Output.Verbosity = 'Diagnostic' # Full diagnostic information -``` - -### Render Mode - -```powershell -$config.Output.RenderMode = 'Auto' # detect terminal capability (default) -$config.Output.RenderMode = 'Ansi' # force ANSI/VT sequences -$config.Output.RenderMode = 'ConsoleColor' # legacy console colors -$config.Output.RenderMode = 'Plaintext' # no color - best for log capture -``` - -### CI/CD Integration - -```powershell -$config.Output.CIFormat = 'GithubActions' # GitHub Actions error/warning annotations -$config.Output.CIFormat = 'AzureDevops' # Azure DevOps logging commands -$config.Output.CIFormat = 'Auto' # Auto-detect (default) -$config.Output.CILogLevel = 'Error' # Error | Warning -$config.Output.CIDebugOutput = 'Auto' # Auto | None -``` - -`CIDebugOutput = 'Auto'` (the default) surfaces `Write-Verbose` and `Write-Debug` output when the CI -system is running with its own debug switch on - Azure DevOps `System.Debug`, GitHub Actions runner -debug logging. Set it to `None` to keep a re-run-with-debug quiet. - -### Showing Tags - -```powershell -$config.Output.ShowTags = $true -# Describing Get-Planet [Tags: Slow, Unix] +Describing Get-Planet [Tags: Unit, Slow] + [+] Returns the planet by name 11ms + Context When the name is unknown [Tags: Negative] + [+] Writes an error [Tags: Fast] 4ms ``` -Appends each `Describe`, `Context`, and `It` tag list to its output line. Use it when a `-Tag` or -`-ExcludeTag` filter selects a surprising set of tests - it shows what the filter actually matched -rather than leaving you to infer it from the names. - -### Stack Traces - -```powershell -$config.Output.StackTraceVerbosity = 'None' -$config.Output.StackTraceVerbosity = 'FirstLine' -$config.Output.StackTraceVerbosity = 'Filtered' # default - hides Pester internals -$config.Output.StackTraceVerbosity = 'Full' -``` +## Test Results -## Test Result Configuration +`TestResult` writes one report in one format for each run. `NUnitXml` and `NUnit2.5` are the same +NUnit 2.5 format, `NUnit3` is the NUnit 3 format, and `JUnitXml` is the JUnit format. -### Output Formats +To write a second format, convert the result object after the run: ```powershell -$config.TestResult.OutputFormat = 'NUnitXml' # NUnit 2.5 schema, most widely consumed (default) -$config.TestResult.OutputFormat = 'NUnit2.5' # explicit alias for the above -$config.TestResult.OutputFormat = 'NUnit3' # NUnit 3 schema, new in v6 -$config.TestResult.OutputFormat = 'JUnitXml' # JUnit, for GitLab and most Java-ecosystem tools -``` - -Reports honor `TestResult.OutputEncoding`. Control characters and ANSI/VT sequences in values are -escaped using Unicode Control Pictures so they cannot corrupt the report XML. +$configuration.Run.PassThru = $true +$result = Invoke-Pester -Configuration $configuration -### Multiple Output Formats - -`TestResult` is a single section, not a collection - you cannot configure two formats in one run. -Convert the result object afterwards instead: - -```powershell -$config.Run.PassThru = $true -$result = Invoke-Pester -Configuration $config - -Export-NUnitReport -Result $result -Path './Tests/Results/NUnit.xml' -Export-JUnitReport -Result $result -Path './Tests/Results/JUnit.xml' +Export-NUnitReport -Result $result -Path (Join-Path -Path $outputPath -ChildPath 'nunit.xml') +Export-JUnitReport -Result $result -Path (Join-Path -Path $outputPath -ChildPath 'junit.xml') ``` -## Configuration Best Practices +`Export-NUnitReport` also has `-Format NUnit3`. -### Environment Detection +A file that fails discovery is written to the report as a failure. -```powershell -# Auto-detect CI/CD environment -if ($env:CI -eq 'true' -or $env:BUILD_ID) { - $environment = 'CI' -} elseif ($env:PERFORMANCE_TESTING -eq 'true') { - $environment = 'Performance' -} else { - $environment = 'Development' -} +A raw control character in a test name or in a failure message breaks the report. Measured on +6.2.0, a message that contains the escape character (0x1B) makes the export fail with +`hexadecimal value 0x1B, is an invalid character` in all three formats, and the report file is left +incomplete. Remove ANSI colour sequences from text before a test throws it or uses it in a name. -$config = Get-PesterConfiguration -Environment $environment -``` +## Experimental Options -### Configuration Validation +`Run.Parallel`, `Run.Shuffle`, and `Mock.Global` are off by default, and Pester marks them as +experimental. Do not enable `Run.Parallel` or `Mock.Global` in a configuration that you generate +unless the user asks. `Run.Shuffle` is the exception: turn it on for the unit tests in CI (TST-46). -```powershell -function Test-PesterConfiguration { - param([PesterConfiguration]$Configuration) - - # Validate Pester version - $pester = Get-Module Pester -ListAvailable | - Sort-Object Version -Descending | Select-Object -First 1 - if ($pester.Version -lt [version]'6.2.0') { - throw "Pester 6.2+ required, found $($pester.Version)" - } - - # Validate required paths exist - foreach ($path in $Configuration.Run.Path.Value) { - if (-not (Test-Path $path)) { - Write-Warning "Test path not found: $path" - } - } - - # Validate output directories - $outputDir = Split-Path $Configuration.TestResult.OutputPath.Value -Parent - if ($outputDir -and -not (Test-Path $outputDir)) { - New-Item -Path $outputDir -ItemType Directory -Force | Out-Null - } - - # Validate coverage target - $target = $Configuration.CodeCoverage.CoveragePercentTarget.Value - if ($target -gt 100 -or $target -lt 0) { - throw "Invalid coverage target: $target" - } - - # 6.2 collects keys that match no option instead of throwing on them. - # Invoke-Pester warns once; a gate should fail on them instead. - $unknown = @($Configuration.GetUnknownKeys()) - if ($unknown.Count -gt 0) { - throw "Configuration keys that match no option: $($unknown -join ', ')" - } -} -``` - -Note that reading a value off the configuration object gives you an option wrapper - use `.Value` -to get the underlying setting. - -### Configuration Inheritance - -```powershell -# Base configuration for organization -$orgConfig = @{ - CodeCoverage = @{ - CoveragePercentTarget = 80 - OutputFormat = 'JaCoCo' - } - TestResult = @{ - OutputFormat = 'NUnitXml' - } -} - -# Project-specific overrides -$projectConfig = @{ - CodeCoverage = @{ - CoveragePercentTarget = 85 # Higher target for critical project - } -} - -# Merge configurations -$finalConfig = Merge-HashTable $orgConfig $projectConfig -``` +- `Run.Parallel` and `Run.ParallelThrottleLimit`: see + [Test Execution Guide](./test-execution.md#parallel-test-execution). +- `Run.Shuffle` and `Run.ShuffleSeed`: see + [Test Execution Guide](./test-execution.md#shuffled-test-order). +- `Mock.Global`: with the option on, a mock applies to calls of the command from any module or + script, and `-ModuleName` no longer limits where it applies. See + [Mocking Patterns Guide](./mocking-patterns.md). diff --git a/.github/instructions/pester-supporting-docs/security-test-template.md b/.github/instructions/pester-supporting-docs/security-test-template.md index 8e1b4f2..a1fbd7b 100644 --- a/.github/instructions/pester-supporting-docs/security-test-template.md +++ b/.github/instructions/pester-supporting-docs/security-test-template.md @@ -1,512 +1,235 @@ # Security Test Template -Targets **Pester 6.2+**. Uses the `Should-*` assertion syntax - see -[Assertion Guide](./assertion-guide.md). +A test file for functions that handle untrusted input, paths, or credentials. Write one only for a +function that has such a requirement (TST-43). The security rules that these tests check are in the +[security rules](../powershell-security.instructions.md), and the testing rules are in the +[Pester rules](../powershell-pester.instructions.md). The file below passes on Pester 6.2.0 under +PowerShell 7.6 and Windows PowerShell 5.1, and each of its tests fails against a copy of the module +that has the defect it looks for. -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. +## The Code Under Test -## Standard Security Test Structure +The template tests the module `ModuleName` from the [unit test template](./unit-test-template.md). -Use this template for validating security controls and input sanitization: +- `Get-Thing -Name <string[]>` puts each name into the address of a web request. It restricts names + with an anchored `ValidatePattern` (SEC-11). +- `Read-ThingFile -Root <string> -ChildPath <string>` reads a file below a root folder. It resolves + the path and refuses one that leaves the root, with the error ID `PathOutsideRoot` (SEC-12). +- `Connect-ThingService -Credential <PSCredential>` signs in to the service. Without a credential it + fails with the error ID `CredentialRequired`; it does not prompt (SEC-05). It writes a verbose + message, and a failed sign-in has the error ID `SignInFailed`. + +## The Test File ```powershell #Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } BeforeDiscovery { - # Attack-pattern data drives -ForEach, so it MUST be built at discovery time. - # BeforeAll runs at RUN time - too late. A variable defined there is $null - # during discovery, and $null piped through ForEach-Object yields exactly one - # iteration, so the suite silently collapses to a single bogus test named - # "rejects: $null" that asserts nothing about any real attack pattern. - # Nothing fails; the run just reports green having tested nothing. - # See "Discovery-Time Data" below. - $MaliciousInputPatterns = @( - "'; DROP TABLE Users; --" - "../../../etc/passwd" - "<script>alert('xss')</script>" - '$(Get-Process)' - "Invoke-Expression 'malicious code'" - "& cmd.exe /c dir" - '$(Get-Content secrets.txt)' - ) - - $PathTraversalPatterns = @( - "..\..\Windows\System32\config" - "../../../../etc/shadow" - "..\..\..\secrets\passwords.txt" - "C:\Windows\System32\SAM" + $injectionCases = @( + @{ Description = 'a command separator'; Text = 'alpha; Remove-Item -Path *' } + @{ Description = 'a subexpression'; Text = '$(Get-Process)' } + @{ Description = 'a pipe'; Text = 'alpha | Out-File -FilePath x' } + @{ Description = 'a relative path'; Text = '../../etc/passwd' } + @{ Description = 'a quote'; Text = "alpha' OR '1'='1" } ) - $InvalidEmailPatterns = @( - "notanemail" - "@domain.com" - "user@" - "user..name@domain.com" - "user@domain" - ) - - $CommandInjectionPatterns = @( - "normalvalue; Remove-Item C:\temp\*" - 'value$(Get-Process)' - "value & dir" - "value | Get-Content secrets.txt" + $traversalCases = @( + @{ ChildPath = '../outside.txt' } + @{ ChildPath = 'reports/../../outside.txt' } + @{ ChildPath = '../root-other/outside.txt' } ) } BeforeAll { - # Import module under test. Each file is self-contained in Pester 6. - $ModulePath = Join-Path $PSScriptRoot '..\..\ModuleName.psd1' - Import-Module $ModulePath -Force - - # Runtime-only configuration - $SecurityConfig = @{ - TestCredentials = @{ - Valid = @{ - Username = "testuser" - Password = "TestPassword123!" - } - Invalid = @{ - Username = "invaliduser" - Password = "wrongpassword" - } - } + $moduleRoot = Split-Path -Path $PSScriptRoot -Parent + if (-not (Get-Module -Name ModuleName)) { + Import-Module -Name (Join-Path -Path $moduleRoot -ChildPath 'ModuleName.psd1') } } -Describe "Security Tests" -Tag "Security", "InputValidation" { - Context "Input Validation and Sanitization" { - It "Should reject malicious input pattern: <MaliciousInput>" -ForEach $MaliciousInputPatterns.ForEach({ - @{ MaliciousInput = $_ } - }) { - { Function-Name -ParameterName $MaliciousInput } | - Should-Throw -ExceptionMessage '*invalid characters*' - } - - It "Should sanitize file path against traversal: <UnsafePath>" -ForEach $PathTraversalPatterns.ForEach({ - @{ UnsafePath = $_ } - }) { - { Function-Name -FilePath $UnsafePath } | - Should-Throw -ExceptionMessage '*invalid path*' - } - - It "Should reject invalid email format: <InvalidEmail>" -ForEach $InvalidEmailPatterns.ForEach({ - @{ InvalidEmail = $_ } - }) { - { Function-Name -EmailAddress $InvalidEmail } | - Should-Throw -ExceptionMessage '*invalid email*' - } - - It "Should prevent command injection: <Injection>" -ForEach $CommandInjectionPatterns.ForEach({ - @{ Injection = $_ } - }) { - { Function-Name -ParameterName $Injection } | - Should-Throw -ExceptionMessage '*invalid characters*' - } - - It "Should validate parameter length limits" { - $oversizedInput = "x" * 10000 # 10KB string - - { Function-Name -ParameterName $oversizedInput } | - Should-Throw -ExceptionMessage '*exceeds maximum length*' - } - - It "Should reject <Description> input" -ForEach @( - @{ Description = 'null'; Value = $null; Expected = '*cannot be null*' } - @{ Description = 'empty'; Value = ''; Expected = '*cannot be empty*' } - @{ Description = 'whitespace-only'; Value = ' '; Expected = '*cannot be empty*' } - ) { - { Function-Name -ParameterName $Value } | - Should-Throw -ExceptionMessage $Expected - } +Describe 'Get-Thing input validation' -Tag 'Security' { + BeforeAll { + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { } } - Context "Credential Handling Security" { - It "Should not expose credentials in logs or output" { - $testCredential = New-Object PSCredential( - $SecurityConfig.TestCredentials.Valid.Username, - (ConvertTo-SecureString $SecurityConfig.TestCredentials.Valid.Password -AsPlainText -Force) - ) - - # Capture all output streams - $allOutput = Function-Name -Credential $testCredential -Verbose -Debug 4>&1 5>&1 6>&1 - - # Convert all output to string for analysis - $outputText = $allOutput | Out-String - - # Ensure credentials are not exposed anywhere. - # Escape the values - they are data, not patterns. - $outputText | Should-NotMatchString ([regex]::Escape($SecurityConfig.TestCredentials.Valid.Username)) - $outputText | Should-NotMatchString ([regex]::Escape($SecurityConfig.TestCredentials.Valid.Password)) - } - - It "Should handle SecureString parameters securely" { - $secureString = ConvertTo-SecureString "SecretValue123" -AsPlainText -Force - - # Function should accept SecureString without exposing value - $result = Function-Name -SecureParameter $secureString -Verbose 4>&1 + It 'Rejects a name that contains <Description>' -ForEach $injectionCases { + { Get-Thing -Name $Text } | + Should-Throw -FullyQualifiedErrorId 'ParameterArgumentValidationError,Get-Thing' - # Verify SecureString value is not exposed in verbose output - ($result | Out-String) | Should-NotMatchString 'SecretValue123' - } - - It "Should validate credential authentication" { - $validCredential = New-Object PSCredential( - $SecurityConfig.TestCredentials.Valid.Username, - (ConvertTo-SecureString $SecurityConfig.TestCredentials.Valid.Password -AsPlainText -Force) - ) - - $invalidCredential = New-Object PSCredential( - $SecurityConfig.TestCredentials.Invalid.Username, - (ConvertTo-SecureString $SecurityConfig.TestCredentials.Invalid.Password -AsPlainText -Force) - ) - - # Valid credentials should work. There is no Should-NotThrow - - # call it directly; an unhandled exception fails the test. - Function-Name -Credential $validCredential - - # Invalid credentials should fail gracefully - { Function-Name -Credential $invalidCredential } | - Should-Throw -ExceptionMessage '*authentication*' - } - - It "Should implement secure credential caching" { - $testCredential = New-Object PSCredential( - "cachetest", - (ConvertTo-SecureString "CachePassword123" -AsPlainText -Force) - ) - - # First call - should cache credential securely - Function-Name -Credential $testCredential -CacheCredentials - - # Verify credential is cached but not exposed - $cacheContent = Get-CredentialCache -ErrorAction SilentlyContinue - if (-not $cacheContent) { - Set-ItResult -Inconclusive -Because 'no credential cache was produced to inspect' - } - - ($cacheContent | Out-String) | Should-NotMatchString 'CachePassword123' - ($cacheContent | Out-String) | Should-NotMatchString 'cachetest' - } + Should-NotInvoke -CommandName Invoke-RestMethod -ModuleName ModuleName } +} - Context "Access Control and Authorization" { - It "Should deny access when the role is insufficient" { - Mock Get-CurrentUserRole { 'User' } - - { Function-Name -RequiredRole 'Administrator' } | - Should-Throw -ExceptionMessage '*insufficient privileges*' - } - - It "Should allow access when the role is sufficient" { - Mock Get-CurrentUserRole { 'Administrator' } - - Function-Name -RequiredRole 'Administrator' - } - - It "Should not perform the privileged action when denied" { - Mock Get-CurrentUserRole { 'User' } - Mock Invoke-PrivilegedAction { } - - { Function-Name -RequiredRole 'Administrator' } | Should-Throw - - # The assertion that actually matters: the action never ran - Should-NotInvoke Invoke-PrivilegedAction - } - - It "Should validate file system permissions" { - $restrictedPath = "C:\Windows\System32\config" - - # Should check permissions before attempting access - { Function-Name -Path $restrictedPath } | - Should-Throw -ExceptionMessage '*access denied*' - } - - It "Should reject an invalid session" { - Mock Get-CurrentSession { $null } - - { Function-Name -RequireValidSession } | - Should-Throw -ExceptionMessage '*invalid session*' - } - - It "Should accept a valid session" { - Mock Get-CurrentSession { @{ Valid = $true; UserId = 'testuser' } } - - Function-Name -RequireValidSession - } +Describe 'Read-ThingFile path handling' -Tag 'Security' { + BeforeAll { + $root = Join-Path -Path $TestDrive -ChildPath 'root' + $sibling = Join-Path -Path $TestDrive -ChildPath 'root-other' + $null = New-Item -Path $root -ItemType Directory + $null = New-Item -Path $sibling -ItemType Directory + + # The files outside the root exist, so a function that followed the path would return them. + $insidePath = Join-Path -Path $root -ChildPath 'inside.txt' + $outsidePath = Join-Path -Path $TestDrive -ChildPath 'outside.txt' + $siblingPath = Join-Path -Path $sibling -ChildPath 'outside.txt' + Set-Content -LiteralPath $insidePath -Value 'inside' -Encoding ascii + Set-Content -LiteralPath $outsidePath -Value 'outside' -Encoding ascii + Set-Content -LiteralPath $siblingPath -Value 'outside' -Encoding ascii } - Context "Data Protection and Encryption" { - It "Should encrypt sensitive data at rest" { - $sensitiveData = "Confidential Information 12345" - - $result = Function-Name -SensitiveData $sensitiveData -EncryptData - - # Verify data is encrypted (not plaintext) - $result.EncryptedData | Should-NotMatchString 'Confidential Information' - $result.EncryptedData | Should-NotBeEmptyString - - # Verify encryption metadata is present - $result.EncryptionAlgorithm | Should-NotBeEmptyString - $result.IV | Should-NotBeNull - } - - It "Should implement secure data transmission" { - # Mock secure transmission - Mock Invoke-SecureTransmission { - param($Data, $Endpoint) - - # Verify data is encrypted before transmission - if ($Data -match "plaintext") { - throw "Data not encrypted for transmission" - } - - return @{ Success = $true; Encrypted = $true } - } + It 'Reads a file inside the root' { + Read-ThingFile -Root $root -ChildPath 'inside.txt' | Should-BeString 'inside' -TrimWhitespace + } - $testData = "Sensitive transmission data" - $result = Function-Name -TransmitData $testData -Endpoint "https://secure-api.test" + It 'Refuses <ChildPath>, which resolves outside the root' -ForEach $traversalCases { + { Read-ThingFile -Root $root -ChildPath $ChildPath } | + Should-Throw -FullyQualifiedErrorId 'PathOutsideRoot,Read-ThingFile' + } - $result.Success | Should-BeTrue - $result.Encrypted | Should-BeTrue - } + It 'Refuses an absolute path outside the root' { + { Read-ThingFile -Root $root -ChildPath $outsidePath } | + Should-Throw -FullyQualifiedErrorId 'PathOutsideRoot,Read-ThingFile' + } +} - It "Should securely hash passwords" { - $password = "UserPassword123!" +Describe 'Connect-ThingService credential handling' -Tag 'Security' { + BeforeAll { + # The password is generated for each run, so the test file stores no secret. + $secretText = [guid]::NewGuid().ToString('N') + $password = ConvertTo-SecureString -String $secretText -AsPlainText -Force + $credential = [System.Management.Automation.PSCredential]::new('svc-test', $password) + $secretPattern = [regex]::Escape($secretText) + } - $result = Function-Name -HashPassword $password + It 'Declares Credential as a PSCredential' { + Get-Command -Name Connect-ThingService | + Should-HaveParameter -ParameterName Credential -Type ([System.Management.Automation.PSCredential]) + } - # Verify password is hashed, not stored in plaintext - $result.HashedPassword | Should-NotMatchString ([regex]::Escape($password)) - $result.HashedPassword | Should-NotBeEmptyString + It 'Fails without prompting when no credential is passed' { + Mock -CommandName Get-Credential -ModuleName ModuleName -MockWith { } + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { } - # Verify salt is used - $result.Salt | Should-NotBeEmptyString + { Connect-ThingService } | + Should-Throw -FullyQualifiedErrorId 'CredentialRequired,Connect-ThingService' - # Verify hash algorithm is secure. - # Should -BeIn has no direct Should-* equivalent; Should-Any over the - # allow-list expresses the same intent. - @('SHA256', 'SHA512', 'bcrypt', 'scrypt', 'PBKDF2') | - Should-Any { $_ -eq $result.Algorithm } - } + Should-NotInvoke -CommandName Get-Credential -ModuleName ModuleName + Should-NotInvoke -CommandName Invoke-RestMethod -ModuleName ModuleName } - Context "Audit and Compliance" { - It "Should log security-relevant events" { - # Clear any existing security logs - Clear-SecurityLog -ErrorAction SilentlyContinue - - # Perform operation that should generate security log - Function-Name -SecuritySensitiveOperation -UserId "testuser" - - # Verify security event was logged - $securityLogs = Get-SecurityLog -Recent 1 - $securityLogs | Should-NotBeNull - $securityLogs[0].EventType | Should-MatchString 'Security' - $securityLogs[0].UserId | Should-Be 'testuser' + It 'Does not write the password to any stream' { + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { + [PSCustomObject]@{ sessionId = 'session-1' } } - It "Should implement data retention policies" { - $testData = @{ - Id = [System.Guid]::NewGuid() - Data = "Test data for retention" - RetentionPeriod = [TimeSpan]::FromDays(30) - } + $output = Connect-ThingService -Credential $credential -Verbose -InformationAction Continue *>&1 + $text = $output | Out-String - # Store data with retention policy - Function-Name -StoreData $testData - - # Verify retention metadata is set - $storedData = Get-StoredData -Id $testData.Id - $storedData.ExpirationDate | Should-BeAfter (Get-Date) - $storedData.ExpirationDate | Should-BeBefore (Get-Date).AddDays(30) - } - - It "Should support compliance data export" { - # Generate test compliance data - 1..5 | ForEach-Object { - Function-Name -CreateComplianceRecord -UserId "user$_" -Action "TestAction$_" - } - - # Export compliance data - $exportResult = Function-Name -ExportComplianceData -StartDate (Get-Date).AddDays(-1) -EndDate (Get-Date) - - # Verify export contains required fields. - # There is no Should -HaveProperty operator in Pester - that was never real. - # Assert the shape instead. - $exportResult | Should-NotBeNull - $exportResult.Records | Should-BeCollection -Count 5 - $exportResult.Records | Should-All { - $null -ne $_.UserId -and $null -ne $_.Action -and $null -ne $_.Timestamp - } - } + # The first assertion proves that the verbose stream was captured. + $text | Should-MatchString 'Signing in' + $text | Should-NotMatchString $secretPattern } - Context "Error Handling Security" { - It "Should not expose sensitive information in error messages" { - $sensitiveConnectionString = "Server=secret.db.com;Database=confidential;User=admin;Password=secret123" - - # Capture the error explicitly. A bare try/catch with assertions only in - # the catch block passes silently when the function does NOT throw - - # the test then proves nothing. - $thrown = $null - try { - Function-Name -ConnectionString $sensitiveConnectionString -ForceError - } - catch { - $thrown = $_ - } - - $thrown | Should-NotBeNull -Because 'the function was expected to fail' - $thrown.Exception.Message | Should-NotMatchString 'secret\.db\.com' - $thrown.Exception.Message | Should-NotMatchString 'secret123' - $thrown.Exception.Message | Should-NotMatchString 'confidential' + It 'Does not put the password in the error when sign-in fails' { + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { + throw [System.UnauthorizedAccessException]::new('The service refused the credential.') } - It "Should implement secure error logging" { - # Generate an error condition - { Function-Name -CauseSecurityError -ErrorAction Stop } | Should-Throw + $failure = { Connect-ThingService -Credential $credential } | + Should-Throw -FullyQualifiedErrorId 'SignInFailed,Connect-ThingService' - # Error should be logged securely without exposing sensitive details - $errorLogs = Get-ErrorLog -Recent 1 - $errorLogs[0].Message | Should-NotBeEmptyString - $errorLogs[0].SanitizedForSecurity | Should-BeTrue - } + $failure.Exception.Message | Should-NotMatchString $secretPattern + ($failure | Out-String) | Should-NotMatchString $secretPattern } } ``` -## Pester 6 Notes for Security Tests - -### Discovery-Time Data +## What The Template Shows -Attack-pattern lists drive `-ForEach`, so they must exist at **discovery** time. Put them in -`BeforeDiscovery`, never `BeforeAll`. +### Attack Data Is Built During Discovery -This matters more for security suites than anywhere else, because the failure is silent and looks -like success: +The lists that drive `-ForEach` must exist during discovery, so they are built in `BeforeDiscovery` +(TST-02). A list built in `BeforeAll` is `$null` at that point, and the outcome depends on how the +cases are derived from it: -```powershell -# WRONG - $SecurityConfig is $null during discovery. -# $null piped through ForEach-Object yields ONE iteration, so this generates a -# single test named "rejects: $null" that exercises no attack pattern at all. -# The run reports green. Nothing was tested. -BeforeAll { - $SecurityConfig = @{ MaliciousInputPatterns = @("'; DROP TABLE Users; --", '$(Get-Process)') } -} -It "rejects: <MaliciousInput>" -TestCases @( - $SecurityConfig.MaliciousInputPatterns | ForEach-Object { @{ MaliciousInput = $_ } } -) { ... } +| Cases derived from a `$null` list with | Result | +| --- | --- | +| `$list \| ForEach-Object { @{ Text = $_ } }` | One test with `$null` as its value. It can pass, and the run looks complete. | +| `foreach ($item in $list) { @{ Text = $item } }` | No cases. Discovery of the file fails. | +| `$list.ForEach({ @{ Text = $_ } })` | No cases. Discovery of the file fails. | -# RIGHT - built at discovery time, generates one test per pattern -BeforeDiscovery { - $MaliciousInputPatterns = @("'; DROP TABLE Users; --", '$(Get-Process)') -} -It "rejects: <MaliciousInput>" -ForEach $MaliciousInputPatterns.ForEach({ - @{ MaliciousInput = $_ } -}) { ... } -``` +Do not build cases with `ForEach-Object`. Do not add `-AllowNullOrEmptyForEach` in a security test +file either: an empty list of attacks must stop the run. -If the source list is genuinely empty (`@()` rather than `$null`), Pester 6 **fails discovery** with -`Run.FailOnNullOrEmptyForEach` rather than running zero tests. For a security suite that is exactly -the behavior you want - do not disable it, and do not reach for `-AllowNullOrEmptyForEach` here. - -Verify the suite generates the test count you expect: +To see how many tests a file produces without running them: ```powershell -$config = New-PesterConfiguration -$config.Run.Path = './Tests/Security' -$config.Run.SkipRun = $true -$config.Run.PassThru = $true -$discovered = Invoke-Pester -Configuration $config -"Discovered $($discovered.TotalCount) security tests" +$configuration = New-PesterConfiguration +$configuration.Run.Path = './Tests' +$configuration.Run.SkipRun = $true +$configuration.Run.PassThru = $true +$discovered = Invoke-Pester -Configuration $configuration +$discovered.TotalCount ``` -### Quote attack patterns correctly +### Attack Strings Are Quoted Literally -Use **single quotes** for patterns containing `$`. In the original template -`"$(Get-Process)"` was a double-quoted string, so PowerShell expanded it at parse time and the test -fed the _output of `Get-Process`_ to the function instead of the literal injection string. +Write a pattern that contains `$` in single quotes. In double quotes PowerShell expands it before +the test runs, and the function receives the output of the command instead of the attack: ```powershell -'$(Get-Process)' # literal - what you want to test -"$(Get-Process)" # expanded at parse time - tests nothing useful -``` - -### Escape values used as regex +# Compliant: the function receives the text +@{ Description = 'a subexpression'; Text = '$(Get-Process)' } -`Should-MatchString` / `Should-NotMatchString` take a regex. Credentials and connection strings -contain `.`, `$`, `(`, and `\`, which are metacharacters. Escape them: - -```powershell -$output | Should-NotMatchString ([regex]::Escape($password)) -``` - -An unescaped `.` matches any character, which usually makes the assertion _more_ likely to match and -therefore _less_ likely to catch a leak - a false sense of security. - -### Assert the action did not happen - -For authorization tests, `Should-NotInvoke` is stronger evidence than `Should-Throw`. A function can -throw _after_ performing the privileged action: - -```powershell -Mock Invoke-PrivilegedAction { } -{ Function-Name -RequiredRole 'Administrator' } | Should-Throw -Should-NotInvoke Invoke-PrivilegedAction +# Non-compliant: the function receives a list of processes +@{ Description = 'a subexpression'; Text = "$(Get-Process)" } ``` -### Do not put the only assertions inside a `catch` +Write path separators as `/`. A backslash is a separator on Windows only, so `..\outside.txt` names +an ordinary file inside the root on Linux and macOS. -A `try`/`catch` whose assertions live only in the `catch` block passes silently when the code does -**not** throw. Capture the error and assert it was thrown, or use `Should-Throw`. +### The Unsafe Outcome Must Be Possible -## Security Test Guidelines +A test proves a control only if it fails when the control is missing: -### Input Validation Testing +- The files outside the root exist. Without the check, `Read-ThingFile` would return their content + and `Should-Throw` would fail. +- The mock of `Invoke-RestMethod` lets `Should-NotInvoke` show that a rejected name never reached + the service. An error ID alone would not show that. +- The first assertion on the captured text shows that the verbose stream is in it. An empty capture + would pass the second assertion without proving anything. -- Test all forms of malicious input -- Validate parameter length limits -- Test encoding and special characters -- Verify path traversal prevention -- Test command injection attempts +### No Secret Is Stored In The Test File -### Credential Security Testing +SEC-01 and SEC-04 apply to test files. The password is a value generated at run time, converted +with `ConvertTo-SecureString -AsPlainText` only because it is not a literal and is not stored in +source. A random value is also a better marker than a fixed one: it cannot appear in the output by +coincidence. -- Verify credentials are never exposed in logs -- Test SecureString handling -- Validate authentication mechanisms -- Test credential caching security -- Verify secure credential transmission +### Every Stream Is Captured -### Access Control Testing +`*>&1` merges the error, warning, verbose, debug, and information streams into the output. The call +passes `-Verbose` and `-InformationAction Continue` so that those streams are written at all. -- Test role-based access control -- Validate file system permissions -- Test session management -- Verify authorization enforcement -- Test privilege escalation prevention +Do not add `-Debug` in a test that must run on Windows PowerShell 5.1. There it makes `Write-Debug` +ask for confirmation, which fails in a non-interactive session. On PowerShell 7 `-Debug` only turns +the stream on. -### Data Protection Testing +### A Value Used As A Pattern Is Escaped -- Test encryption at rest and in transit -- Validate secure data handling -- Test password hashing algorithms -- Verify secure deletion methods -- Test data anonymization features +`Should-MatchString` and `Should-NotMatchString` take a regular expression. A password or a +connection string can contain characters such as `.`, `$`, and `(`, so pass it through +`[regex]::Escape()`. An invalid pattern stops the test with an error, and a valid but unintended one +can fail to match the text it was meant to find. -### Compliance and Audit Testing +### The Error Is Asserted, Not Only Caught -- Verify security event logging -- Test data retention compliance -- Validate audit trail integrity -- Test compliance data export -- Verify regulatory requirement adherence +`Should-Throw` returns the error record, and the test asserts on its message. Do not write the +assertions in the `catch` block of a `try` statement: when the function does not throw, the block +does not run and the test passes. -### Error Handling Security +### What The Function Must Not Do -- Ensure no sensitive data in error messages -- Test error information disclosure -- Validate secure error logging -- Test error handling under attack conditions -- Verify graceful failure modes +For a refusal, `Should-NotInvoke` on the protected action is stronger evidence than `Should-Throw`, +because a function can throw after it has done the damage. For SEC-05, mock `Get-Credential` and +`Read-Host` in the module and assert that neither was called; the mock also keeps a defective +function from waiting for input. diff --git a/.github/instructions/pester-supporting-docs/test-data-guide.md b/.github/instructions/pester-supporting-docs/test-data-guide.md index 286f0b0..fab7817 100644 --- a/.github/instructions/pester-supporting-docs/test-data-guide.md +++ b/.github/instructions/pester-supporting-docs/test-data-guide.md @@ -1,645 +1,386 @@ # Test Data Management Guide -Targets **Pester 6.2+**. +This guide covers the data that tests use: cases for `-ForEach`, data files, files that a test +creates, and helper functions that build objects. It supports rules TST-02, TST-03, TST-12, TST-30, +and TST-31 in [powershell-pester.instructions.md](../powershell-pester.instructions.md). The +behaviour described here was checked on Pester 6.2.0. -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. +## Discovery-Time and Run-Time Data -## Discovery-Time vs. Run-Time Data +Pester reads a test file twice. During discovery it runs the file to find the `Describe`, `Context`, +and `It` blocks. During the run it executes the setup blocks and the tests. Where data is built +decides which of the two can see it. -This is the most important distinction in Pester 6 test data, and getting it wrong fails silently. - -| Data drives... | Must be built in | Why | +| The data is used by | Build it in | Reason | | --- | --- | --- | -| `-ForEach` / `-TestCases` (the test _tree_) | `BeforeDiscovery` | Discovery runs before `BeforeAll` | -| Assertions inside `It` (the test _body_) | `BeforeAll` / `BeforeEach` | Runs at execution time | +| `-ForEach`, which shapes the test tree | `BeforeDiscovery` | Discovery happens before any `BeforeAll` runs. | +| Assertions inside `It` | `BeforeAll` or `BeforeEach` | These blocks run with the tests. | ```powershell BeforeDiscovery { - # Shapes the test tree - one It per user - $TestUsers = New-TestUsers -Count 3 -Type 'Standard' + # Shapes the test tree: one It for each case. + $userCases = @( + @{ UserName = 'ann'; Department = 'Finance' } + @{ UserName = 'bob'; Department = 'Operations' } + ) } -BeforeAll { - # Used inside test bodies - $TestConfig = New-TestConfiguration -Environment 'Testing' -} +Describe 'Get-UserDepartment' -Tag 'Unit' { + BeforeAll { + # Used inside the test bodies. + $directoryPath = Join-Path -Path $TestDrive -ChildPath 'directory.json' + $directory = @( + @{ userName = 'ann'; department = 'Finance' } + @{ userName = 'bob'; department = 'Operations' } + ) + $json = ConvertTo-Json -InputObject $directory + Set-Content -LiteralPath $directoryPath -Value $json -Encoding ascii + } -Describe 'User processing' { - It 'processes <Name>' -ForEach $TestUsers.ForEach({ @{ Name = $_.FullName; User = $_ } }) { - Process-User -User $User -Config $TestConfig | Should-BeTrue + It 'Returns <Department> for <UserName>' -ForEach $userCases { + Get-UserDepartment -LiteralPath $directoryPath -UserName $UserName | Should-Be $Department } } ``` -Building `-ForEach` data in `BeforeAll` leaves it `$null` during discovery. Piping `$null` through -`ForEach-Object` yields **one** iteration, so the suite collapses to a single bogus test and reports -green. If the source is an empty array instead, Pester 6 fails discovery outright -(`Run.FailOnNullOrEmptyForEach`). - -Because Pester 6 discovers **one file at a time**, discovery-time data must also be produced by the -file that uses it - a helper module imported by another test file is not guaranteed to be loaded. -Import helpers in the same file, or provide them from a `Pester.BeforeContainer.ps1`. Top-level code -in that file runs at discovery, which is exactly when `-ForEach` data is built; anything the tests -need at run time goes in its `BeforeAll` - see -[Test Structure Guide](./test-structure-guide.md#shared-bootstrap). +### Data Built in the Wrong Block -### Test data must be deterministic at discovery time +A variable that is assigned in `BeforeAll` is `$null` during discovery. What follows depends on how +the `-ForEach` argument is written. Measured on Pester 6.2.0: -`TestDataFactory` below uses `Get-Random`. That is fine for run-time data, but data feeding -`-ForEach` should be **stable** - under `Run.Parallel` each file is discovered in its own runspace, -and randomized test _names_ make failures hard to correlate across runs and reports. +| `-ForEach` argument, with `$users` assigned in `BeforeAll` | Result | +| --- | --- | +| `-ForEach $users` | Discovery of the file fails: `Value can not be null or empty array`. | +| `-ForEach $users.ForEach({ @{ Name = $_.Name } })` | Discovery of the file fails with the same message. | +| `-ForEach ($users \| ForEach-Object { @{ Name = $_.Name } })` | One test is created with the name `$null` in place of the value, and it runs with empty data. | -For discovery-time data, prefer fixed fixtures or a seeded generator: +The third form is the dangerous one. Piping `$null` to `ForEach-Object` runs the script block once, +so the file reports one test where it should report many, and that test can pass. -```powershell -BeforeDiscovery { - # Stable names - the same test identity on every run and in every runspace - $TestCases = Import-PowerShellDataFile "$PSScriptRoot/../TestData/user-cases.psd1" -} -``` - -Keep `Get-Random` for values consumed inside `It` bodies, where the name is already fixed. +A file that fails discovery adds nothing to `FailedCount`. It sets `FailedContainersCount` and makes +the run result `Failed`, which is why the CI gate tests `Result` (TST-42). -## Test Data Organization +The check for an empty list is the `Run.FailOnNullOrEmptyForEach` option, which is on by default. +`-AllowNullOrEmptyForEach` on a `Describe`, `Context`, or `It` turns it off for that block. TST-30 +requires a list that is not empty, so correct the data instead of adding the switch. -### Test Data Directory Structure +### Each File Builds Its Own Data -```text -Tests/ -├── TestData/ -│ ├── Configurations/ -│ │ ├── development.psd1 -│ │ ├── testing.psd1 -│ │ └── production.psd1 -│ ├── SampleData/ -│ │ ├── users.json -│ │ ├── servers.csv -│ │ └── configurations.xml -│ ├── MockResponses/ -│ │ ├── api-responses.json -│ │ ├── database-results.json -│ │ └── service-responses.json -│ ├── Templates/ -│ │ ├── user-template.json -│ │ ├── server-template.json -│ │ └── config-template.psd1 -│ ├── Baselines/ -│ │ ├── performance-baselines.psd1 -│ │ └── security-baselines.json -│ └── Fixtures/ -│ ├── test-certificates/ -│ ├── test-files/ -│ └── sample-logs/ -├── TestHelpers/ -│ ├── TestDataFactory.ps1 -│ ├── MockDataGenerator.ps1 -│ └── DataValidation.ps1 -``` +Pester 6 discovers and runs one file at a time, and in a parallel run each file has its own +runspace. A file therefore cannot use data or a helper that another test file loaded. Build the +data in the file's own `BeforeDiscovery`, or in a shared setup file; see +[Pester Test Structure Guide](./test-structure-guide.md#shared-setup-files). -## Test Data Factory +## Case Format -### Comprehensive Test Data Factory +Pass each case as a hashtable (TST-30). Each key becomes a variable inside the `It` block, and +`<Key>` in the test name is replaced with its value. ```powershell -# TestHelpers/TestDataFactory.ps1 - -class TestDataFactory { - static [hashtable] $Cache = @{} - static [string] $DataPath = (Join-Path $PSScriptRoot '..\TestData') - - # User data generation - static [object[]] CreateUsers([int]$Count = 5, [string]$Type = 'Standard') { - $cacheKey = "Users_$($Count)_$Type" - - if ([TestDataFactory]::Cache.ContainsKey($cacheKey)) { - return [TestDataFactory]::Cache[$cacheKey] - } - - $users = switch ($Type) { - 'Standard' { [TestDataFactory]::CreateStandardUsers($Count) } - 'Admin' { [TestDataFactory]::CreateAdminUsers($Count) } - 'Disabled' { [TestDataFactory]::CreateDisabledUsers($Count) } - 'Mixed' { [TestDataFactory]::CreateMixedUsers($Count) } - default { [TestDataFactory]::CreateStandardUsers($Count) } - } - - [TestDataFactory]::Cache[$cacheKey] = $users - return $users - } +BeforeDiscovery { + $cases = @( + @{ Text = 'alpha'; Expected = 'ALPHA' } + @{ Text = 'beta'; Expected = 'BETA' } + ) +} - static [object[]] CreateStandardUsers([int]$Count) { - $departments = @('IT', 'HR', 'Finance', 'Marketing', 'Operations') - $titles = @('Analyst', 'Specialist', 'Coordinator', 'Manager', 'Director') - - return 1..$Count | ForEach-Object { - $firstName = [TestDataFactory]::GetRandomFirstName() - $lastName = [TestDataFactory]::GetRandomLastName() - - @{ - Id = $_ - FirstName = $firstName - LastName = $lastName - FullName = "$firstName $lastName" - Email = "$($firstName.ToLower()).$($lastName.ToLower())@company.com" - Department = Get-Random -InputObject $departments - Title = Get-Random -InputObject $titles - Active = $true - CreatedDate = (Get-Date).AddDays(-((Get-Random -Minimum 1 -Maximum 365))) - LastLoginDate = (Get-Date).AddDays(-((Get-Random -Minimum 1 -Maximum 30))) - } - } +Describe 'ConvertTo-UpperText' -Tag 'Unit' { + It 'Converts <Text> to <Expected>' -ForEach $cases { + ConvertTo-UpperText -Text $Text | Should-Be $Expected } +} +``` - static [object[]] CreateAdminUsers([int]$Count) { - $adminTitles = @('System Administrator', 'Database Administrator', 'Network Administrator', 'Security Administrator') - - return 1..$Count | ForEach-Object { - $firstName = [TestDataFactory]::GetRandomFirstName() - $lastName = [TestDataFactory]::GetRandomLastName() - - @{ - Id = $_ + 1000 - FirstName = $firstName - LastName = $lastName - FullName = "$firstName $lastName" - Email = "$($firstName.ToLower()).$($lastName.ToLower())@company.com" - Department = 'IT' - Title = Get-Random -InputObject $adminTitles - Active = $true - IsAdmin = $true - Privileges = @('UserManagement', 'SystemConfiguration', 'SecurityManagement') - CreatedDate = (Get-Date).AddDays(-((Get-Random -Minimum 30 -Maximum 365))) - LastLoginDate = (Get-Date).AddDays(-((Get-Random -Minimum 1 -Maximum 7))) - } - } - } +Other kinds of case behave differently: - # Server data generation - static [object[]] CreateServers([int]$Count = 10, [string]$Environment = 'Mixed') { - $cacheKey = "Servers_$($Count)_$Environment" - - if ([TestDataFactory]::Cache.ContainsKey($cacheKey)) { - return [TestDataFactory]::Cache[$cacheKey] - } - - $environments = switch ($Environment) { - 'Production' { @('Production') } - 'Development' { @('Development') } - 'Testing' { @('Testing') } - 'Mixed' { @('Production', 'Development', 'Testing', 'Staging') } - default { @('Production', 'Development', 'Testing') } - } - - $roles = @('Web Server', 'Database Server', 'Application Server', 'Domain Controller', 'File Server') - $operatingSystems = @('Windows Server 2019', 'Windows Server 2022', 'Ubuntu 20.04 LTS', 'CentOS 8') - - $servers = 1..$Count | ForEach-Object { - $environment = Get-Random -InputObject $environments - $role = Get-Random -InputObject $roles - - @{ - Id = $_ - Name = "SRV$($environment.Substring(0,1).ToUpper())$($_.ToString('00'))" - FQDN = "srv$($environment.ToLower())$($_.ToString('00')).company.local" - IPAddress = "192.168.$((Get-Random -Minimum 1 -Maximum 254)).$((Get-Random -Minimum 1 -Maximum 254))" - Environment = $environment - Role = $role - OperatingSystem = Get-Random -InputObject $operatingSystems - CPU = Get-Random -InputObject @(2, 4, 8, 16) - Memory = Get-Random -InputObject @(8, 16, 32, 64, 128) - DiskSpace = Get-Random -InputObject @(100, 250, 500, 1000, 2000) - Status = Get-Random -InputObject @('Running', 'Running', 'Running', 'Stopped', 'Maintenance') # Weighted toward Running - LastUpdated = (Get-Date).AddDays(-((Get-Random -Minimum 1 -Maximum 30))) - MonitoringEnabled = $true - } - } - - [TestDataFactory]::Cache[$cacheKey] = $servers - return $servers - } +| Case | Inside the `It` block | In the test name | +| --- | --- | --- | +| Hashtable `@{ Text = 'alpha' }` | `$Text` and `$_.Text` | `<Text>` | +| Object `[PSCustomObject]@{ Text = 'alpha' }` | `$_.Text` only. `$Text` is not set. | `<_.Text>`. `<Text>` renders as `$null`. | +| Scalar `'alpha'` | `$_` | `<_>` | - # Configuration data generation - static [hashtable] CreateConfiguration([string]$Environment = 'Testing', [string]$Application = 'Default') { - return @{ - Environment = $Environment - Application = $Application - Database = @{ - ConnectionString = "Server=db-$($Environment.ToLower()).company.local;Database=$Application;Integrated Security=true" - CommandTimeout = 30 - ConnectionPoolSize = 100 - } - Logging = @{ - Level = if ($Environment -eq 'Production') { 'Information' } else { 'Debug' } - Path = "C:\Logs\$Application" - RetentionDays = if ($Environment -eq 'Production') { 90 } else { 30 } - MaxFileSize = '10MB' - } - Security = @{ - RequireSSL = $Environment -eq 'Production' - SessionTimeout = 1800 - MaxLoginAttempts = 3 - PasswordPolicy = @{ - MinLength = 8 - RequireUppercase = $true - RequireNumbers = $true - RequireSpecialChars = $Environment -eq 'Production' - } - } - Performance = @{ - CacheEnabled = $true - CacheTimeout = 3600 - MaxConcurrentUsers = if ($Environment -eq 'Production') { 1000 } else { 100 } - RequestTimeout = 60000 - } - Features = @{ - FeatureA = $true - FeatureB = $Environment -ne 'Production' # Beta features disabled in prod - FeatureC = $false - Maintenance = $Environment -eq 'Development' - } - } - } +Pester evaluates the text between `<` and `>` as a PowerShell expression, so a name can contain +`<User.Name>` or `<($Left + $Right)>`. - # API Response data generation - static [hashtable] CreateAPIResponse([string]$Type = 'Success', [object]$Data = $null) { - $baseResponse = @{ - Timestamp = Get-Date -Format 'yyyy-MM-ddTHH:mm:ss.fffZ' - RequestId = [System.Guid]::NewGuid().ToString() - Version = '1.0.0' - } - - switch ($Type) { - 'Success' { - $baseResponse.Success = $true - $baseResponse.StatusCode = 200 - $baseResponse.Message = 'Request completed successfully' - $baseResponse.Data = $Data ?? @{ Result = 'Success' } - } - 'Error' { - $baseResponse.Success = $false - $baseResponse.StatusCode = 500 - $baseResponse.Message = 'Internal server error occurred' - $baseResponse.Error = @{ - Code = 'INTERNAL_ERROR' - Details = 'An unexpected error occurred while processing the request' - Timestamp = $baseResponse.Timestamp - } - } - 'NotFound' { - $baseResponse.Success = $false - $baseResponse.StatusCode = 404 - $baseResponse.Message = 'Requested resource not found' - $baseResponse.Error = @{ - Code = 'NOT_FOUND' - Details = 'The requested resource could not be located' - } - } - 'Unauthorized' { - $baseResponse.Success = $false - $baseResponse.StatusCode = 401 - $baseResponse.Message = 'Authentication required' - $baseResponse.Error = @{ - Code = 'UNAUTHORIZED' - Details = 'Valid authentication credentials are required' - } - } - 'ValidationError' { - $baseResponse.Success = $false - $baseResponse.StatusCode = 400 - $baseResponse.Message = 'Validation failed' - $baseResponse.Error = @{ - Code = 'VALIDATION_ERROR' - Details = 'One or more validation errors occurred' - ValidationErrors = @( - @{ Field = 'Email'; Message = 'Invalid email format' } - @{ Field = 'Age'; Message = 'Age must be between 18 and 65' } - ) - } - } - } - - return $baseResponse - } +### Keys That Must Not Be Used - # Database result data generation - static [object[]] CreateDatabaseResults([string]$Table = 'Users', [int]$Count = 10) { - switch ($Table) { - 'Users' { return [TestDataFactory]::CreateUsers($Count) } - 'Servers' { return [TestDataFactory]::CreateServers($Count) } - 'Logs' { return [TestDataFactory]::CreateLogEntries($Count) } - default { - return 1..$Count | ForEach-Object { - @{ - Id = $_ - Name = "Item $_" - Value = "Value $_" - CreatedDate = (Get-Date).AddDays(-((Get-Random -Minimum 1 -Maximum 30))) - } - } - } - } - } +A key MUST NOT have the name of an automatic variable (TST-30, STY-13). PowerShell sets these +variables itself, so the value from the case is lost or the test fails. Measured on Pester 6.2.0: - # Performance baseline data - static [hashtable] CreatePerformanceBaseline([string]$Component = 'General') { - return @{ - Component = $Component - LastUpdated = Get-Date - Baselines = @{ - ExecutionTime = @{ - SingleItem = [TimeSpan]::FromMilliseconds(100) - BatchProcessing = [TimeSpan]::FromSeconds(5) - LargeDataset = [TimeSpan]::FromMinutes(2) - } - MemoryUsage = @{ - Baseline = 50MB - Maximum = 200MB - PerItem = 1KB - } - Throughput = @{ - ItemsPerSecond = 100 - RequestsPerMinute = 6000 - ConcurrentUsers = 50 - } - } - } - } +| Key | What happens | Use instead | +| --- | --- | --- | +| `Input` | The test receives an empty enumerator. | `Text`, `InputObject`, `Value` | +| `Args` | The test receives the argument list of the test script block. | `Arguments`, `ArgumentList` | +| `Matches` | The value is replaced by the next `-match` in the test. | `ExpectedMatch` | +| `Host`, `PID` | The test fails: `Cannot overwrite variable Host because it is read-only or constant`. | `ComputerName`, `ProcessId` | - # Helper methods - static [string] GetRandomFirstName() { - $names = @('John', 'Jane', 'Michael', 'Sarah', 'David', 'Lisa', 'Robert', 'Maria', 'James', 'Jennifer', - 'William', 'Patricia', 'Richard', 'Elizabeth', 'Charles', 'Linda', 'Joseph', 'Barbara', - 'Thomas', 'Susan', 'Christopher', 'Jessica', 'Daniel', 'Karen', 'Matthew', 'Nancy') - return Get-Random -InputObject $names - } +The other names in STY-13, such as `Error` and `Event`, are not allowed either, even where a simple +test happens to pass with them. - static [string] GetRandomLastName() { - $names = @('Smith', 'Johnson', 'Williams', 'Brown', 'Jones', 'Garcia', 'Miller', 'Davis', 'Rodriguez', - 'Martinez', 'Hernandez', 'Lopez', 'Gonzalez', 'Wilson', 'Anderson', 'Thomas', 'Taylor', - 'Moore', 'Jackson', 'Martin', 'Lee', 'Perez', 'Thompson', 'White', 'Harris', 'Sanchez') - return Get-Random -InputObject $names - } +```powershell +# Non-compliant: $Input is an automatic variable, so the function receives nothing. +It 'Converts <Input>' -ForEach @( + @{ Input = 'alpha'; Expected = 'ALPHA' } +) { + ConvertTo-UpperText -Text $Input | Should-Be $Expected +} - static [object[]] CreateLogEntries([int]$Count) { - $levels = @('Information', 'Warning', 'Error', 'Debug', 'Verbose') - $sources = @('Application', 'Security', 'System', 'Database', 'Network') - $messages = @( - 'User login successful', - 'Database connection established', - 'Configuration updated', - 'Performance threshold exceeded', - 'Security scan completed', - 'Backup operation started', - 'Service restart initiated', - 'Data synchronization completed' - ) +# Compliant +It 'Converts <Text> to <Expected>' -ForEach @( + @{ Text = 'alpha'; Expected = 'ALPHA' } +) { + ConvertTo-UpperText -Text $Text | Should-Be $Expected +} +``` - return 1..$Count | ForEach-Object { - @{ - Id = $_ - Timestamp = (Get-Date).AddMinutes(-((Get-Random -Minimum 1 -Maximum 1440))) # Last 24 hours - Level = Get-Random -InputObject $levels - Source = Get-Random -InputObject $sources - Message = Get-Random -InputObject $messages - UserId = if ((Get-Random -Minimum 1 -Maximum 100) -gt 30) { Get-Random -Minimum 1 -Maximum 50 } else { $null } - CorrelationId = [System.Guid]::NewGuid().ToString() - } - } - } +## Deterministic Data - # Clear cache - static [void] ClearCache() { - [TestDataFactory]::Cache = @{} - } +Tests MUST NOT depend on the current time or on values that change between runs (TST-31). - # Save data to file - static [void] SaveTestData([string]$Name, [object]$Data, [string]$Format = 'JSON') { - $filePath = Join-Path ([TestDataFactory]::DataPath) "Generated\$Name.$($Format.ToLower())" - - # Ensure directory exists - $directory = Split-Path $filePath -Parent - if (-not (Test-Path $directory)) { - New-Item -Path $directory -ItemType Directory -Force | Out-Null - } - - switch ($Format.ToUpper()) { - 'JSON' { - $Data | ConvertTo-Json -Depth 10 | Out-File $filePath -Encoding UTF8 - } - 'CSV' { - $Data | Export-Csv $filePath -NoTypeInformation -Encoding UTF8 - } - 'PSD1' { - "@{" | Out-File $filePath -Encoding UTF8 - $Data.GetEnumerator() | ForEach-Object { - " $($_.Key) = '$($_.Value)'" | Out-File $filePath -Append -Encoding UTF8 - } - "}" | Out-File $filePath -Append -Encoding UTF8 - } - 'XML' { - $Data | Export-Clixml $filePath - } - } +- Cases for `-ForEach` are fixed values. Do not build them with `Get-Random`, `Get-Date`, or + `[guid]::NewGuid()`: the test names would change on every run, and a failure could not be matched + with an earlier one. +- When the code under test reads the clock, mock `Get-Date`. +- When the code under test needs a unique value, pass a fixed one from the test. + +```powershell +Describe 'Test-ReportStale' -Tag 'Unit' { + BeforeAll { + Mock -CommandName Get-Date -ModuleName ModuleName -MockWith { [datetime]::new(2026, 3, 31) } } -} -# Convenience functions -function New-TestUsers { - param([int]$Count = 5, [string]$Type = 'Standard') - return [TestDataFactory]::CreateUsers($Count, $Type) -} + It 'Returns <Expected> for a report written on day <Day> of March 2026' -ForEach @( + @{ Day = 30; Expected = $false } + @{ Day = 1; Expected = $true } + ) { + $written = [datetime]::new(2026, 3, $Day) -function New-TestServers { - param([int]$Count = 10, [string]$Environment = 'Mixed') - return [TestDataFactory]::CreateServers($Count, $Environment) + Test-ReportStale -LastWriteTime $written -MaximumAgeDays 7 | Should-Be $Expected + } } +``` -function New-TestConfiguration { - param([string]$Environment = 'Testing', [string]$Application = 'Default') - return [TestDataFactory]::CreateConfiguration($Environment, $Application) -} +## Data Files -function New-TestAPIResponse { - param([string]$Type = 'Success', [object]$Data = $null) - return [TestDataFactory]::CreateAPIResponse($Type, $Data) -} +Keep fixed data beside the tests: -function New-TestCredential { - param([string]$Username = 'testuser', [string]$Password = 'TestPassword123!') - return New-Object PSCredential($Username, (ConvertTo-SecureString $Password -AsPlainText -Force)) -} +```text +Tests/ +|-- TestData/ +| |-- server-cases.psd1 cases for -ForEach +| |-- users.json input that the code under test reads +| `-- api-responses.json responses that mocks return +`-- TestHelpers/ + `-- TestData.ps1 functions that build test objects +``` -function New-MockDateTime { - param([string]$BaseDate = '2024-01-01', [int]$DaysRange = 30) - $base = [DateTime]::Parse($BaseDate) - return $base.AddDays((Get-Random -Minimum 0 -Maximum $DaysRange)) -} +A `.psd1` file suits cases, because `Import-PowerShellDataFile` returns hashtables without running +code: -function Clear-TestDataCache { - [TestDataFactory]::ClearCache() +```powershell +# Tests/TestData/server-cases.psd1 +@{ + Cases = @( + @{ ComputerName = 'web01'; Reachable = $true; Expected = 'Healthy' } + @{ ComputerName = 'web02'; Reachable = $false; Expected = 'Unreachable' } + ) } ``` -## Static Test Data Files - -### Configuration Files - ```powershell -# TestData/Configurations/testing.psd1 -@{ - Environment = 'Testing' - Database = @{ - Server = 'test-db.company.local' - Database = 'TestDB' - Timeout = 30 - ConnectionPoolSize = 10 - } - Logging = @{ - Level = 'Debug' - Path = 'C:\Logs\Testing' - RetentionDays = 7 - } - Security = @{ - RequireSSL = $false - SessionTimeout = 3600 - MaxLoginAttempts = 5 - } - Features = @{ - DebugMode = $true - MockData = $true - PerformanceProfiling = $true - } +BeforeDiscovery { + $testsRoot = Split-Path -Path $PSScriptRoot -Parent + $dataPath = Join-Path -Path $testsRoot -ChildPath 'TestData' + $data = Import-PowerShellDataFile -LiteralPath (Join-Path -Path $dataPath -ChildPath 'server-cases.psd1') + $serverCases = $data.Cases } ``` -### Sample Data Files +A JSON file suits input that the code under test parses, and responses that a mock returns: ```json -// TestData/SampleData/users.json [ { "id": 1, - "firstName": "John", - "lastName": "Doe", - "email": "john.doe@company.com", - "department": "IT", - "active": true, - "roles": ["User", "Developer"] + "userName": "ann", + "department": "Finance", + "active": true }, { "id": 2, - "firstName": "Jane", - "lastName": "Smith", - "email": "jane.smith@company.com", - "department": "HR", - "active": true, - "roles": ["User", "Manager"] + "userName": "bob", + "department": "Operations", + "active": false } ] ``` -## Test Data Best Practices +```powershell +BeforeAll { + $testsRoot = Split-Path -Path $PSScriptRoot -Parent + $dataPath = Join-Path -Path $testsRoot -ChildPath 'TestData' + $userJson = Get-Content -LiteralPath (Join-Path -Path $dataPath -ChildPath 'users.json') -Raw + $users = ConvertFrom-Json -InputObject $userJson +} +``` + +Pass the text with `-InputObject` and assign the result. On Windows PowerShell 5.1, +`$userJson | ConvertFrom-Json` sends a JSON array down the pipeline as one object, so wrapping that +pipeline in `@()` gives an array with one element. + +Treat the files under `TestData` as read-only. A test that has to change a file copies it to +`$TestDrive` first. Data files MUST NOT contain real secrets or personal data (SEC-01). + +## Files That a Test Creates -### Data Isolation +Files that a test creates go in `$TestDrive` (TST-03). Measured on Pester 6.2.0: + +- Each test file gets its own `$TestDrive` folder, so files do not leak from one test file to + another. +- A file is removed when the block that created it ends. A file created in a `Describe`-level + `BeforeAll` exists for the whole `Describe` block. A file created inside an `It` exists until the + enclosing `Context` or `Describe` ends, so a later `It` in the same block can still see it. +- `$TestDrive` holds a real file system path, so it also works with .NET methods and native + programs. The `TestDrive:` drive points at the same folder. + +Create the files in `BeforeAll` or `BeforeEach`, not in one test for use by another (TST-31): ```powershell -BeforeEach { - # Create isolated test data for each test. - $script:TestUsers = New-TestUsers -Count 3 -Type 'Standard' - $script:TestConfig = New-TestConfiguration -Environment 'Testing' +Describe 'Import-UserList' -Tag 'Unit' { + BeforeAll { + $userFile = Join-Path -Path $TestDrive -ChildPath 'users.json' + $json = '[{ "userName": "ann" }, { "userName": "bob" }]' + Set-Content -LiteralPath $userFile -Value $json -Encoding ascii + } + + It 'Reads every user in the file' { + $result = @(Import-UserList -LiteralPath $userFile) + + $result | Should-BeCollection -Count 2 + $result[0].UserName | Should-Be 'ann' + $result[1].UserName | Should-Be 'bob' + } } +``` + +A test that changes anything outside `$TestDrive` restores it (TST-31): + +```powershell +Describe 'Get-DeploymentRegion' -Tag 'Unit' { + BeforeAll { + $originalRegion = $env:DEPLOYMENT_REGION + $env:DEPLOYMENT_REGION = 'westeurope' + } + + AfterAll { + $env:DEPLOYMENT_REGION = $originalRegion + } -AfterEach { - # Clean up test data - Clear-TestDataCache - Remove-Variable -Name 'TestUsers', 'TestConfig' -Scope Script -ErrorAction SilentlyContinue + It 'Reads the region from the environment' { + Get-DeploymentRegion | Should-Be 'westeurope' + } } ``` -The `TestDataFactory` cache is **per-runspace**. Under `Run.Parallel` each test file gets its own -runspace and therefore its own cache, so cached data is never shared between files. Do not rely on -one file warming the cache for another - that was already fragile in Pester 5 and is impossible in -a parallel v6 run. +## Functions That Build Test Objects -Use `TestDrive:` for file-based test data rather than `$env:TEMP`. Pester creates and removes it per -container, so it is isolated between files even under parallel: +When many tests need the same kind of object, write a small function that builds it from fixed +defaults, and let each test pass only the values it cares about. Keep the function free of random +values and of the clock. Comment-based help is omitted here to keep the example short. ```powershell -BeforeAll { - $dataFile = Join-Path $TestDrive 'users.json' - New-TestUsers -Count 3 | ConvertTo-Json | Set-Content $dataFile +# Tests/TestHelpers/TestData.ps1 + + +function New-TestUser { + [Diagnostics.CodeAnalysis.SuppressMessageAttribute( + 'PSUseShouldProcessForStateChangingFunctions', '', + Justification = 'Creates an object in memory and changes no state.')] + [CmdletBinding()] + [OutputType('Test.User')] + param( + [Parameter(Mandatory)] + [string]$UserName, + + [string]$Department = 'Operations', + + [switch]$Disabled + ) + + [PSCustomObject]@{ + PSTypeName = 'Test.User' + UserName = $UserName + Department = $Department + Enabled = -not $Disabled + MailAddress = "$UserName@example.com" + } } ``` -### Data Validation +PSScriptAnalyzer reports `PSUseShouldProcessForStateChangingFunctions` for any function whose verb is +`New`. The attribute records why the rule does not apply here. + +Dot-source the file in the top-level `BeforeAll` of each test file that uses it, or in the +`BeforeAll` of a shared setup file. A function that `-ForEach` data needs is dot-sourced in +`BeforeDiscovery` as well. ```powershell -function Test-TestDataIntegrity { - param([object[]]$Data, [string]$Type) - - switch ($Type) { - 'Users' { - $Data | Should-All { $null -ne $_.Id } - $Data | Should-All { $_.Email -match '^[^@]+@[^@]+\.[^@]+$' } - $Data | Should-All { -not [string]::IsNullOrWhiteSpace($_.FirstName) } - $Data | Should-All { -not [string]::IsNullOrWhiteSpace($_.LastName) } - } - 'Servers' { - $Data | Should-All { -not [string]::IsNullOrWhiteSpace($_.Name) } - $Data | Should-All { $_.IPAddress -match '^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$' } - # Should -BeIn has no direct Should-* equivalent - test membership in the filter - $Data | Should-All { $_.Environment -in @('Production', 'Development', 'Testing', 'Staging') } - } +BeforeAll { + $testsRoot = Split-Path -Path $PSScriptRoot -Parent + $helperPath = Join-Path -Path $testsRoot -ChildPath 'TestHelpers' + . (Join-Path -Path $helperPath -ChildPath 'TestData.ps1') +} + +Describe 'Get-UserSummary' -Tag 'Unit' { + It 'Describes a disabled user as inactive' { + $user = New-TestUser -UserName 'ann' -Disabled + + Get-UserSummary -User $user | Should-Be 'ann (inactive)' } } ``` -`Should-All` reports which item failed and why, where a `foreach` loop of individual assertions -stops at the first failure and does not tell you the index. +## Credentials in Test Data -### Performance Test Data +A password MUST NOT be written in a test file or a data file, and +`ConvertTo-SecureString -AsPlainText` MUST NOT be applied to a literal (SEC-01, SEC-04). When a test +needs a `PSCredential` object only to pass it to the code under test, build one from a value created +at run time: ```powershell -function New-PerformanceTestData { - param([int]$ItemCount = 1000, [string]$DataType = 'Users') - - # Generate large datasets for performance testing - $data = switch ($DataType) { - 'Users' { - 1..$ItemCount | ForEach-Object { - [TestDataFactory]::CreateUsers(1, 'Standard')[0] - } - } - 'LargeText' { - 1..$ItemCount | ForEach-Object { - @{ - Id = $_ - Content = 'Lorem ipsum dolor sit amet ' * 100 # ~2KB per item - Timestamp = Get-Date - } - } - } +BeforeAll { + $password = [System.Security.SecureString]::new() + foreach ($character in [guid]::NewGuid().ToString('N').ToCharArray()) { + $password.AppendChar($character) } - - return $data + $testCredential = [System.Management.Automation.PSCredential]::new('test-user', $password) } ``` -### Secure Test Data +The tests assert on the user name or on the call that received the credential, never on the +password. A test that needs a real secret is an integration test, and the secret comes from the CI +system (CIC-06). + +## Checking a Data Set + +To assert something about every item in a collection, assert the count and then use `Should-All` +(TST-12): ```powershell -function New-SecureTestCredentials { - param([int]$Count = 5) - - # Generate test credentials with secure handling - return 1..$Count | ForEach-Object { - @{ - Username = "testuser$_" - Credential = New-Object PSCredential("testuser$_", (ConvertTo-SecureString "TestPass$_!" -AsPlainText -Force)) - Permissions = @('Read', 'Write', 'Execute') - ExpirationDate = (Get-Date).AddDays(30) - } - } +It 'Loads three users that all have a name and a known department' { + $users | Should-BeCollection -Count 3 + $users | Should-All { -not [string]::IsNullOrWhiteSpace($_.userName) } + $users | Should-All { $_.department -in 'Finance', 'Operations' } } ``` + +`Should-All` fails for an empty collection and names the items that did not pass the filter. A +`foreach` loop with an assertion inside it passes when the collection is empty, because the +assertion never runs. + +## Data in Parallel Runs + +In a parallel run each test file has its own runspace. A `$script:` variable, a cache in a helper, +or a loaded module in one file is not visible in another, and each file has its own `$TestDrive`. +Data that follows this guide needs no change for a parallel run. See +[Test Execution Guide](./test-execution.md#parallel-test-execution). diff --git a/.github/instructions/pester-supporting-docs/test-execution.md b/.github/instructions/pester-supporting-docs/test-execution.md index 15dd6d9..5960ab1 100644 --- a/.github/instructions/pester-supporting-docs/test-execution.md +++ b/.github/instructions/pester-supporting-docs/test-execution.md @@ -1,872 +1,274 @@ # Test Execution Guide -Targets **Pester 6.2+** on Windows PowerShell 5.1 or PowerShell 7.4+. +This guide covers how to run tests, how to read the result, and the two experimental run modes, +parallel and shuffled. It supports rules TST-40 to TST-42 in +[powershell-pester.instructions.md](../powershell-pester.instructions.md). The behaviour described +here was checked on Pester 6.2.0 under PowerShell 7.6 and Windows PowerShell 5.1. -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. +## Loading the Right Pester Version -## Comprehensive Test Runner Script - -Create a standardized test execution script for consistent testing across environments: +A test file declares the minimum version with `#Requires` (TST-01). That line does not choose +between installed versions, and Windows PowerShell 5.1 ships with Pester 3.4.0. Install the version +the standard targets and import exactly that version before a run: ```powershell -# Invoke-Tests.ps1 -#Requires -Version 5.1 -[CmdletBinding()] -param( - [ValidateSet('Unit', 'Integration', 'Performance', 'Security', 'All')] - [string]$TestType = 'All', - - [ValidateSet('Development', 'CI', 'Production')] - [string]$Environment = 'Development', - - [string]$OutputPath = './Tests/Results', - [switch]$CodeCoverage, - [switch]$PassThru, - [switch]$ShowReport, - [string[]]$Tag = @(), - [string[]]$ExcludeTag = @(), - - # EXPERIMENTAL: run test files concurrently, one file per runspace. - # Runs on Windows PowerShell 5.1 and PowerShell 7 alike from Pester 6.2. - [switch]$Parallel, - [int]$ThrottleLimit = 0, # 0 = use all available processors - - # EXPERIMENTAL: randomize file/block/test order to surface order dependence. - [switch]$Shuffle, - [int]$ShuffleSeed = 0 # 0 = new seed each run, printed at the start -) - -begin { - Write-Host "PowerShell Test Execution Framework" -ForegroundColor Cyan - Write-Host "Test Type: $TestType | Environment: $Environment" -ForegroundColor Green - - # Pester 6.2 is required - Should-* assertions, New-ShouldAssertion, the parallel - # runner, Run.Shuffle, and BeforeAll in Pester.BeforeContainer.ps1 are not all - # present in earlier versions - $pester = Get-Module Pester -ListAvailable | - Sort-Object Version -Descending | Select-Object -First 1 - - if (-not $pester -or $pester.Version -lt [version]'6.2.0') { - Write-Error "Pester 6.2+ is required (found: $(if ($pester) { $pester.Version } else { 'none' })). Install with: Install-Module Pester -MinimumVersion 6.2.0 -Force" - exit 1 - } - Import-Module Pester -MinimumVersion 6.2.0 -Force - - # Ensure output directory exists - if (-not (Test-Path $OutputPath)) { - New-Item -Path $OutputPath -ItemType Directory -Force | Out-Null - } - - # Import test configuration - $configPath = Join-Path $PSScriptRoot "PesterConfiguration.$Environment.psd1" - if (-not (Test-Path $configPath)) { - $configPath = Join-Path $PSScriptRoot "PesterConfiguration.psd1" - } - - if (Test-Path $configPath) { - $configData = Import-PowerShellDataFile $configPath - $config = New-PesterConfiguration -Hashtable $configData - } else { - $config = New-PesterConfiguration - } -} - -process { - try { - $timestamp = Get-Date -Format 'yyyyMMdd-HHmmss' - - # Configure test execution based on type - switch ($TestType) { - 'Unit' { - $config.Run.Path = @('./Tests/Unit') - $config.Filter.Tag = @('Unit') - Write-Host "Executing Unit Tests..." -ForegroundColor Yellow - } - 'Integration' { - $config.Run.Path = @('./Tests/Integration') - $config.Filter.Tag = @('Integration') - Write-Host "Executing Integration Tests..." -ForegroundColor Yellow - } - 'Performance' { - $config.Run.Path = @('./Tests/Performance') - $config.Filter.Tag = @('Performance') - Write-Host "Executing Performance Tests..." -ForegroundColor Yellow - } - 'Security' { - $config.Run.Path = @('./Tests/Security') - $config.Filter.Tag = @('Security') - Write-Host "Executing Security Tests..." -ForegroundColor Yellow - } - 'All' { - $config.Run.Path = @('./Tests/Unit', './Tests/Integration', './Tests/Performance', './Tests/Security') - Write-Host "Executing All Tests..." -ForegroundColor Yellow - } - } - - # Apply additional tag filtering - if ($Tag) { - $config.Filter.Tag = @($config.Filter.Tag.Value) + $Tag - } - if ($ExcludeTag) { - $config.Filter.ExcludeTag = $ExcludeTag - } - - $config.Run.PassThru = $true - - # Configure code coverage - if ($CodeCoverage) { - $config.CodeCoverage.Enabled = $true - $config.CodeCoverage.OutputPath = Join-Path $OutputPath "Coverage-$TestType-$timestamp.xml" - Write-Host "Code coverage enabled (profiler-based)" -ForegroundColor Green - } - - # Configure parallel execution - if ($Parallel) { - if ($TestType -in 'Performance', 'Integration') { - Write-Warning "$TestType tests should not run in parallel; ignoring -Parallel." - } - else { - $config.Run.Parallel = $true - $config.Run.ParallelThrottleLimit = $ThrottleLimit - $limitText = if ($ThrottleLimit -eq 0) { 'all processors' } else { "$ThrottleLimit files" } - Write-Host "Parallel execution enabled (throttle: $limitText)" -ForegroundColor Green - - # Pester 6.1 collects coverage under parallel, but forces breakpoint mode - # to do it - which is far slower per file than the profiler tracer. - if ($CodeCoverage) { - Write-Warning "Coverage under -Parallel uses breakpoints, not the profiler. Expect it to be slower than a sequential coverage run." - } - } - } - - # Configure shuffled execution order - if ($Shuffle) { - if ($TestType -eq 'Performance') { - Write-Warning "Performance baselines assume a fixed order; ignoring -Shuffle." - } - else { - $config.Run.Shuffle = $true - if ($ShuffleSeed -ne 0) { - $config.Run.ShuffleSeed = $ShuffleSeed - Write-Host "Shuffled execution replaying seed $ShuffleSeed" -ForegroundColor Green - } else { - Write-Host "Shuffled execution enabled (seed printed below)" -ForegroundColor Green - } - } - } - - # Configure test results output - $config.TestResult.Enabled = $true - $config.TestResult.OutputPath = Join-Path $OutputPath "TestResults-$TestType-$timestamp.xml" - - # Set environment-specific verbosity - if ($Environment -eq 'CI') { - $config.Output.Verbosity = 'Normal' - $config.Output.CIFormat = 'Auto' - } else { - $config.Output.Verbosity = 'Detailed' - } - - # Execute tests - $startTime = Get-Date - Write-Host "Test execution started at $($startTime.ToString('yyyy-MM-dd HH:mm:ss'))" -ForegroundColor Gray - - $result = Invoke-Pester -Configuration $config - - $endTime = Get-Date - $duration = $endTime - $startTime - - # Generate comprehensive summary - Write-Host "`nTest Execution Summary:" -ForegroundColor Green - Write-Host " Environment: $Environment" -ForegroundColor Gray - Write-Host " Test Type: $TestType" -ForegroundColor Gray - Write-Host " Duration: $($duration.ToString('hh\:mm\:ss'))" -ForegroundColor Gray - Write-Host " Total Tests: $($result.TotalCount)" -ForegroundColor White - Write-Host " Passed: $($result.PassedCount)" -ForegroundColor Green - Write-Host " Failed: $($result.FailedCount)" -ForegroundColor $(if ($result.FailedCount -gt 0) { 'Red' } else { 'Green' }) - Write-Host " Skipped: $($result.SkippedCount)" -ForegroundColor Yellow - Write-Host " Inconclusive: $($result.InconclusiveCount)" -ForegroundColor Yellow - Write-Host " Not Run: $($result.NotRunCount)" -ForegroundColor Gray - - # Code coverage summary. - # Pester 5/6 property names: CoveragePercent, CommandsExecutedCount, - # CommandsAnalyzedCount. The Pester 4 names (CoveredPercent, - # NumberOfCommandsExecuted) do not exist and silently return $null. - if ($CodeCoverage -and $result.CodeCoverage) { - $coveragePercent = [math]::Round($result.CodeCoverage.CoveragePercent, 2) - $coverageTarget = $result.CodeCoverage.CoveragePercentTarget - $coverageColor = if ($coveragePercent -ge $coverageTarget) { 'Green' } - elseif ($coveragePercent -ge ($coverageTarget * 0.75)) { 'Yellow' } - else { 'Red' } - Write-Host " Code Coverage: $coveragePercent% (target $coverageTarget%)" -ForegroundColor $coverageColor - Write-Host " Commands Covered: $($result.CodeCoverage.CommandsExecutedCount)" -ForegroundColor Gray - Write-Host " Commands Total: $($result.CodeCoverage.CommandsAnalyzedCount)" -ForegroundColor Gray - Write-Host " Files Analyzed: $($result.CodeCoverage.FilesAnalyzedCount)" -ForegroundColor Gray - } - - # Performance summary for performance tests. - # Test.Duration is a TimeSpan - use .TotalMilliseconds, not the raw object. - if ($TestType -eq 'Performance' -or $TestType -eq 'All') { - Write-Host "`nPerformance Summary:" -ForegroundColor Cyan - $performanceTests = $result.Tests | Where-Object { $_.Tag -contains 'Performance' } - if ($performanceTests) { - $avgMs = ($performanceTests.Duration.TotalMilliseconds | Measure-Object -Average).Average - Write-Host " Average Test Duration: $([math]::Round($avgMs, 2))ms" -ForegroundColor Gray - - $slowTests = $performanceTests | - Where-Object { $_.Duration.TotalSeconds -gt 5 } | - Sort-Object { $_.Duration } -Descending - if ($slowTests) { - Write-Host " WARNING - Slow Tests (>5s):" -ForegroundColor Yellow - $slowTests | ForEach-Object { - Write-Host " - $($_.ExpandedPath): $([math]::Round($_.Duration.TotalSeconds, 2))s" -ForegroundColor Yellow - } - } - } - } - - # Failed test details - if ($result.FailedCount -gt 0) { - Write-Host "`nFailed Tests:" -ForegroundColor Red - foreach ($test in $result.Failed) { - Write-Host " - $($test.ExpandedPath)" -ForegroundColor Red - Write-Host " Error: $($test.ErrorRecord.Exception.Message)" -ForegroundColor Red - - # Include troubleshooting hints - $hint = Get-TroubleshootingHint -TestName $test.Name -ErrorRecord $test.ErrorRecord - if ($hint) { - Write-Host " Hint: $hint" -ForegroundColor Cyan - } - } - } - - # Report containers that failed to discover. This is a v6 failure mode - # (empty -ForEach, or a file that cannot be discovered independently) - # and it does NOT show up in FailedCount - - # a suite can report 0 failed tests while whole files never ran. - if ($result.FailedContainersCount -gt 0) { - Write-Host "`nFailed Containers (discovery or setup errors):" -ForegroundColor Red - $result.FailedContainers | ForEach-Object { - Write-Host " - $($_.Item)" -ForegroundColor Red - if ($_.ErrorRecord) { - Write-Host " $($_.ErrorRecord.Exception.Message)" -ForegroundColor Red - } - } - } - - # Generate test report - if ($ShowReport) { - $reportPath = Join-Path $OutputPath "TestReport-$TestType-$timestamp.html" - New-TestReport -TestResult $result -OutputPath $reportPath -CodeCoverage:$CodeCoverage - Write-Host "`nTest report generated: $reportPath" -ForegroundColor Green - } - - # Export metrics for trending - $metrics = @{ - TestType = $TestType - Environment = $Environment - Timestamp = Get-Date -Format 'o' - Duration = $duration.TotalSeconds - TotalTests = $result.TotalCount - PassedTests = $result.PassedCount - FailedTests = $result.FailedCount - SkippedTests = $result.SkippedCount - CodeCoverage = if ($result.CodeCoverage) { $result.CodeCoverage.CoveragePercent } else { $null } - Parallel = [bool]$config.Run.Parallel.Value - # Record the seed. A shuffle failure is only reproducible if the seed - # outlives the console log. - Shuffle = [bool]$config.Run.Shuffle.Value - ShuffleSeed = $result.Configuration.Run.ShuffleSeed.Value - PesterVersion = $pester.Version.ToString() - PowerShellVersion = $PSVersionTable.PSVersion.ToString() - Platform = $PSVersionTable.Platform - } - - $metricsPath = Join-Path $OutputPath "TestMetrics-$TestType-$timestamp.json" - $metrics | ConvertTo-Json | Out-File $metricsPath -Encoding UTF8 - - # Handle CI/CD integration - if ($Environment -eq 'CI') { - # GitHub Actions step outputs. - # ::set-output was disabled by GitHub in 2023 - write to $GITHUB_OUTPUT. - if ($env:GITHUB_OUTPUT) { - "total-tests=$($result.TotalCount)" | Out-File $env:GITHUB_OUTPUT -Append -Encoding utf8 - "passed-tests=$($result.PassedCount)" | Out-File $env:GITHUB_OUTPUT -Append -Encoding utf8 - "failed-tests=$($result.FailedCount)" | Out-File $env:GITHUB_OUTPUT -Append -Encoding utf8 - if ($result.CodeCoverage) { - "code-coverage=$($result.CodeCoverage.CoveragePercent)" | Out-File $env:GITHUB_OUTPUT -Append -Encoding utf8 - } - } - - # GitHub Actions job summary - if ($env:GITHUB_STEP_SUMMARY) { - $summary = @( - "## Test Results - $TestType" - '' - '| Metric | Value |' - '| --- | --- |' - "| Total | $($result.TotalCount) |" - "| Passed | $($result.PassedCount) |" - "| Failed | $($result.FailedCount) |" - "| Skipped | $($result.SkippedCount) |" - ) -join "`n" - $summary | Out-File $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8 - } - - # Azure DevOps variables - if ($env:BUILD_BUILDID) { - Write-Host "##vso[task.setvariable variable=TotalTests]$($result.TotalCount)" - Write-Host "##vso[task.setvariable variable=PassedTests]$($result.PassedCount)" - Write-Host "##vso[task.setvariable variable=FailedTests]$($result.FailedCount)" - if ($result.CodeCoverage) { - Write-Host "##vso[task.setvariable variable=CodeCoverage]$($result.CodeCoverage.CoveragePercent)" - } - } - } - - # Return result for further processing - if ($PassThru) { - return $result - } - - # Exit with appropriate code. Check container failures too - a file that - # failed discovery contributes 0 to FailedCount. - if ($result.FailedCount -gt 0 -or $result.FailedContainersCount -gt 0) { - Write-Host "`nTests failed. Exiting with code 1." -ForegroundColor Red - exit 1 - } else { - Write-Host "`nAll tests passed successfully." -ForegroundColor Green - exit 0 - } - } - catch { - Write-Host "`nTest execution failed: $($_.Exception.Message)" -ForegroundColor Red - Write-Host $_.ScriptStackTrace -ForegroundColor Gray - - if ($PassThru) { - throw - } else { - exit 1 - } - } -} - -end { - Write-Host "`nCleaning up test environment..." -ForegroundColor Gray -} - -# Helper functions -function Get-TroubleshootingHint { - param( - [string]$TestName, - # Do not name this parameter $Error - that shadows the automatic variable - [System.Management.Automation.ErrorRecord]$ErrorRecord - ) - - $hints = [ordered]@{ - 'Connection' = 'Check network connectivity and firewall settings. See ./Troubleshooting/Connectivity/' - 'Authentication' = 'Verify credentials and permissions. See ./Troubleshooting/Security/' - 'Permission' = 'Run as administrator or check file permissions. See ./Troubleshooting/Security/' - 'Memory' = 'Increase available memory or optimize code. See ./Troubleshooting/Performance/' - 'Timeout' = 'Increase timeout values or optimize performance. See ./Troubleshooting/Performance/' - 'not recognized' = 'Command not found. In Pester 6 each test file must import its own modules - check BeforeAll/BeforeDiscovery.' - 'ForEach' = 'Empty -ForEach fails discovery in Pester 6. Build test data in BeforeDiscovery, not BeforeAll.' - 'Assert-Mock' = 'Assert-MockCalled was removed in Pester 6. Use Should -Invoke or Should-Invoke.' - 'to measure or a' = 'Should-BeFasterThan/SlowerThan need a scriptblock or a timespan (Pester 6.2). Pipe the scriptblock, not its result.' - } - - foreach ($keyword in $hints.Keys) { - if ($ErrorRecord.Exception.Message -match [regex]::Escape($keyword) -or $TestName -match [regex]::Escape($keyword)) { - return $hints[$keyword] - } - } - - return "Check ./Troubleshooting/ folder for detailed guidance" -} - -function New-TestReport { - param( - [object]$TestResult, - [string]$OutputPath, - [switch]$CodeCoverage - ) - - $rows = foreach ($test in $TestResult.Tests) { - $resultClass = switch ($test.Result) { - 'Passed' { 'test-passed' } - 'Failed' { 'test-failed' } - default { '' } - } - $errorMessage = if ($test.ErrorRecord) { - [System.Web.HttpUtility]::HtmlEncode($test.ErrorRecord.Exception.Message) - } else { '' } - $name = [System.Web.HttpUtility]::HtmlEncode($test.ExpandedPath) - - @" - <tr class="$resultClass"> - <td>$name</td> - <td class="$($test.Result.ToLower())">$($test.Result)</td> - <td>$([math]::Round($test.Duration.TotalMilliseconds, 2))ms</td> - <td>$errorMessage</td> - </tr> -"@ - } - - $coverageRow = if ($CodeCoverage -and $TestResult.CodeCoverage) { - "<p><strong>Code Coverage:</strong> $([math]::Round($TestResult.CodeCoverage.CoveragePercent, 2))%</p>" - } else { '' } - - $html = @" -<!DOCTYPE html> -<html> -<head> - <meta charset="utf-8"> - <title>PowerShell Test Report - - - -

PowerShell Test Report

-
-

Summary

-

Total Tests: $($TestResult.TotalCount)

-

Passed: $($TestResult.PassedCount)

-

Failed: $($TestResult.FailedCount)

-

Skipped: $($TestResult.SkippedCount)

-

Duration: $($TestResult.Duration)

- $coverageRow -
-

Test Results

- - - - - - - -$($rows -join "`n") -
Test NameResultDurationError Message
- - -"@ - - $html | Out-File $OutputPath -Encoding UTF8 -} +Install-PSResource -Name Pester -Version 6.2.0 -TrustRepository +Import-Module -Name Pester -RequiredVersion 6.2.0 ``` -`New-TestReport` uses `[System.Web.HttpUtility]::HtmlEncode`. On PowerShell 7 add -`Add-Type -AssemblyName System.Web` first, or substitute your own encoder - test names and error -messages routinely contain `<`, `>`, and `&` which would otherwise corrupt the report. - -## Result Object Reference - -Pester 6 keeps the v5 result object. The property names below are the ones that exist - the Pester 4 -names in older guidance return `$null` silently. - -| Use | Property | -| --- | --- | -| Counts | `TotalCount`, `PassedCount`, `FailedCount`, `SkippedCount`, `InconclusiveCount`, `NotRunCount` | -| Test collections | `Tests`, `Passed`, `Failed`, `Skipped`, `Inconclusive`, `NotRun` | -| Per-file results | `Containers` (each has `Item`, `Result`, `Passed`, `ErrorRecord`) | -| Setup files applied | `$container.BeforeContainerFile` - the `Pester.BeforeContainer.ps1` files that ran for that file, outermost first (6.2+) | -| Discovery failures | `FailedContainers`, `FailedContainersCount` | -| Block-level failures | `FailedBlocks`, `FailedBlocksCount` | -| Coverage percent | `CodeCoverage.CoveragePercent` (**not** `CoveredPercent`) | -| Coverage target | `CodeCoverage.CoveragePercentTarget` | -| Commands covered | `CodeCoverage.CommandsExecutedCount` (**not** `NumberOfCommandsExecuted`) | -| Commands total | `CodeCoverage.CommandsAnalyzedCount` (**not** `NumberOfCommandsAnalyzed`) | -| Missed commands | `CodeCoverage.CommandsMissed` | -| Test duration | `$test.Duration` - a `TimeSpan`; use `.TotalMilliseconds` | - -`Duration` is a `TimeSpan`. Comparing it against a raw number (`$_.Duration -gt 5000`) does not do -what it looks like - use `$_.Duration.TotalMilliseconds -gt 5000`. - -Pester 6 reports a **single duration** per test instead of the v5 `user|framework` split. - -**Always check `FailedContainersCount` alongside `FailedCount`.** A file that fails discovery -contributes nothing to `FailedCount`, so a gate that only inspects `FailedCount` reports success -while entire test files never ran. This is the most likely way a v6 upgrade passes CI while silently -losing coverage. - -## Quick Execution Commands - -### Development Testing +## Running Tests ```powershell -# Quick unit tests -.\Invoke-Tests.ps1 -TestType Unit -Environment Development - -# Unit tests with coverage -.\Invoke-Tests.ps1 -TestType Unit -CodeCoverage -ShowReport +# Every test file under a folder +Invoke-Pester -Path ./Tests -# Specific tags -.\Invoke-Tests.ps1 -Tag 'Critical' -ExcludeTag 'Slow' +# One file, listing every test +Invoke-Pester -Path ./Tests/Unit/Get-ServerHealth.Tests.ps1 -Output Detailed -# Fast feedback: unit tests in parallel, no coverage -.\Invoke-Tests.ps1 -TestType Unit -Parallel +# By tag +Invoke-Pester -Path ./Tests -TagFilter 'Unit' +Invoke-Pester -Path ./Tests -ExcludeTagFilter 'Integration', 'Slow' -# Surface order dependence, then replay the order that broke -.\Invoke-Tests.ps1 -TestType Unit -Shuffle -.\Invoke-Tests.ps1 -TestType Unit -Shuffle -ShuffleSeed 852659930 +# By name, with wildcards +Invoke-Pester -Path ./Tests -FullNameFilter '*Get-ServerHealth*' ``` -### CI/CD Pipeline Integration +`-Output` takes `None`, `Normal`, `Detailed`, or `Diagnostic`. It also accepts `Minimal`, which +Pester 6 treats as `Normal`. -```powershell -# Full CI test suite -.\Invoke-Tests.ps1 -TestType All -Environment CI -CodeCoverage - -# Performance testing only -.\Invoke-Tests.ps1 -TestType Performance -Environment CI - -# Security validation -.\Invoke-Tests.ps1 -TestType Security -Environment CI -``` - -## Parallel Test Execution (Experimental) +For coverage, reports, or any other option, pass a configuration object; see +[Pester Configuration Guide](./pester-configuration.md). To run exactly what CI runs, call the gate +script that CI calls; see [CI/CD Integration Guide](./cicd-integration.md#the-gate-script). -Pester 6 runs test **files** concurrently, one file per runspace. From 6.2 the workers run on a -runspace pool, which Windows PowerShell 5.1 and PowerShell 7 both have; 6.0 and 6.1 used -`ForEach-Object -Parallel` and so ran sequentially on 5.1. On a multi-core machine this cuts -wall-clock time substantially for large suites. +### Console Output -```powershell -$config = New-PesterConfiguration -$config.Run.Path = './Tests/Unit' -$config.Run.Parallel = $true -$config.Run.ParallelThrottleLimit = 4 # 0 (default) uses all processors -Invoke-Pester -Configuration $config -``` +A run prints one banner, one line for each test file, and one summary: -```powershell -# Via the runner -.\Invoke-Tests.ps1 -TestType Unit -Parallel -ThrottleLimit 4 +```text +Running tests from 4 files. +[+] C:\repo\Tests\Unit\Get-ServerHealth.Tests.ps1 638ms (5 tests) +Tests completed in 1.2s +Tests Passed: 20, Failed: 0, Skipped: 0, Inconclusive: 0, NotRun: 0 ``` -### When It Falls Back to Sequential +A discovery-only run (`Run.SkipRun`) prints `Starting discovery in 4 files.`, +`Discovery found 20 tests in 39ms.`, and `Test run was skipped.` instead. -The run keeps working but emits a **warning** when: +Do not read results from this text. Set `Run.PassThru` and use the result object. -| Condition | Reason | -| --- | --- | -| `ScriptBlock` containers | In-memory containers cannot cross runspaces | -| `Run.SkipRemainingOnFailure = 'Run'` | A cross-file stop cannot span runspaces | -| Windows PowerShell 5.1 on Pester 6.0 or 6.1 | Those releases used `ForEach-Object -Parallel`, a PowerShell 7 feature. 6.2 moved to a runspace pool and runs parallel on 5.1 | +## Result Object Reference -When every file opts out with `#pester:no-parallel` the run is simply sequential and no warning is -printed - there is nothing left to parallelize. +`Invoke-Pester` returns the result object when `Run.PassThru` is set, or with `-PassThru`. -### A Lost File Is an Error +| Use | Property | +| --- | --- | +| Outcome of the run | `Result`: the string `Passed` or `Failed` | +| Counts | `TotalCount`, `PassedCount`, `FailedCount`, `SkippedCount`, `InconclusiveCount`, `NotRunCount` | +| Failures outside tests | `FailedBlocksCount`, `FailedContainersCount` | +| Tests | `Tests`, `Passed`, `Failed`, `Skipped`, `Inconclusive`, `NotRun` | +| Failed setup or teardown blocks | `FailedBlocks` | +| Test files | `Containers`. Each has `Item`, `Result`, `Passed`, `ErrorRecord`, and `BeforeContainerFile`. | +| Test files that failed | `FailedContainers` | +| Coverage percentage | `CodeCoverage.CoveragePercent` | +| Coverage counts | `CodeCoverage.CommandsAnalyzedCount`, `CommandsExecutedCount`, `CommandsMissedCount`, `FilesAnalyzedCount` | +| Commands that did not run | `CodeCoverage.CommandsMissed`. Each has `File`, `Line`, and `Command`. | +| Coverage target | `CodeCoverage.CoveragePercentTarget` | +| Time | `Duration` on the run, on each file, and on each test. It is a `TimeSpan`. | +| Settings the run used | `Configuration` | -A worker that died before returning its result used to disappear from the run - the file was not -failed, skipped, or errored, and the run looked green with one file fewer. From 6.2 the run compares -results to the files it sent and throws naming the missing ones. A worker that throws is reported -and the remaining files still report their results, including when the caller runs with -`$ErrorActionPreference = 'Stop'`, which used to abort the loop at the first failing file and drop -everything already finished. +`CodeCoverage` is `$null` when coverage was not measured. The Pester 4 names `CoveredPercent`, +`NumberOfCommandsExecuted`, and `NumberOfCommandsAnalyzed` do not exist. -### Coverage Under Parallel +`Duration` is a `TimeSpan`, so compare `$test.Duration.TotalMilliseconds` with a number, not +`$test.Duration` itself. The console shows one duration for each test. The result object also has +`UserDuration` and `FrameworkDuration`. -Pester 6.0 collected no coverage in a parallel run. **6.1 collects it**: each worker measures the -same locations and the parent merges the per-location hits, adding the coverage of any -`#pester:no-parallel` files it ran in-session, into a single report. +### What a Failure Looks Like -The catch is that a parallel run forces **breakpoint-based** coverage, because the profiler tracer -keeps its state in a process-global static and is not concurrency-safe. -`CodeCoverage.UseBreakpoints = $false` is ignored on that path. Breakpoint coverage is much slower -per file, so parallel-plus-coverage can easily be slower overall than sequential-plus-profiler. +A failed run does not always have a failed test. Measured on Pester 6.2.0: -Splitting into **two CI jobs** is still the recommendation - a fast parallel job without coverage for -feedback, and a sequential job with the profiler for the coverage gate - but it is now a performance -choice you can measure rather than a hard requirement. +| What happened | `Result` | `FailedCount` | `FailedBlocksCount` | `FailedContainersCount` | +| --- | --- | --- | --- | --- | +| Two tests fail | `Failed` | 2 | 0 | 0 | +| `BeforeAll` throws in a block with one test | `Failed` | 1 | 1 | 0 | +| `AfterAll` throws after the tests passed | `Failed` | 0 | 1 | 0 | +| A file throws during discovery | `Failed` | 0 | 0 | 1 | +| `-ForEach` receives an empty list | `Failed` | 0 | 0 | 1 | +| A file contains no tests | `Passed` | 0 | 0 | 0 | -### Which Files to Opt Out +When no test file is found at all, `Invoke-Pester` writes an error, returns no result object, and +sets `$LASTEXITCODE` to `-1`. -Add `#pester:no-parallel` at the top of any file that cannot share the machine: +This is why the gate tests for a missing result, for `TotalCount`, and for `Result`, and never for +`FailedCount` alone (TST-42): ```powershell -#pester:no-parallel -Describe 'Performance-Baseline' -Tag 'Performance' { +if ($null -eq $result -or $result.TotalCount -eq 0) { + throw 'Pester ran no tests.' } -``` - -- **Performance tests** - timing measurements are meaningless under CPU contention -- **Integration tests** - shared databases, fixed ports, live endpoints -- Tests mutating global state (environment variables, the registry, the working directory) - -Opted-out files run in the parent session on the serial path, with shared session state and live -output, while everything else runs in parallel. - -### Requirements and Guarantees - -Parallel needs **file-based** containers - `Run.Path`, or `New-PesterContainer -Path`, including -parametrized files built with `-Data` (each file's data reaches its worker, so its `param()` block -binds exactly as in a serial run). - -Each worker runs silently and the parent **replays** every file's output in discovery order, -emitting the same plugin-event sequence as a serial run. Console output, the `TestResult` report, -and IDE adapters behave identically - only concurrency differs. -The run's total `Duration` becomes the orchestrator's elapsed time rather than the sum of the files, -and per-phase run totals (user, framework, discovery) are blank. That breakdown is still reported on -each container. - -### Prerequisite: Self-Contained Files - -Parallel only works if each file can be discovered and run on its own, because each worker starts -from a **clean runspace**. Put shared bootstrap in `Pester.BeforeContainer.ps1` files, which Pester -dot-sources before every file in both serial and parallel runs - from 6.2, every one between -`Run.RepoRoot` and the test file's folder. Run-time setup goes in a `BeforeAll`; top-level code in -the file runs at discovery only: - -```powershell -# Pester.BeforeContainer.ps1, at the repository root -BeforeAll { - . "$PSScriptRoot/Tests/TestHelpers/Bootstrap.ps1" +if ($result.Result -ne 'Passed') { + $counts = $result.FailedCount, $result.FailedBlocksCount, $result.FailedContainersCount + $summary = 'Failed tests: {0}. Failed blocks: {1}. Failed files: {2}.' -f $counts + throw "Pester result is '$($result.Result)'. $summary" } ``` -The `Run.BeforeContainer` option that also did this was **removed in 6.1**. If a CI job sets it, the -assignment now throws. - -The chain starts at `Run.RepoRoot`. When unset, 6.2 resolves it from the session's current location -at run time (6.1 used the .NET process working directory, which `Set-Location` does not move). Set -it explicitly when the run does not start inside the repository: +### Messages and Their Causes -```powershell -$config.Run.RepoRoot = $PSScriptRoot -``` +| Message | Cause | +| --- | --- | +| `Value can not be null or empty array` | A `-ForEach` list is empty or `$null`, usually because it was built in `BeforeAll`. Build it in `BeforeDiscovery`. | +| `No mock for command '...' matched the call` | Every mock of the command has a `-ParameterFilter` and none matched. Add a mock without a filter. | +| `A parameter cannot be found that matches parameter name 'Focus'` | `-Focus` does not exist in Pester 6. | +| `Pester Should -Be syntax is disabled` | `Should.DisableV5` is set and the file uses the `Should -Be` style. | +| `Expected a [scriptblock] to measure or a [timespan] to compare` | `Should-BeFasterThan` or `Should-BeSlowerThan` received something else. Pipe the script block. | +| `No test files were found and no scriptblocks were provided` | `Run.Path` points at a folder without test files, or `Run.ExcludePath` removed them all. | +| `CommandNotFoundException` for a helper function | The helper was dot-sourced by another test file, or at the top level of a setup file. | -Validate isolation before enabling parallel - run a single file on its own: +## Checking Structure Without Running Tests -```powershell -Invoke-Pester -Path ./Tests/Unit/Public/Get-Thing.Tests.ps1 -``` +`Run.SkipRun` discovers every file and runs nothing. Use it to find files that fail discovery, and +with `Filter.Tag = 'None'` to find tests without a tag. Both scripts are in +[Pester Test Structure Guide](./test-structure-guide.md#checking-the-structure). -If it only passes as part of a full run, it is not self-contained. +## Parallel Test Execution -## Shuffled Test Order (Experimental) +`Run.Parallel` is experimental and off by default. Do not enable it in a configuration that you +generate unless the user asks. -New in 6.1. `Run.Shuffle` reorders the test files, and the blocks and tests inside them, so a suite -that depends on declaration order fails instead of passing by luck: +With the option on, Pester runs test files at the same time, each file in its own runspace of the +same process. It works on PowerShell 7 and on Windows PowerShell 5.1. In the examples, `$testRoot` +holds the full path of the test folder. ```powershell -$config = New-PesterConfiguration -$config.Run.Path = './Tests/Unit' -$config.Run.Shuffle = $true -Invoke-Pester -Configuration $config -``` +$configuration = New-PesterConfiguration +$configuration.Run.Path = $testRoot +$configuration.Run.Parallel = $true +$configuration.Run.ParallelThrottleLimit = 4 -```powershell -# Via the runner -.\Invoke-Tests.ps1 -TestType Unit -Shuffle +Invoke-Pester -Configuration $configuration ``` -Reordering happens only within a level - a test never leaves its `Context`. The run prints the seed -it picked and records it on the result: +`Run.ParallelThrottleLimit` is the number of files that run at once. The default `0` uses every +processor. `1` does not turn the mode off: the files still run in worker runspaces, one after +another. -```text -Shuffling execution order using seed 852659930. Set 'Run.ShuffleSeed = 852659930' to repeat this order. -``` - -```powershell -$result.Configuration.Run.ShuffleSeed.Value # the seed this run actually used -$config.Run.ShuffleSeed = 852659930 # replay that exact order -``` +In the result object the files are in the same order as in a sequential run. The `Duration` of the +run is the elapsed time, not the sum of the files, and `UserDuration`, `FrameworkDuration`, and +`DiscoveryDuration` of the run are zero. Each file still has its own values. -Order dependence is the failure mode this finds, and it is one the per-file isolation model in -Pester 6 already narrows: files no longer share discovery-time state, so what is left is order -dependence _within_ a file - a `Describe` that leaves a `$script:` variable another one reads, a -`BeforeAll` that creates a fixture a later `Context` mutates. +### When Pester Runs Sequentially Instead -### Reading a Shuffled Failure +| Condition | What Pester does | +| --- | --- | +| A script block container is used (`Run.ScriptBlock`, or `New-PesterContainer -ScriptBlock`) | Warns `Run.Parallel currently parallelizes only file-based runs` and runs sequentially. | +| `Run.SkipRemainingOnFailure = 'Run'` | Warns that skipping after the first failure cannot span the worker runspaces, and runs sequentially. | +| Every file has the `#pester:no-parallel` directive | Runs sequentially without a warning. | -A failure that appears only under shuffle is a real defect in the tests, not a Pester problem. Work -it in this order: +A file passed with `New-PesterContainer -Path`, with or without `-Data`, runs in parallel. -1. Capture the seed from the run output. Without it the ordering is not reproducible. -2. Re-run with `Run.ShuffleSeed` set to that value and confirm the failure repeats. -3. Find the shared state. It is nearly always a `$script:` variable, a file left on disk outside - `TestDrive`, an environment variable, or a mock counter read across blocks. -4. Fix the test, not the order. Move setup into the block that needs it, or reset state in - `AfterEach`. +### Which Files to Opt Out -A file whose blocks genuinely must run in sequence opts out with a directive, parsed the same way as -`#pester:no-parallel`: +A file that cannot share the machine with other tests starts with the `#pester:no-parallel` +directive: ```powershell -#pester:no-shuffle -Describe 'ordered migration steps' -Tag 'Integration' { +#pester:no-parallel +#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } + +Describe 'Service restart' -Tag 'Integration' { } ``` -Treat that directive the way you treat `#pester:no-parallel`: reasonable for a sequential -integration script, a smell in a unit test file. +Pester runs such files one after another in the calling session, after the parallel batch has +finished. Opt out: -`Run.Shuffle` is experimental and may change. It affects ordering only - never which tests run, nor -how filters apply. +- tests that use a fixed port, a shared database, or another resource that exists once +- tests that change process-wide state, such as an environment variable or the current location +- tests that measure time -## Test Execution Best Practices +### Coverage in a Parallel Run -### Pre-Test Validation +Coverage is collected in a parallel run: each worker measures its file and Pester merges the +results into one report. Measured on 6.2.0, the percentage equals that of a sequential run. -```powershell -# Validate environment before testing -function Test-TestEnvironment { - $issues = @() - - # Check PowerShell version - Pester 6 requires 5.1 or 7.4+ - $psVersion = $PSVersionTable.PSVersion - if ($psVersion.Major -eq 5 -and $psVersion.Minor -lt 1) { - $issues += "Windows PowerShell 5.1+ required (found $psVersion)" - } - elseif ($psVersion.Major -eq 6 -or ($psVersion.Major -eq 7 -and $psVersion -lt [version]'7.4')) { - $issues += "PowerShell 7.4+ required (found $psVersion). Pester 6 dropped support for 6.x and early 7.x." - } - - # Check Pester version - $pester = Get-Module Pester -ListAvailable | - Sort-Object Version -Descending | Select-Object -First 1 - if (-not $pester) { - $issues += "Required module missing: Pester" - } elseif ($pester.Version -lt [version]'6.2.0') { - $issues += "Pester 6.2+ required (found $($pester.Version))" - } - - # Check test data availability - if (-not (Test-Path './Tests/TestData')) { - $issues += "Test data directory missing" - } - - return @{ - Valid = $issues.Count -eq 0 - Issues = $issues - } -} -``` - -### Structural Validation (Discovery-Only Pass) +A parallel run always measures with breakpoints, even when `CodeCoverage.UseBreakpoints` is +`$false`, because the profiler-based tracer cannot run in several runspaces at once. Breakpoints +are the slower method, so a parallel run with coverage is not necessarily faster than a sequential +one. Measure both before choosing. -Run discovery without executing anything. This is fast and catches the v6 structural breakages - -empty `-ForEach` sets, files that cannot be discovered independently, and from 6.2 a configuration -value of the wrong type: - -```powershell -function Test-SuiteStructure { - param([string]$Path = './Tests') +### A Lost File Is an Error - $config = New-PesterConfiguration - $config.Run.Path = $Path - $config.Run.SkipRun = $true - $config.Run.PassThru = $true - $config.Output.Verbosity = 'Normal' +When a worker ends without returning a result, the run throws +`Parallel run lost the results of of file(s)` and names the files. This statement comes +from the source of Pester 6.2.0; it was not reproduced in a run. - $result = Invoke-Pester -Configuration $config +### Before Enabling Parallel Runs - $failed = $result.Containers | Where-Object { -not $_.Passed } - if ($failed) { - $failed | ForEach-Object { Write-Error "Discovery failed: $($_.Item)" } - throw "$($failed.Count) file(s) failed discovery" - } +Each worker starts with an empty runspace. A test file that relies on a module, a variable, or a +helper that another test file loaded fails in a parallel run. Check first that each file passes when +it is run alone, and put shared helpers in a setup file; see +[Pester Test Structure Guide](./test-structure-guide.md#shared-setup-files). - Write-Host "Discovered $($result.TotalCount) tests across $($result.Containers.Count) files" - return $result -} -``` +## Shuffled Test Order -Run this as the first CI step. A discovery failure is cheap to find here and confusing to diagnose -inside a full run. +`Run.Shuffle` is experimental and off by default. Turn it on for the unit tests in CI, with the +seed in the failure message (TST-46). It is what keeps importing the module once for each run +(TST-05) safe. -### Tagging Audit +With the option on, Pester changes the order of the test files, of the blocks in each file, and of +the tests in each block. A test stays inside its `Context`, and a `Context` stays inside its +`Describe`. A suite that depends on the declared order then fails, which exposes a breach of +TST-31. ```powershell -# Fail the build if any test escaped the tagging convention -$config = New-PesterConfiguration -$config.Run.Path = './Tests' -$config.Filter.Tag = 'None' # reserved value: tests with NO tags -$config.Run.SkipRun = $true -$config.Run.PassThru = $true -$config.Output.Verbosity = 'None' - -$result = Invoke-Pester -Configuration $config - -# ShouldRun is the flag Filter.Tag sets, so it is the only count that reflects the filter. -# TotalCount ignores it and reports everything discovered, which would fail every non-empty -# suite; PassedCount only counts untagged tests that ran AND passed, and Run.SkipRun means -# nothing runs, so it is always 0. Both were verified against Pester 6.1.0. -$untagged = @($result.Tests | Where-Object ShouldRun) -if ($untagged.Count -gt 0) { - $untagged | ForEach-Object { Write-Host "::error::Untagged test: $($_.ExpandedPath)" } - throw "$($untagged.Count) test(s) have no tag." -} +$configuration = New-PesterConfiguration +$configuration.Run.Path = $testRoot +$configuration.Run.PassThru = $true +$configuration.Run.Shuffle = $true + +$result = Invoke-Pester -Configuration $configuration ``` -### Coverage Gate +The run prints the seed that it used, and the result object holds it: -```powershell -# CoveragePercentTarget sets the reported target; it does not fail the run. -# Enforce the gate yourself. -$result = Invoke-Pester -Configuration $config -if ($result.CodeCoverage) { - $actual = [math]::Round($result.CodeCoverage.CoveragePercent, 2) - $target = $result.CodeCoverage.CoveragePercentTarget - if ($actual -lt $target) { - Write-Host "Uncovered commands:" - $result.CodeCoverage.CommandsMissed | - Group-Object File | - ForEach-Object { Write-Host " $($_.Name): $($_.Count) commands" } - throw "Code coverage $actual% is below the $target% target" - } -} +```text +Shuffling execution order using seed 314796220. Set 'Run.ShuffleSeed = 314796220' to repeat this order. ``` -### Post-Test Cleanup - ```powershell -# Clean up test artifacts -function Clear-TestArtifacts { - Get-ChildItem -Path $env:TEMP -Filter "PesterTest*" -Recurse -ErrorAction SilentlyContinue | - Remove-Item -Force -Recurse -ErrorAction SilentlyContinue - - # Clean up test databases - if (Test-Path './Tests/TestData/temp.db') { - Remove-Item './Tests/TestData/temp.db' -Force - } -} +$seed = $result.Configuration.Run.ShuffleSeed.Value ``` -### Test Result Analysis +`Run.ShuffleSeed` is `0` by default, which picks a new seed for each run. Setting it to the seed of +an earlier run repeats that order exactly: ```powershell -# Analyze test trends -function Get-TestTrends { - param([string]$ResultsPath = './Tests/Results') - - Get-ChildItem -Path $ResultsPath -Filter "TestMetrics-*.json" | - ForEach-Object { Get-Content $_.FullName -Raw | ConvertFrom-Json } | - Sort-Object Timestamp -} +$configuration.Run.ShuffleSeed = 314796220 ``` -### Converting Results to Other Formats +The option changes only the order. It does not change which tests run or how filters apply. -`TestResult` writes one format per run. Convert the result object for additional formats: +### When a Test Fails Only in a Shuffled Run + +1. Record the seed from the output or from the result object. +2. Run again with `Run.ShuffleSeed` set to that value and confirm that the failure repeats. +3. Find the state that the tests share. It is usually a `$script:` variable, a file outside + `$TestDrive`, an environment variable, or a mock whose calls are counted across blocks. +4. Correct the test: move the setup into the block that needs it, or restore the state in + `AfterEach`. + +A file whose blocks must run in the declared order starts with the `#pester:no-shuffle` directive. +Its blocks and tests then keep their order: ```powershell -$config.Run.PassThru = $true -$result = Invoke-Pester -Configuration $config +#pester:no-shuffle +#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } -Export-NUnitReport -Result $result -Path './Tests/Results/NUnit.xml' -Export-JUnitReport -Result $result -Path './Tests/Results/JUnit.xml' +Describe 'Database migration steps' -Tag 'Integration' { +} ``` + +The directive states that the file depends on its order. That is acceptable for an integration +scenario that is written as a sequence of steps, and it is a defect in a unit test file. diff --git a/.github/instructions/pester-supporting-docs/test-structure-guide.md b/.github/instructions/pester-supporting-docs/test-structure-guide.md index e5aed58..6d07db6 100644 --- a/.github/instructions/pester-supporting-docs/test-structure-guide.md +++ b/.github/instructions/pester-supporting-docs/test-structure-guide.md @@ -1,308 +1,342 @@ # Pester Test Structure Guide -Targets **Pester 6.2+**. +This guide covers where test files live, how each file loads what it needs, shared setup files, and +tags. It supports rules TST-01 to TST-04 in +[powershell-pester.instructions.md](../powershell-pester.instructions.md). The behaviour described +here was checked on Pester 6.2.0. -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. +## Test Directory Layout -## Standard Test Directory Organization - -Create organized test directory structure for enterprise PowerShell projects: +Pester does not require a layout; it runs every `*.Tests.ps1` file under the paths it is given. This +layout suits a module whose tests are split by type: ```text -Tests/ -├── Unit/ -│ ├── Public/ -│ │ ├── Get-ServerHealth.Tests.ps1 -│ │ └── Set-Configuration.Tests.ps1 -│ ├── Private/ -│ │ ├── Test-Connection.Tests.ps1 -│ │ └── Format-Output.Tests.ps1 -│ └── Classes/ -│ └── ServerManager.Tests.ps1 -├── Integration/ -│ ├── EndToEnd/ -│ │ └── CompleteWorkflow.Tests.ps1 -│ └── SystemIntegration/ -│ └── ExternalServices.Tests.ps1 -├── Performance/ -│ ├── Benchmarks/ -│ │ └── ExecutionTime.Tests.ps1 -│ └── LoadTests/ -│ └── MemoryUsage.Tests.ps1 -├── Security/ -│ ├── InputValidation/ -│ │ └── ParameterSanitization.Tests.ps1 -│ └── CredentialHandling/ -│ └── SecureCredentials.Tests.ps1 -├── TestData/ -│ ├── sample-data.json -│ ├── test-config.psd1 -│ └── mock-responses.json -├── TestHelpers/ -│ ├── TestHelpers.ps1 -│ ├── MockFactory.ps1 -│ └── TestDataGenerator.ps1 -├── Results/ -│ ├── Coverage.xml -│ └── TestResults.xml -├── Pester.BeforeContainer.ps1 <- optional, applies to Tests/ and below (6.2+) -├── PesterConfiguration.psd1 -└── Invoke-Tests.ps1 - -Pester.BeforeContainer.ps1 <- optional, at REPOSITORY ROOT - applies to every test file + +|-- ModuleName.psd1 +|-- ModuleName.psm1 +|-- Public/ +|-- Private/ +|-- build/ +| `-- Invoke-Tests.ps1 CI gate script +|-- Tests/ +| |-- Unit/ +| | |-- Get-ServerHealth.Tests.ps1 +| | `-- Set-Configuration.Tests.ps1 +| |-- Integration/ +| | `-- ModuleName.Tests.ps1 +| |-- TestData/ +| | `-- server-cases.psd1 +| |-- TestHelpers/ +| | `-- TestHelpers.ps1 +| `-- Pester.BeforeContainer.ps1 optional: setup for Tests/ and below +`-- Pester.BeforeContainer.ps1 optional: setup for every test file ``` -`Pester.BeforeContainer.ps1` is looked for at the repository root - the directory containing `.git`, -which Pester exposes as `Run.RepoRoot` - and, from 6.2, in every folder between there and the test -file. When present, Pester dot-sources each one before **every** test file below it is discovered -and run, outermost first, in both serial and parallel runs. As of 6.1 this is the only -shared-bootstrap mechanism; the `Run.BeforeContainer` option was removed. +- Write one test file for each source file. Test a private function inside `InModuleScope` + (TST-21). +- Add a `Performance` or `Security` folder only when a function has such a requirement (TST-43). +- Reports that a run writes (test results, coverage) go to a folder that is not committed. +- The gate script is described in [CI/CD Integration Guide](./cicd-integration.md#the-gate-script). + +## File Naming + +A test file is named after the file it tests, `.Tests.ps1` (TST-01): +`Get-ServerHealth.Tests.ps1` tests `Get-ServerHealth.ps1`, and `ModuleName.Tests.ps1` tests the +module as a whole. The suffix is the `Run.TestExtension` option; leave it at its default. + +## Self-Contained Test Files -## Test File Isolation (Pester 6) +Pester 6 discovers one file and runs it before it discovers the next. Pester 5 discovered every file +first. In a parallel run each file is discovered and run in its own runspace. -Pester 6 discovers and runs **one file at a time**, interleaving discovery and execution, rather -than discovering every file up front. Under `Run.Parallel` each file is discovered in its own -runspace. +Each file therefore sets up everything it needs, in two places (TST-02): -**Every test file must be self-contained.** It must import the modules it needs and perform its own -discovery-time setup. It cannot rely on a file that happened to be discovered earlier. +- `BeforeDiscovery` builds what shapes the test tree: the data for `-ForEach`. +- The top-level `BeforeAll` loads what the tests need when they run: the code under test and helpers. ```powershell #Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } BeforeDiscovery { - # Only what is needed to BUILD the test tree: -ForEach data, helper commands - if (-not (Get-Module -Name ModuleName)) { - Import-Module "$PSScriptRoot/../../../ModuleName.psd1" - } - $script:PublicCommands = (Get-Module ModuleName).ExportedFunctions.Keys + $testsRoot = Split-Path -Path $PSScriptRoot -Parent + $dataPath = Join-Path -Path $testsRoot -ChildPath 'TestData' + $data = Import-PowerShellDataFile -LiteralPath (Join-Path -Path $dataPath -ChildPath 'server-cases.psd1') + $serverCases = $data.Cases } BeforeAll { - # What is needed to RUN the tests. Import once per run: -Force in every file - # re-imports the module as many times as there are files. + $testsRoot = Split-Path -Path $PSScriptRoot -Parent + $repositoryRoot = Split-Path -Path $testsRoot -Parent if (-not (Get-Module -Name ModuleName)) { - Import-Module "$PSScriptRoot/../../../ModuleName.psd1" + Import-Module -Name (Join-Path -Path $repositoryRoot -ChildPath 'ModuleName.psd1') + } + + $helperPath = Join-Path -Path $testsRoot -ChildPath 'TestHelpers' + . (Join-Path -Path $helperPath -ChildPath 'TestHelpers.ps1') +} + +Describe 'Get-ServerHealth' -Tag 'Unit' { + It 'Reports for ' -ForEach $serverCases { + Mock -CommandName Test-Connection -ModuleName ModuleName -MockWith { $Reachable } + + $result = Get-ServerHealth -ComputerName $ComputerName + + $result.Status | Should-Be $Expected } - . "$PSScriptRoot/../../TestHelpers/TestHelpers.ps1" } ``` -This was always the recommended style. In Pester 6 it is the model, so suites that were already -isolated need no changes. +A variable assigned in `BeforeDiscovery` does not exist when the tests run, which is why +`$testsRoot` is assigned in both blocks. The cases reach the tests only through `-ForEach`. -### Shared Bootstrap +In a sequential run a module that an earlier file imported is still loaded, so a file with a missing +import can pass by accident. It fails when it runs alone or in a parallel run. To confirm that a file +is self-contained, run it alone: + +```powershell +Invoke-Pester -Path ./Tests/Unit/Get-ServerHealth.Tests.ps1 +``` -When many files need identical setup, put it in one place rather than duplicating it. The setup file -follows the same rule as a test file: top-level code runs during **discovery** only, and what the -tests need at **run** time goes in a `BeforeAll`: +## Shared Setup Files + +Each test file loads what it needs in its own `BeforeAll` (TST-02). When a project chooses to share +setup between files, the mechanism in Pester 6.2.0 is a file named `Pester.BeforeContainer.ps1`. +Pester's source marks it as experimental, so add one only when the user asks for it or the project +already has one. + +Before each test file is discovered and run, Pester dot-sources every `Pester.BeforeContainer.ps1` +that lies between the repository root (`Run.RepoRoot`) and the test file's own folder, outermost +first. It does this in sequential runs, in parallel runs, and in a discovery-only run +(`Run.SkipRun`). + +### Discovery Time and Run Time + +A setup file follows the same rule as a test file. Its top-level code runs during discovery only. +What the tests need when they run goes in a `BeforeAll` in the setup file. ```powershell # Pester.BeforeContainer.ps1 at the repository root -# Discovery only - keep this only where a -ForEach or BeforeDiscovery needs it -if (-not (Get-Module -Name ModuleName)) { - Import-Module "$PSScriptRoot/Source/ModuleName.psd1" -} +# Discovery: keep only what a -ForEach or a BeforeDiscovery block needs. +$supportedRegions = @( + @{ Region = 'westeurope' } + @{ Region = 'northeurope' } +) -# Run time - what the tests themselves need. This file runs before every container, -# so a forced import here costs the same as one in every test file. +# Run time: what the tests themselves use. BeforeAll { - if (-not (Get-Module -Name ModuleName)) { - Import-Module "$PSScriptRoot/Source/ModuleName.psd1" - } - . "$PSScriptRoot/Tests/TestHelpers/TestHelpers.ps1" + $helperRoot = Join-Path -Path $PSScriptRoot -ChildPath 'Tests' + $helperRoot = Join-Path -Path $helperRoot -ChildPath 'TestHelpers' + . (Join-Path -Path $helperRoot -ChildPath 'TestHelpers.ps1') } ``` -Before 6.2 everything sat at top level and reached the tests. On 6.2 that shape fails silently: a -function or variable dot-sourced at top level is gone by the time a test runs (the helper call fails -with `CommandNotFoundException`, the variable reads as `$null`), and only `Import-Module` happens to -survive because module state is session-wide. Wrap run-time setup in `BeforeAll`, and keep the -top-level part only where discovery genuinely needs it. +What a statement in a setup file can reach, measured on Pester 6.2.0 in sequential and parallel +runs: -Anchor every path in it to `$PSScriptRoot`. The file runs before each container in both serial and -parallel runs, and a relative path would resolve against whatever the working directory happens to -be - which is precisely why the `Run.BeforeContainer` scriptblock option was removed in 6.1. It runs -once per container, so what it does must be safe to repeat. +| Statement in the setup file | Visible during discovery | Visible to the tests | +| --- | --- | --- | +| Top-level variable assignment | Yes | No, it reads as `$null` | +| Top-level function definition or dot-sourced file | Yes | No, `CommandNotFoundException` | +| Top-level `Import-Module` | Yes | Yes, because a loaded module stays in the session | +| Variable or function defined inside `BeforeAll` | No | Yes | -#### Per-folder setup (6.2+) +Nothing warns when top-level setup fails to reach the tests. A setup file written for Pester 6.1 has +no `BeforeAll` and needs this change; see +[Pester 6 Migration Guide](./v6-migration.md#the-setup-file-needs-a-beforeall). -A `Pester.BeforeContainer.ps1` in a subfolder applies to that folder and below, after the ones -above it, so each suite carries only what it needs: +Two more requirements: + +- Build every path from `$PSScriptRoot`. The working directory is not reliable. +- The files run once for each test file, so what they do must be safe to repeat. + +A setup file holds shared helpers. It does not replace TST-02: each test file still loads the code +under test in its own `BeforeAll`. + +### Setup for One Folder + +A setup file in a subfolder applies to that folder and below, after the files above it: ```powershell # Tests/Unit/Pester.BeforeContainer.ps1 -BeforeAll { $script:Db = 'in-memory' } +BeforeAll { + $script:storageKind = 'memory' +} +``` +```powershell # Tests/Integration/Pester.BeforeContainer.ps1 -BeforeAll { $script:Db = 'real-sql' } +BeforeAll { + $script:storageKind = 'database' +} ``` -Each file is dot-sourced into the container's own scope, so `Tests/Integration` never inherits what -`Tests/Unit` set up, whichever runs first. A folder that wants none of the setup above it starts its -file with `#pester:no-inherit`. The result object records which files applied to each container as -`BeforeContainerFile`, outermost first - see -[Pester Configuration Guide](./pester-configuration.md#folder-scoped-setup-62). +Each file is dot-sourced for one test file at a time, so a test under `Tests/Integration` never sees +the value that `Tests/Unit` set, whichever runs first. -If the bootstrap does not appear to run, check `Run.RepoRoot` - the chain starts there. From 6.2 the -run resolves it from the session's current location when it is unset (6.1 used the .NET process -working directory), so a run launched from outside the repository, or against a checkout with no -`.git` folder, still looks in the wrong place and simply finds nothing: +A folder that wants none of the setup above it starts its file with the `#pester:no-inherit` +directive. That file still applies; the files above it do not: ```powershell -$config.Run.RepoRoot = $PSScriptRoot +# Tests/Docs/Pester.BeforeContainer.ps1 +#pester:no-inherit +BeforeAll { + $script:storageKind = 'none' +} ``` -This supplements per-file setup; it does not remove the requirement that a file be independently -discoverable. - -## File Naming Conventions - -### Test Files +The result object records which setup files applied to each test file, outermost first: -- **Unit Tests**: `FunctionName.Tests.ps1` -- **Integration Tests**: `ComponentName.Tests.ps1` -- **Performance Tests**: `PerformanceArea.Tests.ps1` -- **Security Tests**: `SecurityArea.Tests.ps1` - -The `.Tests.ps1` suffix is configurable via `Run.TestExtension` but should not be changed. +```powershell +$result = Invoke-Pester -Path ./Tests -PassThru +foreach ($container in $result.Containers) { + $container.Item.Name + foreach ($setupFile in $container.BeforeContainerFile) { + " $setupFile" + } +} +``` -### Test Organization +### When a Setup File Does Not Run -- **Public Functions**: One test file per public function -- **Private Functions**: Group related private functions in single test file -- **Classes**: One test file per class -- **Integration**: Group by business workflow or system integration +The search starts at `Run.RepoRoot` and nothing above it is considered. When the option is not set, +Pester finds the root from the current location, so a run started outside the repository, or in a +checkout that has no `.git` folder, can miss the setup files without any message. Set the option in +scripts and CI jobs; see [Pester Configuration Guide](./pester-configuration.md#runreporoot). -### Hidden Folders Are Now Discovered +## Hidden Folders and Excluded Paths -Pester 6 searches with `Get-ChildItem -Force`, so `*.Tests.ps1` files in hidden or dot-prefixed -folders (for example `.build` or `.config`) **are** discovered and run. Previously they were -skipped. Version-control metadata folders (`.git`, `.svn`, `.hg`) are still ignored. +Pester 6 finds test files in folders that have the hidden attribute, and in dot-prefixed folders +such as `.build`. Pester 5 skipped hidden folders. Folders named `.git`, `.svn`, and `.hg` are never +searched. -Exclude anything else you do not want picked up: +To keep a folder out of a run, set `Run.ExcludePath`. Pester compares each entry with the full path +of every test file, so an entry is either a full folder or file path, or a wildcard pattern that +matches the full path. A relative entry such as `./.build` matches nothing. In this example +`$testRoot` holds the full path of the `Tests` folder: ```powershell -$config.Run.ExcludePath = @('./.build/**', './Tests/Fixtures/**') +$fixturePath = Join-Path -Path $testRoot -ChildPath 'Fixtures' + +$configuration.Run.ExcludePath = @( + $fixturePath + '*/.build/*' +) ``` -## Test Tags Strategy +## Tags -Use consistent tagging for test categorization: +Tag every `Describe` block (TST-04). A tag on a block applies to every test inside it. Use one tag +for the test type and add others where they help to select tests: ```powershell -Describe "Function-Name" -Tag "Unit", "Public" { - # Unit tests for public functions -} - -Describe "Integration-Workflow" -Tag "Integration", "EndToEnd" { - # Integration tests -} - -Describe "Performance-Baseline" -Tag "Performance", "Benchmark" { - # Performance tests +Describe 'Get-ServerHealth' -Tag 'Unit' { } -Describe "Security-Validation" -Tag "Security", "InputValidation" { - # Security tests +Describe 'ModuleName' -Tag 'Integration', 'Slow' { } ``` -### `None` Is a Reserved Tag Value +A tag filter with several tags selects a test that has any one of them. `Filter.Tag = 'Unit', 'Slow'` +runs every test tagged `Unit` and every test tagged `Slow`. To narrow a selection, combine +`Filter.Tag` with `Filter.ExcludeTag`. -In Pester 6, `None` (case-insensitive) is a reserved **filter** value meaning "tests that have no tag -on themselves or any parent block". Never use it as a literal tag name. +### The Reserved Tag None -Use it to audit tagging coverage - a well-tagged suite **runs** zero tests: +Pester 6 reserves `None` (in any letter case) as a filter value. It selects tests that have no tag +on themselves or on any parent block. Do not use it as a tag name (TST-04): a `Describe` block +tagged `None` is selected together with every untagged test. ```powershell -Invoke-Pester -Path ./Tests -TagFilter 'None' # find untagged tests -Invoke-Pester -Path ./Tests -ExcludeTagFilter 'None' # run only tagged tests -Invoke-Pester -Path ./Tests -TagFilter None, Acceptance +Invoke-Pester -Path ./Tests -TagFilter 'None' # only untagged tests +Invoke-Pester -Path ./Tests -ExcludeTagFilter 'None' # only tagged tests +Invoke-Pester -Path ./Tests -TagFilter 'None', 'Integration' # untagged tests and Integration tests ``` -Reading that interactively, look at the **Passed** count in the summary rather than the discovered -count, which stays at the full suite size. +### Finding Untagged Tests -Add the audit to CI so untagged tests cannot slip in. Count `ShouldRun`, the flag the filter -actually sets: +A discovery-only run with the `None` filter lists the tests that have no tag. Count the tests whose +`ShouldRun` property is set; that is the property the filter sets. ```powershell -$config = New-PesterConfiguration -$config.Run.Path = './Tests' -$config.Filter.Tag = 'None' -$config.Run.SkipRun = $true -$config.Run.PassThru = $true -$config.Output.Verbosity = 'None' +# In a script in the build folder +$repositoryRoot = Split-Path -Path $PSScriptRoot -Parent +$testRoot = Join-Path -Path $repositoryRoot -ChildPath 'Tests' + +$configuration = New-PesterConfiguration +$configuration.Run.Path = $testRoot +$configuration.Run.RepoRoot = $repositoryRoot +$configuration.Run.SkipRun = $true +$configuration.Run.PassThru = $true +$configuration.Filter.Tag = 'None' +$configuration.Output.Verbosity = 'None' -$result = Invoke-Pester -Configuration $config +$result = Invoke-Pester -Configuration $configuration -$untagged = @($result.Tests | Where-Object ShouldRun) +$untagged = @($result.Tests | Where-Object -Property ShouldRun) if ($untagged.Count -gt 0) { - $untagged | ForEach-Object { Write-Host "::error::Untagged test: $($_.ExpandedPath)" } - throw "$($untagged.Count) test(s) have no tag. Tag every Describe block." + $names = $untagged.ExpandedPath -join [Environment]::NewLine + throw "$($untagged.Count) test(s) have no tag:$([Environment]::NewLine)$names" } ``` -**Do not gate on `TotalCount` or `PassedCount`.** Both are wrong here, in opposite directions: +Do not use `TotalCount` or `PassedCount` for this check: -| Signal | Behaviour under `Filter.Tag = 'None'` | +| Property | Behaviour with `Filter.Tag = 'None'` | | --- | --- | -| `TotalCount` | Ignores the filter and counts everything **discovered**, so it is non-zero for any non-empty suite. A gate on it can never pass | -| `PassedCount` | Counts only untagged tests that ran **and passed**, so an untagged test that fails is missed. With `Run.SkipRun` nothing runs, so it is always `0` | -| `ShouldRun` | Set by the filter on exactly the matching tests. Correct with or without `SkipRun`, and it names them | +| `TotalCount` | Counts every discovered test and ignores the filter, so it is never zero for a suite that has tests. | +| `PassedCount` | Counts untagged tests that ran and passed. It misses an untagged test that fails, and it is 0 with `Run.SkipRun`. | +| `ShouldRun` | Set on exactly the tests that the filter selected, with or without `Run.SkipRun`. | -Verified against Pester 6.1.0: on one tagged plus one untagged test, `TotalCount` is `2` and -`ShouldRun` is `1`; on a fully tagged suite, `TotalCount` is `2` and `ShouldRun` is `0`. +Measured on Pester 6.2.0 with three tagged and two untagged tests, one of which fails: `TotalCount` +is 5, `PassedCount` is 1, and two tests have `ShouldRun` set. -### Opting Files Out of Parallel Execution +## Directives in a Test File -Tests that must not share the machine - performance benchmarks, tests binding a fixed port, tests -mutating global state - opt out with a comment directive parsed like `#requires`: - -```powershell -#pester:no-parallel -Describe "Performance-Baseline" -Tag "Performance", "Benchmark" { -} -``` +A directive is a comment that Pester reads from the file before it runs it. Pester matches it only +in a comment, never in a string. -These files run in the parent session on the normal serial path while other files run in parallel. -Put the directive at the top of the file; it is matched only inside real comment tokens, never -inside strings. +| Directive | Where | Effect | +| --- | --- | --- | +| `#pester:no-parallel` | Test file | The file runs in the calling session after the parallel batch. See [Test Execution Guide](./test-execution.md#which-files-to-opt-out). | +| `#pester:no-shuffle` | Test file | The file keeps its declared order when `Run.Shuffle` is on. See [Test Execution Guide](./test-execution.md#shuffled-test-order). | +| `#pester:no-inherit` | Setup file | Setup files in the folders above do not apply. See [Setup for One Folder](#setup-for-one-folder). | -## Quality Organization Standards +## Checking the Structure -### Test File Requirements +A discovery-only run checks every file without running a test. It fails for a `-ForEach` value that +is empty or `$null`, for a file that throws during discovery, and for a file that uses a removed +parameter such as `-Focus`. The script uses `$repositoryRoot` and `$testRoot` as set in the previous +script. -- Each test file must import its own modules in `BeforeAll` (and `BeforeDiscovery` when discovery - needs them) -- All external dependencies must be mocked appropriately -- Test isolation must be maintained between tests **and between files** -- Clean test data and resources in `AfterAll` or `AfterEach` -- Every `Describe` block carries at least one tag -- No `-ForEach` / `-TestCases` expression can evaluate to `$null` or `@()` +```powershell +$configuration = New-PesterConfiguration +$configuration.Run.Path = $testRoot +$configuration.Run.RepoRoot = $repositoryRoot +$configuration.Run.SkipRun = $true +$configuration.Run.PassThru = $true -### Verifying Structure +$result = Invoke-Pester -Configuration $configuration -A discovery-only pass validates the whole suite's structure without paying for a full run. It -surfaces empty `-ForEach` sets, files that cannot be discovered independently, and - from 6.2 - a -configuration value of the wrong type: +if ($null -eq $result) { + throw 'Pester found no test files.' +} -```powershell -$config = New-PesterConfiguration -$config.Run.Path = './Tests' -$config.Run.SkipRun = $true -$config.Run.PassThru = $true -Invoke-Pester -Configuration $config +if ($result.Result -ne 'Passed') { + $failedFiles = foreach ($container in $result.FailedContainers) { + "$($container.Item)" + } + throw "Discovery failed in $($result.FailedContainersCount) file(s): $($failedFiles -join ', ')" +} ``` -Run this in CI before the real test job. It is fast and catches structural breakage early. - -### Documentation Integration +## Checklist -- Reference troubleshooting guides in `./Troubleshooting/` folder -- Include performance baselines and expectations -- Document test data requirements and setup -- Maintain test execution guidelines in main test runner +- The file is named `.Tests.ps1` after the file it tests, and starts with the `#Requires` + line for Pester 6.2.0. +- The file loads the code under test in its own top-level `BeforeAll`. +- Data for `-ForEach` is built in `BeforeDiscovery`, and the list cannot be empty or `$null`. +- Paths are built from `$PSScriptRoot` with `Split-Path` and `Join-Path`. +- Every `Describe` block has a tag, and no tag is named `None`. +- Files that a test creates are in `$TestDrive`. +- The file passes when it is run alone. diff --git a/.github/instructions/pester-supporting-docs/unit-test-template.md b/.github/instructions/pester-supporting-docs/unit-test-template.md index 3422b9d..fbf081d 100644 --- a/.github/instructions/pester-supporting-docs/unit-test-template.md +++ b/.github/instructions/pester-supporting-docs/unit-test-template.md @@ -1,331 +1,224 @@ # Unit Test Template -Targets **Pester 6.2+**. Uses the `Should-*` assertion syntax - see -[Assertion Guide](./assertion-guide.md) for the full reference and the v5 mapping table. +A unit test file for functions of a module, with the module's dependencies mocked. The rules it +follows are in the [Pester rules](../powershell-pester.instructions.md), which also contain a +complete test file for a standalone function. The file below passes on Pester 6.2.0 under +PowerShell 7.6 and Windows PowerShell 5.1. -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. +## The Code Under Test -## Standard Unit Test Structure +The template tests a module named `ModuleName`. The test file is in the `Tests` folder directly +under the module root. -> Complete passing implementations of this template: -> [Module-Structure-Example/Tests](../../../powershell-standards/Examples/Module-Structure-Example/Tests/) -> and -> [Testing-Examples](../../../powershell-standards/Examples/Testing-Examples/). +- `Get-Thing -Name ` asks a web service for each name with `Invoke-RestMethod` and emits + one `ModuleName.Thing` object for each answer. Names are validated with `ValidatePattern`. When the + service fails for one name, the function writes a non-terminating error with the ID + `ThingReadFailed` and continues. +- `Remove-Thing -Name ` sends a DELETE request for each name and supports `-WhatIf` and + `-Confirm`. +- `Get-ThingUri` is a private function that builds the address of a request. -Use this template for all unit tests: +## The Test File ```powershell #Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } -BeforeDiscovery { - # Pester 6 discovers and runs one file at a time, so this file must set up - # anything it needs at DISCOVERY time - it cannot rely on another file. - # Only needed when -ForEach data comes from the module itself. - if (-not (Get-Module -Name ModuleName)) { - Import-Module (Join-Path $PSScriptRoot '..\..\ModuleName.psd1') - } -} - BeforeAll { - # Import the module under test, once per run. -Force belongs in the module - # contract test alone; here it would cost every file a re-import. + $moduleRoot = Split-Path -Path $PSScriptRoot -Parent if (-not (Get-Module -Name ModuleName)) { - Import-Module (Join-Path $PSScriptRoot '..\..\ModuleName.psd1') + Import-Module -Name (Join-Path -Path $moduleRoot -ChildPath 'ModuleName.psd1') } - - # Import test helpers - . $PSScriptRoot\..\TestHelpers\TestHelpers.ps1 - - # Mock external dependencies at module level - Mock Write-Verbose { } -ModuleName ModuleName - Mock Write-Information { } -ModuleName ModuleName } -Describe "Function-Name" -Tag "Unit", "Public" { - Context "Parameter Validation" { - It "Should accept valid input: " -ForEach @( - @{ TestValue = 'ValidValue1'; Expected = 'ExpectedResult1' } - @{ TestValue = 'ValidValue2'; Expected = 'ExpectedResult2' } - @{ TestValue = 'ValidValue3'; Expected = 'ExpectedResult3' } - ) { - Function-Name -ParameterName $TestValue | Should-Be $Expected - } - - It "Should reject invalid input: " -ForEach @( - @{ Description = 'null'; InvalidInput = $null; ExpectedError = '*cannot be null*' } - @{ Description = 'empty'; InvalidInput = ''; ExpectedError = '*cannot be empty*' } - @{ Description = 'symbols'; InvalidInput = 'Invalid@#$'; ExpectedError = '*invalid characters*' } - ) { - { Function-Name -ParameterName $InvalidInput } | - Should-Throw -ExceptionMessage $ExpectedError +Describe 'Get-Thing' -Tag 'Unit' { + BeforeAll { + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { + [PSCustomObject]@{ name = $Uri.Segments[-1]; state = 'ready' } } + } - It "Should support pipeline input" { - $results = @('Value1', 'Value2', 'Value3') | Function-Name - $results | Should-BeCollection -Count 3 + Context 'Parameters' { + It 'Declares Name as a mandatory string array' { + Get-Command -Name Get-Thing | + Should-HaveParameter -ParameterName Name -Type ([string[]]) -Mandatory } - It "Should fold a piped collection into the same single result as the by-parameter call" { - # PowerShell unrolls a piped array, so process runs once per element. A function that - # reduces its input to one result has to collect in process and fold in end, and only - # a piped test proves it does; the by-parameter test above passes either way. The @() - # makes the count read the same whether one object or several come back. - $items = @('Value1', 'Value2', 'Value3') - $piped = @($items | ConvertTo-Summary) - $piped | Should-BeCollection -Count 1 - $piped[0].ItemCount | Should-Be (ConvertTo-Summary -InputObject $items).ItemCount - } + It 'Rejects a name before calling the service' -ForEach @( + @{ Description = 'with a path separator'; BadName = '../alpha' } + @{ Description = 'with a query string'; BadName = 'alpha?all=true' } + @{ Description = 'with a space'; BadName = 'alpha beta' } + ) { + { Get-Thing -Name $BadName } | + Should-Throw -FullyQualifiedErrorId 'ParameterArgumentValidationError,Get-Thing' - It "Should declare ParameterName as a mandatory string" { - Get-Command Function-Name | - Should-HaveParameter -ParameterName ParameterName -Type ([string]) -Mandatory + Should-NotInvoke -CommandName Invoke-RestMethod -ModuleName ModuleName } } - Context "Core Functionality" { - BeforeEach { - # Set up mocks for each test. - Mock External-Dependency { - @{ Status = 'Success'; Data = 'MockedData' } - } -ModuleName ModuleName - - Mock Get-ExternalResource { - [PSCustomObject]@{ - Name = 'TestResource' - Value = 'TestValue' - } - } -ModuleName ModuleName - } - - It "Should return expected object structure" { - $result = Function-Name -ParameterName 'TestValue' + Context 'When the service answers' { + It 'Returns a thing with the name and state that the service reported' { + $result = Get-Thing -Name 'alpha' - $result | Should-NotBeNull - $result | Should-HaveType ([PSCustomObject]) - $result.PropertyName | Should-Be 'ExpectedValue' + $result | Should-HaveType 'ModuleName.Thing' + $result.Name | Should-Be 'alpha' + $result.State | Should-Be 'ready' } - It "Should return the full expected shape" { - # Prefer one deep comparison over a run of property assertions. - # -ExcludePathsNotOnExpected ignores properties absent from $expected, - # so adding a new field to the output will not break this test. - $result = Function-Name -ParameterName 'TestValue' + It 'Emits one thing for each name from the pipeline, in order' { + $result = @('beta', 'alpha' | Get-Thing) - $result | Should-BeEquivalent ([PSCustomObject]@{ - Name = 'TestResource' - Status = 'Processed' - }) -ExcludePathsNotOnExpected + $result | Should-BeCollection -Count 2 + $result[0].Name | Should-Be 'beta' + $result[1].Name | Should-Be 'alpha' } - It "Should call external dependencies with correct parameters" { - Function-Name -ParameterName 'TestValue' + It 'Sends one GET request for each name' { + $null = Get-Thing -Name 'alpha', 'beta' - Should-Invoke External-Dependency -Times 1 -Exactly -ModuleName ModuleName -ParameterFilter { - $Parameter -eq 'TestValue' + $alphaRequest = @{ + CommandName = 'Invoke-RestMethod' + ModuleName = 'ModuleName' + ParameterFilter = { $Method -eq 'Get' -and $Uri.AbsolutePath -eq '/api/things/alpha' } } - } - - It "Should handle multiple items correctly" { - $results = Function-Name -ParameterName @('Item1', 'Item2', 'Item3') - - $results | Should-BeCollection -Count 3 - $results | Should-All { $_.Status -eq 'Processed' } + Should-Invoke -CommandName Invoke-RestMethod -ModuleName ModuleName -Times 2 -Exactly + Should-Invoke @alphaRequest -Times 1 -Exactly } } - Context "Error Handling" { - It "Should handle external dependency failures gracefully" { - Mock External-Dependency { - throw 'External service unavailable' - } -ModuleName ModuleName - - { Function-Name -ParameterName 'TestValue' } | - Should-Throw -ExceptionMessage '*External service unavailable*' + Context 'When the service fails for one name' { + BeforeAll { + $brokenRequest = @{ + CommandName = 'Invoke-RestMethod' + ModuleName = 'ModuleName' + ParameterFilter = { $Uri.AbsolutePath -eq '/api/things/broken' } + } + Mock @brokenRequest -MockWith { + throw [System.TimeoutException]::new('The service did not answer.') + } } - It "Should surface a typed error for connection failures" { - Mock External-Dependency { - throw [System.TimeoutException]::new('Connection timeout') - } -ModuleName ModuleName + It 'Writes one non-terminating error and still returns the other things' { + $output = Get-Thing -Name 'broken', 'alpha' 2>&1 + $errors = @($output | Where-Object { $_ -is [System.Management.Automation.ErrorRecord] }) + $things = @($output | Where-Object { $_ -isnot [System.Management.Automation.ErrorRecord] }) - # Assert on the type, not on message text you control and change often - { Function-Name -ParameterName 'TestValue' -ErrorAction Stop } | - Should-Throw -ExceptionType ([System.TimeoutException]) + $errors | Should-BeCollection -Count 1 + $errors[0].FullyQualifiedErrorId | Should-Be 'ThingReadFailed,Get-Thing' + $errors[0].Exception.InnerException | Should-HaveType ([System.TimeoutException]) + $things | Should-BeCollection -Count 1 + $things[0].Name | Should-Be 'alpha' } - It "Should continue processing other items when one fails" { - Mock External-Dependency { - if ($Parameter -eq 'FailingItem') { - throw 'Item processing failed' - } - @{ Status = 'Success' } - } -ModuleName ModuleName - - $results = Function-Name -ParameterName @('GoodItem1', 'FailingItem', 'GoodItem2') -ErrorAction SilentlyContinue - - # Should process the good items despite one failure - @($results | Where-Object { $_.Status -eq 'Success' }) | Should-BeCollection -Count 2 + It 'Stops at the failure when the caller passes -ErrorAction Stop' { + { Get-Thing -Name 'broken', 'alpha' -ErrorAction Stop } | + Should-Throw -FullyQualifiedErrorId 'ThingReadFailed,Get-Thing' } + } +} - It "Should not call the downstream writer when validation fails" { - Mock Write-Result { } -ModuleName ModuleName +Describe 'Remove-Thing' -Tag 'Unit' { + BeforeAll { + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { } + } - { Function-Name -ParameterName '' } | Should-Throw + It 'Does not call the service when -WhatIf is passed' { + Remove-Thing -Name 'alpha' -WhatIf - Should-NotInvoke Write-Result -ModuleName ModuleName - } + Should-NotInvoke -CommandName Invoke-RestMethod -ModuleName ModuleName } - Context "Performance Requirements" { - It "Should complete within acceptable time limits" { - { Function-Name -ParameterName 'TestValue' } | Should-BeFasterThan '5s' + It 'Sends one DELETE request when the caller confirms' { + Remove-Thing -Name 'alpha' -Confirm:$false + + $deleteRequest = @{ + CommandName = 'Invoke-RestMethod' + ModuleName = 'ModuleName' + ParameterFilter = { $Method -eq 'Delete' -and $Uri.AbsolutePath -eq '/api/things/alpha' } } + Should-Invoke @deleteRequest -Times 1 -Exactly + } +} - It "Should scale linearly with input size" { - $smallTime = Measure-Command { Function-Name -ParameterName (1..10) } - $largeTime = Measure-Command { Function-Name -ParameterName (1..100) } +Describe 'Get-ThingUri' -Tag 'Unit' { + It 'Appends the path of the thing to the service address' { + InModuleScope -ModuleName ModuleName -ScriptBlock { + $result = Get-ThingUri -ServiceUri 'https://things.example.test/' -Name 'alpha' - # Large input should not be more than 15x slower (allows for overhead) - $scalingRatio = $largeTime.TotalMilliseconds / $smallTime.TotalMilliseconds - $scalingRatio | Should-BeLessThan 15 + $result.AbsoluteUri | Should-Be 'https://things.example.test/api/things/alpha' } } } ``` -## Pester 6 Authoring Rules - -### Setup blocks compose - -From 6.2 a block may declare several `BeforeAll`, `BeforeEach`, `AfterAll`, or `AfterEach` blocks. -Setups run in declaration order and teardowns in reverse, so setup can be grouped by what it sets -up - one `BeforeAll` that imports the module, another that builds the fixture - instead of merged -into a single block. 6.0 and 6.1 throw on the second one, so a suite that must still run on those -versions keeps one per block. - -### No `param()` block in `It` - -Data from `-ForEach` / `-TestCases` is injected as variables automatically. Do not add a `param()` -block - it is unnecessary and invites the `$Input` bug below. +## What The Template Shows + +- **Loading.** The top-level `BeforeAll` imports the module from a path built on `$PSScriptRoot` + (TST-02, TST-03). With the test file one folder deeper, add one more `Split-Path`. +- **Mocks.** Every mock and every `Should-Invoke` names the module (TST-21). The `Describe` block + declares the answer for the normal case once, and the failure context adds a filtered mock for one + address. `Should-Invoke` counts only the calls of the current `It` block. The + [mocking guide](./mocking-patterns.md) explains scopes and filters. +- **Validation failures.** The error ID `ParameterArgumentValidationError,Get-Thing` identifies a + rejected argument without depending on message text, and `Should-NotInvoke` shows that the service + was not reached. +- **Order.** The pipeline test asserts the count and then each index, because `Should-BeCollection` + does not compare order (TST-14). +- **Both pipeline paths.** Test a parameter that accepts pipeline input with a piped call and with a + call by parameter (TST-44). A function that reduces its input to one result runs different code + on each path, and only the piped test proves that it collects first (FUN-25). +- **Per-item failures.** The error stream is merged into the output and the records are counted + (TST-17). `Should-Throw` would not see this error, because a module function ignores the error + preference that `Should-Throw` sets; with `-ErrorAction Stop` in the call it does. +- **State changes.** `-WhatIf` must not reach the service, and `-Confirm:$false` lets the test run a + function whose `ConfirmImpact` is `High` without a prompt. +- **Private functions.** `InModuleScope` is used only to call `Get-ThingUri` directly (TST-21). + +What to cover is set by TST-41: each parameter set, each documented output, each validation +failure, and each error path. Add timing or security tests only where the function has such a +requirement (TST-43); the [performance](./performance-test-template.md) and +[security](./security-test-template.md) templates show how. + +## Authoring Details + +The [assertion guide](./assertion-guide.md) describes each assertion used above. + +### Test Cases + +Each key of a `-ForEach` hashtable is a variable in the `It` block, so the block needs no `param()` +block. Do not add one, and do not name a key after an automatic variable (TST-30). With a key named +`Input`, the block reads an empty value in place of the test case: ```powershell -# WRONG - $Input is an automatic variable and will not hold your test data -It 'test ' -ForEach @(@{ Input = 'a' }) { +# Non-compliant: Input is an automatic variable, and the param() block is not needed +It 'Converts ' -ForEach @(@{ Input = 'alpha' }) { param($Input) - ... + ConvertTo-UpperText -Text $Input | Should-Be 'ALPHA' } -# RIGHT - name the key something else; no param() needed -It 'test ' -ForEach @(@{ TestValue = 'a' }) { - $TestValue | Should-Be 'a' +# Compliant +It 'Converts ' -ForEach @(@{ Text = 'alpha' }) { + ConvertTo-UpperText -Text $Text | Should-Be 'ALPHA' } ``` -Never use `Input`, `Args`, `Error`, `Host`, `Matches`, or `PSItem` as `-ForEach` keys - they collide -with PowerShell automatic variables. - -### `-ForEach` must not be empty - -`Run.FailOnNullOrEmptyForEach` is on by default, so a `-ForEach` that evaluates to `$null` or `@()` -**fails discovery**. When an empty set is legitimate, opt out explicitly: +A `-ForEach` value that is empty or `$null` stops discovery of the file with +`Value can not be null or empty array`. That is usually a real defect: the code that builds the +cases returned nothing. Where an empty list is legitimate, say so on the block: ```powershell -It 'handles ' -ForEach $cases -AllowNullOrEmptyForEach { - ... +It 'Reaches ' -ForEach $configuredEndpoints -AllowNullOrEmptyForEach { + Test-Endpoint -Uri $Endpoint | Should-BeTrue } ``` -Prefer fixing the generator over adding the switch - an empty test case list usually means the data -source silently returned nothing. - -### Test names expand only `<...>` - -Everything outside `<...>` stays literal, including backticks, `$`, and quotes. Inside `<...>` the -content is evaluated as a full PowerShell expression and rendered through Pester's formatter: - -```powershell -It 'returns for ' # property references -It 'totals <($a + $b)>' # full expressions work in v6 -It 'handles a literal `' # escape the bracket for literal text -``` - -### `-Focus` and `-Pending` are gone - -Use `-Skip`, tags, or the `Filter` configuration to select which tests run. Use -`Set-ItResult -Skipped` or `-Inconclusive` instead of `-Pending`. - -## Test Context Guidelines - -### Parameter Validation Context - -Test all parameter validation scenarios: - -- Valid input variations -- Invalid input rejection -- Pipeline support: piped and by parameter, since a function that reduces its input to one result runs - different code on each path -- Parameter binding and metadata (`Should-HaveParameter`) -- Mandatory parameter enforcement - -### Core Functionality Context - -Test the main business logic: - -- Expected return values and types -- Object structure validation -- External dependency interaction -- Multiple item processing -- Business rule compliance - -### Error Handling Context - -Validate error scenarios: - -- External dependency failures -- Invalid state handling -- Meaningful error messages -- Graceful degradation -- Recovery mechanisms -- Downstream calls _not_ made on failure (`Should-NotInvoke`) - -### Performance Requirements Context - -Establish performance baselines: - -- Execution time limits (`Should-BeFasterThan`) -- Scaling characteristics -- Memory usage patterns -- Resource cleanup -- Bottleneck identification - -## Assertion Guidelines - -### Comprehensive Assertions - -- Test return values and types -- Verify object properties and structure -- Validate external dependency calls -- Check error conditions and messages -- Measure performance characteristics +### Test Names -### Common Assertions +Only text inside `<` and `>` is expanded in a test name. Everything else is literal, including `$` +and quotes. -| Intent | Assertion | +| Name | Displayed as | | --- | --- | -| Exact value | `Should-Be` | -| String with options | `Should-BeString -CaseSensitive` / `-TrimWhitespace` | -| Type validation | `Should-HaveType ([T])` | -| Pattern matching | `Should-MatchString 'regex'` | -| Error validation | `Should-Throw -ExceptionType` / `-ExceptionMessage` | -| Performance limits | `Should-BeFasterThan '5s'` | -| Collection size | `Should-BeCollection -Count 3` | -| Every item matches | `Should-All { ... }` | -| Whole-object shape | `Should-BeEquivalent -ExcludePathsNotOnExpected` | -| Mock was called | `Should-Invoke -Times 1 -Exactly` | -| Mock was not called | `Should-NotInvoke` | - -There is no `Should-NotThrow`. Call the code directly - an unhandled exception fails the test. - -`Should -BeNullOrEmpty` has no single `Should-*` equivalent. Pick the one you mean: `Should-BeNull`, -`Should-BeEmptyString`, or `Should-BeFalsy`. +| `'Returns for '` | The values of the keys `Expected` and `Text` | +| `'Totals <($First + $Second)>'` | The value of the expression | +| ``'Handles a literal `'`` | `Handles a literal ` | +| `'Uses '`, with no such key | `Uses $null` | diff --git a/.github/instructions/pester-supporting-docs/v6-migration.md b/.github/instructions/pester-supporting-docs/v6-migration.md index 5659e8b..a1523ed 100644 --- a/.github/instructions/pester-supporting-docs/v6-migration.md +++ b/.github/instructions/pester-supporting-docs/v6-migration.md @@ -1,509 +1,368 @@ # Pester 6 Migration Guide -Pester 6.0.0 shipped 2026-07-07. It builds on the v5 runtime (Discovery and Run, the configuration -object, the rich result object). The test-authoring API and configuration object are unchanged, so -most suites upgrade with small, mechanical edits. +This guide lists what has to change when a test suite moves from Pester 5 to Pester 6, and what +changed between the 6.0, 6.1, and 6.2 releases. It supports the testing rules in +[powershell-pester.instructions.md](../powershell-pester.instructions.md), which target Pester +6.2.0. -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. +Pester 6.0.0 was published on 2026-07-07, 6.1.0 on 2026-08-11, and 6.2.0 on 2026-09-09. The +statements in this guide were checked by running Pester 5.9.1, 6.0.1, 6.1.0, and 6.2.0. ## Supported Platforms -Pester 6 targets **Windows PowerShell 5.1** and **PowerShell 7.4+**. Support for PowerShell 3, 4, 6, -and unsupported 7.x was removed. Update CI matrices accordingly - `7.2` and `7.3` entries no longer -apply. +Pester 6 runs on Windows PowerShell 5.1 and on PowerShell 7.4 or later. Of the PowerShell 7 +versions, only 7.6 is still supported; 7.4 and 7.5 reached their end-of-support date on 10-Nov-2026. +Remove them, and any older version, from CI matrices (CIC-04). + +Every test file starts with the line that declares the Pester version (TST-01): ```powershell -#Requires -Version 5.1 #Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } ``` -These standards target **6.2+**. Nothing in 6.1 or 6.2 breaks a test file written for 6.0, so the -migration below is the whole job for test files; see [Moving From 6.0 to 6.1](#moving-from-60-to-61) -and [Moving From 6.1 to 6.2](#moving-from-61-to-62) at the end for what changed underneath - -configuration, positional parameters, and the shape of `Pester.BeforeContainer.ps1`. +Nothing in 6.1 or 6.2 breaks a test file that was written for 6.0. The changes in those releases +that can affect a suite are in configuration, in shared setup files, and in a few assertion +parameters; see [Moving From 6.0 to 6.1](#moving-from-60-to-61) and +[Moving From 6.1 to 6.2](#moving-from-61-to-62). ## Upgrade Checklist -Work through these in order. Items 1-3 are hard breakages that fail immediately; the rest are -behavior changes that can pass silently and mislead. - -- [ ] **1. Replace `Assert-MockCalled` and `Assert-VerifiableMock`.** Both were **removed**. Use - `Should -Invoke` / `Should -InvokeVerifiable`, or the new `Should-Invoke` / `Should-NotInvoke`. -- [ ] **2. Remove `-Focus` and `-Pending`.** `Describe`/`Context`/`It` no longer accept `-Focus`, and - the `Focus` property is gone from the result object. `Set-ItResult -Pending` is gone - use - `-Skipped` or `-Inconclusive`. Use `-Skip`, tags, or `Filter` to select which tests run. -- [ ] **3. Audit every `-ForEach` / `-TestCases` that can produce an empty set.** `$null` or `@()` - now **fails discovery** (`Run.FailOnNullOrEmptyForEach`, on by default). Opt out per block or - test with `-AllowNullOrEmptyForEach`, or fix the generator so it cannot be empty. -- [ ] **4. Make every test file self-contained.** Discovery and run now happen per file - a module - imported at discovery time in one file is not guaranteed to be loaded when another file is - discovered. See below. -- [ ] **5. Check for a literal tag named `None`.** `None` is now a reserved filter value meaning - "tests with no tags". Rename any real tag called `None`. -- [ ] **6. Review code coverage settings.** Profiler-based coverage is now the default; set - `CodeCoverage.UseBreakpoints = $true` only if you depend on breakpoint-based numbers. The - `CoverageGutters` output format was **removed** - use `JaCoCo` or `Cobertura`. -- [ ] **7. Check test and block names containing `<...>`.** Only `<...>` templates are expanded now, - and their contents are evaluated as full PowerShell expressions. -- [ ] **8. Check for `*.Tests.ps1` in hidden or dot-prefixed folders.** These are now discovered and - run. Add `Run.ExcludePath` entries for any you do not want picked up. -- [ ] **9. Adopt `Should-*` assertions in new tests.** Optional and additive - see - [Assertion Guide](./assertion-guide.md). Do not set `Should.DisableV5 = $true` until the whole - suite is migrated. - -A second `BeforeAll` (or `BeforeEach`, `AfterAll`, `AfterEach`) in one block threw in 6.0 and 6.1 -and was a migration item. 6.2 allows it again - see -[Moving From 6.1 to 6.2](#moving-from-61-to-62) - so it is no longer on the list. - -## Discovery and Run Now Happen Per File - -This is the most significant change, and it is invisible for well-isolated suites. - -In v5 a run had two global phases: Pester discovered **every** file first, building the whole tree -of `Describe`/`Context`/`It` blocks, and only then ran them all. In v6 the unit of work is a single -file: Pester discovers a file and runs it before moving to the next, interleaving discovery and -execution. This is what makes parallel execution possible, and serial runs follow the same model so -the two behave consistently. - -**What this breaks.** Discovery-time side effects no longer carry across files: - -- A module imported at discovery time in one file (at the top of the file, or inside - `BeforeDiscovery`) is not guaranteed to be loaded while another file is being discovered. Under - `Run.Parallel` it definitely is not - each file is discovered in its own runspace. -- Anything a file needs in order to be _discovered_ - helper modules, the data behind a `-ForEach` - or `BeforeDiscovery`, variables - must be set up **by that file**. +Items 1 to 3 fail at once on Pester 6. The rest change behaviour and can go unnoticed. + +1. Replace `Assert-MockCalled` and `Assert-VerifiableMock`. Both commands were removed. In a file + that uses the Pester 6 assertions, use `Should-Invoke`. In a file that keeps the `Should -Be` + style, use `Should -Invoke` and `Should -InvokeVerifiable` (TST-10, TST-22). +2. Remove `It -Pending`, `Set-ItResult -Pending`, and `-Focus`. Use `-Skip`, or + `Set-ItResult -Skipped` or `-Inconclusive`. To run a selection of tests, use tags or a filter. +3. Check every `-ForEach` and `-TestCases` list that can be empty. An empty or `$null` list now + fails discovery of the file (TST-30). +4. Give every mock that has a `-ParameterFilter` a default mock beside it. A call that matches no + filter no longer reaches the real command; it throws. +5. Make every test file self-contained (TST-02). Discovery and run now happen file by file. +6. Rename any tag called `None`. It is now a reserved filter value (TST-04). +7. Review the code coverage settings. The default method changed, and the `CoverageGutters` format + was removed. +8. Check test and block names that contain `<`, `>`, or a backtick. Name expansion changed. +9. Look for `*.Tests.ps1` files in hidden folders. They are now found and run. +10. Replace the Pester 4 parameters of `Invoke-Pester`, such as `-Script` and `-EnableExit`, with a + configuration object. +11. Change the CI gate so that it tests `Result` and `TotalCount`, not `FailedCount` (TST-42). +12. Write new test files with the Pester 6 assertions (TST-10). + +## Discovery and Run Happen Per File + +Pester 5 discovered every file and then ran every file. Pester 6 discovers one file and runs it +before it discovers the next. Measured with two files, A and B: + +| Version | Order | +| --- | --- | +| Pester 5.9.1 | discover A, discover B, run A, run B | +| Pester 6.2.0 | discover A, run A, discover B, run B | + +In a parallel run each file is discovered and run in its own runspace. + +What this breaks: a test file that relies on something another test file set up. Anything a file +needs to be discovered, such as a helper module or the data for `-ForEach`, has to be loaded by that +file. ```powershell -# WRONG - relies on another file having imported the module during discovery +# Non-compliant: relies on another test file having imported the module BeforeDiscovery { - $script:Cases = Get-ModuleTestCase # command may not exist yet + $cases = Get-ModuleTestCase } -# RIGHT - the file sets up its own discovery-time dependencies +# Compliant: the file loads what its own discovery needs BeforeDiscovery { - Import-Module "$PSScriptRoot/../../MyModule.psd1" -Force - $script:Cases = Get-ModuleTestCase -} -``` - -Runtime setup in `BeforeAll` was never affected by this and still works as before. - -**Shared bootstrap.** When several files need the same setup, put a `Pester.BeforeContainer.ps1` in -the repository root (`Run.RepoRoot`). Pester dot-sources it before **every** test file is discovered -and run, in both serial and parallel runs. Run-time setup goes in a `BeforeAll`; the file's top-level -code runs at discovery only (6.2): - -```powershell -# Pester.BeforeContainer.ps1, at the repository root -BeforeAll { - . "$PSScriptRoot/Tests/TestHelpers/Bootstrap.ps1" + $testsRoot = Split-Path -Path $PSScriptRoot -Parent + $repositoryRoot = Split-Path -Path $testsRoot -Parent + if (-not (Get-Module -Name ModuleName)) { + Import-Module -Name (Join-Path -Path $repositoryRoot -ChildPath 'ModuleName.psd1') + } + $cases = Get-ModuleTestCase } ``` -6.0 also offered a `Run.BeforeContainer` configuration option for this. It was **removed in 6.1** - -see [Moving From 6.0 to 6.1](#moving-from-60-to-61). The convention file is now the only mechanism, -and from 6.2 it may also sit in any folder under the root - see -[Moving From 6.1 to 6.2](#moving-from-61-to-62). - -**Console output changed.** A run prints one `Running tests from N files.` banner, then per-file -results, then one grand-total summary. The old `Starting discovery in N files.` / -`Discovery found X tests` / `Running tests.` framing is no longer printed during a normal run. A -discovery-only run (`Run.SkipRun = $true`) still prints discovery counts. Do not parse for the old -strings. - -## Test and Block Name Expansion - -In v5 names were expanded by re-parsing the whole name as a double-quoted string. A literal -backtick, `$`, `$(...)` or quote could break the name or be used to run code. In v6 **only `<...>` -tokens become sub-expressions; every other character stays inert.** - -Inside `<...>` the content is now evaluated as a full PowerShell expression - the current -`-ForEach`/`-TestCases` item and its properties, any in-scope variable, arithmetic, method calls - -and the result is rendered through Pester's formatter. This is broader than v5, which substituted -only simple data/variable/property references and left anything more complex verbatim. - -```powershell -It 'adds up to <($a + $b)>' # v5: literal text. v6: renders "adds up to 3" -It 'has `' # escape the leading bracket to keep the literal text -It 'handles `backticks`' # v5: parse error. v6: fine, stays literal -``` +Setup that many files share can go in a `Pester.BeforeContainer.ps1` file, which Pester marks as +experimental; see [Pester Test Structure Guide](./test-structure-guide.md#shared-setup-files). -Arrays, hashtables, and objects interpolated via `<...>` now render through Pester's formatter, so -they read properly in the test name instead of printing as `System.Object[]`. +The console output changed with this. A run prints `Running tests from files.` and then one line +for each file. Pester 5 printed `Starting discovery in files.`, `Discovery found tests`, and +`Running tests.` A discovery-only run on Pester 6 still prints the discovery lines. Do not parse +this text; use the result object. -## Configuration Changes +## Removed Commands, Parameters, and Behaviour -| Setting | Change | +| Removed in Pester 6 | Replacement | | --- | --- | -| `Run.Parallel` | New. Experimental parallel runner, one file per runspace | -| `Run.ParallelThrottleLimit` | New. Cap concurrent files; `0` (default) uses all processors | -| `Run.BeforeContainer` | New in 6.0, **removed in 6.1**. Use a `Pester.BeforeContainer.ps1` at the repo root | -| `Run.RepoRoot` | New. Repository root, found from the `.git` directory | -| `Run.FailOnNullOrEmptyForEach` | New, default `$true`. Empty `-ForEach` fails discovery | -| `Run.SkipRemainingOnFailure` | `None`, `Run`, `Container`, `Block` | -| `Should.DisableV5` | New. `$true` makes `Should -Be` throw | -| `CodeCoverage.UseBreakpoints` | Default flipped to `$false` (profiler-based, much faster) | -| `CodeCoverage.OutputFormat` | `CoverageGutters` **removed**. Use `JaCoCo` or `Cobertura` | -| `CodeCoverage.ExcludeTests` | Default `$true`. Keeps test files out of coverage numbers | -| `CodeCoverage.ReportRoot` | New. Defaults to `Run.RepoRoot`; coverage paths are relative to it | -| `TestResult.OutputFormat` | `NUnit3` added. Valid: `NUnitXml`, `NUnit2.5`, `NUnit3`, `JUnitXml` | -| `Output.RenderMode` | New. `Auto`, `Ansi`, `ConsoleColor`, `Plaintext` | -| `Debug.ShowStartMarkers` | New. Writes an indication when each test starts | - -`TestResult` and `CodeCoverage` now **auto-enable** when you set any of their non-default options, -so you cannot silently configure a report that never gets written. - -There is **no** `CodeCoverage.Threshold` or `CodeCoverage.PerFileThreshold` setting - that was never -real. The coverage target is `CodeCoverage.CoveragePercentTarget` (default `75`). - -## Removed and Renamed - -| Removed in v6 | Replacement | -| --- | --- | -| `Assert-MockCalled` | `Should -Invoke` or `Should-Invoke` | -| `Assert-VerifiableMock` | `Should -InvokeVerifiable` or `Should-Invoke -Verifiable` | -| `-Focus` on `Describe`/`Context`/`It` | `-Skip`, tags, or `Filter` configuration | -| `Set-ItResult -Pending`, `Pending` status | `Set-ItResult -Skipped` or `-Inconclusive` | -| `CodeCoverage.OutputFormat = 'CoverageGutters'` | `JaCoCo` (works with Coverage Gutters now) | -| Mock fall-through to the real command | Define the behavior explicitly in the mock | -| `Invoke-Pester` Legacy parameter set | `-Configuration` with a `PesterConfiguration` object | - -Mock **fall-through to the real command** was removed for predictability. A mock whose -`-ParameterFilter` does not match no longer quietly calls the real command - define every case you -need explicitly. - -## Reserved Tag Filter Value: None - -`-TagFilter 'None'` / `Filter.Tag = 'None'` now selects **tests that have no tag** on themselves or -any parent block. `-ExcludeTagFilter 'None'` skips untagged tests so you can run only tagged ones. -Combine with real tags: `-TagFilter None, Acceptance`. Comparison is case-insensitive. +| `Assert-MockCalled` | `Should-Invoke`, or `Should -Invoke` in a file that keeps the old style | +| `Assert-VerifiableMock` | `Should-Invoke -Verifiable`, or `Should -InvokeVerifiable` | +| `It -Pending` and `Set-ItResult -Pending` | `It -Skip`, `Set-ItResult -Skipped`, or `Set-ItResult -Inconclusive` | +| The `Focus` property of a test in the result object | None | +| `CodeCoverage.OutputFormat = 'CoverageGutters'` | `JaCoCo` | +| The parameter set of `Invoke-Pester` with `-Script`, `-EnableExit`, and other Pester 4 parameters | `Invoke-Pester -Configuration` | +| Calling the real command when no mock filter matches | A default mock without `-ParameterFilter` | + +`-Focus` is not a parameter of `Describe`, `Context`, or `It` in Pester 6, and a file that uses it +fails discovery with `A parameter cannot be found that matches parameter name 'Focus'`. The +parameter was already absent from these commands in Pester 5.9.1. + +### Mocks No Longer Fall Through + +In Pester 5.9.1 a call that matched no `-ParameterFilter` ran the real command. In Pester 6 it +throws: + +```text +No mock for command 'Get-Thing' matched the call: none of the parameter filters matched, and there +is no default mock to fall back to. +``` -This is useful for finding tests that escaped the tagging convention: +Declare the default case as well: ```powershell -Invoke-Pester -Path ./Tests -TagFilter 'None' # a well-tagged suite RUNS zero tests +Mock -CommandName Get-Thing -MockWith { 'default' } +Mock -CommandName Get-Thing -ParameterFilter { $Name -eq 'alpha' } -MockWith { 'first' } ``` -Read the **Passed** count in the summary, not the discovered count. The discovered count stays at -the full suite size - `TotalCount` ignores the filter - so a scripted gate must count -`$result.Tests | Where-Object ShouldRun` instead. `PassedCount` does not work for a gate either: it -misses an untagged test that fails, and it is always `0` under `Run.SkipRun`. See -[Test Execution Guide](./test-execution.md). +### An Empty ForEach Fails Discovery -If you used `None` as a literal tag, rename it - filtering by it now also selects every untagged -test. +In Pester 5.9.1 a test with an empty `-ForEach` list was left out, and the run passed. In Pester 6 +the file fails discovery with `Value can not be null or empty array`. The option is +`Run.FailOnNullOrEmptyForEach`, and `-AllowNullOrEmptyForEach` turns it off for one block or test. +See [Test Data Management Guide](./test-data-guide.md#data-built-in-the-wrong-block). -## Parallel Execution (Experimental) - -See [Test Execution Guide](./test-execution.md) for the full treatment. In short: +## Test and Block Name Expansion -```powershell -$config.Run.Parallel = $true -$config.Run.ParallelThrottleLimit = 4 # 0 (default) uses all processors -``` +In Pester 6 only the text between `<` and `>` is evaluated, as a PowerShell expression. Every other +character of a name is kept as written. -Requires file-based containers. Runs on PowerShell 7 and, from 6.2, on Windows PowerShell 5.1 (6.0 -and 6.1 fell back to sequential there). Falls back to a sequential run **with a warning** for -in-memory `ScriptBlock` containers and when `Run.SkipRemainingOnFailure = 'Run'`. Coverage under -parallel was unsupported in 6.0 and works from 6.1 onward, at the cost of forced breakpoint mode - -see [Test Execution Guide](./test-execution.md). +| Name | Pester 5.9.1 | Pester 6.2.0 | +| --- | --- | --- | +| `'Adds up to <($Left + $Right)>'` with 1 and 2 | `Adds up to <($Left + $Right)>` | `Adds up to 3` | +| `'Lists '` with the array 1, 2, 3 | `Lists 1 2 3` | `Lists @(1, 2, 3)` | -Opt a single file out with a comment directive parsed like `#requires`: +A backtick before `<` keeps the bracket as text, and backticks elsewhere stay as written. Pester +5.9.1 read a backtick as the start of an escape sequence when the name also contained a template: ```powershell -#pester:no-parallel -Describe 'integration that must not share the box' { +It 'Reports items with `backtick` text' -ForEach @(@{ Count = 1 }) { } -``` - -Treat `Run.Parallel` as opt-in. The directive name, config shape, and behavior may still change -before it is declared stable. - -## Verifying The Migration - -```powershell -# 1. Confirm the installed version -Get-Module Pester -ListAvailable | Select-Object Name, Version - -# 2. Find removed mock commands -Get-ChildItem -Recurse -Filter *.Tests.ps1 | - Select-String -Pattern 'Assert-MockCalled|Assert-VerifiableMock' | - Select-Object Path, LineNumber, Line - -# 3. Find removed test-selection features -Get-ChildItem -Recurse -Filter *.Tests.ps1 | - Select-String -Pattern '-Focus\b|Set-ItResult\s+-Pending' | - Select-Object Path, LineNumber, Line - -# 4. Discovery-only pass - surfaces empty -ForEach sets and files that cannot be discovered alone -$config = New-PesterConfiguration -$config.Run.Path = './Tests' -$config.Run.SkipRun = $true -$config.Run.PassThru = $true -Invoke-Pester -Configuration $config - -# 5. Find untagged tests -Invoke-Pester -Path ./Tests -TagFilter 'None' -``` - -Step 4 is the highest-value check: it walks every file through discovery, so empty `-ForEach` sets -and files that depend on another file having run first fail there without paying for a full run. +# Pester 5.9.1: Reports 1 items with acktick text +# Pester 6.2.0: Reports 1 items with `backtick` text -## Moving From 6.0 to 6.1 - -6.1.0 is overwhelmingly additive for **test files** - the assertion and mocking APIs a test file uses -did not lose anything. The breakages are in **configuration** and in a few positional parameters. - -```powershell -#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.1.0' } +It 'Keeps ` as text' { +} +# Pester 6.2.0: Keeps as text ``` -### Removed in 6.1 +A `$(...)` sequence in a name is not evaluated, in 5.9.1 or in 6.2.0. -Neither of these appears in the 6.1.0 release announcement. Check for both before upgrading. - -- [ ] **`Run.BeforeContainer` was removed.** 6.0 had two bootstrap mechanisms - this option and the - `Pester.BeforeContainer.ps1` convention file. The option had no file to anchor relative paths - against, so it was dropped. Assigning it now throws - `The property 'BeforeContainer' cannot be found on this object`. Move the scriptblock body - into a `Pester.BeforeContainer.ps1` at the repository root. - -- [ ] **A hashtable config lost it silently on 6.1.** `New-PesterConfiguration -Hashtable` ignored - unknown keys, so a `Run.BeforeContainer` entry in a `PesterConfiguration.psd1` did **not** - throw - the bootstrap simply stopped running. From 6.2 `Invoke-Pester` warns - `Ignoring configuration keys 'Run.BeforeContainer'`; on 6.1 grep for the name rather than - relying on the run to tell you. - -- [ ] **`Should-BeEquivalent -StrictOrder` was removed.** It never worked. If a call passes it, - the switch was not doing what its name implied - assert collection order with - `Should-BeCollection` instead. - -### Positional Parameters Moved +## Configuration Changes -6.1 made `-Actual` bind consistently across the new assertions: **`Position = 0` on a single-subject -assertion**, `Position = 1` when a positional `-Expected` already sits at `Position = 0`. Named -arguments and piped input are unaffected; only positional `-Actual` calls can break. +Compared with Pester 5.9.1: -`Should-BeHashtable` is the one most likely to bite - its `-Actual` moved from position 1 to 0: +| Option | Change | +| --- | --- | +| `Run.Parallel`, `Run.ParallelThrottleLimit` | New, experimental | +| `Run.RepoRoot` | New, experimental | +| `Run.FailOnNullOrEmptyForEach` | New, on by default | +| `Run.Shuffle`, `Run.ShuffleSeed` | New in 6.1, experimental | +| `Run.BeforeContainer` | Existed only in 6.0 | +| `Should.DisableV5` | New | +| `Mock.Global` | New in 6.1, experimental | +| `Output.ShowTags`, `Output.CIDebugOutput` | New in 6.1 | +| `CodeCoverage.UseBreakpoints` | Default changed from `$true` to `$false` | +| `CodeCoverage.OutputFormat` | `CoverageGutters` removed. `JaCoCo` and `Cobertura` remain. | +| `CodeCoverage.ReportRoot` | New. Paths in the report are relative to it, and it defaults to `Run.RepoRoot`. | + +These exist in Pester 5.9.1 as well and are unchanged: the `NUnit3` test result format, the +`Cobertura` coverage format, `Output.RenderMode`, `Debug.ShowStartMarkers`, +`CodeCoverage.ExcludeTests`, `Run.SkipRemainingOnFailure`, and the default of 75 for +`CodeCoverage.CoveragePercentTarget`. + +Setting any option of `TestResult` or `CodeCoverage` to a value other than its default now turns +that section on. There is no `CodeCoverage.Threshold` option; the target is +`CodeCoverage.CoveragePercentTarget`, and it does not fail a run. Every option is listed in +[Pester Configuration Guide](./pester-configuration.md#option-reference). + +## Other Changes in Short + +- Files in folders with the hidden attribute are found and run. Pester 5.9.1 skipped them. See + [Pester Test Structure Guide](./test-structure-guide.md#hidden-folders-and-excluded-paths). +- `None` is a reserved tag filter value that selects tests without a tag. See + [Pester Test Structure Guide](./test-structure-guide.md#the-reserved-tag-none). +- Test files can run in parallel. See + [Test Execution Guide](./test-execution.md#parallel-test-execution). +- Pester 6 adds the `Should-*` assertions, and the `Should -Be` style still works. New test files + use the new assertions, existing files keep their style, and one file does not mix the two + (TST-10). Do not set `Should.DisableV5` until no file uses the old style. See + [Assertion Guide](./assertion-guide.md). + +## Verifying the Migration ```powershell -Get-Command -Syntax Should-BeHashtable # confirm against the installed version +$repositoryRoot = Split-Path -Path $PSScriptRoot -Parent +$testRoot = Join-Path -Path $repositoryRoot -ChildPath 'Tests' +$testFiles = @(Get-ChildItem -LiteralPath $testRoot -Filter '*.Tests.ps1' -File -Recurse) + +# 1. The version that is loaded +Import-Module -Name Pester -RequiredVersion 6.2.0 +(Get-Module -Name Pester).Version + +# 2. Commands and parameters that Pester 6 does not have +$removedPattern = 'Assert-MockCalled|Assert-VerifiableMock|-Focus\b|-Pending\b' +$testFiles | + Select-String -Pattern $removedPattern | + Select-Object -Property Path, LineNumber, Line + +# 3. A discovery-only run: finds empty -ForEach lists and files that fail discovery +$configuration = New-PesterConfiguration +$configuration.Run.Path = $testRoot +$configuration.Run.SkipRun = $true +$configuration.Run.PassThru = $true +$result = Invoke-Pester -Configuration $configuration +$result.FailedContainers | Select-Object -Property Item, ErrorRecord + +# 4. Each file alone: finds files that are not self-contained +foreach ($testFile in $testFiles) { + $fileResult = Invoke-Pester -Path $testFile.FullName -PassThru -Output None + if ($fileResult.Result -ne 'Passed') { + Write-Warning "Fails when run alone: $($testFile.FullName)" + } +} ``` -`-Expected` also became **mandatory** on `Should-NotBeString`, `Should-BeFasterThan`, and -`Should-BeSlowerThan`. A call that omitted it was not asserting anything meaningful, so this -surfaces a latent bug rather than creating one. +Step 4 also reports a file that fails for another reason, so compare its list with a full run. + +## Moving From 6.0 to 6.1 -`Should-Throw -Because` became **named-only**; a positional third argument no longer binds to it. +The differences below were measured between Pester 6.0.1 and 6.1.0. -### What Is New +### Check Before Upgrading -| Addition | Where | +- `Run.BeforeContainer` was removed. Assigning it throws + `The property 'BeforeContainer' cannot be found on this object`. In a hashtable or `.psd1` file, + 6.1 ignores the key without a message, so search for the name. Move the script block into a + `Pester.BeforeContainer.ps1` file. +- `Should-BeHashtable`: `-Actual` moved from position 1 to position 0. A call that passes the value + by position can break; a call that pipes it or names the parameter is not affected. +- `-Expected` became mandatory on `Should-NotBeString`, `Should-BeFasterThan`, and + `Should-BeSlowerThan`. +- `Should-Throw -Because` can only be passed by name. In 6.0 it was also the fourth positional + parameter. +- `Should-BeEquivalent` has no `-StrictOrder` parameter in 6.0.1, 6.1.0, or 6.2.0. To assert the + order of a collection, assert the count and then the element at each index (TST-14). + +### New in 6.1 + +| Addition | Described in | | --- | --- | -| `New-ShouldAssertion` - author your own `Should-*` assertions | [Custom Assertion Guide](./custom-assertions.md) | -| `Mock.Global` - a mock reaches every module in the runspace (experimental) | [Mocking Patterns Guide](./mocking-patterns.md#global-mocks-experimental) | -| `Run.Shuffle` / `Run.ShuffleSeed` - randomize order to surface order dependence (experimental) | [Test Execution Guide](./test-execution.md) | -| `Output.ShowTags` - append `[Tags: ...]` to output lines | [Pester Configuration Guide](./pester-configuration.md) | -| `Output.CIDebugOutput` - surface verbose/debug on a CI debug re-run | [Pester Configuration Guide](./pester-configuration.md) | +| `New-ShouldAssertion`, for writing a custom assertion | [Custom Assertion Guide](./custom-assertions.md) | +| `Mock.Global` (experimental) | [Mocking Patterns Guide](./mocking-patterns.md) | +| `Run.Shuffle` and `Run.ShuffleSeed` (experimental) | [Test Execution Guide](./test-execution.md#shuffled-test-order) | +| `Output.ShowTags` and `Output.CIDebugOutput` | [Pester Configuration Guide](./pester-configuration.md#output) | | `Should-BeString -NormalizeLineEnding` | [Assertion Guide](./assertion-guide.md) | | `Should-ContainCollection -IgnoreOrder` | [Assertion Guide](./assertion-guide.md) | -| Code coverage collected under `Run.Parallel` | [Test Execution Guide](./test-execution.md) | - -### Behavior Worth Knowing About - -None of these fail an existing suite, but they change what you see: - -- **`Should-Throw -ExceptionMessage` explains wildcard mismatches.** A message containing `[ ] * ?` - that failed against itself now says why instead of printing two identical-looking strings. -- **Report output paths are resolved to absolute during configuration,** including a relative - `CodeCoverage.ReportRoot`. A job that wrote its report relative to a directory it changed into - mid-run now writes where the path pointed when the configuration was built. -- **`Should-BeString -Expected` accepts an empty string,** which previously tripped the mandatory - check. -- **`ExcludePath` excludes directories,** not only files. An entry that was silently doing nothing - starts excluding. -- **A stray unmatched-label `break`/`continue` fails its test** instead of aborting the whole run, - so a suite that appeared to stop early now reports a failure and keeps going - expect the failed - count to rise and the test count to rise with it. -- **The `Normal`-verbosity passing container line carries a test count.** Anything scraping that - line needs to tolerate the extra field. -- **Type assertions honor `PSTypeNames`,** so `Should-HaveType 'MyModule.Session'` works against a - synthetic type name. -- **Skipped data-driven tests expand their names.** `handles <_>` repeated N times becomes - `handles foo`, `handles bar`. A CI report that keyed off the raw template text will see new - strings. -- **Complex values are summarised in failure messages.** A `CommandInfo` renders as - `FunctionInfo{Name=Invoke-Pester}` instead of expanding into a slow, huge tree. -- **Containers that fail during discovery reach the `TestResult` XML** instead of vanishing from it. - A report consumer counting test cases may see entries it did not see before - which is the point. - -### Adopting the Experimental Options - -`Mock.Global` and `Run.Shuffle` are both off by default and configured per run: - -```powershell -$config = New-PesterConfiguration -$config.Mock.Global = $true -$config.Run.Shuffle = $true -``` - -Turning either on can surface real problems in an existing suite - that is what they are for. -`Mock.Global` can make a previously-unmocked call start hitting a mock; `Run.Shuffle` fails tests -that depended on declaration order. Both may still change before they are declared stable, so pin -the behavior you rely on in a dedicated job rather than across the whole suite. +| Code coverage in a parallel run | [Test Execution Guide](./test-execution.md#coverage-in-a-parallel-run) | + +### Behaviour That Changed in 6.1 + +- Coverage in a parallel run is collected. In 6.0.1 a run with both options warned + `Run.Parallel does not support CodeCoverage yet` and ran sequentially. +- `Run.ExcludePath` excludes a folder given by its full path. In 6.0.1 such an entry had no effect. +- Report paths are made absolute when the run starts. In 6.0.1 a relative + `TestResult.OutputPath` was resolved when the report was written, so a test that changed the + location moved the report. +- A file that fails discovery is written to the test result report. In 6.0.1 it was missing. +- A `break` or `continue` with a label that matches no loop fails its test, and the run goes on. In + 6.0.1 it ended the whole run without a result. +- A skipped test with `-ForEach` gets its expanded name, for example `Skips foo`. In 6.0.1 it kept + the template text. +- `Should-HaveType` accepts a type name as a string, so it works for an object with a `PSTypeName` + (TST-13). In 6.0.1 the string could not be converted to a type. +- `Should-BeString -Expected ''` is accepted. In 6.0.1 the empty string was rejected. +- `Should-Throw -ExceptionMessage` adds a hint when the pattern and the message are identical apart + from the wildcard characters `[`, `]`, `*`, and `?`. +- A complex value in a failure message is shortened, for example + `Management.Automation.FunctionInfo{Name='Invoke-Pester'}`. On 6.0.1 the same failing test did not + finish within three minutes. ## Moving From 6.1 to 6.2 -6.2.0 shipped 2026-09-09. It is additive for test files - no assertion or mocking API a test file -uses was removed or renamed. The changes that can affect an existing suite are in -`Pester.BeforeContainer.ps1`, in the two timing assertions, and in how the configuration treats bad -input. Everything below was verified against an installed 6.2.0. - -```powershell -#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } -``` +The differences below were measured between Pester 6.1.0 and 6.2.0. ### Check Before Upgrading -- [ ] **Top-level code in `Pester.BeforeContainer.ps1` runs during discovery only.** Anything the - tests need at run time has to be in a `BeforeAll`. A setup file written for 6.1 has no - `BeforeAll` and stops working without a warning - see - [The Setup File Needs a BeforeAll](#the-setup-file-needs-a-beforeall) below. -- [ ] **`Should-BeFasterThan` and `Should-BeSlowerThan` throw on input they cannot measure.** Both - take a `[scriptblock]` to run or a `[timespan]` to compare. On 6.1 a string, a number, or - `$null` fell through and the test passed having asserted nothing; on 6.2 it fails with - `Expected a [scriptblock] to measure or a [timespan] to compare, but got [string] '...'`. A - test that starts failing here was never measuring - fix it to pipe the scriptblock. -- [ ] **A configuration value of the wrong type throws while the configuration is built.** - `Run.Parallel = 'yes'` fails with `Run.Parallel expects a bool, but got the string 'yes'`. - This bites `psd1` and JSON files first, where a boolean written in quotes arrives as a string. - An `int` for a `decimal` is still accepted, and a `$null` value still means "not set". -- [ ] **A key that matches no option is reported.** `Invoke-Pester` warns once: - `WARNING: Ignoring configuration keys 'Run.Paralel', there are no such options`. The list is - also on the object as `$config.GetUnknownKeys()`, which is the thing to gate on in CI since a - warning does not fail a job. Before 6.2 a misspelled key was silently ignored. -- [ ] **Assertions name themselves in the collection-on-`-Expected` error.** The message that read - "is not allowed by this assertion" now reads "is not allowed by Should-Be". Anything matching - on that text sees a new string. -- [ ] **Stray output from a setup file no longer warns.** It cannot escape the container any more, - so a pipeline that grepped for that warning finds nothing. +- Top-level code in `Pester.BeforeContainer.ps1` runs during discovery only. A setup file written + for 6.1 stops working without a message; see + [The Setup File Needs a BeforeAll](#the-setup-file-needs-a-beforeall). +- `Should-BeFasterThan` and `Should-BeSlowerThan` throw for a value that is neither a script block + nor a time span. The message starts with + `Expected a [scriptblock] to measure or a [timespan] to compare`. In 6.1 such a test passed + without measuring anything. Pipe the script block. +- A configuration value of the wrong type throws when the configuration is created, for example + `Run.Parallel expects a bool, but got the string 'yes'`. In 6.1 the value was ignored. +- A configuration key that matches no option produces a warning from `Invoke-Pester`, and the keys + are returned by `$configuration.GetUnknownKeys()`. In 6.1 the key was ignored and the method did + not exist. See [Pester Configuration Guide](./pester-configuration.md#checking-what-was-loaded). +- The message for a collection passed to `-Expected` names the assertion. It reads + `is not allowed by Should-Be` where 6.1 said `is not allowed by this assertion`. +- Output written by a setup file no longer produces the warning + `Pester received unexpected output while running tests and ignored it`. ### The Setup File Needs a BeforeAll -On 6.1 everything in `Pester.BeforeContainer.ps1` sat at top level and reached the tests. On 6.2 the -file follows the same rule as a test file: top-level code runs at discovery, `BeforeAll` runs before -the tests. Measured on 6.2 with the 6.1 shape, in both sequential and parallel runs: - -| Top-level statement in the setup file | Visible at discovery | Visible to the tests | -| --- | --- | --- | -| `Import-Module` | yes | yes - module state is session-wide, not because the file ran | -| `. ./Bootstrap.ps1` defining a function | yes | **no** - `CommandNotFoundException` | -| `$script:Var = ...` | yes | **no** - reads as `$null` | - -Nothing warns. Wrap the run-time part: +In 6.1 a function defined at the top level of `Pester.BeforeContainer.ps1` was available to the +tests, and a `BeforeAll` in the file had no effect. In 6.2 the file follows the same rule as a test +file: top-level code runs during discovery, and `BeforeAll` runs before the tests. ```powershell -# before (6.1) -Import-Module "$PSScriptRoot/Source/MyModule.psd1" -Force -. "$PSScriptRoot/Tests/TestHelpers/Bootstrap.ps1" +# Pester 6.1 +. (Join-Path -Path $PSScriptRoot -ChildPath 'Tests/TestHelpers/TestHelpers.ps1') -# after (6.2) +# Pester 6.2 BeforeAll { - Import-Module "$PSScriptRoot/Source/MyModule.psd1" -Force - . "$PSScriptRoot/Tests/TestHelpers/Bootstrap.ps1" + . (Join-Path -Path $PSScriptRoot -ChildPath 'Tests/TestHelpers/TestHelpers.ps1') } ``` -Keep a top-level copy only for what discovery itself needs - a helper command used inside a -`-ForEach` or `BeforeDiscovery`. `BeforeAll` in a setup file does nothing on 6.1 - none of its setup -reaches discovery or the tests - so one file cannot serve both versions; the version floor moves -with this change. +One file cannot serve both versions. What reaches the tests in 6.2, and what does not, is in the +table in [Pester Test Structure Guide](./test-structure-guide.md#discovery-time-and-run-time). -### Restriction Lifted +### A Block Can Have Several Setup Blocks -A block can have as many `BeforeAll`, `AfterAll`, `BeforeEach` and `AfterEach` blocks as you want. -They all run - setups in declaration order, teardowns in reverse - so setup can be grouped by what it -sets up: +In 6.2 a block can contain more than one `BeforeAll`, `BeforeEach`, `AfterEach`, or `AfterAll`. +Setup blocks run in the order they are written, and teardown blocks run in the reverse order. In 6.0 +and 6.1 the second one failed discovery of the file with the message +`BeforeAll is already defined in this block`. ```powershell -Describe 'Get-User' { - BeforeAll { Import-Module "$PSScriptRoot/../src/MyModule.psd1" -Force } - BeforeAll { $script:user = New-TestUser -Name 'jakub' } - AfterAll { Remove-TestUser -Name 'jakub' } - AfterAll { Remove-Module MyModule -Force } -} -``` - -6.0 and 6.1 threw on the second one. A CI hint keyed on that error, or a lint rule enforcing one -block per scope, can go. - -### What Is New - -| Addition | Where | -| --- | --- | -| `Pester.BeforeContainer.ps1` in any folder under `Run.RepoRoot` - every one from the root down applies, outermost first | [Pester Configuration Guide](./pester-configuration.md#folder-scoped-setup-62) | -| `#pester:no-inherit` - a folder's setup file opts out of everything above it | [Pester Configuration Guide](./pester-configuration.md#folder-scoped-setup-62) | -| `$container.BeforeContainerFile` - which setup files applied, on the result object | [Test Execution Guide](./test-execution.md#result-object-reference) | -| `Should-BeString` prints every differing region with line numbers for strings over 10 lines or 120 characters | [Assertion Guide](./assertion-guide.md#long-strings-get-a-real-diff) | -| `$config.GetUnknownKeys()` - configuration keys that matched no option | [Pester Configuration Guide](./pester-configuration.md#dynamic-configuration-loading) | -| `Run.Parallel` on Windows PowerShell 5.1 (experimental) - the runner moved to a runspace pool | [Test Execution Guide](./test-execution.md#parallel-test-execution-experimental) | -| A parallel run throws when a worker's file goes missing, and a failed worker no longer aborts the rest under `$ErrorActionPreference = 'Stop'` | [Test Execution Guide](./test-execution.md#a-lost-file-is-an-error) | -| Failures point at the line that caused them - errors from inside Pester keep their stack trace, and an assertion failing inside a helper reports the helper's caller too | Output only | - -### Behavior Worth Knowing About - -None of these fail an existing suite, but they change what you see: - -- **`Run.RepoRoot` is resolved from the session's current location** when you did not set it. - `New-PesterConfiguration` still shows the .NET process working directory on the object, but - `Invoke-Pester` re-resolves from `$PWD` before the run, so a session that started elsewhere and - then changed into the repository now finds its setup files. Setting it explicitly still wins. -- **`Run.SkipRun` applies the setup-file chain.** A discovery-only pass - the path the VS Code Test - Explorer uses - used to skip the setup files, so a `-ForEach` over data they provided came back - empty in the explorer and populated in a real run. -- **A `BeforeAll` that throws reports the real error.** 6.1 reported _A 'break' or 'continue' - statement with a label that does not match any enclosing loop escaped from your code_ and - discarded the exception, so a database being down read as a misspelled loop label. -- **`Invoke-Pester` keeps its `-1` exit code when it fails internally.** It could overwrite it with - `$null` when the failure came before the run was created, or with `0` when a plugin failed after - an otherwise successful run. -- **Pester imports on PowerShell 7.4.0 to 7.4.5 again.** 6.0 and 6.1 failed there with - `Cannot convert "PesterConfigurationDeserializer" from String to Type`, because the `net8.0` - assembly referenced a newer `System.Management.Automation` than those releases carry. -- **Stack traces from Pester's own C# code no longer carry the build agent's path.** - `D:\a\1\s\src\csharp\Pester\...` became `/_/src/csharp/Pester/...`, and the build is reproducible - as a side effect. -- **The `TestRegistry` retry message is a debug message now.** `IO exception during a TestRegistry - operation, retrying.` no longer appears as a warning when the retry recovers. - -### Verifying The Upgrade +Describe 'Get-User' -Tag 'Unit' { + BeforeAll { + $userFile = Join-Path -Path $TestDrive -ChildPath 'users.json' + } -```powershell -# 1. Find setup files with top-level statements other than BeforeAll/AfterAll - -# those run at discovery only on 6.2 -Get-ChildItem -Recurse -Filter Pester.BeforeContainer.ps1 | ForEach-Object { - $ast = [System.Management.Automation.Language.Parser]::ParseFile($_.FullName, [ref]$null, [ref]$null) - $topLevel = @($ast.EndBlock.Statements | Where-Object { - $first = $_.PipelineElements[0] - -not ($first -is [System.Management.Automation.Language.CommandAst] -and - $first.GetCommandName() -in 'BeforeAll', 'AfterAll') - }) - if ($topLevel.Count -gt 0) { - "$($_.FullName): $($topLevel.Count) top-level statement(s) run at discovery only" + BeforeAll { + Set-Content -LiteralPath $userFile -Value '[{ "userName": "ann" }]' -Encoding ascii } } +``` -# 2. Confirm which setup files each test file actually got -$result = Invoke-Pester -Path ./Tests -PassThru -Output None -$result.Containers | ForEach-Object { "$($_.Item.Name): $($_.BeforeContainerFile -join ', ')" } - -# 3. Find timing assertions whose left side does not end in a scriptblock's closing brace -Get-ChildItem -Recurse -Filter *.Tests.ps1 | - Select-String -Pattern '[^}\s]\s*\|\s*Should-Be(Faster|Slower)Than' | - Select-Object Path, LineNumber, Line +### New in 6.2 -# 4. Fail on configuration keys that match no option -$config = New-PesterConfiguration -Hashtable (Import-PowerShellDataFile ./Tests/PesterConfiguration.psd1) -if ($config.GetUnknownKeys()) { throw "Unknown keys: $($config.GetUnknownKeys() -join ', ')" } -``` +| Addition | Described in | +| --- | --- | +| `Pester.BeforeContainer.ps1` in any folder between the repository root and the test file. In 6.1 only the file at the root applied. | [Pester Test Structure Guide](./test-structure-guide.md#setup-for-one-folder) | +| The `#pester:no-inherit` directive | [Pester Test Structure Guide](./test-structure-guide.md#setup-for-one-folder) | +| `BeforeContainerFile` on each file in the result object | [Pester Test Structure Guide](./test-structure-guide.md#setup-for-one-folder) | +| `GetUnknownKeys()` on the configuration object | [Pester Configuration Guide](./pester-configuration.md#checking-what-was-loaded) | +| `Run.Parallel` on Windows PowerShell 5.1. In 6.1 it warned and ran sequentially there. | [Test Execution Guide](./test-execution.md#parallel-test-execution) | +| An error when a parallel run loses the result of a file | [Test Execution Guide](./test-execution.md#a-lost-file-is-an-error) | +| `Should-BeString` shows every region that differs, with line numbers, for a long string | [Assertion Guide](./assertion-guide.md) | + +### Behaviour That Changed in 6.2 + +- `Run.RepoRoot`, when it is not set, is found from the current location when the run starts. In 6.1 + the run used the working directory of the process, which `Set-Location` does not change. See + [Pester Configuration Guide](./pester-configuration.md#runreporoot). +- A `BeforeAll` that throws is reported with its own error. In 6.1 the block was reported with a + message about a `break` or `continue` statement whose label matches no enclosing loop. diff --git a/.github/instructions/pester.instructions.md b/.github/instructions/pester.instructions.md deleted file mode 100644 index bd76dce..0000000 --- a/.github/instructions/pester.instructions.md +++ /dev/null @@ -1,263 +0,0 @@ ---- -applyTo: "**/Tests/**/*.ps1,**/*.Tests.ps1" -description: 'Creates comprehensive Pester 6 test suites for PowerShell code with enterprise testing standards' ---- - -# PowerShell Pester Testing - Core Instructions - -Generate enterprise-grade Pester test suites following these core requirements. - -**Target version: Pester 6.2+** on Windows PowerShell 5.1 or PowerShell 7.4+. Pester 6 removed -support for PowerShell 3, 4, 6, and unsupported 7.x. 6.1 and 6.2 are additive for test files - no -test file needs to change to move between 6.0, 6.1, and 6.2. The one thing 6.2 changes underneath a -suite is `Pester.BeforeContainer.ps1`: top-level code in it now runs at discovery only, so run-time -setup there must sit in a `BeforeAll` - see -[Moving From 6.1 to 6.2](./pester-supporting-docs/v6-migration.md#moving-from-61-to-62). - -**NOTE**: Do not use Unicode emojis in any generated code, documentation, or test output. Use plain -text descriptions and standard ASCII characters only. - -## Quick Reference - -### Test Structure Requirements - -- **Directory Structure**: Follow [Test Structure Guide](./pester-supporting-docs/test-structure-guide.md) -- **Coverage Target**: Minimum 80% code coverage for production code -- **Test Types**: Unit (mandatory), Integration, Performance, Security -- **Quality Gates**: All tests pass, performance within limits, security validation -- **File Isolation**: Every test file must be self-contained - see below - -### Core Test Patterns - -Generate tests using these templates: - -- **Unit Tests**: Use [Unit Test Template](./pester-supporting-docs/unit-test-template.md) -- **Integration Tests**: Use [Integration Test Template](./pester-supporting-docs/integration-test-template.md) -- **Performance Tests**: Use [Performance Test Template](./pester-supporting-docs/performance-test-template.md) -- **Security Tests**: Use [Security Test Template](./pester-supporting-docs/security-test-template.md) - -### Assertions - -- **Guide**: Use [Assertion Guide](./pester-supporting-docs/assertion-guide.md) -- **New test files**: prefer the Pester 6 `Should-*` assertions (dash, no space) - they are - type-aware and produce far better failure messages. -- **Existing files**: keep the file's existing style. Do not mix `Should -Be` and `Should-Be` - within a single file. -- **Do not** set `Should.DisableV5 = $true` until every test file in the repository is migrated. -- **Custom assertions**: the `Should-*` set is open for extension in 6.1 via `New-ShouldAssertion` - - see [Custom Assertion Guide](./pester-supporting-docs/custom-assertions.md). Write one only when - the same domain rule is asserted across several files and naming the offending value is the point. - -### Migrating From Pester 5 - -Follow the [Pester 6 Migration Guide](./pester-supporting-docs/v6-migration.md). The three changes -that break existing suites outright: - -1. `Assert-MockCalled` and `Assert-VerifiableMock` were **removed** - use `Should -Invoke` / - `Should -InvokeVerifiable` (or `Should-Invoke` / `Should-NotInvoke`). -2. `-Focus` and `Set-ItResult -Pending` were **removed**. -3. A `-ForEach` / `-TestCases` that evaluates to `$null` or `@()` now **fails discovery**. - -A second `BeforeAll` (or `BeforeEach`, `AfterAll`, `AfterEach`) in one block threw in 6.0 and 6.1. -6.2 allows it again, so it is no longer a migration item. - -### Test Requirements Checklist - -- [ ] **File Isolation**: File imports its own modules and does its own discovery-time setup -- [ ] **Parameter Validation**: Test all input validation scenarios -- [ ] **Error Handling**: Verify graceful error handling with meaningful messages -- [ ] **Mocking**: Mock all external dependencies appropriately -- [ ] **Performance**: Include timing and memory usage validation -- [ ] **Security**: Test input sanitization and credential handling -- [ ] **Pipeline Support**: For every `ValueFromPipeline` parameter, test both `$collection | Verb-Noun` and - `-Parameter $collection`, piping the shape the real upstream command produces. A function that reduces - its input to one result runs different code on each path -- [ ] **Documented Examples**: Every usage example in the README and in help has a test that runs it as written -- [ ] **Non-Empty Test Cases**: No `-ForEach`/`-TestCases` expression can yield `$null` or `@()` -- [ ] **Mock Scope**: A mock that a `BeforeAll` depends on is defined in an enclosing `BeforeAll`, and - `Should-Invoke` for a call made in setup passes `-Scope Context` -- [ ] **One Import**: Only the module contract test imports with `-Force`; every other file imports only when - the module is not already loaded, and none removes it afterwards - -### Configuration & Execution - -- **Configuration**: Use [Pester Configuration Guide](./pester-supporting-docs/pester-configuration.md) -- **Test Execution**: Use [Test Execution Guide](./pester-supporting-docs/test-execution.md) -- **CI/CD Integration**: Follow [CI/CD Integration Guide](./pester-supporting-docs/cicd-integration.md) - -### Experimental Options - -Three configuration options are experimental, off by default, and may change. Do not enable -`Run.Parallel` or `Mock.Global` in generated code unless asked. `Run.Shuffle` is the exception: turn -it on in CI with the seed printed, as -[Shuffled Test Order](./pester-supporting-docs/pester-configuration.md#shuffled-test-order-experimental) -describes, because it is what makes importing the module once per run safe. When a project enables -one, these are the consequences: - -| Option | Effect | Note | -| --- | --- | --- | -| `Run.Parallel` | One test file per runspace | Requires file-based containers. Runs on PowerShell 7 and, from 6.2, on Windows PowerShell 5.1. Coverage works from 6.1 but is forced onto slower breakpoint mode | -| `Run.Shuffle` | Randomizes file, block, and test order | Fails tests that depend on declaration order. Prints a seed; `Run.ShuffleSeed` replays it. Opt a file out with `#pester:no-shuffle`. Recommended in CI: it found three tests in one suite that passed only because an earlier test had created their folder | -| `Mock.Global` | A mock applies to calls from any module in the runspace | `-ModuleName` becomes a resolution hint, not a scope. Does **not** reinstate fall-through - a `-ParameterFilter` guard still needs a default mock | - -All three are per-run configuration, not per-file, apart from the `#pester:no-parallel` and -`#pester:no-shuffle` directives. - -### Quality Standards - -- **Execution Speed**: Unit tests <30s total, integration tests <5min -- **Test Isolation**: Tests must be independent and repeatable -- **Documentation**: Include troubleshooting references in `./Troubleshooting/` folder -- **Enterprise Standards**: Follow PowerShell community best practices - -## Implementation Requirements - -When generating Pester tests: - -1. **Analyze Function**: Determine test types needed (Unit/Integration/Performance/Security) -2. **Apply Templates**: Use appropriate templates from supporting documentation -3. **Mock Dependencies**: Mock all external calls using the - [Mocking Patterns Guide](./pester-supporting-docs/mocking-patterns.md) -4. **Validate Coverage**: Ensure 80%+ code coverage with meaningful assertions -5. **Test Data**: Use [Test Data Management Guide](./pester-supporting-docs/test-data-guide.md) -6. **Integration**: Configure for CI/CD pipeline execution - -### Every Test File Must Be Self-Contained - -Pester 6 discovers and runs **one file at a time**, interleaving discovery and execution, rather -than discovering every file up front. Discovery-time side effects therefore do not carry across -files, and under `Run.Parallel` each file is discovered in its own runspace. - -Each test file must import the modules it needs and perform its own discovery-time setup: - -```powershell -#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } - -BeforeDiscovery { - # Anything needed to BUILD the test tree (-ForEach data, helper commands) - if (-not (Get-Module -Name ModuleName)) { - Import-Module "$PSScriptRoot/../../ModuleName.psd1" - } -} - -BeforeAll { - # Anything needed to RUN the tests - if (-not (Get-Module -Name ModuleName)) { - Import-Module "$PSScriptRoot/../../ModuleName.psd1" - } -} -``` - -Self-contained does not mean re-imported. `Import-Module -Force` costs about 190 ms warm and 800 ms -cold; importing a module that is already loaded costs about 9 ms. One suite of 111 files that forced -the import in every `BeforeAll` and removed the module in every `AfterAll` spent 21 seconds of an -80-second run doing nothing else. Import only when the module is not loaded, and do not remove it -afterwards. Keep the forced import in exactly one file, the module contract test, which asserts what -a freshly imported module looks like. - -The trade is that state one file leaves in module scope is visible to the next. That is what the -shuffled CI run exists to catch: a test that passes only after a fresh import, or only before another -file connected, fails there with a seed to replay. The other consequence is local: CI starts a fresh -process, but an interactive session that already holds the module keeps serving the code it loaded, -so after editing the module import it once with `-Force` before `Invoke-Pester`, or run the suite in -a fresh process the way CI does. - -When several files share bootstrap, put it in a `Pester.BeforeContainer.ps1` rather than relying on -another file having run first. From 6.2 every such file from `Run.RepoRoot` down to the test file's -own folder applies, outermost first, so unit and integration tests can each carry their own setup. -The file follows the same rule as a test file: top-level code runs at **discovery** only, and -anything the tests need at run time goes in a `BeforeAll`: - -```powershell -# Pester.BeforeContainer.ps1 - at the repository root, or in any folder under it -BeforeAll { - Import-Module "$PSScriptRoot/Source/ModuleName.psd1" -Force - . "$PSScriptRoot/Tests/TestHelpers/TestHelpers.ps1" -} -``` - -The `Run.BeforeContainer` option that also did this was **removed in 6.1**; the convention file is -the only mechanism. The chain starts at `Run.RepoRoot` - see -[Pester Configuration Guide](./pester-supporting-docs/pester-configuration.md). - -### Quick Test Generation Pattern - -```powershell -# Standard test structure for any function -Describe "Function-Name" -Tag "Unit", "Public" { - Context "Parameter Validation" { <# Validation tests #> } - Context "Core Functionality" { <# Main logic tests #> } - Context "Error Handling" { <# Error scenarios #> } - Context "Performance Requirements" { <# Performance tests #> } -} -``` - -From 6.2 a block may hold more than one `BeforeAll`, `BeforeEach`, `AfterAll`, or `AfterEach`. -Setups run in declaration order and teardowns in reverse, so group setup by what it sets up rather -than merging unrelated work into one block. 6.0 and 6.1 throw on the second one. - -### Tagging - -Tag every `Describe` block. `None` is a **reserved** filter value in Pester 6 meaning "tests with no -tags" - never use it as a literal tag. Verify tagging coverage with: - -```powershell -Invoke-Pester -Path ./Tests -TagFilter 'None' # a well-tagged suite RUNS zero tests -``` - -Read the **Passed** count, not the discovered count - `TotalCount` ignores the filter. Scripted -gates must count `$result.Tests | Where-Object ShouldRun`; see -[Test Structure Guide](./pester-supporting-docs/test-structure-guide.md). - -### Testing Private Functions - -A module built to these standards exports only what `FunctionsToExport` names, so private functions -are unreachable from a test file. Use `InModuleScope` to run assertions inside the module's scope, -where internal functions and classes are visible: - -```powershell -It 'Returns a session for the target environment' { - InModuleScope MyModule { - $session = Connect-Service -Environment 'Test' -CorrelationId ([guid]::NewGuid()) - $session.Environment | Should-Be 'Test' - } -} -``` - -`InModuleScope` is also how you mock a private function that a public one calls, and how you reach a -class defined in `Classes/`: - -```powershell -InModuleScope MyModule { - Mock Get-ServiceStatus { throw 'unreachable' } - 'A', 'B' | Get-Data -ErrorAction SilentlyContinue | Should-BeFalsy -} -``` - -Do not export a function purely to make it testable - that widens the public contract to serve the -tests. Reach into the module instead. - -### Worked Examples - -These are complete, passing implementations of the patterns above. Prefer matching them over -inventing a structure: - -- [Module-Structure-Example/Tests](../../powershell-standards/Examples/Module-Structure-Example/Tests/) - - module contract, class assertions, `InModuleScope` for two private functions, and a per-item - failure path -- [Basic-Function.Tests.ps1](../../powershell-standards/Examples/Testing-Examples/Basic-Function.Tests.ps1) - - CIM mocking, `-RemoveParameterType`, `-TestCases`, and mock scoping across contexts -- [Tools/Tests](https://github.com/fadwen/ai-powershell-standards/tree/main/Tools/Tests) - tests for the standards - repository's own tooling, including fixture files written per test and error-path coverage. Not - mirrored into consuming projects - -### Documentation Integration - -All test implementations must reference: - -- **Troubleshooting**: Link to `./Troubleshooting/` folder documentation -- **Supporting Guides**: Reference detailed templates and patterns -- **Enterprise Standards**: Follow established PowerShell development practices - -For detailed implementation guidance, templates, and examples, refer to the supporting documentation -files in the `pester-supporting-docs/` folder. diff --git a/.github/instructions/platyps.instructions.md b/.github/instructions/platyps.instructions.md deleted file mode 100644 index 8a30650..0000000 --- a/.github/instructions/platyps.instructions.md +++ /dev/null @@ -1,454 +0,0 @@ ---- -applyTo: "**/docs/**/*.md,**/Public/*.ps1,**/*.psd1" -description: 'Generates and maintains module help documentation with Microsoft.PowerShell.PlatyPS, shipping MAML external help' ---- - -# PowerShell Help Documentation with PlatyPS - -Every module generates its command help with **Microsoft.PowerShell.PlatyPS** and ships compiled -MAML external help. Markdown under `docs/` is the source you edit; `en-US/-Help.xml` is -the build output that `Get-Help` actually reads. - -## Use the Supported Module - -**Target version: Microsoft.PowerShell.PlatyPS 1.0.3+.** - -```powershell -Install-PSResource -Name Microsoft.PowerShell.PlatyPS -``` - -The original `platyPS` v0.14.2 is **no longer supported**. It is a different module with different -cmdlet names, and its Markdown uses an older schema. Never generate `platyPS` 0.14 commands: - -| Do not use (platyPS 0.14.2) | Use instead (Microsoft.PowerShell.PlatyPS 1.x) | -| --- | --- | -| `New-MarkdownHelp` | `New-MarkdownCommandHelp` | -| `Update-MarkdownHelp` | `Update-MarkdownCommandHelp` | -| `New-ExternalHelp` | `Export-MamlCommandHelp` | -| `New-ExternalHelpCab` | `New-HelpCabinetFile` | -| `Get-HelpPreview` | `Show-HelpPreview` | -| `Update-MarkdownHelpModule` | `Update-MarkdownModuleFile` | - -`Update-MarkdownCommandHelp` can read 0.14.2-era Markdown and rewrite it in the current schema, so -migrating an existing project does not mean starting the documentation over. See -[Migrating existing docs](#migrating-existing-014-documentation). - -## Authoring Model - -Markdown is the source of truth for public command help. Comment-based help seeds it once, then the -Markdown is what you edit. The seeding only works if `.EXTERNALHELP` is added _after_ the first -generation — see [that ordering rule](#add-it-after-first-generation-not-before). - -```text -Public/Get-Thing.ps1 - | <# .EXTERNALHELP ModuleName-Help.xml <-- required; see below - | .SYNOPSIS one line for source readers #> - | - | New-MarkdownCommandHelp (once, at first generation) - | Update-MarkdownCommandHelp (every time the signature changes) - v -docs/ModuleName/Get-Thing.md <-- EDIT HERE. Canonical. Committed. -docs/ModuleName/ModuleName.md <-- module page. Committed. - | - | Export-MamlCommandHelp (build step) - v -en-US/ModuleName-Help.xml <-- build output. What Get-Help reads. -``` - -Consequences to hold onto: - -- **Do not hand-edit `en-US/*.xml`.** It is generated and will be overwritten. -- **Do not treat the `.ps1` help block as the place to add detail.** Parameter descriptions, - examples, notes, and links belong in the Markdown. A public function's comment block shrinks to - `.EXTERNALHELP` plus a one-line `.SYNOPSIS`. -- **Private functions are the exception.** They are never exported, so PlatyPS never sees them and - they get no Markdown. They keep full comment-based help — see - [comments.instructions.md](./comments.instructions.md). - -## `.EXTERNALHELP` Is Mandatory on Public Functions - -This is the single detail that decides whether shipped MAML is used or silently ignored. - -**Comment-based help takes precedence over XML-based help.** If a public function keeps a normal -help block and the module also ships `ModuleName-Help.xml`, `Get-Help` displays the comment block -and the MAML you built is dead weight. The `.EXTERNALHELP` keyword reverses that precedence. - -Put the keyword **inside the same `<# #>` block** as the synopsis, as its first entry: - -```powershell -function Get-ServerHealth { - <# - .EXTERNALHELP ModuleName-Help.xml - .SYNOPSIS - Collects health metrics from one or more servers. - #> - [CmdletBinding()] - [OutputType('ServerHealth')] - param( - [Parameter(Mandatory, ValueFromPipeline)] - [string[]]$ComputerName - ) - - # ... -} -``` - -### Add It After First Generation, Not Before - -`.EXTERNALHELP` suppresses comment-based help for `Get-Help` — and `New-MarkdownCommandHelp` reads -`Get-Help` to populate descriptions and examples. Add the keyword to a function that has never been -generated and PlatyPS sees no prose to seed from, so it emits `{{ Fill in }}` placeholders and the -comment-based help you already wrote is thrown away. - -The order for a new public function is therefore: - -1. Write full comment-based help in the `.ps1`, as - [comments.instructions.md](./comments.instructions.md) describes. -2. Run `New-MarkdownCommandHelp` — the prose lands in the Markdown. -3. Add `.EXTERNALHELP ModuleName-Help.xml` and trim the block to a one-line `.SYNOPSIS`. - -Getting this backwards is silent: the build succeeds and the published help is empty. - -### Rules for the Keyword - -- The value is a **filename with no path**. `Get-Help` resolves it against the culture-specific - subdirectory of the module folder, so `ModuleName-Help.xml` is correct and - `.\en-US\ModuleName-Help.xml` is not. -- **The capital `H` in `-Help.xml` is not a typo.** `Export-MamlCommandHelp` emits - `-Help.xml`, while most documentation and the PowerShell 5.0+ auto-discovery - convention write `-help.xml`. On Windows the mismatch is invisible; on Linux and macOS the - lookup fails and every command loses its help. Copy the name PlatyPS actually produced rather - than the one you expect — check with `Get-ChildItem ./maml/ModuleName/`. -- The value must be on the **same line** as the keyword. Any other placement is silently ignored. -- It wins **even when the XML file is missing**. This is the development-time gotcha below. - -### Keep It Inside the Block - -A `# .EXTERNALHELP` single-line comment also works, but it has a failure mode that produces no -error and no warning. Comment-based help must be contiguous, and a comment group that opens with -ordinary prose is disqualified as a help topic unless a blank line separates the prose from the -keyword. When a separate `<# #>` block follows, that block then wins and the keyword is ignored — -`Get-Help` quietly serves the stub synopsis and the MAML is never read. - -Tested against PowerShell 7.6, with the same MAML present in `en-US/` in every case: - -| Arrangement | MAML used | -| --- | --- | -| `.EXTERNALHELP` inside the `<# #>` block with `.SYNOPSIS` | yes | -| `# .EXTERNALHELP` alone, no other help block | yes | -| `# .EXTERNALHELP` alone, then a separate `<# .SYNOPSIS #>` block | yes | -| prose comment, blank line, `# .EXTERNALHELP`, then a separate block | yes | -| **prose comment, no blank line, `# .EXTERNALHELP`, then a separate block** | **no** | - -Only the last row fails, and it is the arrangement a helpful comment above the keyword naturally -produces. Putting the keyword inside the block avoids the question entirely. - -### Development-Time Gotcha - -Before `Export-MamlCommandHelp` has run — a fresh clone, a working tree, a dot-sourced `.ps1` — -`Get-Help Get-ServerHealth` shows only autogenerated syntax. `.EXTERNALHELP` suppressed the comment -block and the XML does not exist yet. This is expected, not a bug. - -Two ways to see real help while developing: - -```powershell -# Preview a built MAML file as Get-Help would render it -Show-HelpPreview -Path ./maml/ModuleName/ModuleName-Help.xml - -# Or build the MAML into the module first, then use Get-Help normally -./build.ps1 -Task Docs -``` - -Make the docs build part of the normal local build so a working tree always has current help. - -## First-Time Generation - -Import the module, then generate command Markdown and the module page together: - -```powershell -Import-Module ./ModuleName.psd1 -Force - -$newMarkdownSplat = @{ - ModuleInfo = Get-Module -Name ModuleName - OutputFolder = './docs' - WithModulePage = $true - Locale = 'en-US' -} -New-MarkdownCommandHelp @newMarkdownSplat -``` - -**Always pass `-Locale` explicitly.** It defaults to the generating machine's culture, so a -developer running in `en-GB` or `en-AE` stamps that into the front matter of every file while the -MAML still ships to `en-US/`. The mismatch does not fail the build; it just makes the committed -Markdown disagree with the folder it compiles into, and the next person on a different machine sees -a diff on every file. - -This creates `./docs/ModuleName/` containing one `.md` per exported command plus `ModuleName.md`, -the module page listing every command with its synopsis. - -PlatyPS writes **templates, not content**. Every generated file contains placeholder strings such as -`{{ Fill in the Description }}`. Filling those in is the actual documentation work, and the standards -in [comments.instructions.md](./comments.instructions.md) — business value in the description, -validation rules and business context per parameter, three progressive examples, troubleshooting -links in notes — apply to the Markdown now. A file still containing `{{ Fill in` is not done. - -If you generated without `-WithModulePage`, add the module page later, once synopses are written: - -```powershell -Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | - Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - New-MarkdownModuleFile -OutputFolder ./docs -Force -``` - -> **`-Path {$_.FilePath}` is not a typo.** The braces are a delayed-binding script block, evaluated -> once per pipeline item. Writing `-Path $_.FilePath` binds a single value before the pipeline runs -> and fails. This shape recurs in every PlatyPS pipeline below. - -## Updating When the Module Changes - -Whenever a public function gains a parameter, changes a type, adds a parameter set, or is added or -removed, refresh the Markdown from the loaded module. Do not hand-patch the syntax blocks. - -```powershell -Import-Module ./ModuleName.psd1 -Force - -Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | - Where-Object Filetype -match 'CommandHelp' | - Update-MarkdownCommandHelp -Path {$_.FilePath} -``` - -`Update-MarkdownCommandHelp` is deliberately conservative: it adds what it can verify and does not -delete your prose. It writes backups next to the originals — diff against them before committing. - -Then refresh the module page: - -```powershell -Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | - Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - Update-MarkdownModuleFile -Path ./docs/ModuleName/ModuleName.md -``` - -Two things the update cannot infer, which you must check by hand every time: - -- **Output types.** PlatyPS reads them from `Get-Command`, so they are only as good as the - `[OutputType()]` attribute. It adds what it can verify and never removes what it cannot. -- **Wildcard support.** Only reflected when the parameter carries `[SupportsWildcards()]`. Add the - attribute rather than documenting the behaviour in prose alone. - -New commands added since the last run have no Markdown to update. Run `New-MarkdownCommandHelp` for -those, or regenerate into the same folder — without `-Force`, existing files are left alone. - -## Validating - -Structure validation belongs in the build, before MAML is generated: - -```powershell -Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | - Where-Object Filetype -match 'CommandHelp' | - Test-MarkdownCommandHelp -Path {$_.FilePath} -DetailView -``` - -`Test-MarkdownCommandHelp` returns `True` for a file whose `## RELATED LINKS` entries are relative -paths, but `Get-Help` throws `The specified URI ... is not valid` at read time and returns nothing. -A `.LINK` value must be a bare topic name or an absolute `http`/`https` URL — never a relative path -to a file in the repository. PlatyPS writes a bare topic as `[Get-Thing]()`, so the check -below has to allow empty parentheses while still rejecting a path. Check before building: - -```powershell -# The |\) in the lookahead is what permits a bare topic name. Without it this flags every -# [Get-Thing]() cross-reference as a relative link - rejecting the exact form the paragraph -# above calls correct. -Select-String -Path ./docs/ModuleName/*.md -Pattern '^\s*-?\s*\[.+\]\((?!https?://|\))' | - ForEach-Object { Write-Error "Relative link in $($_.Filename):$($_.LineNumber)" -ErrorAction Stop } -``` - -Both forms are legal, and they are not interchangeable: - -| Target | Form | Renders as | -| --- | --- | --- | -| A command in this module, or an `about_` topic | `- [Get-Thing]()` | the plain name | -| Anything outside the installed module | `- [Title](https://...)` | the URL | - -Use the bare form for anything `Get-Help` can resolve on its own — sibling commands above all. -Reaching for an absolute URL there is the common mistake: it still passes the gate, but -`Get-Help -Full` then prints a GitHub URL where a command name would read better, and the link stops -working the moment the repository moves or goes private. Reserve URLs for material that genuinely -lives outside the module, remembering that a user who installed from the Gallery has no repository -checkout — which is also why a relative path would be useless even if `Get-Help` accepted it. - -[Module-Structure-Example](../../powershell-standards/Examples/Module-Structure-Example/docs/ModuleExample/Get-ExampleData.md) -shows both forms in one file. - -Also fail the build on leftover placeholders — `Test-MarkdownCommandHelp` checks structure, not -whether anyone wrote the content: - -```powershell -$unfilled = Select-String -Path ./docs/ModuleName/*.md -Pattern '\{\{\s*Fill in' -List -if ($unfilled) { - $names = ($unfilled.Path | Split-Path -Leaf) -join ', ' - Write-Error "Help templates still contain placeholders: $names" -ErrorAction Stop -} -``` - -### Exclude Generated Help From the Prose Linter - -PlatyPS Markdown does not satisfy a normal markdownlint configuration, and the violations are -structural rather than fixable: - -- **MD040** — the `## SYNTAX` code fence carries no language label -- **MD013** — the module page writes the manifest `Description` as one unwrapped line - -Both are rewritten on every `Update-MarkdownCommandHelp` run, so a hand-correction lasts until the -next regeneration and then reappears in the diff. Exclude the generated help instead of fighting it: - -```yaml -- name: Lint Markdown - uses: DavidAnson/markdownlint-cli2-action@v25 - with: - globs: | - **/*.md - !**/docs/*/*.md - config: '.markdownlint.json' -``` - -A `.markdownlintignore` file does **not** work here — `markdownlint-cli2` ignores it once explicit -globs are passed on the command line. Use a negated glob in the same list. - -## Building MAML - -```powershell -Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | - Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - Export-MamlCommandHelp -OutputFolder ./maml -Force -``` - -This writes `./maml/ModuleName/ModuleName-Help.xml`. Copy it into the module's culture folder as -part of packaging: - -```powershell -$cultureDir = Join-Path $ModuleOutputPath 'en-US' -New-Item -Path $cultureDir -ItemType Directory -Force | Out-Null -Copy-Item -Path ./maml/ModuleName/ModuleName-Help.xml -Destination $cultureDir -Force -``` - -The filename must match the value in every `.EXTERNALHELP` keyword. Add a culture folder per -language if the module is localized. - -## Module Layout - -```text -ModuleName/ -├── ModuleName.psd1 -├── ModuleName.psm1 -├── Public/ -│ └── Get-Thing.ps1 # carries `.EXTERNALHELP ModuleName-Help.xml` -├── Private/ -├── docs/ # PlatyPS Markdown - SOURCE, committed -│ └── ModuleName/ -│ ├── ModuleName.md # module page -│ └── Get-Thing.md # one per exported command -├── en-US/ # packaged with the module -│ ├── ModuleName-Help.xml # generated by Export-MamlCommandHelp -│ └── about_ModuleName.help.txt # hand-written, see below -└── Tests/ -``` - -`maml/` is a build intermediate — add it to `.gitignore`. Whether `en-US/` is committed or produced -only at package time is a per-project call; if it is committed, the drift gate below is what keeps -it honest. - -### About Topics - -`about_*.help.txt` files are plain text, hand-written, and not produced by PlatyPS. Place them in -the same culture folder. A module with more than a handful of commands should have one covering -concepts that do not belong to any single command — authentication setup, configuration precedence, -correlation ID conventions. - -## CI Drift Gate - -Stale MAML is worse than no MAML: `.EXTERNALHELP` guarantees users see the stale content instead of -falling back to anything correct. CI must fail when the checked-in docs no longer match the module. - -```powershell -#Requires -Modules @{ ModuleName = 'Microsoft.PowerShell.PlatyPS'; ModuleVersion = '1.0.3' } - -Import-Module ./ModuleName.psd1 -Force - -$documented = (Get-ChildItem ./docs/ModuleName/*.md).BaseName | - Where-Object { $_ -ne 'ModuleName' } -$exported = (Get-Module ModuleName).ExportedFunctions.Keys - -$missing = $exported | Where-Object { $_ -notin $documented } -$orphan = $documented | Where-Object { $_ -notin $exported } - -if ($missing) { - Write-Error "Exported commands with no help Markdown: $($missing -join ', ')" -ErrorAction Stop -} -if ($orphan) { - Write-Error "Help Markdown for commands that no longer exist: $($orphan -join ', ')" -ErrorAction Stop -} -``` - -That catches added and removed commands. To also catch a changed **signature** — a new parameter, a -changed type, a new parameter set — compare the committed Markdown against the loaded module: - -```powershell -$committed = Import-MarkdownCommandHelp -Path ./docs/ModuleName/Get-Thing.md -$current = New-CommandHelp -Command (Get-Command Get-Thing) - -$diff = Compare-CommandHelp -ReferenceCommandHelp $committed -DifferenceCommandHelp $current -if ($diff) { - Write-Error 'Help Markdown is out of date - run the docs update task' -ErrorAction Stop -} -``` - -Run this on the same pull request trigger as the Pester and PSScriptAnalyzer gates. See -[cicd.instructions.md](./cicd.instructions.md). - -## Migrating Existing 0.14 Documentation - -1. Do not import `platyPS` 0.14.2 and `Microsoft.PowerShell.PlatyPS` in the same session. Start a - clean session for the migration. -2. Run `Update-MarkdownCommandHelp` over the existing files. It reads the old schema and rewrites in - the current one. -3. Fill in the new `## ALIASES` section that appears in every converted file. It is optional content - — delete the section if the command has no aliases — but the placeholder must not survive. -4. Add `.EXTERNALHELP ModuleName-Help.xml` to every public function, and cut the now-duplicated - comment-based help down to a one-line `.SYNOPSIS`. -5. Diff every file against its backup before committing. Conversion is mechanical; the review is not. - -## Checklist - -Before a module is considered documented: - -- [ ] `Microsoft.PowerShell.PlatyPS` 1.0.3+ is used, and no `platyPS` 0.14 cmdlet names appear - anywhere in build scripts or workflows -- [ ] Every exported function carries `.EXTERNALHELP ModuleName-Help.xml` with the filename only, - on the same line as the keyword -- [ ] Every exported function has a Markdown file under `docs/ModuleName/`, and no Markdown file - exists for a command that is no longer exported -- [ ] No `{{ Fill in` placeholder survives in any committed Markdown -- [ ] Every command has at least three examples, each with a description and expected output -- [ ] `[OutputType()]` and `[SupportsWildcards()]` are present on the source functions so PlatyPS - can reflect them accurately -- [ ] The module page `ModuleName.md` lists every command with a real synopsis -- [ ] `Test-MarkdownCommandHelp` passes in the build -- [ ] MAML is built to `en-US/ModuleName-Help.xml` and packaged with the module, with the filename - byte-for-byte identical to every `.EXTERNALHELP` value including the capital `H` -- [ ] `Get-Help -Full` verified against the packaged module on a case-sensitive - filesystem, not only on Windows -- [ ] `maml/` is gitignored; `en-US/*.xml` is never hand-edited -- [ ] The CI drift gate fails on a command documented but not exported, or exported but not - documented -- [ ] Private functions retain full comment-based help — PlatyPS does not document them - -## Related Instructions - -- [Comment Standards](./comments.instructions.md) — content quality standards, which now apply to - the Markdown, and full comment-based help for private functions -- [Module Development](./module.instructions.md) — module layout and manifest -- [CI/CD Integration](./cicd.instructions.md) — where the docs build and drift gate run -- [README Standards](./readme.instructions.md) — project-level documentation, distinct from command help diff --git a/.github/instructions/powershell-cicd.instructions.md b/.github/instructions/powershell-cicd.instructions.md new file mode 100644 index 0000000..a5ef340 --- /dev/null +++ b/.github/instructions/powershell-cicd.instructions.md @@ -0,0 +1,206 @@ +--- +applyTo: "**/.github/workflows/*.yml,**/.github/workflows/*.yaml,**/azure-pipelines.yml" +description: "CI pipeline rules for repositories that contain PowerShell code." +--- + +# CI pipelines for PowerShell projects + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to workflow and pipeline files, and to the build scripts they call, in a +repository that contains PowerShell code. + +## Rules + +- **CIC-01** A pull request pipeline runs PSScriptAnalyzer and Pester, and fails when either reports + a problem. A module that ships compiled help also runs the help checks. +- **CIC-02** Install build tools at a fixed version, for example + `Install-PSResource -Name Pester -Version 6.2.0`. An unpinned install can change what a passing + build means. +- **CIC-03** Run PowerShell steps with `shell: pwsh`. When the project declares Windows PowerShell 5.1 + support, add a job that runs the tests under 5.1 (`shell: powershell` on a Windows runner). Do not + add one otherwise. +- **CIC-04** A build matrix MUST NOT include a PowerShell version that is past its end-of-support + date. +- **CIC-05** A pipeline script fails by throwing, with `$ErrorActionPreference = 'Stop'` set at the + top. It MUST NOT report failure only by writing text, and it MUST NOT reset `$LASTEXITCODE` without + first acting on the failure it carried. +- **CIC-06** Secrets come from the CI system's secret store and reach a step as environment + variables. A secret MUST NOT be written in a workflow file or printed to the log. +- **CIC-07** Give each job the least permissions it needs with an explicit `permissions` block. +- **CIC-08** Publish a module only from a tagged release, with the API key taken from a secret. +- **CIC-09** Reference an action by a release tag or a full commit ID, never by a branch name such as + `@main`. +- **CIC-10** A module that is published rehearses its release on every pull request: the release + script runs with `-WhatIf`, stages the package, imports it in a new process, checks the Gallery's + limits, and stops before the upload (MOD-10 to MOD-14). +- **CIC-11** The repository has a `.gitattributes` file that fixes line endings, for example + `* text=auto eol=lf`, so that every platform checks out the same bytes. + +## Notes and examples + +### Pull request workflow (CIC-01 to CIC-05, CIC-07) + +```yaml +name: Quality gates + +on: + pull_request: + branches: [main] + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - name: Install build tools + shell: pwsh + run: | + Install-PSResource -Name PSScriptAnalyzer -Version 1.25.0 -TrustRepository + Install-PSResource -Name Pester -Version 6.2.0 -TrustRepository + + - name: Run PSScriptAnalyzer + shell: pwsh + run: | + $ErrorActionPreference = 'Stop' + $findings = @(Invoke-ScriptAnalyzer -Path . -Recurse -Severity Error, Warning) + $findings | Format-Table -Property Severity, RuleName, ScriptName, Line -AutoSize + if ($findings.Count -gt 0) { + throw "PSScriptAnalyzer reported $($findings.Count) finding(s)." + } + + - name: Run Pester + shell: pwsh + run: ./build/Invoke-Tests.ps1 +``` + +The test script is the gate shown under "The CI gate" in +`.github/instructions/powershell-pester.instructions.md`: it fails when the Pester result is not +`Passed`, when no tests ran, and when coverage is below 80 percent. + +A commit ID is the stricter choice for CIC-09, because a tag can be moved. Write the tag after it in a +comment, as in `actions/checkout@ # v7.0.1`, and look the ID up; do not invent one. + +Use `runs-on: windows-latest` when the code is Windows-only. For a project that declares Windows +PowerShell 5.1 support, add a second job on a Windows runner whose steps use `shell: powershell`. + +### PSScriptAnalyzer settings + +PSScriptAnalyzer's default rules cover correctness but not layout. To check layout as well, enable +the formatting rules in a settings file. Save this as `PSScriptAnalyzerSettings.psd1` in the +repository root and run +`Invoke-ScriptAnalyzer -Path . -Recurse -Settings ./PSScriptAnalyzerSettings.psd1`: + +```powershell +@{ + IncludeDefaultRules = $true + + Rules = @{ + PSPlaceOpenBrace = @{ + Enable = $true + OnSameLine = $true + NewLineAfter = $true + IgnoreOneLineBlock = $true + } + + PSPlaceCloseBrace = @{ + Enable = $true + NewLineAfter = $false + IgnoreOneLineBlock = $true + NoEmptyLineBefore = $false + } + + PSUseConsistentIndentation = @{ + Enable = $true + Kind = 'space' + IndentationSize = 4 + PipelineIndentation = 'IncreaseIndentationForFirstPipeline' + } + + PSUseConsistentWhitespace = @{ + Enable = $true + CheckInnerBrace = $true + CheckOpenBrace = $true + CheckOpenParen = $true + CheckOperator = $true + CheckPipe = $true + CheckSeparator = $true + } + + PSAvoidLongLines = @{ + Enable = $true + MaximumLineLength = 115 + } + } +} +``` + +With these settings a hashtable padded to align its `=` signs is reported, which enforces STY-04. + +PSScriptAnalyzer 1.25.0 also applies a file with this name when it is in the folder passed to +`-Path` and `-Settings` is omitted. Pass `-Settings` anyway, so that the result does not depend on +which folder is analyzed. + +`PSUseCorrectCasing` is left out on purpose. In PSScriptAnalyzer 1.25.0 it intermittently fails with a +`NullReferenceException` in a new session, which makes a CI run fail at random. + +Do not use the built-in `CodeFormattingOTBS` preset for this standard. It enables +`PSAlignAssignmentStatement`, which requires the `=` signs of a hashtable to be aligned, the opposite +of STY-04. + +### Help checks for a module with compiled help (CIC-01) + +Run the validation and drift checks from `.github/instructions/powershell-platyps.instructions.md` on +every pull request, and build the compiled help into the module before packaging it. + +### Publishing (CIC-06, CIC-08) + +```yaml +name: Publish + +on: + push: + tags: ['v*'] + +permissions: + contents: read + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - name: Publish to the PowerShell Gallery + shell: pwsh + env: + GALLERY_API_KEY: ${{ secrets.GALLERY_API_KEY }} + run: | + $ErrorActionPreference = 'Stop' + Publish-PSResource -Path ./ModuleName -ApiKey $env:GALLERY_API_KEY +``` + +### Failing correctly (CIC-05) + +`Invoke-Pester` sets `$LASTEXITCODE` to the number of failures, and the runner fails the step on a +non-zero value. A script that resets it to zero has to have thrown for every failure first, or the +step passes with failing tests. + +### Line endings (CIC-11) + +Without a `.gitattributes` file, git decides the line endings of a checkout from each computer's +settings. GitHub's Windows runners check text files out with CRLF, and Linux runners with LF. A test +that compares the text of a file with a here-string, or with text built in the test, then passes on +one and fails on the other (STY-34). + +```text +* text=auto eol=lf +``` + +This line stores text files with LF and checks them out with LF on every platform. PowerShell 7 and +Windows PowerShell 5.1 both read such files. diff --git a/.github/instructions/powershell-error-handling.instructions.md b/.github/instructions/powershell-error-handling.instructions.md new file mode 100644 index 0000000..d6bb261 --- /dev/null +++ b/.github/instructions/powershell-error-handling.instructions.md @@ -0,0 +1,253 @@ +--- +applyTo: "**/*.ps1,**/*.psm1" +description: "PowerShell error handling, strict mode, and output stream rules." +--- + +# PowerShell error handling, strict mode, and streams + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to every `.ps1` and `.psm1` file. They separate two kinds of code: a script that is +run directly, and a function, which a caller invokes and which must leave the caller in control. + +## Rules + +### Scripts and modules + +- **ERR-01** A script that is run directly MUST set `Set-StrictMode -Version Latest` and + `$ErrorActionPreference = 'Stop'` immediately after its `param()` block. +- **ERR-02** Module code MUST NOT set `$ErrorActionPreference`, at module scope or inside a function. + A module sets `Set-StrictMode -Version Latest` once, at the top of its `.psm1`. +- **ERR-03** Code MUST run without errors under strict mode: assign a variable before reading it, test + for an optional property with `$object.PSObject.Properties['Name']`, test for a hashtable key with + `.ContainsKey()`, and wrap a result in `@()` before reading `.Count` or an index. + +### Reporting failure from a function + +- **ERR-10** In an advanced function, put the work that can fail inside `try`, and end the function + on an unrecoverable failure by calling `$PSCmdlet.ThrowTerminatingError()` in `catch`. +- **ERR-11** `throw` and `Write-Error -ErrorAction Stop` MUST NOT be used in an advanced function. Use + `throw` only where `$PSCmdlet` does not exist: top-level script code, class methods, and plain + script blocks. +- **ERR-12** Inside `try`, pass `-ErrorAction Stop` to every command whose failure the `catch` must + see. A non-terminating error does not enter `catch`. +- **ERR-13** When one input item fails and the rest can still be processed, report the failure with + `$PSCmdlet.WriteError()` and continue with the next item. +- **ERR-14** To add context to a failure, create a new `ErrorRecord` whose exception wraps the + original as its inner exception. An error MUST NOT be rethrown as a string. +- **ERR-15** Write output to the pipeline after the `try` block, not inside it. An error raised by a + command further down the pipeline is otherwise caught by this function's `catch`. + +### Handling failure + +- **ERR-20** A `catch` block MUST NOT be empty and MUST NOT hide the error. To tolerate one expected + failure, catch that exception type and state the reason in a comment. +- **ERR-21** In `catch`, read the error from `$_`. `$Error[0]` MUST NOT be used. +- **ERR-22** Release resources in `finally`, and assign before `try` every variable that `finally` + reads. +- **ERR-23** After running a native executable, test `$LASTEXITCODE` and fail when it reports an + error. A non-zero exit code does not raise a PowerShell error by default. +- **ERR-24** In a script, pass `-ErrorAction Stop` to a module command whose non-terminating errors + must stop the script. The script's own `$ErrorActionPreference` does not reach module functions. + +### Streams + +- **ERR-30** Send only data to the success stream. Use `Write-Verbose` for progress detail, + `Write-Debug` for diagnostics, `Write-Warning` for a condition that did not stop the work but that + the caller should know about, and `Write-Information` for status messages. +- **ERR-31** `Write-Host` MUST NOT be used in a function or module. +- **ERR-32** In code that runs for every item of a large input, a `Write-Verbose` or `Write-Debug` + call that builds its message SHOULD sit inside a test of `$VerbosePreference` or + `$DebugPreference`. + +## Notes and examples + +### A script that is run directly (ERR-01, ERR-23, ERR-24) + +```powershell +#requires -Version 7.6 + +<# +.SYNOPSIS +Publishes the build output. + +.PARAMETER OutputPath +Folder that contains the build output. +#> +[CmdletBinding()] +param( + [Parameter(Mandatory)] + [string]$OutputPath +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +$files = @(Get-ChildItem -LiteralPath $OutputPath -File) +if ($files.Count -eq 0) { + throw "Nothing to publish: '$OutputPath' contains no files." +} + +& git tag --annotate 'release' --message 'Release' +if ($LASTEXITCODE -ne 0) { + throw "git tag failed with exit code $LASTEXITCODE." +} +``` + +With `$ErrorActionPreference = 'Stop'`, the script stops on any terminating error, on any error from +a compiled cmdlet, and on any error from a function defined in the script itself. + +### A function (ERR-10 to ERR-15) + +```powershell +function Get-ReleaseNote { + [CmdletBinding()] + [OutputType([string])] + param( + [Parameter(Mandatory)] + [string]$LiteralPath + ) + + try { + $content = Get-Content -LiteralPath $LiteralPath -Raw -ErrorAction Stop + } catch [System.Management.Automation.ItemNotFoundException] { + $message = "Release notes were not found at '$LiteralPath'. Run the changelog task first." + $exception = [System.InvalidOperationException]::new($message, $_.Exception) + $category = [System.Management.Automation.ErrorCategory]::ObjectNotFound + $errorRecord = [System.Management.Automation.ErrorRecord]::new( + $exception, 'ReleaseNoteNotFound', $category, $LiteralPath) + $PSCmdlet.ThrowTerminatingError($errorRecord) + } catch { + $PSCmdlet.ThrowTerminatingError($_) + } + + $content.Trim() +} +``` + +The first `catch` adds context and keeps the original as `InnerException`. The second passes any +other failure on unchanged. The result is written after the `try` block. + +When each input item can fail on its own, report the failure and continue. The object is again +written after the `try` block: + +```powershell +process { + foreach ($item in $Name) { + try { + $record = Get-Record -Name $item -ErrorAction Stop + } catch { + $PSCmdlet.WriteError($_) + continue + } + + $record + } +} +``` + +If `$record` were written inside the `try`, an error thrown by a later command in the caller's +pipeline, such as `Get-Thing | ForEach-Object { throw 'stop' }`, would arrive in this `catch`. The +function would report it as its own failure and carry on, and the caller would never see it. + +### Why the rules are written this way + +Each statement below was verified on PowerShell 7.6 and Windows PowerShell 5.1. + +- `throw` is suppressed when any caller up the call stack passed `-ErrorAction SilentlyContinue` or + `-ErrorAction Ignore`. Execution then continues with the statement after the `throw`, and the + function returns as if it had succeeded. +- `Write-Error -ErrorAction Stop` ignores the caller's `-ErrorAction`, and unless `-ErrorRecord` is + passed it replaces the original exception with a `WriteErrorException`. +- `$PSCmdlet.ThrowTerminatingError()` always ends the function, and the caller's `-ErrorAction` does + not hide it. It ends only the statement that called the function: the caller continues at its next + statement unless that call is inside `try` or the caller's `$ErrorActionPreference` is `Stop`. + Passing `-ErrorAction Stop` on the call does not change this. That is why ERR-10 puts the calls + inside `try` and ERR-01 sets `Stop` in scripts. +- A module function does not see `$ErrorActionPreference` set by the script that calls it, except when + the script runs in the global scope, as `pwsh -File` does. That is why ERR-12 and ERR-24 ask for an + explicit `-ErrorAction Stop`. +- `$ErrorActionPreference = 'Stop'` at module scope turns every non-terminating error from the + module's functions into a terminating one, so a caller can no longer continue past a per-item + failure. +- Under `$ErrorActionPreference = 'Stop'`, `Write-Error` terminates. Statements that follow it in the + same block do not run. + +### Strict mode (ERR-02, ERR-03) + +`Set-StrictMode` applies to the scope where it runs and to the scopes below it. At the top of a +`.psm1` it therefore covers every function file the module dot-sources. Do not put it in a file that +is dot-sourced into a caller's scope, such as a function file or a test helper, because it would +change that caller's mode. + +```powershell +Set-StrictMode -Version Latest + +# Each line after the first is an error under strict mode +$settings = @{ Region = 'westeurope' } +$tier = $settings.Tier +$count = (Get-Item -LiteralPath $PSHOME).Count +$first = @()[0] +$total = $neverAssigned + 1 + +# Compliant equivalents +$tier = if ($settings.ContainsKey('Tier')) { $settings['Tier'] } else { 'standard' } +$count = @(Get-Item -LiteralPath $PSHOME).Count +$items = @(Get-ChildItem -LiteralPath $PSHOME -Filter '*.none') +$first = if ($items.Count -gt 0) { $items[0] } else { $null } +``` + +### Tolerating one expected failure (ERR-20) + +```powershell +try { + Remove-Item -LiteralPath $lockFilePath -ErrorAction Stop +} catch [System.Management.Automation.ItemNotFoundException] { + # The lock file is already gone, which is the state this code wants. + Write-Debug "No lock file at '$lockFilePath'." +} +``` + +A typed `catch` matches the exception that a failing .NET method call raised, and its base types, +even though PowerShell wraps that exception in a `MethodInvocationException`. + +### Releasing resources (ERR-22) + +```powershell +$reader = $null +try { + $reader = [System.IO.StreamReader]::new($fullPath) + $firstLine = $reader.ReadLine() +} finally { + if ($null -ne $reader) { + $reader.Dispose() + } +} +``` + +### Native executables (ERR-23) + +Setting `$PSNativeCommandUseErrorActionPreference = $true` (PowerShell 7.4 and later) makes a +non-zero exit code raise an error that follows `$ErrorActionPreference`. It does not exist in Windows +PowerShell 5.1, and some tools use non-zero exit codes for success (`robocopy` returns values up to 7 +for normal outcomes), so an explicit `$LASTEXITCODE` test is the portable form. + +### Messages in a loop (ERR-32) + +PowerShell builds the message before `Write-Verbose` decides whether to show it. Measured with +200,000 messages that were not shown: 2.7 seconds without the test and 0.5 seconds with it on +PowerShell 7.6, and 13.6 seconds against 0.5 seconds on Windows PowerShell 5.1. + +```powershell +foreach ($record in $records) { + if ($VerbosePreference -ne 'SilentlyContinue') { + Write-Verbose ('Processing record {0} of {1}.' -f $record.Index, $records.Count) + } + + Convert-Record -InputObject $record +} +``` + +Inside an advanced function, `-Verbose` and `-Debug` set these preferences, so the test follows the +caller's switch. A message that is written a few times needs no test. diff --git a/.github/instructions/powershell-functions.instructions.md b/.github/instructions/powershell-functions.instructions.md new file mode 100644 index 0000000..5681957 --- /dev/null +++ b/.github/instructions/powershell-functions.instructions.md @@ -0,0 +1,311 @@ +--- +applyTo: "**/*.ps1,**/*.psm1" +description: "PowerShell function structure, parameter, and output rules." +--- + +# PowerShell functions: structure, parameters, output + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to every function in a `.ps1` or `.psm1` file. The function template in the core +instructions shows them together. + +## Rules + +### Structure + +- **FUN-01** Write every function as an advanced function, with `[CmdletBinding()]` and a `param()` + block. `$args` MUST NOT be used. +- **FUN-02** A function does one job and returns objects. Formatting (`Format-*`), `Out-*`, and + `Write-Host` belong in the script that calls it, not in a reusable function. +- **FUN-03** State kept between calls lives in `$script:` variables. `$global:` variables MUST NOT be + created. +- **FUN-04** `return` in a `begin` block ends only that block; `process` and `end` still run. To stop + the command there, call `$PSCmdlet.ThrowTerminatingError()`, or set a variable and test it at the + top of `process`. +- **FUN-05** Code that runs in `Start-Job`, a runspace, or `ForEach-Object -Parallel` does not see the + caller's variables, `$script:` state, or the module's private functions. Pass what it needs with + `-ArgumentList`, `$using:`, or a parameter. + +### Output + +- **FUN-10** Declare `[OutputType()]` with the type the function emits. For a custom object, name the + type as a string and set `PSTypeName` on the object. `[OutputType([PSCustomObject])]` MUST NOT be + used. +- **FUN-11** Write each object to the pipeline as soon as it is ready. A function MUST NOT collect + its results in a list and return the list at the end. +- **FUN-12** Only intended output may reach the success stream. Discard a value returned by a method + or command that is called for its side effect, with `$null = ...` or `[void](...)`. + +### Parameters + +- **FUN-20** Give every parameter a type. Use `[switch]` for a flag, never `[bool]`, and never give a + switch a default of `$true`. +- **FUN-21** A parameter that accepts pipeline input MUST be handled in a `process` block. Declare it + as an array and loop over it there, so that pipeline input and a directly passed array behave the + same way. +- **FUN-22** Validate input with attributes so that a bad value fails at binding: `ValidateSet`, + `ValidateRange`, `ValidatePattern`, `ValidateScript`, `ValidateNotNullOrEmpty`. A default value is + not validated, so it MUST itself be valid. +- **FUN-23** Do not add `[ValidateNotNullOrEmpty()]` to a mandatory `[string]` parameter; mandatory + binding already rejects `$null` and an empty string. Reject whitespace-only text with a validation + attribute, not with a check in the function body. +- **FUN-24** At most the first one or two parameters SHOULD be positional. When only some are, set + `[CmdletBinding(PositionalBinding = $false)]` and mark those parameters with `Position`. +- **FUN-25** A function that reduces its pipeline input to one result collects the input in `process` + and emits the result in `end`, so that piped input and an array argument give the same answer. +- **FUN-26** Read data that came from an API or a file through one accessor that handles both a + dictionary and an object. Index syntax (`$data['key']`) reads only a dictionary, and member syntax + (`$data.key`) can return a dictionary's own property instead of the data. + +### State changes + +- **FUN-30** A function that changes state MUST declare `SupportsShouldProcess` and guard every change + with `$PSCmdlet.ShouldProcess()`. Add `ConfirmImpact = 'High'` when the change is destructive. +- **FUN-31** A read-only function, such as one with the verb `Get`, `Test`, or `Find`, MUST NOT + declare `SupportsShouldProcess`. +- **FUN-32** A command that asks for confirmation beyond `ShouldProcess` MUST offer `-Force` for + unattended use, and MUST treat a session that cannot answer as a refusal. +- **FUN-33** `-WhatIf` sets `$WhatIfPreference` for every command and script that the function calls. + Pass `-WhatIf:$false` to a call that must still run, and enumerate with a script block, not with + `ForEach-Object -MemberName`, which returns nothing under `-WhatIf`. + +## Notes and examples + +The fragments below omit comment-based help to stay short. A real function carries it. + +**FUN-04.** A `return` in `begin` that was meant to cancel the command lets `process` run for every +input object. Record the decision and act on it in `process`: + +```powershell +begin { + $targetExists = Test-Path -LiteralPath $LiteralPath +} + +process { + if (-not $targetExists) { + return + } + + foreach ($item in $Name) { + Remove-ReportEntry -LiteralPath $LiteralPath -Name $item + } +} +``` + +**FUN-05.** A job starts in a new process, and a runspace or parallel block starts without the +calling scope. A read of `$script:` state there returns `$null`, a call to a private function fails +only inside the worker, and a Pester mock does not reach the worker either. No error appears in the +caller unless the worker's output is checked. + +```powershell +$results = $computerNames | ForEach-Object -Parallel { + Test-Connection -TargetName $_ -Count 1 -TimeoutSeconds $using:timeoutSeconds -Quiet +} -ThrottleLimit 8 +``` + +Measure before making code parallel. A module that keeps one session for each process can fail +under runspaces in ways that separate processes do not. + +**FUN-10.** `PSTypeName` becomes the object's first type name. It is not a property of the object, so +read it with `$object.PSObject.TypeNames[0]`, not `$object.PSTypeName`. + +```powershell +[CmdletBinding()] +[OutputType('Contoso.DiskReport')] +param() + +[PSCustomObject]@{ + PSTypeName = 'Contoso.DiskReport' + Name = $drive.Name + FreeGigabytes = [math]::Round($drive.Free / 1GB, 1) +} +``` + +For a class that the module defines, write the class name as a string too +(`[OutputType('DiskReport')]`), so that the function file parses before the class is loaded. + +**FUN-11, FUN-21.** Streaming keeps memory flat and lets the caller stop early. A caller that needs an +array wraps the call: `$reports = @(Get-DiskReport)`. + +```powershell +function Get-FileHashSummary { + [CmdletBinding()] + [OutputType('Contoso.FileHashSummary')] + param( + [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)] + [Alias('FullName')] + [string[]]$LiteralPath + ) + + process { + foreach ($item in $LiteralPath) { + $hash = Get-FileHash -LiteralPath $item -Algorithm SHA256 -ErrorAction Stop + [PSCustomObject]@{ + PSTypeName = 'Contoso.FileHashSummary' + Path = $hash.Path + Hash = $hash.Hash + } + } + } +} +``` + +Without the `process` block, a function that receives pipeline input runs once, with the last item +only. + +**FUN-12.** Anything a statement returns and nothing captures becomes function output. Common +sources are `StringBuilder.Append()`, `HashSet.Add()`, `Dictionary.Remove()`, and `New-Item`. + +```powershell +$null = $builder.AppendLine($line) +$null = New-Item -Path $reportDirectory -ItemType Directory -Force +``` + +**FUN-23.** `[ValidateNotNullOrWhiteSpace()]` exists in PowerShell 7.6 but not in Windows +PowerShell 5.1. + +```powershell +# PowerShell 7.6 +[Parameter(Mandatory)] +[ValidateNotNullOrWhiteSpace()] +[string]$DisplayName + +# Also valid on Windows PowerShell 5.1 +[Parameter(Mandatory)] +[ValidateScript({ -not [string]::IsNullOrWhiteSpace($_) })] +[string]$DisplayName +``` + +**FUN-25.** Passed by parameter, a collection reaches `process` once, as one argument. Piped, it is +unrolled and `process` runs once for each element. A function that folds its input into one result +therefore gives a different answer on each path unless it collects first. No error is raised either +way, and every result has the declared type. + +```powershell +function Get-SizeSummary { + [CmdletBinding()] + [OutputType('Contoso.SizeSummary')] + param( + [Parameter(Mandatory, ValueFromPipeline)] + [long[]]$Length + ) + + begin { + $lengths = [System.Collections.Generic.List[long]]::new() + } + + process { + foreach ($item in $Length) { + $lengths.Add($item) + } + } + + end { + [PSCustomObject]@{ + PSTypeName = 'Contoso.SizeSummary' + Count = $lengths.Count + Total = ($lengths | Measure-Object -Sum).Sum + } + } +} +``` + +Without the `end` block, `10, 20, 30 | Get-SizeSummary` emits three summaries of one item each. This +is the one case where a function holds its input: FUN-11 still applies to its results. When the +parameter is typed `[object]`, decide what one element arriving alone means, and test for `[string]` +and `[hashtable]` before testing for `IEnumerable`: a string enumerates as characters and a hashtable +as entries, and each is one object. Test both paths, as TST-44 requires. + +**FUN-26.** The same JSON reaches a function in two shapes. `ConvertFrom-Json` returns objects, or +dictionaries with `-AsHashtable` (PowerShell 7 only). Some SDK commands, such as +`Invoke-MgGraphRequest`, return dictionaries unless asked for objects. A fixture read back from disk +comes through `ConvertFrom-Json`. Measured on PowerShell 7.6 and Windows PowerShell 5.1: + +| Read | Dictionary | Object | +| --- | --- | --- | +| `$data['value']` | The value | `$null`; an error under strict mode | +| `$data.value` | The value | The value | +| `$data.missing` | `$null`; an error under strict mode | `$null`; an error under strict mode | +| `$data.Count` | The entry named `Count` when there is one, otherwise the number of entries | The property when there is one; otherwise `1` on PowerShell 7, and `$null` or a strict-mode error on 5.1 | + +Without strict mode, code written for one shape computes from `$null` when it meets the other, and +nothing fails. One private accessor removes the difference: + +```powershell +function Get-ResponseProperty { + [CmdletBinding()] + [OutputType([object])] + param( + [Parameter(Mandatory)] + [AllowNull()] + [object]$InputObject, + + [Parameter(Mandatory)] + [string]$Name + ) + + if ($null -eq $InputObject) { + return $null + } + + if ($InputObject -is [System.Collections.IDictionary]) { + if ($InputObject.Contains($Name)) { + return $InputObject[$Name] + } + return $null + } + + $property = $InputObject.PSObject.Properties[$Name] + if ($null -ne $property) { + return $property.Value + } + return $null +} +``` + +Like any function, it unrolls a collection on the way out, so wrap a read of a collection in `@()` +(STY-42). Test the public function with both shapes, and keep fixtures real: a recorded response +with its identifiers rewritten. + +**FUN-30.** `ShouldProcess` gives the caller `-WhatIf` and `-Confirm`: + +```powershell +function Remove-StaleReport { + [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] + param( + [Parameter(Mandatory)] + [string]$LiteralPath, + + [ValidateRange(1, 3650)] + [int]$OlderThanDays = 30 + ) + + $cutoff = (Get-Date).AddDays(-$OlderThanDays) + $staleFiles = Get-ChildItem -LiteralPath $LiteralPath -Filter '*.html' -File -ErrorAction Stop | + Where-Object { $_.LastWriteTime -lt $cutoff } + + foreach ($file in $staleFiles) { + if ($PSCmdlet.ShouldProcess($file.FullName, 'Remove report')) { + Remove-Item -LiteralPath $file.FullName -ErrorAction Stop + } + } +} +``` + +**FUN-31.** A read-only function has nothing to confirm. If it wraps its query in `ShouldProcess()`, +`-WhatIf` makes the query return nothing. If it declares the attribute and never calls +`ShouldProcess()`, PSScriptAnalyzer reports `PSShouldProcess`. + +**FUN-32.** `Read-Host` and `$PSCmdlet.ShouldContinue()` cannot be answered in an unattended session: +the prompt fails, returns nothing, or waits. A confirmation that compares the answer with a word +must take anything else, including no answer, as a refusal, and `-Force` is how a scheduled job says +yes. See SEC-05 for values that are missing. + +**FUN-33.** Measured on PowerShell 7.6 and Windows PowerShell 5.1: under `-WhatIf`, +`$items | ForEach-Object -MemberName Name` returns nothing, because that parameter set calls +`ShouldProcess` for each object, while `$items | ForEach-Object { $_.Name }` returns the names. A +script that the function calls also runs its cmdlets under `-WhatIf`, even when the script does not +declare `SupportsShouldProcess`. A release script depends on this; see MOD-14 in +`.github/instructions/powershell-modules.instructions.md`. diff --git a/.github/instructions/powershell-help.instructions.md b/.github/instructions/powershell-help.instructions.md new file mode 100644 index 0000000..9589ea3 --- /dev/null +++ b/.github/instructions/powershell-help.instructions.md @@ -0,0 +1,160 @@ +--- +applyTo: "**/*.ps1,**/*.psm1" +description: "PowerShell comment-based help and code comment rules." +--- + +# PowerShell help and comments + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to every `.ps1` and `.psm1` file. They cover comment-based help and ordinary +comments. Help for commands that a module exports is built from Markdown; that process is described +in `.github/instructions/powershell-platyps.instructions.md`. + +## Rules + +### Comment-based help + +- **DOC-01** Every function and every script has comment-based help with `.SYNOPSIS`, `.DESCRIPTION`, + one `.PARAMETER` for each parameter, at least one `.EXAMPLE`, `.INPUTS`, and `.OUTPUTS`. +- **DOC-02** In a function, the help block is the first thing inside the function body, before + `[CmdletBinding()]`. +- **DOC-03** In a script, the help block comes before the `param()` block, with a blank line between + it and any `#requires` line. +- **DOC-04** Write new help as a `<# ... #>` block. Help written as consecutive `#` lines is equally + valid; do not convert it, and keep a blank line between it and any comment above it. +- **DOC-05** Help MUST describe what the code does. Performance figures, compliance claims, and + behaviour that the code does not have MUST NOT be invented. If a fact is not known, leave it out. +- **DOC-06** `.OUTPUTS` names the same type as `[OutputType()]`. `.INPUTS` names the type that can be + piped in, or says `None`. +- **DOC-07** Help MUST NOT contain a version number, a date, or a change history. An author name is + added only when the user supplies one. +- **DOC-08** Each `.EXAMPLE` starts with a command that runs as written, followed by a blank line and + a sentence saying what it does. An explanatory line placed before that blank line MUST start with + `#` and MUST NOT be the first line. +- **DOC-09** A function that a module exports and documents as external help carries only + `.EXTERNALHELP -Help.xml` and a one-line `.SYNOPSIS`. Private functions and scripts keep + full comment-based help. + +### Comments + +- **DOC-20** A comment explains why the code is the way it is. A comment MUST NOT restate what the + code does, and commented-out code MUST NOT be left in a file. +- **DOC-21** A comment MUST stay true when read on its own. References to a conversation, a review, or + an earlier version of the code MUST NOT be written into a file. + +## Notes and examples + +The function template in the core instructions shows complete help for a function. + +**DOC-02.** `Get-Help` finds a help block only in certain positions. Verified on PowerShell 7.6 and +Windows PowerShell 5.1: + +| Position of the help block | Found by `Get-Help` | +| --- | --- | +| First in the function body, before `[CmdletBinding()]` | Yes | +| Last in the function body | Yes | +| Immediately before the `function` keyword, at most one blank line between | Yes | +| Before the `function` keyword with two or more blank lines between | No | +| Between `[CmdletBinding()]` and `param()` | No | +| After `param()`, before the code | No | + +A block that is not found produces no error. `Get-Help` shows only the generated syntax. + +**DOC-03.** A `#requires` line directly above the help block, with no blank line, stops `Get-Help` +from finding the help: + +```powershell +#requires -Version 7.6 + +<# +.SYNOPSIS +Rotates the application log files. + +.DESCRIPTION +Compresses log files older than the retention period and removes the originals. + +.PARAMETER LogDirectory +Folder that contains the log files. + +.EXAMPLE +./Invoke-LogRotation.ps1 -LogDirectory './logs' + +Rotates the log files in the logs folder. + +.INPUTS +None. + +.OUTPUTS +None. +#> +[CmdletBinding()] +param( + [Parameter(Mandatory)] + [string]$LogDirectory +) +``` + +**DOC-04.** In help written with `#` lines, an ordinary comment directly above the first keyword makes +the whole block an ordinary comment: + +```powershell +function Get-Example { + # Looks up the example record. + + # .SYNOPSIS + # Gets an example. + [CmdletBinding()] + param() +} +``` + +Without the blank line after the first comment, `Get-Help Get-Example` shows no synopsis. + +**DOC-08.** `Get-Help` adds the prompt to the first line of an example, so do not type one. Text after +the blank line is shown as the description. PowerShell 7 shows every line before the blank line as +code; Windows PowerShell 5.1 shows only the first line as code, which is why the command comes first. + +```powershell +<# +.EXAMPLE +Get-ConfigValue -Path './settings.json' -Name 'Region' + +Gets the Region value from settings.json. + +.EXAMPLE +$values = 'Region', 'Tier' | Get-ConfigValue -Path './settings.json' +# $values[0].Name is 'Region' + +Takes the names from the pipeline and keeps the results in a variable. +#> +``` + +**DOC-09.** `.EXTERNALHELP` makes `Get-Help` read the module's compiled help file and ignore the rest +of the comment block, so detail written there is never shown: + +```powershell +function Get-Widget { + <# + .EXTERNALHELP Contoso.Widgets-Help.xml + .SYNOPSIS + Gets widgets from the inventory service. + #> + [CmdletBinding()] + [OutputType('Contoso.Widget')] + param() +} +``` + +**DOC-20.** + +```powershell +# Compliant: says why +# The service rejects requests for more than 100 items, so page through the results. +$pageSize = 100 + +# Non-compliant: restates the code +# Set page size to 100 +$pageSize = 100 +``` diff --git a/.github/instructions/powershell-modules.instructions.md b/.github/instructions/powershell-modules.instructions.md new file mode 100644 index 0000000..f1c8f94 --- /dev/null +++ b/.github/instructions/powershell-modules.instructions.md @@ -0,0 +1,269 @@ +--- +applyTo: "**/*.psm1,**/*.psd1" +description: "PowerShell module layout, manifest, and root module rules." +--- + +# PowerShell modules: layout, manifest, loading + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to `.psm1` and `.psd1` files and to the function files a module loads. + +## Rules + +- **MOD-01** Lay a module out as a manifest (`ModuleName.psd1`), a root module (`ModuleName.psm1`), a + `Public` folder for exported functions, and a `Private` folder for internal ones. Put each function + in its own file, named after the function. +- **MOD-02** The manifest names every exported function in `FunctionsToExport`. Wildcards MUST NOT be + used there, and `CmdletsToExport`, `VariablesToExport`, and `AliasesToExport` are `@()` unless the + module really exports one. +- **MOD-03** A manifest contains only literal values. `GUID` is a real GUID generated once with + `New-Guid`, and `ModuleVersion` follows semantic versioning. +- **MOD-04** `RequiredModules` lists only modules that the code calls. A dependency MUST NOT be added + for a feature the module does not use. +- **MOD-05** The root module sets strict mode, then dot-sources `Classes`, `Private`, and `Public` in + that order, and fails the import when any file fails to load. +- **MOD-06** A module MUST NOT do work when it is imported beyond loading its files: no network calls, + no prompts, no changes to the session outside the module. +- **MOD-07** A function MUST NOT be exported only so that a test can reach it. Tests reach private + functions with `InModuleScope`. + +### Releasing to the PowerShell Gallery + +- **MOD-10** Publish from a staging folder that an allowlist of files and folders fills. + `Publish-PSResource` MUST NOT be pointed at the repository root. +- **MOD-11** Before the upload, import the staged copy in a new process and compare what it exports + with the manifest. +- **MOD-12** `ReleaseNotes` in the manifest covers the current release and points to `CHANGELOG.md`. + Measure `ReleaseNotes`, `Description`, and the full tag list against the Gallery's limits before + the release. +- **MOD-13** Leave a URI key such as `IconUri` out of the manifest until it has a value. An empty + string MUST NOT be assigned to it. +- **MOD-14** In a release script, only the publish step is guarded by `$PSCmdlet.ShouldProcess()`. + Every other step runs with `-WhatIf:$false` or with `$WhatIfPreference` cleared, so that `-WhatIf` + rehearses the whole release. + +## Notes and examples + +### Layout (MOD-01) + +```text +ModuleName/ + ModuleName.psd1 + ModuleName.psm1 + Classes/ optional + Private/ + Get-InternalThing.ps1 + Public/ + Get-Thing.ps1 + Tests/ + Get-Thing.Tests.ps1 + docs/ only when help ships as compiled external help + en-US/ only when help ships as compiled external help +``` + +Add other folders only when the module has something to put in them. + +### Manifest (MOD-02, MOD-03, MOD-04) + +A `.psd1` file is data. PowerShell does not evaluate expressions in it, so `'$(New-Guid)'` stays the +literal text `$(New-Guid)` and the manifest is rejected. Generate the value once and paste it in. + +```powershell +@{ + RootModule = 'ModuleName.psm1' + ModuleVersion = '1.0.0' + GUID = '00000000-0000-0000-0000-000000000000' + Author = 'Name supplied by the user' + Description = 'One sentence that says what the module does.' + + PowerShellVersion = '7.6' + CompatiblePSEditions = @('Core') + + FunctionsToExport = @('Get-Thing', 'Set-Thing') + CmdletsToExport = @() + VariablesToExport = @() + AliasesToExport = @() + + PrivateData = @{ + PSData = @{ + Tags = @('Example') + ProjectUri = 'https://github.com/owner/repository' + LicenseUri = 'https://github.com/owner/repository/blob/main/LICENSE' + } + } +} +``` + +The GUID above is a placeholder. Run `New-Guid` once and paste its output: every module needs its own +GUID, and it never changes afterwards. Set `Author`, the URIs, and `Tags` from what the user or the +repository provides; do not invent them. Leave out `HelpInfoURI` unless the project publishes +updatable help at that address, and leave out `IconUri` when there is no icon (MOD-13). + +### Root module (MOD-05) + +```powershell +# Root module. Files load in the order Classes, Private, Public, so that a type exists before a +# function that names it is defined. The manifest's FunctionsToExport decides what is exported. + +Set-StrictMode -Version Latest + +foreach ($folder in 'Classes', 'Private', 'Public') { + $folderPath = Join-Path -Path $PSScriptRoot -ChildPath $folder + if (-not (Test-Path -LiteralPath $folderPath)) { + continue + } + + foreach ($file in Get-ChildItem -LiteralPath $folderPath -Filter '*.ps1' -File) { + try { + . $file.FullName + } catch { + # A file that fails to load must fail the import. Without this, the loop would carry + # on and the module would import with commands missing. + throw + } + } +} +``` + +Without the `try` and `throw`, a function file that fails to load would produce an error message and +the import would continue, leaving the module loaded with commands missing. + +Classes load first because a function file that uses a class as a parameter type needs the type to +exist when the file is read. When the function file is read first, the import still succeeds and the +function fails with `TypeNotFound` each time it is called. For the same reason such a file cannot be +dot-sourced on its own in a test; import the module instead. A function that only names a class in +`[OutputType()]` writes the name as a string. + +The root module does not set `$ErrorActionPreference`; see ERR-02 in +`.github/instructions/powershell-error-handling.instructions.md`. + +### Testing private functions (MOD-07) + +```powershell +InModuleScope ModuleName { + Get-InternalThing -Name 'alpha' | Should-Be 'ALPHA' +} +``` + +### Releasing to the PowerShell Gallery (MOD-10 to MOD-14) + +A Gallery version is in use from the moment it uploads. It can be unlisted but not deleted. Each +rule here answers a release that passed every local check and then shipped the wrong content or +failed at the upload. + +**MOD-10, MOD-11.** When the repository is the module root, publishing that folder packs the working +tree. Measured with Microsoft.PowerShell.PSResourceGet 1.2.0: the package contains `.git`, the tests, +and the build scripts. A staging folder ships only what the allowlist names: + +```powershell +$shipFiles = 'ModuleName.psd1', 'ModuleName.psm1', 'README.md', 'CHANGELOG.md', 'LICENSE' +$shipFolders = 'Classes', 'Private', 'Public', 'en-US' + +$repositoryRoot = Split-Path -Path $PSScriptRoot -Parent +$outputRoot = Join-Path -Path $repositoryRoot -ChildPath 'out' +$stagePath = Join-Path -Path $outputRoot -ChildPath 'ModuleName' +if (Test-Path -LiteralPath $stagePath) { + Remove-Item -LiteralPath $stagePath -Recurse -Force -WhatIf:$false +} +$null = New-Item -Path $stagePath -ItemType Directory -Force -WhatIf:$false + +foreach ($item in $shipFiles + $shipFolders) { + $sourcePath = Join-Path -Path $repositoryRoot -ChildPath $item + Copy-Item -LiteralPath $sourcePath -Destination $stagePath -Recurse -WhatIf:$false +} + +# A new process proves that the staged copy imports by itself. +$manifestPath = Join-Path -Path $stagePath -ChildPath 'ModuleName.psd1' +$listExports = '(Import-Module -Name $args[0] -PassThru).ExportedFunctions.Keys' +$exported = @(& pwsh -NoProfile -Command $listExports -args $manifestPath) +if ($LASTEXITCODE -ne 0) { + throw "The staged module failed to import. Exit code $LASTEXITCODE." +} + +$expected = @((Import-PowerShellDataFile -LiteralPath $manifestPath).FunctionsToExport) +if (Compare-Object -ReferenceObject $expected -DifferenceObject $exported) { + throw 'The staged module does not export what its manifest lists.' +} + +if ($PSCmdlet.ShouldProcess($stagePath, 'Publish to the PowerShell Gallery')) { + Publish-PSResource -Path $stagePath -Repository PSGallery -ApiKey $env:PSGALLERY_API_KEY +} +``` + +The script declares `[CmdletBinding(SupportsShouldProcess)]`, keeps `out/` in `.gitignore`, and takes +the API key from an environment variable that the CI secret store fills (CIC-06). + +**MOD-12.** Three manifest fields have limits that are enforced only at upload, so every local check +passes until the publish step is refused. The limits below were met in real releases; the release +notes limit is stated in the Gallery's error response. + +| Field | Limit | +| --- | --- | +| `ReleaseNotes` | 10,600 characters | +| `Description` | 4,000 characters | +| Tags | 4,000 characters for the whole list | + +The tag list that the Gallery stores is the manifest's `Tags` plus the tags the publish adds: +`PSModule`, `PSEdition_` for each compatible edition, `PSIncludes_Function`, and +`PSFunction_` and `PSCommand_` for every exported function. A module that keeps adding +commands therefore reaches the limit without its `Tags` key changing, and `ReleaseNotes` grows the +same way when every release adds a paragraph and none removes one. Measure all three in the release +script and in a test: + +```powershell +$manifest = Import-PowerShellDataFile -LiteralPath $manifestPath +$psData = $manifest.PrivateData.PSData +$publishTags = @( + $psData.Tags + 'PSModule' + 'PSIncludes_Function' + foreach ($edition in $manifest.CompatiblePSEditions) { + "PSEdition_$edition" + } + foreach ($functionName in $manifest.FunctionsToExport) { + "PSFunction_$functionName" + "PSCommand_$functionName" + } +) + +$measurements = @( + @{ Field = 'Description'; Length = $manifest.Description.Length; Limit = 4000 } + @{ Field = 'Tags'; Length = ($publishTags -join ' ').Length; Limit = 4000 } + @{ Field = 'ReleaseNotes'; Length = $psData.ReleaseNotes.Length; Limit = 10600 } +) +foreach ($measurement in $measurements) { + if ($measurement.Length -gt $measurement.Limit) { + $problem = "The manifest's $($measurement.Field) is $($measurement.Length) characters." + throw "$problem The PowerShell Gallery accepts at most $($measurement.Limit)." + } +} +``` + +A module that exports cmdlets or DSC resources gains further tags of the same kind. + +**MOD-13.** `IconUri = ''` is not "no icon". Measured with PSResourceGet 1.2.0, the pack fails with +`IconUrl cannot be empty`, and the message names neither the manifest nor the key. + +**MOD-14.** `-WhatIf` sets `$WhatIfPreference`, and every cmdlet and script that the release script +calls inherits it (FUN-33). Unless the other steps are pinned, a rehearsal copies nothing and builds +nothing, and then either fails on the empty folder or passes having checked nothing. A script that +does not declare `SupportsShouldProcess` has no `-WhatIf` parameter to pin, so clear the preference +around the call: + +```powershell +$savedWhatIf = $WhatIfPreference +$WhatIfPreference = $false +try { + & (Join-Path -Path $PSScriptRoot -ChildPath 'Build-Help.ps1') +} finally { + $WhatIfPreference = $savedWhatIf +} +``` + +Rehearse from a clean checkout, and test `-WhatIf` together with the script's other switches. A +folder left by an earlier run hides a step that now produces nothing. + +Run the release from a version tag. The workflow runs every check again, refuses a tag that differs +from the manifest's `ModuleVersion`, stages, verifies, and publishes (CIC-08, CIC-10). diff --git a/.github/instructions/powershell-pester.instructions.md b/.github/instructions/powershell-pester.instructions.md new file mode 100644 index 0000000..4d70edd --- /dev/null +++ b/.github/instructions/powershell-pester.instructions.md @@ -0,0 +1,383 @@ +--- +applyTo: "**/*.Tests.ps1" +description: "Pester 6 testing rules for PowerShell code." +--- + +# PowerShell testing with Pester + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to test files (`*.Tests.ps1`). They target Pester 6.2.0, which runs on PowerShell 7 +and Windows PowerShell 5.1. Longer guides for specific topics are listed at the end. + +## Rules + +### Files + +- **TST-01** A test file is named after the file it tests, `.Tests.ps1`, and starts with + `#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' }`. +- **TST-02** Every test file is self-contained. It loads the code under test in its own top-level + `BeforeAll`, and builds the data for `-ForEach` in `BeforeDiscovery`. +- **TST-03** Build paths from `$PSScriptRoot`. Files that a test creates go in `$TestDrive`. +- **TST-04** Tag every `Describe` block, for example `Unit` or `Integration`. `None` is reserved by + Pester and MUST NOT be used as a tag. +- **TST-05** Import a module under test only when it is not already loaded, and do not remove it + afterwards. Only the module's contract test imports it with `-Force`. + +### Assertions + +- **TST-10** In a new test file use the Pester 6 assertions (`Should-Be`, `Should-Throw`). In an + existing file keep the style it already uses. The two styles MUST NOT be mixed in one file. +- **TST-11** Every `It` block MUST contain at least one assertion that fails when the behaviour is + wrong. Asserting only that a result is not null is not enough when a specific value is known. +- **TST-12** Assert the number of results before reading one by index, and use `Should-All` instead of + assertions inside a `foreach` loop, so that an empty result cannot pass. +- **TST-13** Assert a custom object's type with `Should-HaveType ''`. + `Should-HaveType ([PSCustomObject])` MUST NOT be used; it passes for any value. +- **TST-14** `Should-BeCollection` does not check order in Pester 6.2.0. To assert order, assert the + count and then the element at each index. +- **TST-15** Assert an expected failure with `Should-Throw`, giving the exception type or the error ID + where the code defines one. A message pattern needs wildcards: `-ExceptionMessage '*not found*'`. +- **TST-16** There is no `Should-NotThrow`. To assert that a command does not fail, call it with + `-ErrorAction Stop`; any error then fails the test. Without it, a non-terminating error does not. +- **TST-17** Assert a non-terminating error by calling the command with `-ErrorAction Continue`, + merging the error stream (`2>&1`), and counting the `ErrorRecord` objects. + +### Mocks + +- **TST-20** Mock only what crosses a boundary: network, file system, clock, other modules. The + function under test MUST NOT be mocked, and a helper in the same module is mocked only when the + helper is itself the boundary. +- **TST-21** A mock for a command that a module calls MUST name the module: `Mock -ModuleName`. Run + assertions against private functions inside `InModuleScope`. +- **TST-22** Assert calls with `Should-Invoke -Times -Exactly`. `Assert-MockCalled` was removed in + Pester 6. +- **TST-23** Define a mock that setup code depends on in an enclosing `BeforeAll`, and assert a call + that was made in `BeforeAll` with `Should-Invoke -Scope Context`. + +### Test data + +- **TST-30** Pass cases with `-ForEach` as hashtables. The list MUST NOT be empty or `$null`, and a key + MUST NOT have the name of an automatic variable such as `Input` or `Args`. +- **TST-31** Tests MUST NOT depend on each other, on execution order, on the real network, or on the + current time. Mock `Get-Date` when time matters, and restore anything the test changes. + +### Coverage and CI + +- **TST-40** Tests cover at least 80% of shipped code, as Pester's `CoveragePercent` reports it, and + CI fails below that. +- **TST-41** Cover the contract, not only the lines: each parameter set, each documented output, each + validation failure, each error path, and both outcomes of a `Test-` function. +- **TST-42** CI fails when the Pester result is not `Passed` or when no tests ran. Checking + `FailedCount` alone misses a failed `BeforeAll` or `AfterAll` and a file that failed discovery. +- **TST-43** Add performance or security tests only for a function that has such a requirement. +- **TST-44** For every parameter that accepts pipeline input, test both the piped call and the call + by parameter, piping what the real upstream command emits. +- **TST-45** Every usage example in the README and in help has a test that runs it as written. +- **TST-46** CI runs the unit tests with `Run.Shuffle` enabled and puts the seed in the failure + message. + +## Notes and examples + +### A complete test file + +The function under test is the template in the core instructions. + +```powershell +#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } + +BeforeAll { + . (Join-Path -Path $PSScriptRoot -ChildPath 'Get-ConfigValue.ps1') +} + +Describe 'Get-ConfigValue' -Tag 'Unit' { + BeforeAll { + $configPath = Join-Path -Path $TestDrive -ChildPath 'settings.json' + $json = '{ "Region": "westeurope", "Tier": "standard" }' + Set-Content -LiteralPath $configPath -Value $json -Encoding ascii + } + + Context 'When the requested values exist' { + It 'Returns with the value ' -ForEach @( + @{ ValueName = 'Region'; Expected = 'westeurope' } + @{ ValueName = 'Tier'; Expected = 'standard' } + ) { + $result = Get-ConfigValue -Path $configPath -Name $ValueName + + $result | Should-HaveType 'Example.ConfigValue' + $result.Name | Should-Be $ValueName + $result.Value | Should-Be $Expected + } + + It 'Emits one object for each name received from the pipeline, in order' { + $result = @('Tier', 'Region' | Get-ConfigValue -Path $configPath) + + $result | Should-BeCollection -Count 2 + $result[0].Name | Should-Be 'Tier' + $result[1].Name | Should-Be 'Region' + } + } + + Context 'When a requested value is missing' { + It 'Writes one non-terminating error and still returns the values that exist' { + $output = Get-ConfigValue -Path $configPath -Name 'Missing', 'Region' -ErrorAction Continue 2>&1 + $errors = @($output | Where-Object { $_ -is [System.Management.Automation.ErrorRecord] }) + $values = @($output | Where-Object { $_ -isnot [System.Management.Automation.ErrorRecord] }) + + $errors | Should-BeCollection -Count 1 + $errors[0].FullyQualifiedErrorId | Should-BeLikeString 'ConfigValueNotFound*' + $values | Should-BeCollection -Count 1 + $values[0].Name | Should-Be 'Region' + } + } + + Context 'When the file cannot be used' { + It 'Throws when the file does not exist' { + $missingPath = Join-Path -Path $TestDrive -ChildPath 'absent.json' + + { Get-ConfigValue -Path $missingPath -Name 'Region' } | + Should-Throw -ExceptionType ([System.Management.Automation.ItemNotFoundException]) + } + + It 'Throws when the file does not contain a JSON object' { + $arrayPath = Join-Path -Path $TestDrive -ChildPath 'array.json' + Set-Content -LiteralPath $arrayPath -Value '[1, 2]' -Encoding ascii + + { Get-ConfigValue -Path $arrayPath -Name 'Region' } | + Should-Throw -ExceptionType ([System.IO.InvalidDataException]) + } + } +} +``` + +This file passes on Pester 6.2.0 under PowerShell 7.6 and Windows PowerShell 5.1. + +### Loading the code under test (TST-02, TST-03, TST-21) + +For a standalone function file, dot-source it as the file above does. For a module, import the +manifest and name the module in mocks: + +```powershell +#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } + +BeforeAll { + if (-not (Get-Module -Name ModuleName)) { + $moduleRoot = Split-Path -Path $PSScriptRoot -Parent + Import-Module -Name (Join-Path -Path $moduleRoot -ChildPath 'ModuleName.psd1') + } +} + +Describe 'Get-Thing' -Tag 'Unit' { + It 'Asks the service once for each name' { + Mock -CommandName Invoke-RestMethod -ModuleName ModuleName -MockWith { + [PSCustomObject]@{ name = 'alpha'; state = 'ready' } + } + + $result = Get-Thing -Name 'alpha' + + $result.State | Should-Be 'ready' + Should-Invoke -CommandName Invoke-RestMethod -ModuleName ModuleName -Times 1 -Exactly + } +} +``` + +A mock declared without `-ModuleName` replaces the command only for calls made from the test file. A +call made inside the module still reaches the real command. + +A mock of a native executable reports its exit code with `$global:LASTEXITCODE = 3`. An assignment +to `$LASTEXITCODE` without the scope creates a local variable that the code under test never reads. + +**TST-05.** Self-contained does not mean imported again. `Import-Module -Force` in every `BeforeAll` +and `Remove-Module` in every `AfterAll` reloads the module once for each file; one suite of 111 files +spent 21 seconds of an 80-second run doing only that. The contract test, which asserts what a newly +imported module looks like, is the one file that passes `-Force`. Two consequences follow. State +that one file leaves in module scope is visible to the next, which is what the shuffled run in +TST-46 exists to catch. And an interactive session keeps the code it loaded, so after editing the +module, import it once with `-Force` or run the tests in a new process, as CI does. + +**TST-23.** A `BeforeAll` in a `Context` runs before any `BeforeEach`, so a mock defined in the +parent's `BeforeEach` is not active while it runs, and the command it calls runs for real. +`Should-Invoke` counts only the calls made inside the current `It` unless a scope is given. Both +were measured on Pester 6.2.0. + +```powershell +Describe 'Get-ServerHealth' -Tag 'Unit' { + BeforeAll { + Mock -CommandName Get-CimInstance -ModuleName ModuleName -MockWith { + [PSCustomObject]@{ FreePhysicalMemory = 4GB } + } + } + + Context 'When one server is queried for the whole context' { + BeforeAll { + $health = Get-ServerHealth -ComputerName 'server01.example.com' + } + + It 'Queries the server once' { + $health | Should-NotBeNull + Should-Invoke -CommandName Get-CimInstance -ModuleName ModuleName -Times 1 -Exactly -Scope Context + } + } +} +``` + +`Split-Path` and a two-argument `Join-Path` also work on Windows PowerShell 5.1. `Join-Path` with +several child paths, and paths written as `"$PSScriptRoot/../.."`, are fragile there. + +### Assertions that cannot pass by accident (TST-11 to TST-17) + +Each statement was verified on Pester 6.2.0. + +| Assertion | Behaviour | +| --- | --- | +| `5 \| Should-HaveType ([PSCustomObject])` | Passes. Every piped value is wrapped, so this proves nothing. | +| `$widget \| Should-HaveType 'Contoso.Widget'` | Passes only when that is the object's type name. | +| `$widget.PSTypeName \| Should-Be 'Contoso.Widget'` | Always fails. `PSTypeName` is not a property. | +| `1, 2, 3 \| Should-BeCollection @(3, 2, 1)` | Passes. Order is not checked. | +| `1, 2, 3 \| Should-BeCollection -Count 3` | Passes. Use this before indexing. | +| `@() \| Should-All { $_ -gt 0 }` | Fails. An empty input cannot pass. | +| `@() \| Should-NotBeNull` | Fails. | +| `{ throw 'a b c' } \| Should-Throw -ExceptionMessage 'b'` | Fails. The pattern must match the whole message. | +| `{ throw 'a b c' } \| Should-Throw -ExceptionMessage '*b*'` | Passes. | + +Pin the Pester version in CI. The ordering behaviour of `Should-BeCollection` is changing in Pester's +development branch, so an unpinned install can change what a test means. + +For a typed array, pass the value with `-Actual` so that the pipeline does not unroll it: + +```powershell +Should-HaveType -Actual $result.Names -Expected ([string[]]) +``` + +`-ErrorVariable` can hold more than one record for a single failure, so count records from the merged +stream as the complete test file does. + +Pass `-ErrorAction Continue` on a call that is expected to write a non-terminating error. Without it +the outcome depends on `$ErrorActionPreference` in the session that runs the tests. GitHub Actions +sets that to `Stop` for `pwsh` steps, which turns the error into a terminating one, so the test fails +in CI and passes on a developer's computer. + +`Should-Throw -ExceptionType` compares the outer exception. A failure inside a .NET method call +arrives wrapped in a `MethodInvocationException`, so assert that type, or assert the message or the +error ID instead. + +`Should-Throw -FullyQualifiedErrorId` compares the whole ID with `-like`. The ID that a function gives +its `ErrorRecord` is followed by a comma and the command name, so write +`'ConfigValueNotFound,Get-ConfigValue'` or `'ConfigValueNotFound,*'`, not `'ConfigValueNotFound'`. + +`Should-Throw` runs its script block with the error preference `Stop`, so a non-terminating error +from a compiled cmdlet, or from a function defined in the test file, counts as thrown. A function in +a module does not see that preference. Its non-terminating error counts only where the session +preference is `Stop`, so the same test passes in CI and fails on a developer's computer. To assert +that a module function fails when its caller asks it to stop, pass `-ErrorAction Stop` inside the +script block. With `-AllowNonTerminatingError`, only a terminating error passes. + +### Pipeline input and documented examples (TST-44, TST-45) + +```powershell +It 'Gives the same summary for piped input and for an array argument' { + $lengths = 10, 20, 30 + + $piped = @($lengths | Get-SizeSummary) + $byParameter = @(Get-SizeSummary -Length $lengths) + + $piped | Should-BeCollection -Count 1 + $piped[0].Total | Should-Be $byParameter[0].Total +} +``` + +The call by parameter passes whether or not the function collects its input (FUN-25). Only the piped +call proves that it does. A usage example in the README or in help is an untested claim until a test +runs it as written. + +### Test data (TST-30) + +```powershell +BeforeDiscovery { + $cases = @( + @{ Text = 'alpha'; Expected = 'ALPHA' } + @{ Text = 'beta'; Expected = 'BETA' } + ) +} + +Describe 'ConvertTo-UpperText' -Tag 'Unit' { + It 'Converts to ' -ForEach $cases { + ConvertTo-UpperText -Text $Text | Should-Be $Expected + } +} +``` + +Each key becomes a variable inside the `It` block. A `-ForEach` value that is empty or `$null` fails +discovery in Pester 6. + +### The CI gate (TST-40, TST-42) + +```powershell +Import-Module -Name Pester -RequiredVersion 6.2.0 + +$configuration = New-PesterConfiguration +$configuration.Run.Path = './Tests' +$configuration.Run.PassThru = $true +$configuration.Run.Shuffle = $true +$configuration.CodeCoverage.Enabled = $true +$configuration.CodeCoverage.Path = './Public', './Private' + +$result = Invoke-Pester -Configuration $configuration + +if ($null -eq $result -or $result.TotalCount -eq 0) { + throw 'Pester ran no tests.' +} + +if ($result.Result -ne 'Passed') { + $counts = $result.FailedCount, $result.FailedBlocksCount, $result.FailedContainersCount + $summary = 'Failed tests: {0}. Failed blocks: {1}. Failed files: {2}.' -f $counts + $seed = $result.Configuration.Run.ShuffleSeed.Value + throw "Pester result is '$($result.Result)'. $summary Replay with Run.ShuffleSeed = $seed." +} + +$coverage = [math]::Round($result.CodeCoverage.CoveragePercent, 2) +if ($coverage -lt 80) { + throw "Code coverage is $coverage percent. The minimum is 80." +} +``` + +`CodeCoverage.CoveragePercentTarget` only sets the figure that Pester reports against. It does not +fail the run, so the script compares the percentage itself. When Pester 6.2.0 finds no test files it +reports an error and returns nothing, which is why the script tests for `$null` first. + +`CoveragePercent` is the share of commands that ran, not of lines. A line that holds several +commands counts once for each of them. + +### Pester 6 specifics + +- A second `BeforeAll`, `BeforeEach`, `AfterAll`, or `AfterEach` in one block is allowed from 6.2. + Pester 6.1 reports it as an error. +- `Run.Parallel`, `Mock.Global`, and shared setup in `Pester.BeforeContainer.ps1` files are marked + experimental in 6.2.0. Do not enable or add them unless the user asks; TST-02 keeps each test file + self-contained. +- `Run.Shuffle` is marked experimental too, and is the exception (TST-46). It randomizes the order + of files, blocks, and tests, which exposes a test that passes only after another one has run. Leave + `Run.ShuffleSeed` at `0` for a new seed on each run, and replay a failure by setting it to the seed + in the message. A file opts out with a `#pester:no-shuffle` comment. +- Do not set `Should.DisableV5` while any test file still uses the `Should -Be` style. +- Removed in Pester 6: `Assert-MockCalled`, `Assert-VerifiableMock`, `It -Pending`, and + `Set-ItResult -Pending`. Use `Should-Invoke`, and `It -Skip` or `Set-ItResult -Skipped`. + +### Further reading + +These guides are reference material. They are not loaded automatically; open the one that matches +the task. + +| Topic | File | +| --- | --- | +| Assertion reference | `.github/instructions/pester-supporting-docs/assertion-guide.md` | +| Mocking patterns | `.github/instructions/pester-supporting-docs/mocking-patterns.md` | +| Test layout and tagging | `.github/instructions/pester-supporting-docs/test-structure-guide.md` | +| Test data | `.github/instructions/pester-supporting-docs/test-data-guide.md` | +| Configuration options | `.github/instructions/pester-supporting-docs/pester-configuration.md` | +| Running tests | `.github/instructions/pester-supporting-docs/test-execution.md` | +| CI integration | `.github/instructions/pester-supporting-docs/cicd-integration.md` | +| Custom assertions | `.github/instructions/pester-supporting-docs/custom-assertions.md` | +| Migrating from Pester 5 | `.github/instructions/pester-supporting-docs/v6-migration.md` | +| Unit, integration, performance, and security templates | `.github/instructions/pester-supporting-docs/unit-test-template.md` and the three files beside it | diff --git a/.github/instructions/powershell-platyps.instructions.md b/.github/instructions/powershell-platyps.instructions.md new file mode 100644 index 0000000..ab94094 --- /dev/null +++ b/.github/instructions/powershell-platyps.instructions.md @@ -0,0 +1,312 @@ +--- +applyTo: "**/docs/**/*.md" +description: "Rules for PowerShell module help built with Microsoft.PowerShell.PlatyPS." +--- + +# PowerShell module help with PlatyPS + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to the help Markdown under a module's `docs` folder and to the scripts that build +it. A module that exports commands writes their help as Markdown, and ships it compiled as external +help (MAML) that `Get-Help` reads. Functions that are not exported, and standalone scripts, use +comment-based help instead; see `.github/instructions/powershell-help.instructions.md`. + +## Rules + +- **PLT-01** Use Microsoft.PowerShell.PlatyPS 1.0.3 or later. The retired `platyPS` module and its + commands (`New-MarkdownHelp`, `Update-MarkdownHelp`, `New-ExternalHelp`, `Get-HelpPreview`) MUST NOT + be used. +- **PLT-02** The Markdown under `docs//` is the source of help for exported commands. The + compiled `en-US/-Help.xml` is build output and MUST NOT be edited by hand. +- **PLT-03** Syntax blocks and parameter metadata in the Markdown are generated. To change them, + change the function and run `Update-MarkdownCommandHelp`; they MUST NOT be edited by hand. +- **PLT-04** Every exported function carries `.EXTERNALHELP -Help.xml` inside its + `<# ... #>` block. Add it only after the Markdown has first been generated from the function's + comment-based help. +- **PLT-05** In the Markdown, put the command of each example in a fenced `powershell` code block, + with the explanation as ordinary text after it. +- **PLT-06** Committed Markdown MUST NOT contain a placeholder in double braces, such as + `{{ Fill in the Description }}`. The content follows the same rules as comment-based help: it + describes what the code does and invents nothing. +- **PLT-07** A related link is either a bare topic name, written `[Get-Thing]()`, or an absolute + `https://` URL. A relative path MUST NOT be used. +- **PLT-08** Pass `-Locale` explicitly whenever Markdown is generated. +- **PLT-09** CI fails when the documented commands differ from the exported commands, when a command's + documented parameters differ from its real ones, and when `Test-MarkdownCommandHelp` reports a + problem. + +## Notes and examples + +### Use the supported module (PLT-01) + +```powershell +Install-PSResource -Name Microsoft.PowerShell.PlatyPS -TrustRepository +``` + +The two modules have different command names and a different Markdown schema: + +| Retired `platyPS` 0.14 | Microsoft.PowerShell.PlatyPS 1.x | +| --- | --- | +| `New-MarkdownHelp` | `New-MarkdownCommandHelp` | +| `Update-MarkdownHelp` | `Update-MarkdownCommandHelp` | +| `New-ExternalHelp` | `Export-MamlCommandHelp` | +| `New-ExternalHelpCab` | `New-HelpCabinetFile` | +| `Get-HelpPreview` | `Show-HelpPreview` | +| `Update-MarkdownHelpModule` | `Update-MarkdownModuleFile` | + +`Update-MarkdownCommandHelp` reads Markdown written by the old module and rewrites it in the current +schema, so an existing project does not start its documentation again. + +### How the pieces fit (PLT-02) + +```text +Public/Get-Thing.ps1 the function, with .EXTERNALHELP and a one-line .SYNOPSIS + | New-MarkdownCommandHelp once, at first generation + | Update-MarkdownCommandHelp whenever the signature changes + v +docs/ModuleName/Get-Thing.md source: edit here, commit +docs/ModuleName/ModuleName.md module page, commit + | Export-MamlCommandHelp build step + v +en-US/ModuleName-Help.xml build output: what Get-Help reads +``` + +### The `.EXTERNALHELP` keyword (PLT-04) + +Comment-based help takes precedence over a compiled help file. Without the keyword, `Get-Help` shows +the comment block and ignores the compiled file. With it, `Get-Help` reads the compiled file and +ignores the rest of the comment block. + +```powershell +function Get-Thing { + <# + .EXTERNALHELP ModuleName-Help.xml + .SYNOPSIS + Gets things from the inventory service. + #> + [CmdletBinding()] + [OutputType('Contoso.Thing')] + param( + [Parameter(Mandatory, ValueFromPipeline)] + [string[]]$Name + ) +} +``` + +Order matters for a new exported function, because `New-MarkdownCommandHelp` takes its text from +`Get-Help`, and the keyword hides the comment block from `Get-Help`: + +1. Write full comment-based help in the function. +2. Run `New-MarkdownCommandHelp`. The text is copied into the Markdown. +3. Add `.EXTERNALHELP` and reduce the block to a one-line `.SYNOPSIS`. + +Done in the wrong order, the build succeeds and the generated Markdown contains only placeholders. + +Details that decide whether the compiled help is found: + +- The value is a file name with no path, on the same line as the keyword. +- `Export-MamlCommandHelp` writes `-Help.xml` with a capital `H`. Copy that exact name. On + Linux and macOS a different case means the file is not found and every command loses its help. +- Keep the keyword inside the `<# ... #>` block. Written as a `#` line directly under an ordinary + comment, it is ignored without any error. +- The keyword applies even when the compiled file does not exist yet. In a working tree that has not + been built, `Get-Help` shows only the generated syntax. Preview with + `Show-HelpPreview -Path ./maml/ModuleName/ModuleName-Help.xml`, or build first. + +### Generating the Markdown the first time (PLT-08) + +```powershell +Import-Module -Name ./ModuleName.psd1 -Force + +$newMarkdownParameters = @{ + ModuleInfo = Get-Module -Name ModuleName + OutputFolder = './docs' + WithModulePage = $true + Locale = 'en-US' +} +New-MarkdownCommandHelp @newMarkdownParameters +``` + +Without `-Locale`, the generating computer's culture is written into every file, which then disagrees +with the `en-US` folder the help is compiled into. + +The result is `./docs/ModuleName/` with one file for each exported command and a module page. The +files are templates: every placeholder in double braces has to be replaced with real content, or its +section removed where the section is optional, as `## ALIASES` is. + +Check the `## INPUTS` and `## OUTPUTS` sections after generating. Each type is a level-three heading +that holds the full type name and nothing else, with the description as text under it. Text taken +from comment-based help can end up in the heading. + +### Writing examples (PLT-05) + +````markdown +### Example 1: Get one thing + +```powershell +Get-Thing -Name 'alpha' +``` + +Gets the thing named alpha. +```` + +This is the form that Microsoft documents for the Markdown, and it is what renders as code where the +Markdown is published. Microsoft.PowerShell.PlatyPS 1.0.3 does not convert the block when it compiles +the help: `Get-Help` shows the example with its fence lines as plain text. Keep the fences anyway. +Without them the command is compiled as a paragraph, followed by a stray control character. + +### Updating after the module changes (PLT-03) + +```powershell +Import-Module -Name ./ModuleName.psd1 -Force + +Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | + Where-Object Filetype -Match 'CommandHelp' | + Update-MarkdownCommandHelp -Path { $_.FilePath } + +Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | + Where-Object Filetype -Match 'CommandHelp' | + Import-MarkdownCommandHelp -Path { $_.FilePath } | + Update-MarkdownModuleFile -Path ./docs/ModuleName/ModuleName.md +``` + +`-Path { $_.FilePath }` is a script block that is evaluated for each pipeline item. Writing +`-Path $_.FilePath` binds one value before the pipeline runs and fails. + +The update adds what it can verify and keeps the existing text. It writes backup files next to the +originals; compare against them before committing. Two things it cannot infer: + +- Output types come from `[OutputType()]` on the function. +- Wildcard support is shown only when the parameter has `[SupportsWildcards()]`. + +A command added since the last run has no Markdown to update. Run `New-MarkdownCommandHelp` for it. + +### Validating (PLT-06, PLT-07) + +```powershell +Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | + Where-Object Filetype -Match 'CommandHelp' | + Test-MarkdownCommandHelp -Path { $_.FilePath } -DetailView + +$unfilled = Select-String -Path ./docs/ModuleName/*.md -Pattern '\{\{[^}]*\}\}' -List +if ($unfilled) { + $names = ($unfilled.Path | Split-Path -Leaf) -join ', ' + throw "Help templates still contain placeholders: $names" +} + +$relativeLinks = Select-String -Path ./docs/ModuleName/*.md -Pattern '^\s*-?\s*\[.+\]\((?!https?://|\))' +if ($relativeLinks) { + $places = ($relativeLinks | ForEach-Object { "$($_.Filename):$($_.LineNumber)" }) -join ', ' + throw "Relative links in help Markdown: $places" +} +``` + +`Test-MarkdownCommandHelp` accepts a relative path in a related link, but `Get-Help` then fails when +it reads the compiled help. The two valid forms are not interchangeable: + +| Target | Form | +| --- | --- | +| A command in this module, or an `about_` topic | `- [Get-Thing]()` | +| Anything outside the installed module | `- [Title](https://example.com/page)` | + +The pattern above allows empty parentheses so that the bare form passes. + +### Building the compiled help + +```powershell +Measure-PlatyPSMarkdown -Path ./docs/ModuleName/*.md | + Where-Object Filetype -Match 'CommandHelp' | + Import-MarkdownCommandHelp -Path { $_.FilePath } | + Export-MamlCommandHelp -OutputFolder ./maml -Force + +$cultureFolder = Join-Path -Path $moduleOutputPath -ChildPath 'en-US' +$null = New-Item -Path $cultureFolder -ItemType Directory -Force +Copy-Item -LiteralPath ./maml/ModuleName/ModuleName-Help.xml -Destination $cultureFolder -Force +``` + +`maml/` is a build intermediate; add it to `.gitignore`. `about_*.help.txt` files are plain text +written by hand and go in the same culture folder. + +### Markdown linting + +Generated help does not pass a general markdownlint configuration: the syntax block has no language +label, and the module page writes the description on one line. Both are rewritten on every update, so +exclude the generated files from the linter instead of correcting them: + +```yaml +- name: Lint Markdown + uses: DavidAnson/markdownlint-cli2-action@v14 + with: + globs: | + **/*.md + !**/docs/*/*.md +``` + +A `.markdownlintignore` file has no effect once globs are passed on the command line. + +### The CI drift gate (PLT-09) + +```powershell +#Requires -Modules @{ ModuleName = 'Microsoft.PowerShell.PlatyPS'; ModuleVersion = '1.0.3' } + +Import-Module -Name ./ModuleName.psd1 -Force + +$documented = @((Get-ChildItem -Path ./docs/ModuleName/*.md).BaseName | Where-Object { $_ -ne 'ModuleName' }) +$exported = @((Get-Module -Name ModuleName).ExportedFunctions.Keys) + +$missing = @($exported | Where-Object { $_ -notin $documented }) +$orphaned = @($documented | Where-Object { $_ -notin $exported }) + +if ($missing.Count -gt 0) { + throw "Exported commands with no help Markdown: $($missing -join ', ')" +} +if ($orphaned.Count -gt 0) { + throw "Help Markdown for commands that are no longer exported: $($orphaned -join ', ')" +} +``` + +To catch a changed signature as well, compare the parameters in the committed Markdown with those of +the loaded command: + +```powershell +$commonParameters = [System.Management.Automation.PSCmdlet]::CommonParameters + + [System.Management.Automation.PSCmdlet]::OptionalCommonParameters + +foreach ($commandName in $exported) { + $committed = Import-MarkdownCommandHelp -Path "./docs/ModuleName/$commandName.md" + $documented = @($committed.Parameters | ForEach-Object { $_.Name } | Sort-Object) + $actual = @((Get-Command -Name $commandName).Parameters.Keys | + Where-Object { $commonParameters -notcontains $_ } | + Sort-Object) + + if (($documented -join ',') -ne ($actual -join ',')) { + throw "The documented parameters of $commandName are out of date. Run the help update." + } +} +``` + +`Compare-CommandHelp` is not suitable for this check. It writes a line for every property it +inspects, so it returns output even when the two sides are identical. + +### Migrating documentation written with platyPS 0.14 + +1. Do not load both modules in one session. Start a new session for the migration. +2. Run `Update-MarkdownCommandHelp` over the existing files. +3. Fill in or delete the `## ALIASES` section that appears in each converted file. +4. Add `.EXTERNALHELP` to every exported function and reduce its comment block to a one-line + `.SYNOPSIS`. +5. Compare every file with its backup before committing. + +### Comment-based help keywords and their Markdown headings + +| Comment-based help | PlatyPS Markdown | +| --- | --- | +| `.SYNOPSIS` | `## SYNOPSIS` | +| `.DESCRIPTION` | `## DESCRIPTION` | +| `.PARAMETER Name` | `### -Name` under `## PARAMETERS` | +| `.EXAMPLE` | `### Example 1: ` under `## EXAMPLES` | +| `.INPUTS`, `.OUTPUTS` | `## INPUTS`, `## OUTPUTS` | +| `.NOTES` | `## NOTES` | +| `.LINK` | `## RELATED LINKS` | diff --git a/.github/instructions/powershell-pull-requests.instructions.md b/.github/instructions/powershell-pull-requests.instructions.md new file mode 100644 index 0000000..a779dd9 --- /dev/null +++ b/.github/instructions/powershell-pull-requests.instructions.md @@ -0,0 +1,157 @@ +--- +applyTo: "**" +description: "Branch, commit, and pull request conventions." +--- + +# Branches, commits, and pull requests + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply whenever you commit or open a pull request in a repository that uses these +standards. They match the history of those repositories, so a new pull request reads like the ones +before it. + +## Rules + +### Branch + +- **PRQ-01** Never commit to the default branch. Before starting work, run `git fetch` and confirm + that the local default branch is not behind the remote, then branch from the up-to-date default + branch. +- **PRQ-02** Name the branch `<type>/<short-kebab-description>`, with the same type as the title. A + release branch is `release/vX.Y.Z`. +- **PRQ-03** One concern per branch. An unrelated fix found on the way gets its own branch and pull + request. + +### Commit messages and titles + +- **PRQ-10** Use Conventional Commits, `<type>(<scope>): <subject>`, for commit messages and for the + pull request title. A squash merge turns the title into the commit on the default branch. +- **PRQ-11** The type is `feat`, `fix`, `docs`, `refactor`, `test`, `perf`, `ci`, `build`, or `chore`, + and a release is `release: X.Y.Z`. The subject is imperative, lower case, has no trailing period, + and is at most 72 characters. +- **PRQ-12** Wrap the body at 72 columns and explain why the change was needed. Mark a breaking + change with `!` after the type or scope and a `BREAKING CHANGE:` footer that says what a caller + must do. +- **PRQ-13** Commits, titles, pull request bodies, and files MUST NOT carry AI tool attribution: no + `Co-Authored-By` trailer for a tool and no "Generated with" footer. + +### A reader who was not there + +- **PRQ-20** Describe the change, not the session: what the code does now and why. Leave out how the + work unfolded, and mention a rejected approach only when a reviewer would otherwise ask about it. +- **PRQ-21** Write in the third person about the code. Conversational voice, references that a + stranger cannot resolve, mentions of an AI tool or a chat, and hedging MUST NOT appear. + +### Before opening the pull request + +- **PRQ-30** Run the repository's checks locally with the commands that CI runs, and report each + result as it was. A skipped or failing check is written as skipped or failing. +- **PRQ-31** When the repository keeps a `CHANGELOG.md`, add the change under `## [Unreleased]` in the + Keep a Changelog section that fits: `Added`, `Changed`, `Fixed`, `Removed`, `Deprecated`, or + `Security`. +- **PRQ-32** When a public function's signature changed, update its help Markdown under `docs/`. +- **PRQ-33** In a repository that consumes these standards, the files that the standards installed + MUST NOT be edited. Change them in the standards repository. +- **PRQ-34** Open the pull request as a draft when a check fails and cannot be fixed, and name the + check in the body. + +### Body + +- **PRQ-40** The body has the sections Summary, Changes, Verification, and Notes, in that order. + Leave out a section only when it would be empty. + +### After opening + +- **PRQ-50** Watch the checks. When one fails, read its log, fix the cause, and push to the same + branch. +- **PRQ-51** Annotate the diff: leave inline review comments on the lines whose reason the code does + not make plain, posted as one review with the `COMMENT` event. +- **PRQ-52** Do not merge your own pull request, force-push a branch that someone has reviewed, or + delete a branch unless asked. + +## Notes and examples + +**PRQ-01.** A local clone can be many merges behind without showing it: `git status` and +`git log` compare with the last fetched state, not with the remote. Work that starts from a stale +branch conflicts with everything merged since, and the conflict appears only when the pull request +is opened. + +```powershell +& git fetch origin +$behind = & git rev-list --count 'HEAD..origin/main' +if ([int]$behind -gt 0) { + throw "The local branch is $behind commit(s) behind origin/main. Update it before starting." +} +``` + +**PRQ-10 to PRQ-12.** The scope is optional and names the area touched, in lower case: +`feat(graph)`, `fix(release)`, `docs(pester)`. The subject says what the change does, not which +files it touched. + +**PRQ-20, PRQ-21.** Commit messages and pull requests are permanent records. They are read months +later by reviewers and maintainers who never saw the conversation that produced the change. + +- Write "Adds", "Fixes", "The gate now fails when". Do not write "as discussed", "you asked", + "I noticed", "let me know", or "we decided". +- Do not write "the earlier issue", "the approach above", or a name coined during the work. Link an + issue, a pull request, a commit, or a file, or describe the thing itself. +- Do not write hedging for the person at the keyboard, such as "should work now". +- Expand an acronym on first use and name the command or setting involved. + +A quick test: if the text would read oddly when pasted into a changelog, rewrite it. + +**PRQ-33.** The files that the standards install either carry a "Generated from" notice or have a +name that starts with `powershell-`. The next update replaces them. + +**PRQ-40.** Use this shape: + +```markdown +## Summary + +What changed and why, in a few sentences. Lead with the problem it solves. + +## Changes + +- One bullet for each change a reviewer should know about. + +## Verification + +- The commands that were run and their results, for example "Pester: 248 passed, 0 failed". +- Anything that could not be verified, stated plainly. + +## Notes + +- Merge order, follow-ups, or decisions left for the reviewer. +``` + +Link the issue that the pull request resolves with `Closes #123` in the Summary. When it depends on +another pull request, say which one merges first. + +**PRQ-51.** Decide first where each explanation belongs. Why the code is the way it is belongs in a +code comment, because it must stay true as long as the code does. Why the code changed belongs in a +review comment, because it describes this change and would go stale in the code: a deleted guard, a +changed default, a test expectation that moved, a workaround for a tool, or a value chosen from +several reasonable ones. Skip lines whose reason is already plain, and do not restate what a line +does. A pull request with nothing to explain needs no annotations. + +`gh pr review` cannot comment on lines, so use the REST API: + +```powershell +$review = @{ + commit_id = (& gh pr view $number --json headRefOid --jq '.headRefOid') + event = 'COMMENT' + body = 'Notes on the lines whose reason the diff does not show.' + comments = @( + @{ path = 'Public/Get-Thing.ps1'; line = 42; side = 'RIGHT'; body = 'Why this line changed.' } + ) +} +# ConvertTo-Json stops at a depth of 2 by default, which would turn each comment into a string. +$json = $review | ConvertTo-Json -Depth 5 +$json | & gh api --method POST "repos/$owner/$repository/pulls/$number/reviews" --input - +``` + +`line` is the line number in the file as the pull request leaves it, with `side = 'RIGHT'`. For a +deleted line, use its number in the old file with `side = 'LEFT'`. A comment must sit on a line that +is inside the diff. diff --git a/.github/instructions/powershell-readme.instructions.md b/.github/instructions/powershell-readme.instructions.md new file mode 100644 index 0000000..ab78b74 --- /dev/null +++ b/.github/instructions/powershell-readme.instructions.md @@ -0,0 +1,72 @@ +--- +applyTo: "**/README.md" +description: "README rules for PowerShell projects." +--- + +# README files for PowerShell projects + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to a project's `README.md`. + +## Rules + +- **RDM-01** A README says what the project does, what it needs, how to install it, how to use it, and + how to run its tests, in that order. +- **RDM-02** State requirements exactly: the PowerShell version and edition, the operating systems, + and each required module with its minimum version. Take them from the manifest and `#requires` + lines, not from memory. +- **RDM-03** Every command in a README MUST run as written against the current code, and MUST be valid + for the project's declared PowerShell version. +- **RDM-04** A README MUST NOT contain invented content: no badges for pipelines that do not exist, no + coverage or performance figures that were not measured, no compliance claims, no testimonials. +- **RDM-05** Write in plain language. Do not add emoji to headings or marketing text. +- **RDM-06** Link to files with relative paths that exist in the repository. Do not describe folders + or documents the repository does not contain. + +## Notes and examples + +A README built from these rules has this shape. Leave out a section that has nothing true to say. + +````markdown +# ModuleName + +One or two sentences that say what the module does and who it is for. + +## Requirements + +- PowerShell 7.6 or later +- Windows, Linux, or macOS +- Microsoft.PowerShell.SecretManagement 1.1.2 or later + +## Installation + +```powershell +Install-PSResource -Name ModuleName +``` + +## Usage + +```powershell +Get-Thing -Name 'alpha' +``` + +Gets the thing named alpha. Run `Get-Help Get-Thing -Full` for every parameter. + +## Tests + +```powershell +Invoke-Pester -Path ./Tests +``` + +## License + +MIT. See [LICENSE](LICENSE). +```` + +**RDM-03.** Before writing a usage example, read the function's parameters. Common mistakes are a +parameter name that does not exist, and a command that the declared version does not have. + +**RDM-04.** Add a status badge only for a workflow file that exists in the repository, using that +workflow's own badge URL. diff --git a/.github/instructions/powershell-security.instructions.md b/.github/instructions/powershell-security.instructions.md new file mode 100644 index 0000000..2541809 --- /dev/null +++ b/.github/instructions/powershell-security.instructions.md @@ -0,0 +1,140 @@ +--- +applyTo: "**/*.ps1,**/*.psm1" +description: "PowerShell rules for secrets, credentials, untrusted input, and command execution." +--- + +# PowerShell security: secrets, credentials, input, execution + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to every `.ps1` and `.psm1` file. + +## Rules + +### Secrets and credentials + +- **SEC-01** Secrets MUST NOT appear in source: no passwords, tokens, keys, or connection strings in + code, parameter defaults, comments, or example values. +- **SEC-02** Get a secret at run time from the caller or from a secret store: a `[PSCredential]` + parameter, `Get-Secret` from Microsoft.PowerShell.SecretManagement, or a secret that the CI system + injects. +- **SEC-03** Accept a credential as a `[PSCredential]` parameter carrying the + `[System.Management.Automation.Credential()]` attribute. A password MUST NOT be accepted as a + `[string]` parameter. +- **SEC-04** `ConvertTo-SecureString -AsPlainText` MUST NOT be applied to a literal or to a value + stored in source. +- **SEC-05** A function or an unattended script MUST NOT fall back to an interactive prompt + (`Get-Credential`, `Read-Host`) when a credential or value is missing. It fails with an error that + names what is missing. +- **SEC-06** Secrets and personal data MUST NOT be written to any stream, log, error message, or + file. This includes dumping `$PSBoundParameters` or a whole input object. + +### Input and execution + +- **SEC-10** Commands MUST NOT be built from strings: no `Invoke-Expression`, and no + `[scriptblock]::Create()` on text that includes input. Pass arguments with splatting, or as an + array for a native executable. +- **SEC-11** Treat input from outside the script as untrusted. Constrain it at the parameter with an + allow-list (`ValidateSet`, or an anchored `ValidatePattern`), not by removing bad characters. +- **SEC-12** Before using a path that comes from input, resolve it to a full path and confirm that it + stays inside the folder it is allowed in. +- **SEC-13** Send values to SQL, LDAP, and similar query languages as parameters. Input MUST NOT be + concatenated or interpolated into query text. +- **SEC-14** TLS certificate validation MUST NOT be disabled, whether with `-SkipCertificateCheck` or + with a validation callback that always succeeds. +- **SEC-15** Code MUST NOT change the execution policy or require elevation that the task does not + need. Declare a real need for elevation with `#requires -RunAsAdministrator`. + +## Notes and examples + +**SEC-03.** The attribute lets a caller pass either a `PSCredential` or a user name, and the default +keeps the parameter optional: + +```powershell +param( + [Parameter()] + [System.Management.Automation.PSCredential] + [System.Management.Automation.Credential()] + $Credential = [System.Management.Automation.PSCredential]::Empty +) +``` + +**SEC-02, SEC-05.** Fail clearly when the secret is not available: + +```powershell +try { + $apiCredential = Get-Secret -Name 'ReportingApi' -ErrorAction Stop +} catch { + $PSCmdlet.ThrowTerminatingError($_) +} +``` + +**SEC-06.** Log that a value is present, not the value: + +```powershell +# Compliant +Write-Verbose "Using API token: $(-not [string]::IsNullOrEmpty($ApiToken))" + +# Non-compliant +Write-Verbose "Using API token $ApiToken" +Write-Debug ($PSBoundParameters | ConvertTo-Json) +``` + +**SEC-10.** Arguments passed as an array reach a native executable as separate arguments, so input +cannot add switches or commands: + +```powershell +# Compliant +$gitArguments = @('clone', '--depth', '1', '--', $RepositoryUrl, $destinationPath) +& git @gitArguments + +# Non-compliant +Invoke-Expression "git clone --depth 1 $RepositoryUrl $destinationPath" +``` + +**SEC-11.** Anchor a pattern at both ends, or a match anywhere in the value passes: + +```powershell +[ValidatePattern('^[A-Za-z0-9][A-Za-z0-9-]{0,62}$')] +[string]$ComputerName +``` + +**SEC-12.** Checking for `..` after a path has been resolved proves nothing, because a resolved path +never contains it. Compare the resolved path with the resolved root instead: + +```powershell +function Test-PathInRoot { + [CmdletBinding()] + [OutputType([bool])] + param( + [Parameter(Mandatory)] + [string]$Root, + + [Parameter(Mandatory)] + [string]$ChildPath + ) + + $separator = [System.IO.Path]::DirectorySeparatorChar + $rootFull = [System.IO.Path]::GetFullPath($Root).TrimEnd($separator) + $separator + $candidate = [System.IO.Path]::GetFullPath([System.IO.Path]::Combine($rootFull, $ChildPath)) + $comparison = if ($separator -eq '\') { + [System.StringComparison]::OrdinalIgnoreCase + } else { + [System.StringComparison]::Ordinal + } + + $candidate.StartsWith($rootFull, $comparison) +} +``` + +`Root` must already be an absolute path. The function returns `$false` for `..\secret.txt`, for an +absolute path outside the root, and for a sibling folder whose name starts with the root's name. + +**SEC-13.** A parameterized query keeps the value out of the query text: + +```powershell +$command = $connection.CreateCommand() +$command.CommandText = 'SELECT Id, Name FROM dbo.Customer WHERE Region = @region' +$null = $command.Parameters.AddWithValue('@region', $Region) +``` diff --git a/.github/instructions/powershell-style.instructions.md b/.github/instructions/powershell-style.instructions.md new file mode 100644 index 0000000..d7947bd --- /dev/null +++ b/.github/instructions/powershell-style.instructions.md @@ -0,0 +1,276 @@ +--- +applyTo: "**/*.ps1,**/*.psm1,**/*.psd1" +description: "PowerShell layout, naming, strings, paths, and collection rules." +--- + +# PowerShell style: layout, naming, strings, paths, collections + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to every `.ps1`, `.psm1`, and `.psd1` file. Apply them to code you write or +change. Do not reformat code that the task does not otherwise touch. + +## Rules + +### Layout + +- **STY-01** Indent with four spaces. Tabs MUST NOT be used. +- **STY-02** Use One True Brace Style: an opening brace ends the line that starts the block, a closing + brace starts its own line, and `else`, `elseif`, `catch`, and `finally` follow that closing brace on + the same line. +- **STY-03** Lines SHOULD NOT exceed 115 characters. Shorten a long command with splatting, or break + the line after a pipe, comma, or operator. Backtick line continuation MUST NOT be used. +- **STY-04** Put one space around binary and assignment operators and after commas. Padding that + aligns `=` or values across lines MUST NOT be added. +- **STY-05** Lines MUST NOT end in whitespace, and a file MUST end with exactly one newline. +- **STY-06** Source MUST be ASCII unless a string literal needs another character: no emoji, + typographic quotes, or en and em dashes in code or comments. +- **STY-07** Put two blank lines between a function definition and the code around it, and at most + one blank line between statements inside a function. + +### Naming + +- **STY-10** Name a function `Verb-Noun`, with a verb that `Get-Verb` lists and a singular PascalCase + noun. +- **STY-11** Name parameters in PascalCase and reuse the standard names where they fit: `Path`, + `LiteralPath`, `Name`, `Id`, `ComputerName`, `Credential`, `Force`, `PassThru`. +- **STY-12** Name local variables in descriptive camelCase without a type prefix: `$retryCount`, not + `$RetryCount` or `$intRetryCount`. +- **STY-13** Automatic variables MUST NOT be assigned or reused as parameter, loop, or test-data + names. The ones most often hit are `$args`, `$input`, `$matches`, `$error`, `$event`, `$host`, + `$home`, `$pid`, `$profile`, `$sender`, `$this`, `$_`, and `$PSItem`. +- **STY-14** Call commands by their full name with named parameters. Aliases such as `gci`, `ls`, + `%`, `?`, and `where` MUST NOT be used. One leading positional argument is acceptable where it is + unambiguous, as in `Write-Verbose 'text'`. +- **STY-15** Write keywords and operators in lowercase (`foreach`, `-eq`), and write command, + parameter, and type names with their defined casing (`Get-ChildItem`, `-LiteralPath`). +- **STY-16** A local variable MUST NOT have the name of a parameter in any letter case. Variable names + are case-insensitive, so `$settings = @{}` replaces the value that was passed as `-Settings`. + +### Comparisons and strings + +- **STY-20** Put `$null` on the left of a comparison: `$null -eq $value`. +- **STY-21** Use single quotes for a string that needs no expansion and contains no single quote. In + an expandable string write `$($object.Property)` for member access, and `${name}` when a colon or + a name character follows the variable. +- **STY-22** Build a long or looped string with `-join`, the `-f` operator, or + `[System.Text.StringBuilder]`. A string MUST NOT be extended with `+=` inside a loop. +- **STY-23** Apply the `-f` operator inside the parentheses of a command argument: + `Write-Verbose ('{0} items' -f $count)`. Written after the closing parenthesis, `-f` is passed to + the command as an argument. + +### Paths and files + +- **STY-30** Build paths with `Join-Path` or `[System.IO.Path]::Combine()`. Path separators MUST NOT be + concatenated by hand. +- **STY-31** Locate files relative to `$PSScriptRoot`, never relative to the current location, and + pass only absolute paths to .NET methods. +- **STY-32** Use `-LiteralPath` whenever the path names one specific item, and always for a path held + in a variable. `-Path` is for wildcard patterns. +- **STY-33** State the encoding whenever code writes text to a file. +- **STY-34** Normalize line endings before comparing text that came from a file, a here-string, or a + serializer, and before writing a file that is compared exactly. Read the whole file with + `Get-Content -Raw` or `[System.IO.File]::ReadAllText()`, and compare bytes with + `[System.IO.File]::ReadAllBytes()`. +- **STY-35** Code that does long work and then writes a file SHOULD confirm, before the work starts, + that the file can be written, without truncating a file that is already there. + +### Collections + +- **STY-40** Build a collection by assigning the output of a loop or pipeline to a variable. An array + MUST NOT be grown with `+=` inside a loop. +- **STY-41** When items are added conditionally or from several places, use + `[System.Collections.Generic.List[T]]` with the most specific `T` that fits. + `[System.Collections.ArrayList]` MUST NOT be used. +- **STY-42** Wrap a command call in `@()` before the code reads `.Count` or an index from its result, + or passes the result to a parameter that needs a collection. +- **STY-43** Filter at the source: prefer a command's own filtering parameters (`-Filter`, `-Include`, + a query) to piping everything into `Where-Object`. +- **STY-44** Prefer the `foreach` statement for a collection that is already in memory. Use the + pipeline to stream input whose size is unknown. + +## Notes and examples + +Compliant layout (STY-02, STY-03, STY-04). Splatting replaces a long line and needs no backticks: + +```powershell +$copyParameters = @{ + LiteralPath = $sourcePath + Destination = $destinationPath + Force = $true + ErrorAction = 'Stop' +} + +if (Test-Path -LiteralPath $sourcePath) { + Copy-Item @copyParameters +} else { + Write-Warning "Nothing to copy: '$sourcePath' does not exist." +} +``` + +**STY-06.** Windows PowerShell 5.1 reads a UTF-8 file that has no byte order mark in the system ANSI +code page, so a typographic quote or dash can change how the file parses. If a file must contain +non-ASCII characters and must also run on 5.1, save it as UTF-8 with a byte order mark. + +**STY-07.** A file that holds a single function needs no blank lines around it. A comment that +describes a function sits directly above it, after the two blank lines. + +**STY-13.** A parameter named `$Input`, or a loop written as `foreach ($event in $events)`, silently +reads or replaces the automatic variable. PSScriptAnalyzer reports assignments under +`PSAvoidAssignmentToAutomaticVariable`. + +**STY-16.** STY-12 writes local variables in camelCase and STY-11 writes parameters in PascalCase, but +the two spellings name the same variable. In a function that has a `-Settings` parameter, call the +local `$mergedSettings`, not `$settings`. + +**STY-20.** When the left operand is a collection, `-eq` returns the matching elements instead of a +Boolean, so `$values -eq $null` does not test whether `$values` is null. + +**STY-21.** `"$computer: failed"` does not parse, because PowerShell reads `$computer:` as a drive +reference. `"$state.Attempt"` parses but expands only `$state`, followed by the literal text +`.Attempt`. + +```powershell +Write-Verbose "${computer}: retry $($state.Attempt) of $maximumAttempts" +``` + +**STY-23.** Measured on PowerShell 7.6 and Windows PowerShell 5.1: +`Write-Output ('{0} items' + ' found') -f 5` emits three objects, the unformatted text, `-f`, and +`5`, and raises no error. `Write-Warning` rejects the same call, because it has no parameter that +`-f` could mean. + +```powershell +# Compliant +Write-Warning ('{0} of {1} items failed.' -f $failedCount, $totalCount) + +# Non-compliant: -f and the values are arguments of Write-Warning +Write-Warning ('{0} of {1} items failed.') -f $failedCount, $totalCount +``` + +**STY-30.** On Windows PowerShell 5.1 `Join-Path` accepts one child path. Nest the calls in code that +must run there; `Join-Path -Path $root -ChildPath 'a' -AdditionalChildPath 'b'` needs PowerShell 6 or +later. + +**STY-31.** .NET resolves a relative path against the process working directory, which `Set-Location` +does not change. Convert the path first: + +```powershell +# The item may not exist yet +$fullPath = $PSCmdlet.GetUnresolvedProviderPathFromPSPath($Path) + +# The item must exist +$fullPath = Convert-Path -LiteralPath $Path -ErrorAction Stop +``` + +**STY-32.** `-Path` treats `[`, `]`, `*`, and `?` as wildcard characters, so +`Get-Content -Path 'report[1].txt'` finds nothing. `New-Item` and `Join-Path` have no `-LiteralPath` +parameter; their `-Path` is correct. + +**STY-33.** `-Encoding utf8` writes a byte order mark on Windows PowerShell 5.1 and none on +PowerShell 7. To write UTF-8 without a byte order mark on both: + +```powershell +[System.IO.File]::WriteAllText($fullPath, $text, [System.Text.UTF8Encoding]::new($false)) +``` + +In code that targets PowerShell 7 only, `-Encoding utf8NoBOM` and `-Encoding utf8BOM` state the choice +directly. + +**STY-34.** The same text has different line endings depending on where it comes from. Measured on +PowerShell 7.6 and Windows PowerShell 5.1: + +- A here-string takes the line endings of the script file that holds it, so it has CRLF or LF + according to how git checked the file out. +- `ConvertTo-Json` and `Out-String` use the line ending of the platform, which is CRLF on Windows. +- `Get-Content` without `-Raw` returns the lines without their endings, which hides the difference. + +A comparison that passes on a developer's computer therefore fails on a CI runner, or the reverse. +Normalize both sides, and normalize what is written when the file itself is compared: + +```powershell +$expected = $expectedText.Replace("`r`n", "`n") +$actual = [System.IO.File]::ReadAllText($fullPath).Replace("`r`n", "`n") +$isSame = $actual -ceq $expected + +$json = ($settings | ConvertTo-Json -Depth 5).Replace("`r`n", "`n") + "`n" +[System.IO.File]::WriteAllText($fullPath, $json, [System.Text.UTF8Encoding]::new($false)) +``` + +A `.gitattributes` file removes the difference between checkouts; see CIC-11 in +`.github/instructions/powershell-cicd.instructions.md`. + +**STY-35.** A report that takes an hour to build and then cannot be saved has wasted the hour. Check +the destination first: + +```powershell +$fullPath = $PSCmdlet.GetUnresolvedProviderPathFromPSPath($OutputPath) +$existed = [System.IO.File]::Exists($fullPath) +try { + # OpenOrCreate does not truncate, so a file that is already there keeps its content. + $stream = [System.IO.File]::Open( + $fullPath, + [System.IO.FileMode]::OpenOrCreate, + [System.IO.FileAccess]::Write, + [System.IO.FileShare]::None) + $stream.Dispose() + if (-not $existed) { + [System.IO.File]::Delete($fullPath) + } +} catch { + $PSCmdlet.ThrowTerminatingError($_) +} +``` + +The code belongs in an advanced function or script that has an `-OutputPath` parameter. Tested on +both versions: the check leaves no file behind when the file did not exist, leaves the +content of an existing file unchanged, and fails for a missing folder, a read-only file, and a file +that another process holds open. + +**STY-40, STY-41.** Direct assignment is the fastest form on every version: + +```powershell +# Compliant: the loop's output becomes the array +$reports = foreach ($server in $servers) { + Get-ServerReport -ComputerName $server +} + +# Compliant: items come from more than one place +$missingPaths = [System.Collections.Generic.List[string]]::new() +foreach ($requiredPath in $requiredPaths) { + if (-not (Test-Path -LiteralPath $requiredPath)) { + $missingPaths.Add($requiredPath) + } +} + +# Non-compliant: copies the whole array on every iteration +$reports = @() +foreach ($server in $servers) { + $reports += Get-ServerReport -ComputerName $server +} +``` + +Each `+=` allocates a new array and copies the old one. Measured on PowerShell 7.6, `+=` keeps pace +with `List.Add()` up to about 10,000 elements and is more than ten times slower by 40,000. On Windows +PowerShell 5.1 it is slower at every size. When reviewing existing code that targets PowerShell 7.5 or +later only, `+=` on a collection that is known to stay small is not a defect; do not write it in new +code. + +`$list.Add((Get-Thing))` adds one element even when the command returns several objects. Use +`foreach` with `Add()`, or `AddRange()`, when each object should be an element. + +**STY-42.** A command can emit nothing, one object, or many. Under strict mode, `.Count` on a single +object and an index past the end are errors. Apply `@()` to the call, not to a variable that may hold +`$null`: `@($null).Count` is 1. + +```powershell +$logFiles = @(Get-ChildItem -LiteralPath $logDirectory -Filter '*.log' -File) +if ($logFiles.Count -eq 0) { + Write-Warning "No log files were found in '$logDirectory'." +} +``` + +A function that writes an empty array gives its caller nothing, which is `$null` once it is assigned, +because PowerShell unrolls the array on the way out. `@()` around the call restores the empty array. +A mandatory collection parameter rejects both `$null` and an empty array unless it carries +`[AllowEmptyCollection()]`. diff --git a/.github/instructions/powershell-version.instructions.md b/.github/instructions/powershell-version.instructions.md index 94d0d22..959d3da 100644 --- a/.github/instructions/powershell-version.instructions.md +++ b/.github/instructions/powershell-version.instructions.md @@ -1,326 +1,299 @@ --- applyTo: "**/*.ps1,**/*.psm1,**/*.psd1" -description: 'PowerShell version baseline, support lifecycle, and version-dependent language/cmdlet features' +description: "PowerShell target version, support lifecycle, and version-dependent features." --- -# PowerShell Version Baseline - -Which PowerShell version to target, and which features are safe to emit at that target. -Verified against the Microsoft support lifecycle as of **2026-08-01**. +# PowerShell versions: target, lifecycle, and version-dependent features + +> Generated from ai-powershell-standards 2.0.0. Do not edit this file. +> Its source is the `standards` folder of that repository; `Tools/Build-AgentInstructions.ps1` rebuilds it. + +These rules apply to every `.ps1`, `.psm1`, and `.psd1` file. They say which PowerShell version to +write for and which features that version has. + +The dates and version numbers on this page were checked against Microsoft's documentation on +2026-11-15. A version is supported until its end-of-support date; compare that date with today's +date instead of relying on the wording here. + +## Rules + +- **VER-01** Write for PowerShell 7.6 (LTS) unless the project declares another target. The + declaration is the project's `#requires -Version` lines and the `PowerShellVersion` and + `CompatiblePSEditions` keys of its module manifest. +- **VER-02** Write code that also runs on Windows PowerShell 5.1 only when the project declares it: + `PowerShellVersion = '5.1'`, `CompatiblePSEditions` containing `Desktop`, or + `#requires -Version 5.1`. +- **VER-03** Declare the target. A script that is run directly starts with + `#requires -Version <target>`, and a module manifest sets `PowerShellVersion` and + `CompatiblePSEditions`. A file that only defines functions for a module or script to load needs no + `#requires` line. +- **VER-04** Code MUST NOT use a command, parameter, operator, or type that the declared target does + not have. The feature tables in the PowerShell version rules list the ones that differ. +- **VER-05** Code, `#requires` lines, and CI matrices MUST NOT target a PowerShell version that is + past its end-of-support date. +- **VER-06** Commands that exist only in Windows PowerShell MUST NOT be used in code that targets + PowerShell 7: use `Get-CimInstance` in place of `Get-WmiObject`, and `Get-WinEvent` in place of + `Get-EventLog`. +- **VER-07** Compare versions as `[version]` values, never by `Major` alone, and detect the operating + system in a way that also works where `$IsWindows` does not exist. +- **VER-08** Install and publish modules with Microsoft.PowerShell.PSResourceGet (`Install-PSResource`, + `Find-PSResource`, `Publish-PSResource`). Use `Install-Module` only on Windows PowerShell 5.1 where + PSResourceGet is not installed. +- **VER-09** Detect a parameter that only some versions have on the command itself, with + `(Get-Command -Name <Command>).Parameters.ContainsKey('<Parameter>')`, not from the version number. +- **VER-10** Code that works on some operating systems only MUST test for them before its first + platform-specific operation, and fail with an error that names the systems it supports. ## Support lifecycle | Version | Type | Released | End of support | Runtime | | --- | --- | --- | --- | --- | -| **7.6** | **LTS - current target** | 18-Mar-2026 | 14-Nov-2028 | .NET 10 | -| 7.5 | Stable | 23-Jan-2025 | **10-Nov-2026** | .NET 9 | -| 7.4 | LTS (previous) | 16-Nov-2023 | **10-Nov-2026** | .NET 8 | -| 5.1 | Windows component | Aug-2016 | Windows lifecycle | .NET Framework 4.x | - -Everything below 7.4 is retired and receives no security updates. Never generate code or CI -matrices targeting PowerShell 6.x, 7.0-7.3. - -> **Act on this:** PowerShell 7.4 and 7.5 both go out of support on **10-Nov-2026**. Any project -> pinned to 7.4 or 7.5 needs a 7.6 upgrade planned now. Recommend 7.6 for all new work. +| 7.6 | LTS | 18-Mar-2026 | 14-Nov-2028 | .NET 10 | +| 7.5 | Stable | 23-Jan-2025 | 10-Nov-2026 | .NET 9 | +| 7.4 | LTS | 16-Nov-2023 | 10-Nov-2026 | .NET 8 | +| 5.1 | Windows component | Aug-2016 | Follows the Windows lifecycle | .NET Framework 4.x | -Windows PowerShell 5.1 is not deprecated - it ships with Windows and is supported under the -Windows lifecycle - but it receives no new features. Treat it as a compatibility target, never -as the target you optimize for. +Versions 6.x and 7.0 to 7.3 ended support earlier. Windows PowerShell 5.1 ships with Windows and is +still supported, but it receives no new features: treat it as a compatibility target, never as the +version to design for. -## Choosing a target +When a project is pinned to a version whose end-of-support date has passed, say so and recommend +moving to the current LTS. Do not silently change the project's declared target. -Ask which applies before generating code: +## Choosing and declaring a target -- **Cross-version modules** (shipping to unknown estates) - target `5.1` with - `CompatiblePSEditions = @('Desktop', 'Core')`. Gate 7.x-only features behind version checks. -- **Modern-only automation** (containers, CI, greenfield) - target **7.6** with - `CompatiblePSEditions = @('Core')`. Do not carry 5.1 compatibility cost for no reason. -- **Windows-estate tooling** that must run in-box on servers without pwsh installed - target `5.1`. - -Declare the target explicitly, at the top of scripts and in the module manifest: +| Situation | Target | Manifest keys | +| --- | --- | --- | +| New automation, CI, containers | 7.6 | `PowerShellVersion = '7.6'`, `CompatiblePSEditions = @('Core')` | +| Module for machines that may not have PowerShell 7 | 5.1 | `PowerShellVersion = '5.1'`, `CompatiblePSEditions = @('Desktop', 'Core')` | ```powershell #requires -Version 7.6 ``` -```powershell -@{ - PowerShellVersion = '7.6' - CompatiblePSEditions = @('Core') -} -``` +## Features by version -Use `#requires -Version 7.4` only when you have verified the code avoids every 7.5/7.6 feature -listed below. `#requires -Version 7.0` is obsolete - that version is retired; if you mean "any -PowerShell 7", the lowest supported floor is `7.4`, and after 10-Nov-2026 it is `7.6`. +### Not available in Windows PowerShell 5.1 -## Version-dependent features +Code that must run on 5.1 MUST NOT use these: -Do not emit these unless the declared target supports them. - -### PowerShell 7.5+ +| Feature | Use on 5.1 | +| --- | --- | +| Ternary `a ? b : c`, `??`, `??=`, `?.`, `?[]` | `if` / `else` | +| Pipeline chain operators `&&` and `\|\|` | Separate statements that test `$?` or `$LASTEXITCODE` | +| `ForEach-Object -Parallel` | `Start-Job`, or the ThreadJob module installed separately | +| `$IsWindows`, `$IsLinux`, `$IsMacOS` | See operating system detection below | +| `Join-Path` with more than one child path | Nested `Join-Path` calls | +| `-Encoding utf8NoBOM` | `[System.IO.File]::WriteAllText()` with `[System.Text.UTF8Encoding]::new($false)` | +| `ConvertFrom-Json -AsHashtable` | Read properties from the object that `ConvertFrom-Json` returns | +| `Test-Json` | `ConvertFrom-Json` inside `try` / `catch` | +| `Get-Content -AsByteStream` | `Get-Content -Encoding Byte` | +| `[ValidateNotNullOrWhiteSpace()]` | `[ValidateScript({ -not [string]::IsNullOrWhiteSpace($_) })]` | +| `clean { }` block, `Get-Error`, `$PSStyle` | No equivalent; use `try` / `finally` in place of `clean` | +| `Invoke-WebRequest` without `-UseBasicParsing` | Pass `-UseBasicParsing` in unattended code | +| `-SkipHttpErrorCheck`, and other parameters added in PowerShell 7 | Test for the parameter on the command (VER-09) | + +One use of 7-only syntax in any file that a root module dot-sources fails the whole import on 5.1, +so one helper can take every command of the module with it. + +### Added in PowerShell 7.5 | Feature | Notes | | --- | --- | -| `ConvertTo-CliXml` / `ConvertFrom-CliXml` | Serialize to CliXml without a temp file. Replaces `Export-Clixml` to a scratch path. | -| `ConvertFrom-Json -DateKind` | Controls how date strings deserialize (`Local`, `Utc`, `Offset`, `String`). Use `Utc` or `Offset` for audit data. | -| `Test-Json -IgnoreComments` / `-AllowTrailingCommas` | Validate JSONC-style config without pre-stripping. | -| `Resolve-Path -Force` / `Convert-Path -Force` | Wildcard resolution that includes hidden files. | -| `New-Guid -Empty` / `-InputObject` | Empty GUID and string-to-GUID conversion without a cast. | -| `Get-Process -IncludeUserName` | No longer requires admin. | -| Error `ConciseView` `RecommendedAction` | Surfaced in error output. | +| `ConvertTo-CliXml`, `ConvertFrom-CliXml` | Serialize to CLIXML text without a temporary file | +| `ConvertFrom-Json -DateKind` | Controls how date strings are converted (`Local`, `Utc`, `Offset`, `String`) | +| `Test-Json -Options IgnoreComments, AllowTrailingCommas` | Validates JSON that has comments or trailing commas | +| `Resolve-Path -Force`, `Convert-Path -Force` | Wildcard resolution that includes hidden items | +| `New-Guid -Empty`, `New-Guid -InputObject` | An empty GUID, and conversion of a string to a GUID | +| `Get-Process -IncludeUserName` | No longer needs elevation on Windows | -### PowerShell 7.6+ +### Added in PowerShell 7.6 | Feature | Notes | | --- | --- | -| `Get-Command -ExcludeModule` | Filter discovery without post-filtering the pipeline. | -| `Register-ArgumentCompleter -NativeFallback` | Register one cover-all completer for native commands. | -| `Get-Clipboard -Delimiter` | Split clipboard content on read. | -| `PSForEach()` / `PSWhere()` | Aliases for the `.Foreach()` / `.Where()` intrinsic methods. Prefer these when `.Where()` collides with a LINQ-style method on the piped type. | -| `PipelineStopToken` on `Cmdlet` | For binary cmdlets - signaled when the pipeline stops. | - -### Promoted from experimental (now always on) - -Do not tell users to enable these with `Enable-ExperimentalFeature`; they are mainstream. - -- **7.5**: `PSCommandNotFoundSuggestion`, `PSCommandWithArgs`, `PSModuleAutoLoadSkipOfflineFiles` -- **7.6**: `PSFeedbackProvider`, `PSNativeWindowsTildeExpansion`, `PSRedirectToVariable`, - `PSSubsystemPluginModel` - -`PSRedirectToVariable` means redirection to a variable is now valid syntax in 7.6: - -```powershell -# 7.6+ - capture a stream without a temp file or subexpression -Get-Item .\missing 2>&1 > variable:capturedErrors -``` - -## Breaking changes to code around - -These changed behavior in supported versions. Generated code must not depend on the old behavior. +| `Get-Command -ExcludeModule` | Leaves out commands from the named modules | +| `Get-Clipboard -Delimiter` | Splits clipboard text while reading it | +| `Register-ArgumentCompleter -NativeFallback` | One completer for native commands that have none | +| `.PSForEach()`, `.PSWhere()` | Aliases for the `.ForEach()` and `.Where()` intrinsic methods | +| Redirection to a variable | `Get-Item -LiteralPath $path 2>&1 > variable:itemResult` | -### PowerShell 7.6 +### Behaviour that changed -- **`ThreadJob` module renamed to `Microsoft.PowerShell.ThreadJob`.** `Start-ThreadJob` itself is - unchanged, so only module-qualified calls and manifest dependencies break. +Code MUST NOT depend on the older behaviour. - ```powershell - # ❌ Breaks on 7.6 - ThreadJob\Start-ThreadJob -ScriptBlock { ... } - RequiredModules = @(@{ ModuleName = 'ThreadJob'; ModuleVersion = '2.0.3' }) - - # ✅ - Microsoft.PowerShell.ThreadJob\Start-ThreadJob -ScriptBlock { ... } - RequiredModules = @(@{ ModuleName = 'Microsoft.PowerShell.ThreadJob'; ModuleVersion = '2.2.0' }) - ``` - - Simplest fix: call `Start-ThreadJob` unqualified and let module autoloading resolve it. - -- **`Join-Path -ChildPath` accepts `string[]`.** Multi-segment joins now work in one call, but - code that relied on an array argument stringifying into a single segment breaks. - - ```powershell - # 7.6+ - one call instead of nesting - Join-Path $PSScriptRoot 'Private' 'Helpers' 'Write-Log.ps1' - ``` - -- **`WildcardPattern.Escape` escapes lone backticks correctly.** Code that double-escaped to work - around the old bug now over-escapes. - -### PowerShell 7.5 - -- **`ConvertTo-Json` serializes `BigInteger` as a number**, not an object. Consumers expecting the - old object shape break. -- **`Test-Path -OlderThan` and `-NewerThan` both apply** when specified together. Previously - `-OlderThan` was silently ignored - a date-range check that appeared to work was not filtering. -- **`New-FileCatalog -CatalogVersion` defaults to 2.** Pass `-CatalogVersion 1` explicitly if a - downstream validator still requires v1. -- **`Select-String` `LineNumber` is now `ulong`.** Strict-typed downstream assignments to `int` - break. - -## Array accumulation - version-dependent guidance - -This is the most commonly miscited PowerShell performance rule, and it changed in 7.5. - -PowerShell 7.5 optimized `+=` on object arrays. It is no longer the pathological case it is in -5.1 and 7.4 - it is now **faster than `List<T>.Add()`** for that scenario. The blanket advice -"never use `+=`" is stale for 7.5+. - -What did not change: **assigning the loop output directly is still fastest in every version**, by -a wide margin. Prefer it regardless of target. - -```powershell -# ✅ Best on every version - no per-iteration allocation at all -$results = foreach ($item in $collection) { - Get-ProcessedItem -Item $item -} +| Version | Change | +| --- | --- | +| 7.6 | The `ThreadJob` module is now `Microsoft.PowerShell.ThreadJob`. Call `Start-ThreadJob` without a module prefix; `ThreadJob\Start-ThreadJob` and a `RequiredModules` entry for `ThreadJob` no longer resolve. | +| 7.6 | `Join-Path -ChildPath` accepts an array. An array that used to be joined into one segment is now treated as several segments. | +| 7.6 | `[WildcardPattern]::Escape()` escapes a lone backtick correctly. Code that escaped twice to work around the old result now escapes too much. | +| 7.5 | `ConvertTo-Json` writes a `BigInteger` as a number, not as an object. | +| 7.5 | `Test-Path -OlderThan` and `-NewerThan` both apply when used together. | +| 7.5 | `New-FileCatalog -CatalogVersion` defaults to 2. | +| 7.5 | `Select-String` returns `LineNumber` as `[ulong]`. | +| 7.4 | `Test-Json` accepts only strictly valid JSON and no longer supports Draft 4 schemas. | + +### Windows PowerShell commands that are not part of PowerShell 7 (VER-06) + +| Do not use | Use instead | +| --- | --- | +| `Get-WmiObject`, `Invoke-WmiMethod`, `Set-WmiInstance`, `Remove-WmiObject`, `Register-WmiEvent` | `Get-CimInstance`, `Invoke-CimMethod`, `Set-CimInstance`, `Remove-CimInstance`, `Register-CimIndicationEvent` | +| `Get-EventLog`, `Write-EventLog`, `New-EventLog`, `Clear-EventLog` | `Get-WinEvent`; `New-WinEvent` to write an event for a registered provider | +| `New-WebServiceProxy` | `Invoke-RestMethod`, or a generated client | +| `Add-PSSnapin`, workflows, `*-Transaction` | Modules; no equivalent for workflows and transactions | -# ✅ Also fine - pipeline output -$results = $collection | ForEach-Object { Get-ProcessedItem -Item $_ } -``` +On Windows, some of these still resolve in PowerShell 7 through the Windows PowerShell compatibility +session. That path is slow, exists only on Windows, and returns deserialized objects without methods, +so do not rely on it. `Send-MailMessage` exists in PowerShell 7 but is obsolete; do not use it in new +code. -When you must accumulate conditionally and cannot assign loop output directly: +### Behaviour that differs on Windows PowerShell 5.1 -```powershell -# ✅ Portable across 5.1 and 7.x - use the generic List, not ArrayList -$results = [System.Collections.Generic.List[object]]::new() -foreach ($item in $collection) { - if (Test-ItemRelevant -Item $item) { - $results.Add((Get-ProcessedItem -Item $item)) - } -} -``` +None of these raises a parse error. Each was measured on PowerShell 7.6 and Windows PowerShell 5.1. -Rules for generated code: +| Area | PowerShell 7.6 | Windows PowerShell 5.1 | +| --- | --- | --- | +| `Group-Object` | Groups are sorted by name | Groups keep the order in which they first appear | +| `.Count` on a `[PSCustomObject]` | `1` | `$null`, or an error under strict mode | +| `[System.IO.Compression.ZipFile]::CreateFromDirectory()` | Entry names use `/` | Entry names use `\` | +| `[System.Net.HttpStatusCode]` | Defines 429 | Does not define 429 | +| A 4xx or 5xx reply to `Invoke-WebRequest` | Returned when `-SkipHttpErrorCheck` is passed | Thrown as a `WebException` | -- Never generate `[System.Collections.ArrayList]`. It is a non-generic .NET 1.1 type kept only for - back-compat, it boxes values, and it forces `[void]` noise on every `.Add()`. Use - `[System.Collections.Generic.List[object]]` or a typed `List[T]`. -- Do not flag `+=` as a defect when the declared target is 7.5+ and the collection is small or the - loop is not hot. Flag it when the target includes **5.1 or 7.4**, where it remains O(n²). -- Do flag `+=` in any loop over an unbounded collection, on any version - direct assignment is - still the correct pattern. +Sort explicitly before relying on the order of groups. Build an archive entry by entry, with `/` in +the names, when it must open on another platform. Read an HTTP status as an integer, not by name. -## Module installation - use PSResourceGet +A statement used as an expression enumerates its output on both versions. A `WebHeaderCollection` +assigned from an `if` expression therefore arrives as an array of its key names; assign it inside +the branch instead. -`Microsoft.PowerShell.PSResourceGet` (v1.2.0 ships in 7.6) is the supported package client. -PowerShellGet v2 `Install-Module` / `Find-Module` still work via the compatibility layer, but new -instructions should use the PSResourceGet verbs. +Windows PowerShell 5.1 uses `[System.Net.ServicePointManager]::SecurityProtocol`. Where that is +`SystemDefault`, the operating system chooses the protocols and the code should leave it alone: +adding `Tls12` with `-bor` to `SystemDefault` restricts the session to TLS 1.2. Add `Tls12` only when +the value names specific protocols and TLS 1.2 is not one of them. -```powershell -# ✅ Preferred -Install-PSResource -Name Pester -Scope CurrentUser -TrustRepository -Find-PSResource -Name PSScriptAnalyzer -# Publish a staged allowlist, never the repository root - see module.instructions.md -Publish-PSResource -Path ./out/MyModule -ApiKey $env:NUGET_KEY - -# ⚠️ PowerShellGet v2 - still functional, use only when targeting 5.1 without PSResourceGet installed -Install-Module -Name Pester -Scope CurrentUser -Force -SkipPublisherCheck -``` +### Reading a failed HTTP reply on both versions (VER-09) -On Windows PowerShell 5.1, `Microsoft.PowerShell.PSResourceGet` is not in-box and must be -installed first with `Install-Module`. Scripts that must bootstrap on both should detect: +On PowerShell 7, `-SkipHttpErrorCheck` returns a 4xx or 5xx reply like any other. Windows PowerShell +5.1 has no such parameter: the cmdlet throws a `WebException`, and the reply is on the exception. +The function below gives callers one error on both versions and was run against a local server on +each. On 5.1 the body came back empty until the stream was moved back to its start. ```powershell -if (Get-Command Install-PSResource -ErrorAction SilentlyContinue) { - Install-PSResource -Name $Module -Scope CurrentUser -TrustRepository -} -else { - Install-Module -Name $Module -Scope CurrentUser -Force -SkipPublisherCheck -} -``` - -## Windows PowerShell 5.1 differences to code around +# Detected once, when the module is imported +$script:canSkipHttpErrorCheck = (Get-Command -Name Invoke-WebRequest).Parameters.ContainsKey('SkipHttpErrorCheck') -Everything here was found by running a module that declares `CompatiblePSEditions = @('Desktop', 'Core')` -on 5.1 after its suite had passed on 7. When a module declares the Desktop edition, run the suite under -5.1 in CI; a 5.1 trap otherwise shows on a device before it shows in a pull request. - -### Syntax that parses on 7 and breaks every command on 5.1 - -A single use of any of these in any file the root module dot-sources fails the whole import, so one -convenience in one helper takes every command with it: - -| Construct | 5.1 replacement | -| --- | --- | -| Ternary `$a ? $b : $c` | `if ($a) { $b } else { $c }` | -| Null-coalescing `??` and `??=`, null-conditional `?.` and `?[]` | explicit `if ($null -eq ...)` | -| `ForEach-Object -Parallel` | `Start-Job`, a runspace pool, or sequential | -| `Join-Path a b c` (several child paths) | nested `Join-Path` | -| A 7-only parameter such as `-SkipHttpErrorCheck` | detect it on the cmdlet and branch; see below | - -Two run-time differences the same suites hit: `Group-Object` orders its groups differently, so sort -explicitly before relying on order; and .NET Framework's `ZipFile::CreateFromDirectory` writes -backslash entry names, so build an archive entry by entry with forward slashes when it must open -elsewhere. - -### Reading a failed HTTP response - -`Invoke-WebRequest` and `Invoke-RestMethod` return a 4xx or 5xx response on PowerShell 7 when asked to -with `-SkipHttpErrorCheck`; the body is decoded like any other. On 5.1 the cmdlet throws, the body is -readable once from the exception's response stream, and TLS 1.2 is not negotiated by default. Detect -the capability on the cmdlet, never from a version number, and give callers one error shape: - -```powershell -# Detected once at import and cached in module scope -$script:CanSkipHttpErrorCheck = (Get-Command Invoke-WebRequest).Parameters.ContainsKey('SkipHttpErrorCheck') -if (-not $script:CanSkipHttpErrorCheck) { - [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor - [Net.SecurityProtocolType]::Tls12 -} function Invoke-ModuleWebRequest { [CmdletBinding()] + [OutputType([string])] param( [Parameter(Mandatory)] - [hashtable]$Request # splatted into Invoke-WebRequest + [hashtable]$Request ) - if ($script:CanSkipHttpErrorCheck) { - $response = Invoke-WebRequest @Request -SkipHttpErrorCheck + try { + if ($script:canSkipHttpErrorCheck) { + $response = Invoke-WebRequest @Request -SkipHttpErrorCheck -ErrorAction Stop + } else { + $response = Invoke-WebRequest @Request -UseBasicParsing -ErrorAction Stop + } $status = [int]$response.StatusCode $body = $response.Content - } else { + } catch [System.Net.WebException] { + $failedResponse = $_.Exception.Response + if ($null -eq $failedResponse) { + # No reply arrived, so there is no status or body to read. + $PSCmdlet.ThrowTerminatingError($_) + } + + $status = [int]$failedResponse.StatusCode + # The cmdlet may already have read the reply, so start again from the beginning. + $stream = $failedResponse.GetResponseStream() + if ($stream.CanSeek) { + $stream.Position = 0 + } + $reader = [System.IO.StreamReader]::new($stream) try { - $response = Invoke-WebRequest @Request - $status = [int]$response.StatusCode - $body = $response.Content - } catch [System.Net.WebException] { - if ($null -eq $_.Exception.Response) { - throw # a transport failure with no response propagates untouched - } - # .NET Framework's HttpStatusCode has no 429 member; read the integer, not the name - $status = [int]$_.Exception.Response.StatusCode - $reader = [System.IO.StreamReader]::new($_.Exception.Response.GetResponseStream()) - try { - $body = $reader.ReadToEnd() # readable once; keep it - } finally { - $reader.Dispose() - } + $body = $reader.ReadToEnd() + } finally { + $reader.Dispose() } + } catch { + $PSCmdlet.ThrowTerminatingError($_) } if ($status -ge 400) { - $message = "HTTP $status from $($Request.Uri): $body" - Write-Error -Message $message -ErrorAction Stop + $exception = [System.InvalidOperationException]::new("The request failed with HTTP status $status.") + $exception.Data['Body'] = $body + $category = [System.Management.Automation.ErrorCategory]::InvalidResult + $errorRecord = [System.Management.Automation.ErrorRecord]::new( + $exception, 'HttpRequestFailed', $category, $status) + $PSCmdlet.ThrowTerminatingError($errorRecord) } + $body } ``` -Two more things the suite for that function has to know. A `WebHeaderCollection` assigned from an -`if` expression arrives as an array of its key names, because a statement's output is enumerated on -the way out, so assign it inside the branch. Windows PowerShell rewraps a bare thrown exception and -drops any member added to it, so a test fake that needs `Response` on its exception throws an -`ErrorRecord`. +The body goes into the exception's `Data`, not into the message, because a reply can carry personal +data (SEC-06). -## Detecting version at runtime +## Detecting the version and operating system (VER-07, VER-10) ```powershell -# ✅ Compare the whole version, not just Major - 7.4 and 7.6 both have Major 7 +# Compliant: compares the whole version if ($PSVersionTable.PSVersion -ge [version]'7.6') { - # 7.6+ path + $delimitedText = Get-Clipboard -Delimiter ',' +} + +# Compliant: $IsWindows does not exist on Windows PowerShell 5.1, which runs only on Windows +$onWindows = $PSVersionTable.PSVersion.Major -lt 6 -or $IsWindows + +# Non-compliant: true for every 7.x release, supported or not +if ($PSVersionTable.PSVersion.Major -ge 7) { + $delimitedText = Get-Clipboard -Delimiter ',' } +``` -# ✅ $IsWindows is undefined on 5.1, which is always Windows -$onWindows = $PSVersionTable.PSVersion.Major -eq 5 -or $IsWindows +**VER-10.** Test at the start of the function or script, before anything platform-specific runs: -# ❌ Wrong - true on 7.0 through 7.6 alike -if ($PSVersionTable.PSVersion.Major -ge 7) { } +```powershell +$onWindows = $PSVersionTable.PSVersion.Major -lt 6 -or $IsWindows +if (-not $onWindows) { + $exception = [System.PlatformNotSupportedException]::new('Get-ServiceReport requires Windows.') + $category = [System.Management.Automation.ErrorCategory]::NotImplemented + $errorRecord = [System.Management.Automation.ErrorRecord]::new( + $exception, 'UnsupportedOperatingSystem', $category, $null) + $PSCmdlet.ThrowTerminatingError($errorRecord) +} ``` -Report the runtime .NET version when diagnosing platform-specific behavior: +The test also runs under strict mode on Windows PowerShell 5.1, where `$IsWindows` does not exist: +`-or` does not evaluate its right side when the left side is true. + +## Installing modules (VER-08) ```powershell -[System.Runtime.InteropServices.RuntimeInformation]::FrameworkDescription +Install-PSResource -Name Pester -Version 6.2.0 -Scope CurrentUser -TrustRepository +``` + +Microsoft.PowerShell.PSResourceGet is included with PowerShell 7.4 and later. On Windows +PowerShell 5.1 it has to be installed first, so a script that must bootstrap on both checks for it: + +```powershell +if (Get-Command -Name Install-PSResource -ErrorAction SilentlyContinue) { + Install-PSResource -Name $moduleName -Scope CurrentUser -TrustRepository +} else { + Install-Module -Name $moduleName -Scope CurrentUser -Force +} ``` -## Tooling versions +## Tool versions -| Tool | Current | Notes | +| Tool | Version | Notes | | --- | --- | --- | -| PSScriptAnalyzer | 1.25.0 | Released 20-Mar-2026 | -| Pester | 6.x | See [pester.instructions.md](pester.instructions.md) | -| Microsoft.PowerShell.PSResourceGet | 1.2.0 | In-box with 7.6 | -| PSReadLine | 2.4.5 | In-box with 7.6 | -| Microsoft.PowerShell.ThreadJob | 2.2.0 | In-box with 7.6, renamed from `ThreadJob` | +| PSScriptAnalyzer | 1.25.0 | | +| Pester | 6.2.0 | See `.github/instructions/powershell-pester.instructions.md` | +| Microsoft.PowerShell.PlatyPS | 1.0.3 | See `.github/instructions/powershell-platyps.instructions.md` | +| Microsoft.PowerShell.PSResourceGet | 1.2.0 | Included with PowerShell 7.6 | +| Microsoft.PowerShell.ThreadJob | 2.2.0 | Included with PowerShell 7.6 | +| PSReadLine | 2.4.5 | Included with PowerShell 7.6 | diff --git a/.github/instructions/pull-requests.instructions.md b/.github/instructions/pull-requests.instructions.md deleted file mode 100644 index c4efe2f..0000000 --- a/.github/instructions/pull-requests.instructions.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -applyTo: '**' -description: 'How to branch, commit, and open pull requests in repositories that use these standards' ---- - -# Branches, Commits, and Pull Requests - -Follow these whenever you commit or open a pull request. They match the history already in these -repositories, so a new PR reads like the ones before it. - -## Branch - -- Never commit to the default branch. Start from an up-to-date default branch. -- Name the branch `<type>/<short-kebab-description>`, with the same type as the title: - `feat/onelogin-provider`, `fix/release-notes-length`, `docs/pester-6-2`. -- A release branch is `release/vX.Y.Z`. -- One concern per branch. Unrelated fixes found on the way get their own branch and PR. - -## Commit Messages and PR Title - -Use [Conventional Commits](https://www.conventionalcommits.org/). The PR title follows the same form -as the commit, because a squash merge turns the title into the commit on the default branch. - -```text -<type>(<scope>): <subject> -``` - -- **Type**: `feat`, `fix`, `docs`, `refactor`, `test`, `perf`, `ci`, `build`, or `chore`. A release - is `release: X.Y.Z`. -- **Scope**: optional. The area touched, in lower case: `feat(graph)`, `fix(release)`, - `docs(pester)`. -- **Subject**: imperative mood, lower case, no trailing period, at most 72 characters. Say what the - change does, not which files it touched. -- **Body**: wrap at 72 columns. Explain why the change was needed and what it fixes. The diff already - shows how. -- **Breaking change**: add `!` after the type or scope, and a `BREAKING CHANGE:` footer saying what a - caller must do. -- **Attribution**: no `Co-Authored-By` trailer, "Generated with" footer, or any other AI tool - attribution in commits, PR titles, PR bodies, or files. - -## Write for a Reader Who Was Not There - -Commit messages and PRs are permanent records. They are read months later by reviewers, maintainers, -and auditors who never saw the conversation that produced the change. Write every one so it stands on -its own for that reader. - -- **Describe the change, not the session.** State what the code does now and why. Leave out how the - work unfolded: the approaches tried and dropped, the order things were done in, what was fixed - along the way. Mention a rejected approach only when a reviewer would otherwise ask why it was not - used. -- **No conversational voice.** No "as discussed", "per your request", "you asked", "I noticed", - "let me know", "happy to", or "we decided". Write in the third person about the code: "Adds", - "Fixes", "The gate now fails when". -- **No references a stranger cannot resolve.** No "the earlier issue", "the approach above", "option - B", "the second fix", or names coined during the session. Link an issue, PR, commit, or file, or - describe the thing itself. -- **No assistant artifacts.** No mention of an AI tool, prompts, or chat. No hedging written for the - person at the keyboard, such as "should work now" or "hopefully". -- **Explain the domain.** Expand acronyms on first use and name the command or setting involved, so - a reviewer outside the team can follow. - -A quick test: if the text would read oddly pasted into a changelog or a release note, rewrite it. - -## Before Opening the PR - -1. Run the repository's gates locally. At minimum PSScriptAnalyzer and Pester, plus markdownlint - when Markdown changed. Use the same commands the CI workflow runs. -2. When the repository keeps a `CHANGELOG.md`, add the change under `## [Unreleased]` in the - [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) section that fits: `Added`, `Changed`, - `Fixed`, `Removed`, `Deprecated`, or `Security`. Write it for someone using the module. -3. When a public function's signature changed, update its PlatyPS Markdown under `docs/`, as - [platyps.instructions.md](./platyps.instructions.md) describes. -4. In a repository that consumes these standards, one with - `.github/workflows/sync-copilot-standards.yml`, do not edit the paths that workflow mirrors: - `.github/copilot-instructions.md`, `.github/instructions/`, `.github/prompts/`, - `powershell-standards/`, `.claude/rules/powershell-standards/`, and - `.claude/commands/powershell-standards/`. The next sync overwrites them, so change - [ai-powershell-standards](https://github.com/fadwen/ai-powershell-standards) instead. In - ai-powershell-standards itself those paths are the source, and editing them is the point. - -Open the PR as a draft when a gate fails and you cannot fix it, and say which gate in the body. - -## PR Body - -Use these sections, in this order. Leave out a section only when it would be empty. - -```markdown -## Summary - -What changed and why, in a few sentences. Lead with the problem it solves. - -## Changes - -- One bullet per change a reviewer should know about. - -## Verification - -- The commands you ran and their results, for example "Pester: 248 passed, 0 failed". -- Anything you could not verify, stated plainly. - -## Notes - -- Merge order, follow-ups, or decisions left for the reviewer. -``` - -- Link the issue it resolves with `Closes #123` in the Summary. -- When the PR depends on another, in this repository or elsewhere, say which one merges first. -- Report results as they were. A skipped or failing check is written as skipped or failing. - -## After Opening - -- Watch the PR's checks. When one fails, read its log, fix the cause, and push to the same branch. -- Annotate the diff, as described below. -- Do not merge your own PR, force-push a branch someone else has reviewed, or delete a branch unless - asked. - -## Annotate the Diff - -Once the PR is open, read its diff as a reviewer would and leave inline review comments on the lines -whose reason the code does not make plain. They explain the change to the reviewer now and stay -attached to the PR for anyone tracing the line's history later. - -Decide first where each explanation belongs: - -- **Why the code is the way it is** belongs in a code comment, because it must stay true as long as - the code does. Add the code comment rather than a review comment. -- **Why the code changed** belongs in a review comment, because it describes this change and would - go stale in the code. That covers a deleted guard, a changed default, a test expectation that - moved, a workaround for a tool's behavior, a value chosen from several reasonable ones, or a line - that fixes a bug found elsewhere. - -Skip lines whose reason is already plain from the code, a code comment, or the PR body. Do not -restate what a line does. A PR with nothing that needs explaining needs no annotations. - -Post all the annotations as a single review with the `COMMENT` event, so they arrive together and -do not approve or block the PR. The same audience rules apply as for the PR body. `gh pr review` -cannot comment on lines, so use the REST API: - -```powershell -$review = @{ - commit_id = (gh pr view <number> --json headRefOid --jq .headRefOid) - event = 'COMMENT' - body = 'Notes on the lines whose reason the diff does not show.' - comments = @( - @{ path = 'Public/Get-Thing.ps1'; line = 42; side = 'RIGHT'; body = 'Why this line changed.' } - ) -} -# ConvertTo-Json stops at a depth of 2 by default, which would turn each comment into a string -$review | ConvertTo-Json -Depth 5 | gh api --method POST repos/<owner>/<repo>/pulls/<number>/reviews --input - -``` - -`line` is the line number in the file as the PR leaves it, with `side = 'RIGHT'`. For a deleted line, -use its number in the old file with `side = 'LEFT'`. A comment must sit on a line inside the diff. diff --git a/.github/instructions/readme.instructions.md b/.github/instructions/readme.instructions.md deleted file mode 100644 index f061402..0000000 --- a/.github/instructions/readme.instructions.md +++ /dev/null @@ -1,533 +0,0 @@ ---- -applyTo: "**/README.md,**/readme.md,**/Readme.md" -description: 'Creates comprehensive, enterprise-grade README documentation for PowerShell projects' ---- - -# PowerShell README Documentation Generator - -Create comprehensive, enterprise-grade README documentation that serves as both technical reference and business -communication tool. Generate documentation that supports automatic integration, provides clear value proposition, and -maintains consistency with organizational standards. - -## README Generation Requirements - -### Content Assessment - -Gather information needed for complete README generation: - -#### Project Information - -- **Project Name**: Clear, descriptive name following PowerShell conventions -- **Primary Purpose**: Business value and technical function -- **Target Audience**: System administrators, developers, end users, or automation systems -- **Key Features**: Core capabilities and unique value propositions -- **Dependencies**: Required modules, system requirements, and external services -- **Current Status**: Development phase, version, and maturity level - -#### Technical Specifications - -- **PowerShell Versions**: State the supported range explicitly — PowerShell 7.6 (LTS) is the current target; note - Windows PowerShell 5.1 support only if actually tested -- **Platform Support**: Windows, Linux, macOS, or cross-platform -- **Installation Methods**: PowerShell Gallery, manual installation, or enterprise deployment -- **Configuration Requirements**: Environment setup, credentials, and permissions -- **Integration Points**: External systems, APIs, databases, or services - -## Comprehensive README Structure - -### Generate Complete README with Required Sections - -#### Header Section with Badges - -```markdown -# Project Title - -[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](./Actions) -[![PowerShell Gallery](https://img.shields.io/badge/PowerShell%20Gallery-v1.0.0-blue)](https://www.powershellgallery.com/) -[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE) -[![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen)](./Tests/Results/) -``` - -#### 📖 Overview Section - -Create compelling overview with business focus: - -```markdown -## 📖 Overview - -**Business Value:** [Clear ROI statement and organizational benefits] - -**Technical Summary:** [High-level description of what the solution does] - -### Key Features -- 🚀 **Feature 1**: Business impact and technical capability -- 📊 **Feature 2**: Performance improvements and efficiency gains -- 🔔 **Feature 3**: Automation capabilities and time savings -- 🛡️ **Feature 4**: Security controls and compliance features -- 📱 **Feature 5**: User experience and accessibility improvements - -### Target Audience -- **System Administrators**: Daily operations and troubleshooting tasks -- **Infrastructure Managers**: Capacity planning and strategic decisions -- **DevOps Teams**: CI/CD integration and automation workflows -- **Compliance Officers**: Audit trails and regulatory requirements -``` - -#### 🚀 Quick Start Section - -Provide immediate value with copy-paste examples: - -````markdown -## 🚀 Quick Start - -**TL;DR for experienced users:** - -```powershell -# One-line installation and basic usage -Install-PSResource ModuleName -Scope CurrentUser -TrustRepository -Get-ModuleFunction -Parameter "Value" -ExportFormat HTML -``` - -**Expected Output:** - -```text -✅ Processing completed successfully -📊 Results: 15 items processed in 2.3 seconds -📄 Report: .\Reports\Output_2024-01-15.html -``` - -**Next Steps:** See [Configuration](#️-configuration) for enterprise setup and [Advanced Examples](#advanced-scenarios) for automation patterns. - -```` - -#### 📋 Prerequisites Section - -Comprehensive requirements documentation: - -````markdown -## 📋 Prerequisites - -### System Requirements -| Component | Minimum | Recommended | Notes | -|-----------|---------|-------------|-------| -| **PowerShell** | 5.1 | 7.6 (LTS) | 7.4/7.5 lose support 10-Nov-2026; cross-platform in 7.x | -| **Operating System** | Windows 10 | Windows Server 2022+ | Linux/macOS supported in PS 7.x | -| **Memory** | 2GB RAM | 8GB+ RAM | Depends on dataset size | -| **Disk Space** | 100MB | 1GB+ | For logs, reports, and temporary files | -| **Network** | 1 Mbps | 10 Mbps+ | For multi-server environments | - -### Dependencies -```powershell -# Install required PowerShell modules -Install-PSResource PSFramework -Scope CurrentUser -TrustRepository -Install-PSResource ImportExcel -Scope CurrentUser -TrustRepository -``` - -| Module | Version | Purpose | Installation | -|--------|---------|---------|--------------| -| **PSFramework** | 1.7.0+ | Structured logging and configuration | `Install-PSResource PSFramework` | -| **ImportExcel** | 7.8.0+ | Excel report generation | `Install-PSResource ImportExcel` | - -> On Windows PowerShell 5.1, `Install-PSResource` is not in-box — install -> `Microsoft.PowerShell.PSResourceGet` first, or fall back to `Install-Module`. - -### Permissions & Access - -<details> -<summary>🔐 Detailed Permission Requirements</summary> - -#### Service Account Setup - -1. **Domain Account**: Recommended for enterprise environments -2. **Local Administrator**: Required on target systems -3. **WinRM Access**: Remote PowerShell connectivity - -#### Network Requirements - -| Protocol | Port | Direction | Purpose | -|----------|------|-----------|---------| -| **WinRM HTTP** | 5985 | Outbound | Remote PowerShell (default) | -| **WinRM HTTPS** | 5986 | Outbound | Secure remote PowerShell | -| **SMTP** | 25/587 | Outbound | Email reporting | - -</details> - -```` - -#### 🔧 Installation Section - -Multiple installation methods with validation: - -````markdown -## 🔧 Installation - -### Method 1: PowerShell Gallery (Recommended) -```powershell -# Install latest stable version -Install-PSResource ModuleName -Scope CurrentUser -TrustRepository - -# Verify installation -Get-Module ModuleName -ListAvailable -``` - -### Method 2: Manual Installation - -1. **Download Latest Release** - - ```powershell - $url = "https://github.com/user/repo/releases/latest/download/ModuleName.zip" - Invoke-WebRequest -Uri $url -OutFile "ModuleName.zip" - ``` - -2. **Extract and Verify** - - ```powershell - Expand-Archive -Path "ModuleName.zip" -DestinationPath "C:\Scripts\ModuleName" - - # Verify digital signature (recommended) - Get-AuthenticodeSignature -FilePath "C:\Scripts\ModuleName\ModuleName.ps1" - ``` - -### Method 3: Enterprise Deployment - -```powershell -# Using organizational package manager or deployment system -Deploy-EnterpriseModule -ModuleName "ModuleName" -Version "1.0.0" -TargetComputers $ServerList -``` - -```` - -#### ⚙️ Configuration Section - -Environment-specific configuration guidance: - -````markdown -## ⚙️ Configuration - -### Basic Configuration -```powershell -# Copy and customize configuration template -Copy-Item ".\Templates\config-template.json" ".\config.json" - -# Edit configuration for your environment -notepad ".\config.json" -``` - -### Configuration File Structure - -```json -{ - "environment": "Production", - "logging": { - "level": "Information", - "path": "./Logs/", - "retention": "30 days" - }, - "email": { - "smtpServer": "smtp.company.com", - "fromAddress": "monitoring@company.com", - "recipients": ["it-team@company.com"] - }, - "thresholds": { - "cpu": 80, - "memory": 85, - "disk": 90 - } -} -``` - -### Environment Variables - -```powershell -# Set environment-specific variables -$env:MODULE_CONFIG_PATH = "C:\Config\production-config.json" -$env:MODULE_LOG_LEVEL = "Information" -``` - -```` - -#### 💡 Usage Section - -Progressive examples from basic to enterprise: - -````markdown -## 💡 Usage - -### Basic Operations - -#### Example 1: Simple Execution -```powershell -# Basic usage with minimal parameters -Get-ModuleFunction -ComputerName "SERVER01" -``` - -**Expected Output:** - -```text -🔍 Analyzing SERVER01... -✅ Status: Healthy (Score: 92%) -📊 CPU: 45% | Memory: 62% | Disk: 78% -⏱️ Completed in 28 seconds -``` - -#### Example 2: Multiple Targets with Custom Settings - -```powershell -# Advanced scenario with multiple servers and custom thresholds -$servers = "WEB01", "WEB02", "WEB03" -Get-ModuleFunction -ComputerName $servers -Threshold 75 -ExportFormat HTML -Verbose -``` - -**Business Use Case:** Weekly infrastructure review preparation with visual dashboard - -### Advanced Scenarios - -#### Enterprise Active Directory Integration - -```powershell -# Automated discovery and monitoring of domain servers -Get-ADComputer -Filter "OperatingSystem -like '*Server*'" -SearchBase "OU=Servers,DC=contoso,DC=com" | - Select-Object -ExpandProperty Name | - Get-ModuleFunction -ExportFormat JSON -EmailReport -Credential (Get-Credential) -``` - -**ROI Impact:** Eliminates manual server inventory maintenance, ensures comprehensive coverage - -#### CI/CD Pipeline Integration - -```yaml -# Azure DevOps Pipeline Example -- task: PowerShell@2 - displayName: 'Infrastructure Health Check' - inputs: - targetType: 'inline' - script: | - $result = Get-ModuleFunction -ComputerName $env:SERVERS -Threshold 85 -PassThru - if ($result | Where-Object HealthStatus -eq 'Critical') { - Write-Error "Critical issues detected. Deployment aborted." - exit 1 - } -``` - -#### Scheduled Automation with Error Handling - -```powershell -# Enterprise scheduled monitoring with comprehensive error handling -try { - $servers = Get-Content ".\ServerLists\ProductionServers.txt" - $results = Get-ModuleFunction -ComputerName $servers -ExportFormat Excel -EmailReport - - Write-EventLog -LogName Application -Source "ModuleName" -EventId 1000 -EntryType Information -Message "Monitoring completed: $($servers.Count) servers processed" -} -catch { - Write-EventLog -LogName Application -Source "ModuleName" -EventId 1001 -EntryType Error -Message "Monitoring failed: $($_.Exception.Message)" - Send-MailMessage -To "alerts@company.com" -Subject "🚨 Monitoring Alert" -Body $_.Exception.Message -} -``` - -```` - -#### 🔍 Troubleshooting Section - -Comprehensive problem-solving guidance: - -````markdown -## 🔍 Troubleshooting - -### Quick Diagnostics -```powershell -# Built-in health check and diagnostics -Test-ModuleHealth -Verbose -ExportDiagnostics -``` - -### Common Issues - -<details> -<summary>❌ "Access Denied" or Permission Errors</summary> - -**Symptoms:** Script fails with "Access is denied" or authentication errors - -**Root Causes:** - -1. Insufficient user privileges on target systems -2. WinRM not enabled or configured -3. Firewall blocking required ports -4. Credential delegation issues - -**Solutions:** - -```powershell -# Test connectivity and permissions -Test-WSMan -ComputerName "SERVER01" -Credential (Get-Credential) - -# Enable WinRM on target servers (run as administrator) -Enable-PSRemoting -Force -Set-WSManQuickConfig -Force -``` - -**Related Documentation:** [Security Configuration Guide](./Troubleshooting/Security/WinRM-Setup.md) - -</details> - -<details> -<summary>⚠️ Performance Issues or Timeouts</summary> - -**Symptoms:** Slow execution, timeout errors, high memory usage - -**Diagnostic Commands:** - -```powershell -# Enable detailed performance logging -Get-ModuleFunction -ComputerName $servers -Verbose -Debug -PerformanceLogging - -# Monitor resource usage -Get-Process -Name powershell | Select-Object CPU, WorkingSet, VirtualMemorySize -``` - -**Optimization Strategies:** - -```powershell -# Process servers in batches for large environments -$serverBatches = $allServers | Group-Object {[math]::Floor($_.ReadCount / 10)} -foreach ($batch in $serverBatches) { - Get-ModuleFunction -ComputerName $batch.Group -ExportFormat JSON - Start-Sleep -Seconds 30 -} -``` - -**Related Documentation:** [Performance Optimization Guide](./Troubleshooting/Performance/Large-Scale-Operations.md) - -</details> - -### Error Code Reference - -| Error Code | Description | Immediate Action | Documentation | -|------------|-------------|------------------|---------------| -| **E001** | Connection timeout | Verify network connectivity and WinRM | [Connectivity Guide](./Troubleshooting/Connectivity/) | -| **E002** | Authentication failure | Check credentials and permissions | [Security Setup](./Troubleshooting/Security/) | -| **E003** | Invalid parameter format | Review parameter syntax and examples | [Usage Examples](#-usage) | - -### Self-Diagnostic Tools - -```powershell -# Comprehensive environment validation -Test-ModuleEnvironment -IncludeNetworkTest -IncludePermissionTest -ExportReport -``` - -```` - -#### Performance & Monitoring Section - -Document performance characteristics and monitoring integration: - -````markdown -## 📊 Performance & Monitoring - -### Performance Characteristics -| Environment Size | Execution Time | Memory Usage | Recommended Approach | -|------------------|----------------|--------------|---------------------| -| **Small (1-10 servers)** | 2-5 minutes | <100MB | Standard execution | -| **Medium (10-50 servers)** | 10-20 minutes | 100-500MB | Chunked processing | -| **Large (50+ servers)** | 20+ minutes | 500MB+ | Parallel processing | - -### Monitoring Integration -- **Application Insights**: Telemetry and performance tracking -- **SCOM Integration**: Enterprise monitoring system compatibility -- **Custom Dashboards**: Power BI and Grafana integration examples -- **Alerting**: Integration with PagerDuty, ServiceNow, and email systems - -### Optimization Guidelines -```powershell -# PowerShell 7.x parallel processing -$servers | ForEach-Object -Parallel { - Get-ModuleFunction -ComputerName $_ -ExportFormat JSON -} -ThrottleLimit 5 - -# Memory-efficient processing for large datasets -$servers | ForEach-Object { - Get-ModuleFunction -ComputerName $_ -StreamOutput -} | Export-Csv "results.csv" -NoTypeInformation -``` - -```` - -## Quality Assurance Integration - -### Documentation Validation - -Ensure README meets enterprise standards: - -#### Content Verification Checklist - -- [ ] Business value clearly articulated in overview -- [ ] All prerequisites documented with specific versions -- [ ] Installation instructions tested on clean environment -- [ ] Configuration examples validated and functional -- [ ] Usage examples copy-paste ready and tested -- [ ] Troubleshooting section addresses common issues -- [ ] Performance characteristics measured and documented -- [ ] Integration with `./Troubleshooting/` folder structure maintained - -#### Technical Accuracy Standards - -- [ ] All code examples executed and output verified -- [ ] Links reference existing files and documentation -- [ ] Version numbers current and consistent -- [ ] Dependencies list complete and accurate -- [ ] Error codes match actual script output -- [ ] Performance metrics realistic and measured - -#### Accessibility and Usability - -- [ ] Table of contents functional and complete -- [ ] Heading hierarchy logical and consistent -- [ ] Language appropriate for target audience -- [ ] Examples progress from simple to complex -- [ ] Mobile-friendly formatting considerations - -## Enhanced Features - -### Interactive Elements - -Add collapsible sections for detailed information: - -````markdown -<details> -<summary>🔧 Advanced Configuration Options</summary> - -### Enterprise Security Settings -```json -{ - "security": { - "encryptionRequired": true, - "certificateValidation": "strict", - "auditLogging": true, - "sessionTimeout": 3600 - } -} -``` - -**Security Note:** These settings affect compliance and should be reviewed by security teams. - -</details> - -```` - -### Visual Enhancements - -- **Status badges** for build, version, downloads, and coverage -- **Emoji icons** for section headers and visual navigation -- **Code syntax highlighting** with language specification -- **Tables** for structured information presentation -- **Mermaid diagrams** for workflow and architecture visualization - -### Business Integration - -- **ROI calculations** and cost-benefit analysis -- **Compliance mapping** to regulatory requirements -- **Executive summary** sections for management audiences -- **Success metrics** and KPI tracking integration - -Generate comprehensive README documentation that serves multiple audiences, provides immediate value through quick start -sections, includes thorough troubleshooting guidance with proper references to `./Troubleshooting/` folder structure, -and maintains consistency with enterprise PowerShell development standards. diff --git a/.github/instructions/securitycompliance.instructions.md b/.github/instructions/securitycompliance.instructions.md deleted file mode 100644 index d7ae4b6..0000000 --- a/.github/instructions/securitycompliance.instructions.md +++ /dev/null @@ -1,746 +0,0 @@ ---- -applyTo: "**/*.ps1,**/*.psm1,**/Security/**/*.ps1" -description: 'Implements security controls and compliance-support patterns for PowerShell solutions' ---- - -# PowerShell Security and Compliance Implementation - -Implement security controls for PowerShell solutions: input validation, credential handling, audit -logging, and threat mitigation. Apply security-by-design principles throughout development. - -These patterns support regulatory work such as SOX, GDPR, and HIPAA by producing the audit trails, -access controls, and data-handling evidence those programmes rely on. They do not make a system -compliant on their own — that depends on controls, evidence, and audit outside this codebase. Do not -describe generated code as compliant with any regulation. - -## Security Assessment and Implementation - -### Security Requirements Analysis - -Evaluate and implement security controls based on: - -#### Security Classification - -- **Public**: No restrictions, publicly accessible code -- **Internal**: Internal use only, basic access controls required -- **Confidential**: Sensitive data, enhanced protection required -- **Restricted**: Highly sensitive, strict access controls mandatory -- **Top Secret**: Maximum security, compartmentalized access - -#### Threat Model Assessment - -Identify and mitigate threats using STRIDE methodology: - -- **Spoofing**: Identity verification and authentication controls -- **Tampering**: Data integrity and code signing requirements -- **Repudiation**: Audit logging and non-repudiation controls -- **Information Disclosure**: Data protection and access controls -- **Denial of Service**: Availability and resilience measures -- **Elevation of Privilege**: Authorization and privilege management - -### Input Validation and Sanitization - -Implement comprehensive input validation for all user inputs: - -```powershell -function Protect-UserInput { - param( - [Parameter(Mandatory = $true)] - [string]$InputString, - [ValidateSet('ComputerName', 'FileName', 'UserName', 'FilePath', 'EmailAddress')] - [string]$InputType = 'General', - [string]$CorrelationId = [System.Guid]::NewGuid().ToString() - ) - - # Log security validation attempt - Write-SecurityLog -SecurityEventType 'DataValidation' -Message "Input validation requested" -Outcome 'Attempt' -CorrelationId $CorrelationId -SecurityContext @{ - InputType = $InputType - InputLength = $InputString.Length - } - - # Length validation - if ($InputString.Length -gt 1000) { - throw [SecurityException]::new("Input exceeds maximum length of 1000 characters", 'InputValidation', 'Length-Check') - } - - # Type-specific validation patterns - switch ($InputType) { - 'ComputerName' { - if ($InputString -notmatch '^[a-zA-Z0-9\-\.]+$') { - throw [SecurityException]::new("Invalid computer name format", 'InputValidation', 'Format-Check') - } - } - 'FileName' { - $invalidChars = [System.IO.Path]::GetInvalidFileNameChars() - foreach ($char in $invalidChars) { - if ($InputString.Contains($char)) { - throw [SecurityException]::new("Invalid file name character: $char", 'InputValidation', 'Character-Check') - } - } - } - 'FilePath' { - # Prevent path traversal attacks - $normalizedPath = [System.IO.Path]::GetFullPath($InputString) - if ($normalizedPath.Contains('..') -or $normalizedPath.Contains('~')) { - throw [SecurityException]::new("Path traversal attempt detected", 'InputValidation', 'Path-Traversal') - } - } - 'EmailAddress' { - if ($InputString -notmatch '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$') { - throw [SecurityException]::new("Invalid email address format", 'InputValidation', 'Email-Format') - } - } - } - - # Check for common injection patterns - $dangerousPatterns = @( - ';', # Command separator - '&', # Command separator - '|', # Pipe operator - '<', # Redirect - '>', # Redirect - '`', # Backtick execution - '$(', # Subexpression - 'Invoke-', # Dangerous cmdlets - 'iex', # Invoke-Expression alias - 'Remove-', # Destructive operations - 'Format-' # Format string attacks - ) - - foreach ($pattern in $dangerousPatterns) { - if ($InputString -like "*$pattern*") { - Write-SecurityLog -SecurityEventType 'SecurityViolation' -Message "Dangerous pattern detected in input" -Outcome 'Failure' -CorrelationId $CorrelationId -SecurityContext @{ - Pattern = $pattern - InputSample = $InputString.Substring(0, [Math]::Min(50, $InputString.Length)) - } -RiskLevel 'High' - - throw [SecurityException]::new("Input contains potentially dangerous pattern: $pattern", 'InputValidation', 'Injection-Prevention') - } - } - - Write-SecurityLog -SecurityEventType 'DataValidation' -Message "Input validation successful" -Outcome 'Success' -CorrelationId $CorrelationId - return $InputString.Trim() -} -``` - -### Credential and Secret Management - -Implement secure credential handling using SecretManagement: - -```powershell -function Get-SecureCredential { - param( - [Parameter(Mandatory = $true)] - [ValidateNotNullOrEmpty()] - [string]$Name, - [string]$VaultName, - [string]$Purpose = 'General', - [string]$CorrelationId = [System.Guid]::NewGuid().ToString() - ) - - try { - Write-SecurityLog -SecurityEventType 'Authentication' -Message "Credential retrieval requested" -Outcome 'Attempt' -CorrelationId $CorrelationId -SecurityContext @{ - CredentialName = $Name - VaultName = $VaultName - Purpose = $Purpose - } - - # Rate limiting check to prevent brute force - $rateLimitResult = Test-CredentialAccessRateLimit -CredentialName $Name -CorrelationId $CorrelationId - if (-not $rateLimitResult.Allowed) { - Write-SecurityLog -SecurityEventType 'SecurityViolation' -Message "Credential access rate limit exceeded" -Outcome 'Failure' -CorrelationId $CorrelationId -SecurityContext @{ - CredentialName = $Name - AttemptsInLastHour = $rateLimitResult.RecentAttempts - } -RiskLevel 'High' - - throw [SecurityException]::new("Credential access rate limit exceeded for: $Name", 'CredentialManagement', 'Rate-Limiting') - } - - # Attempt to retrieve from SecretManagement vault - $credential = Get-Secret -Name $Name -Vault $VaultName -AsPlainText:$false -ErrorAction Stop - - if ($credential) { - Write-SecurityLog -SecurityEventType 'Authentication' -Message "Credential retrieved successfully" -Outcome 'Success' -CorrelationId $CorrelationId -SecurityContext @{ - CredentialName = $Name - VaultName = $VaultName - } - - return $credential - } - - } - catch { - Write-SecurityLog -SecurityEventType 'Authentication' -Message "Credential retrieval failed" -Outcome 'Failure' -CorrelationId $CorrelationId -SecurityContext @{ - CredentialName = $Name - Error = $_.Exception.Message - } -RiskLevel 'Medium' - - # Fallback to interactive prompt with security warning - Write-Warning "Credential not found in secure vault. Interactive prompt required." - return Get-Credential -Message "Enter credentials for: $Name" - } -} - -function Set-SecureCredential { - param( - [Parameter(Mandatory = $true)] - [string]$Name, - [Parameter(Mandatory = $true)] - [System.Management.Automation.PSCredential]$Credential, - [string]$VaultName, - [ValidateSet('Low', 'Medium', 'High', 'Critical')] - [string]$SecurityLevel = 'Medium', - [string]$CorrelationId = [System.Guid]::NewGuid().ToString() - ) - - try { - # Validate credential strength - $credentialValidation = Test-CredentialSecurity -Credential $Credential -SecurityLevel $SecurityLevel - - if (-not $credentialValidation.IsValid) { - throw [SecurityException]::new("Credential does not meet security requirements: $($credentialValidation.Errors -join '; ')", 'CredentialManagement', 'Security-Validation') - } - - # Store credential with metadata - $metadata = @{ - StoredBy = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name - StoredAt = Get-Date -Format 'yyyy-MM-dd HH:mm:ss' - SecurityLevel = $SecurityLevel - CorrelationId = $CorrelationId - } - - Set-Secret -Name $Name -Secret $Credential -Vault $VaultName -Metadata $metadata - - Write-SecurityLog -SecurityEventType 'DataAccess' -Message "Credential stored successfully" -Outcome 'Success' -CorrelationId $CorrelationId -SecurityContext @{ - CredentialName = $Name - SecurityLevel = $SecurityLevel - } - - } - catch { - Write-SecurityLog -SecurityEventType 'DataAccess' -Message "Credential storage failed" -Outcome 'Failure' -CorrelationId $CorrelationId -SecurityContext @{ - CredentialName = $Name - Error = $_.Exception.Message - } -RiskLevel 'High' - throw - } -} -``` - -## Compliance Framework Implementation - -### SOX (Sarbanes-Oxley) Compliance - -Implement controls for financial data processing: - -```powershell -function Invoke-SOXCompliance { - param( - [Parameter(Mandatory = $true)] - [string]$Operation, - [hashtable]$FinancialData = @{}, - [string]$BusinessJustification, - [string]$CorrelationId = [System.Guid]::NewGuid().ToString() - ) - - try { - Write-SecurityLog -SecurityEventType 'DataAccess' -Message "SOX compliance validation initiated" -Outcome 'Attempt' -CorrelationId $CorrelationId -SecurityContext @{ - Operation = $Operation - BusinessJustification = $BusinessJustification - ComplianceFramework = 'SOX' - } - - $complianceResults = @{ - Operation = $Operation - ComplianceStatus = 'Compliant' - ControlsValidated = @() - DeficienciesFound = @() - AuditTrail = @() - } - - # Validate management approval for financial operations - $operationsRequiringApproval = @('FinancialDataModification', 'ReportGeneration', 'DataDeletion') - if ($Operation -in $operationsRequiringApproval) { - $approvalValidation = Test-ManagementApproval -Operation $Operation -BusinessJustification $BusinessJustification - - if (-not $approvalValidation.Approved) { - $complianceResults.DeficienciesFound += 'Management approval required but not obtained' - $complianceResults.ComplianceStatus = 'Non-Compliant' - } else { - $complianceResults.ControlsValidated += 'Management Approval: Verified' - } - } - - # Validate data integrity controls - if ($FinancialData.Count -gt 0) { - $integrityValidation = Test-DataIntegrityControls -Data $FinancialData - - if (-not $integrityValidation.IntegrityVerified) { - $complianceResults.DeficienciesFound += 'Data integrity validation failed' - $complianceResults.ComplianceStatus = 'Non-Compliant' - } - } - - # Ensure audit trail requirements - $auditTrailValidation = Test-AuditTrailRequirements -Operation $Operation - if (-not $auditTrailValidation.Compliant) { - $complianceResults.DeficienciesFound += $auditTrailValidation.Deficiencies - $complianceResults.ComplianceStatus = 'Non-Compliant' - } - - # Generate compliance report - $complianceReport = @{ - ComplianceFramework = 'SOX' - AssessmentDate = Get-Date - CorrelationId = $CorrelationId - Operation = $Operation - OverallStatus = $complianceResults.ComplianceStatus - ControlsValidated = $complianceResults.ControlsValidated - DeficienciesFound = $complianceResults.DeficienciesFound - } - - # Store compliance record - Set-ComplianceRecord -Framework 'SOX' -Report $complianceReport - - return $complianceReport - } - catch { - Write-SecurityLog -SecurityEventType 'DataAccess' -Message "SOX compliance validation failed" -Outcome 'Failure' -CorrelationId $CorrelationId -SecurityContext @{ - Operation = $Operation - Error = $_.Exception.Message - } -RiskLevel 'Critical' - throw - } -} -``` - -### GDPR (General Data Protection Regulation) Compliance - -Implement data protection controls for personal data: - -```powershell -function Invoke-GDPRCompliance { - param( - [Parameter(Mandatory = $true)] - [ValidateSet('Collection', 'Processing', 'Storage', 'Transfer', 'Deletion', 'Access')] - [string]$DataOperation, - [hashtable]$PersonalData = @{}, - [ValidateSet('Consent', 'Contract', 'LegalObligation', 'VitalInterests', 'PublicTask', 'LegitimateInterests')] - [string]$LegalBasis, - [string]$DataSubjectId, - [string]$CorrelationId = [System.Guid]::NewGuid().ToString() - ) - - try { - Write-SecurityLog -SecurityEventType 'DataAccess' -Message "GDPR compliance validation initiated" -Outcome 'Attempt' -CorrelationId $CorrelationId -SecurityContext @{ - DataOperation = $DataOperation - LegalBasis = $LegalBasis - ComplianceFramework = 'GDPR' - } - - $gdprCompliance = @{ - Operation = $DataOperation - ComplianceStatus = 'Compliant' - LegalBasisValidated = $false - ConsentVerified = $false - DataMinimizationCompliant = $false - SecurityMeasuresValid = $false - ViolationsFound = @() - } - - # Article 6: Legal basis validation - $legalBasisValidation = Test-GDPRLegalBasis -Operation $DataOperation -LegalBasis $LegalBasis -DataSubjectId $DataSubjectId - if ($legalBasisValidation.Valid) { - $gdprCompliance.LegalBasisValidated = $true - } else { - $gdprCompliance.ViolationsFound += "Invalid legal basis: $($legalBasisValidation.Reason)" - $gdprCompliance.ComplianceStatus = 'Non-Compliant' - } - - # Article 7: Consent validation (if consent is the legal basis) - if ($LegalBasis -eq 'Consent') { - $consentValidation = Test-GDPRConsent -DataSubjectId $DataSubjectId -DataOperation $DataOperation - if ($consentValidation.Valid -and $consentValidation.Current) { - $gdprCompliance.ConsentVerified = $true - } else { - $gdprCompliance.ViolationsFound += "Invalid or expired consent" - $gdprCompliance.ComplianceStatus = 'Non-Compliant' - } - } - - # Article 5: Data minimization principle - if ($PersonalData.Count -gt 0) { - $minimizationValidation = Test-DataMinimization -PersonalData $PersonalData -DataOperation $DataOperation - if ($minimizationValidation.Compliant) { - $gdprCompliance.DataMinimizationCompliant = $true - } else { - $gdprCompliance.ViolationsFound += $minimizationValidation.Violations - $gdprCompliance.ComplianceStatus = 'Non-Compliant' - } - } - - # Article 32: Security of processing - $securityValidation = Test-GDPRSecurityMeasures -DataOperation $DataOperation -PersonalData $PersonalData - if ($securityValidation.Adequate) { - $gdprCompliance.SecurityMeasuresValid = $true - } else { - $gdprCompliance.ViolationsFound += $securityValidation.Deficiencies - } - - # Generate GDPR compliance report - $gdprReport = @{ - ComplianceFramework = 'GDPR' - AssessmentDate = Get-Date - CorrelationId = $CorrelationId - DataOperation = $DataOperation - DataSubjectId = $DataSubjectId - LegalBasis = $LegalBasis - OverallStatus = $gdprCompliance.ComplianceStatus - ViolationsFound = $gdprCompliance.ViolationsFound - } - - # Record processing activity (Article 30) - Set-GDPRProcessingRecord -Record $gdprReport - - return $gdprReport - } - catch { - Write-SecurityLog -SecurityEventType 'DataAccess' -Message "GDPR compliance validation failed" -Outcome 'Failure' -CorrelationId $CorrelationId -SecurityContext @{ - DataOperation = $DataOperation - Error = $_.Exception.Message - } -RiskLevel 'Critical' - throw - } -} -``` - -### HIPAA Compliance (Healthcare) - -Implement healthcare data protection controls: - -```powershell -function Invoke-HIPAACompliance { - param( - [Parameter(Mandatory = $true)] - [string]$DataOperation, - [hashtable]$HealthInformation = @{}, - [string]$CoveredEntity, - [string]$CorrelationId = [System.Guid]::NewGuid().ToString() - ) - - $hipaaCompliance = @{ - Operation = $DataOperation - ComplianceStatus = 'Compliant' - SafeguardsImplemented = @() - Violations = @() - } - - # Administrative Safeguards (§164.308) - $adminSafeguards = Test-HIPAAAdministrativeSafeguards -Operation $DataOperation - if ($adminSafeguards.Compliant) { - $hipaaCompliance.SafeguardsImplemented += 'Administrative Safeguards: Compliant' - } else { - $hipaaCompliance.Violations += $adminSafeguards.Violations - } - - # Physical Safeguards (§164.310) - $physicalSafeguards = Test-HIPAAPhysicalSafeguards -Operation $DataOperation - if ($physicalSafeguards.Compliant) { - $hipaaCompliance.SafeguardsImplemented += 'Physical Safeguards: Compliant' - } else { - $hipaaCompliance.Violations += $physicalSafeguards.Violations - } - - # Technical Safeguards (§164.312) - $technicalSafeguards = Test-HIPAATechnicalSafeguards -HealthInformation $HealthInformation - if ($technicalSafeguards.Compliant) { - $hipaaCompliance.SafeguardsImplemented += 'Technical Safeguards: Compliant' - } else { - $hipaaCompliance.Violations += $technicalSafeguards.Violations - } - - if ($hipaaCompliance.Violations.Count -gt 0) { - $hipaaCompliance.ComplianceStatus = 'Non-Compliant' - } - - return $hipaaCompliance -} -``` - -## Code Signing and Certificate Management - -### Automated Code Signing Implementation - -```powershell -function Invoke-CodeSigning { - param( - [Parameter(Mandatory = $true, ValueFromPipeline = $true)] - [string[]]$FilePath, - [string]$Environment = 'Development', - [string]$CertificateThumbprint, - [string]$CorrelationId = [System.Guid]::NewGuid().ToString() - ) - - begin { - Write-SecurityLog -SecurityEventType 'DataAccess' -Message "Code signing operation initiated" -Outcome 'Attempt' -CorrelationId $CorrelationId -SecurityContext @{ - Environment = $Environment - FileCount = @($FilePath).Count - } - - # Get signing configuration - $signingConfig = Get-CodeSigningConfiguration -Environment $Environment - if (-not $signingConfig) { - throw [SecurityException]::new("Code signing not configured for environment: $Environment", 'CodeSigning', 'Configuration') - } - - # Override certificate if specified - if ($CertificateThumbprint) { - $signingConfig.CertificateThumbprint = $CertificateThumbprint - } - - # Validate certificate - $certificate = Get-Item "Cert:\CurrentUser\My\$($signingConfig.CertificateThumbprint)" -ErrorAction SilentlyContinue - if (-not $certificate) { - throw [SecurityException]::new("Code signing certificate not found: $($signingConfig.CertificateThumbprint)", 'CodeSigning', 'Certificate-Access') - } - - $signedFiles = @() - $failedFiles = @() - } - - process { - foreach ($file in $FilePath) { - try { - # Validate file exists and is appropriate type - if (-not (Test-Path $file)) { - throw "File not found: $file" - } - - $fileInfo = Get-Item $file - $allowedExtensions = @('.ps1', '.psm1', '.psd1', '.ps1xml') - if ($fileInfo.Extension -notin $allowedExtensions) { - throw "File type not approved for signing: $($fileInfo.Extension)" - } - - # Perform security scan before signing - $scanResult = Invoke-SecurityScan -FilePath $file - if ($scanResult.HighRiskIssues -gt 0) { - throw "Security scan failed: High risk issues found" - } - - # Sign the file - $signature = Set-AuthenticodeSignature -FilePath $file -Certificate $certificate -TimestampServer $signingConfig.TimestampServer - - if ($signature.Status -eq 'Valid') { - $signedFiles += @{ - FilePath = $file - SignatureStatus = $signature.Status - SignerCertificate = $signature.SignerCertificate.Thumbprint - SignedAt = Get-Date - } - - Write-SecurityLog -SecurityEventType 'DataAccess' -Message "File signed successfully" -Outcome 'Success' -CorrelationId $CorrelationId -SecurityContext @{ - FilePath = $file - CertificateThumbprint = $certificate.Thumbprint - } - } - } - catch { - $failedFiles += @{ - FilePath = $file - Error = $_.Exception.Message - FailedAt = Get-Date - } - - Write-SecurityLog -SecurityEventType 'DataAccess' -Message "File signing failed" -Outcome 'Failure' -CorrelationId $CorrelationId -SecurityContext @{ - FilePath = $file - Error = $_.Exception.Message - } -RiskLevel 'Medium' - } - } - } - - end { - $summary = @{ - TotalFiles = @($FilePath).Count - SignedFiles = $signedFiles.Count - FailedFiles = $failedFiles.Count - SignedFileDetails = $signedFiles - FailedFileDetails = $failedFiles - CorrelationId = $CorrelationId - } - - Write-SecurityLog -SecurityEventType 'DataAccess' -Message "Code signing operation completed" -Outcome 'Success' -CorrelationId $CorrelationId -SecurityContext $summary - - return $summary - } -} -``` - -### Security Scanning Integration - -Implement automated security scanning: - -```powershell -function Invoke-SecurityScan { - param( - [Parameter(Mandatory = $true)] - [string]$FilePath, - [string]$CorrelationId = [System.Guid]::NewGuid().ToString() - ) - - $scanResults = @{ - FilePath = $FilePath - ScanDate = Get-Date - TotalIssues = 0 - CriticalIssues = 0 - HighRiskIssues = 0 - MediumRiskIssues = 0 - LowRiskIssues = 0 - SecurityFindings = @() - OverallRisk = 'Low' - } - - try { - Write-SecurityLog -SecurityEventType 'SecurityViolation' -Message "Security scan initiated" -Outcome 'Attempt' -CorrelationId $CorrelationId -SecurityContext @{ - FilePath = $FilePath - ScanType = 'Comprehensive' - } - - $fileContent = Get-Content -Path $FilePath -Raw - - # Credential leak detection - $credentialPatterns = @( - @{ Pattern = '(?i)(password|pwd|pass)\s*[:=]\s*["\']?[^"\'\s]{8,}'; Risk = 'Critical'; Description = 'Potential hardcoded password' } - @{ Pattern = '(?i)(api[_-]?key|apikey)\s*[:=]\s*["\']?[a-zA-Z0-9]{20,}'; Risk = 'Critical'; Description = 'Potential API key exposure' } - @{ Pattern = '(?i)(secret|token)\s*[:=]\s*["\']?[a-zA-Z0-9]{16,}'; Risk = 'High'; Description = 'Potential secret or token exposure' } - @{ Pattern = 'ConvertTo-SecureString\s+-String\s+["\'][^"\']+["\']'; Risk = 'High'; Description = 'Hardcoded secure string conversion' } - ) - - foreach ($patternInfo in $credentialPatterns) { - if ($fileContent -match $patternInfo.Pattern) { - $finding = @{ - Type = 'CredentialLeak' - Risk = $patternInfo.Risk - Description = $patternInfo.Description - Pattern = $patternInfo.Pattern - LineNumber = ($fileContent.Substring(0, $fileContent.IndexOf($Matches[0])).Split("`n").Count) - } - - $scanResults.SecurityFindings += $finding - - switch ($patternInfo.Risk) { - 'Critical' { $scanResults.CriticalIssues++ } - 'High' { $scanResults.HighRiskIssues++ } - 'Medium' { $scanResults.MediumRiskIssues++ } - 'Low' { $scanResults.LowRiskIssues++ } - } - } - } - - # Command injection detection - $injectionPatterns = @( - @{ Pattern = 'Invoke-Expression'; Risk = 'High'; Description = 'Use of Invoke-Expression detected' } - @{ Pattern = 'iex\s'; Risk = 'High'; Description = 'Use of iex alias detected' } - @{ Pattern = 'Add-Type.*-TypeDefinition'; Risk = 'Medium'; Description = 'Dynamic type compilation detected' } - ) - - foreach ($patternInfo in $injectionPatterns) { - if ($fileContent -match $patternInfo.Pattern) { - $finding = @{ - Type = 'CodeInjection' - Risk = $patternInfo.Risk - Description = $patternInfo.Description - Pattern = $patternInfo.Pattern - } - - $scanResults.SecurityFindings += $finding - - switch ($patternInfo.Risk) { - 'High' { $scanResults.HighRiskIssues++ } - 'Medium' { $scanResults.MediumRiskIssues++ } - 'Low' { $scanResults.LowRiskIssues++ } - } - } - } - - # Calculate overall risk - if ($scanResults.CriticalIssues -gt 0) { - $scanResults.OverallRisk = 'Critical' - } elseif ($scanResults.HighRiskIssues -gt 0) { - $scanResults.OverallRisk = 'High' - } elseif ($scanResults.MediumRiskIssues -gt 0) { - $scanResults.OverallRisk = 'Medium' - } - - $scanResults.TotalIssues = $scanResults.CriticalIssues + $scanResults.HighRiskIssues + $scanResults.MediumRiskIssues + $scanResults.LowRiskIssues - - Write-SecurityLog -SecurityEventType 'SecurityViolation' -Message "Security scan completed" -Outcome 'Success' -CorrelationId $CorrelationId -SecurityContext @{ - FilePath = $FilePath - TotalIssues = $scanResults.TotalIssues - OverallRisk = $scanResults.OverallRisk - CriticalIssues = $scanResults.CriticalIssues - } - - return $scanResults - } - catch { - Write-SecurityLog -SecurityEventType 'SecurityViolation' -Message "Security scan failed" -Outcome 'Failure' -CorrelationId $CorrelationId -SecurityContext @{ - FilePath = $FilePath - Error = $_.Exception.Message - } -RiskLevel 'Medium' - throw - } -} -``` - -## Implementation Requirements - -### Security Integration Checklist - -When implementing security and compliance controls: - -#### Required Security Components - -- [ ] **Input validation** for all user-provided data with type-specific patterns -- [ ] **Credential management** using SecretManagement with secure vault integration -- [ ] **Security logging** with correlation IDs and appropriate detail levels -- [ ] **Code signing** infrastructure with certificate validation and timestamp services -- [ ] **Security scanning** integration for credential leaks and injection vulnerabilities -- [ ] **Access controls** implementing principle of least privilege -- [ ] **Audit trail** maintenance for compliance and forensic requirements - -#### Compliance Framework Support - -Controls these programmes depend on. Implementing them supports an audit; it does not by itself -establish compliance with any of these regulations. - -- [ ] **SOX** — approval workflows and tamper-evident audit trails for financial data operations -- [ ] **GDPR** — consent capture and verification for personal data processing -- [ ] **GDPR Article 17** — right-to-erasure handling -- [ ] **HIPAA** — administrative, physical, and technical safeguards for health information -- [ ] **PCI DSS** — cardholder data handling (if applicable) -- [ ] **Data retention** policies and automated enforcement - -#### Enterprise Integration Points - -- [ ] Integration with enterprise identity management systems -- [ ] Connection to centralized logging and SIEM platforms -- [ ] Compliance reporting automation and dashboard integration -- [ ] Security incident response procedures and escalation -- [ ] Regular security assessment and penetration testing integration -- [ ] Security awareness training integration and tracking - -### Troubleshooting Documentation Integration - -All security and compliance implementations must include: - -- **Security troubleshooting guides** in `./Troubleshooting/Security/` folder -- **Compliance procedures** in `./Troubleshooting/Compliance/` folder -- **Incident response playbooks** in `./Troubleshooting/Incident-Response/` folder -- **Configuration guides** with step-by-step security setup procedures -- **Error resolution** documentation with correlation ID usage examples - -Generate comprehensive security and compliance implementations that provide enterprise-grade protection while -maintaining usability and performance. Ensure all controls integrate with established PowerShell development standards -and maintain proper documentation in the `./Troubleshooting/` folder structure for consistent organizational reference. diff --git a/.github/instructions/style-enforcement.instructions.md b/.github/instructions/style-enforcement.instructions.md deleted file mode 100644 index 2bd109d..0000000 --- a/.github/instructions/style-enforcement.instructions.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -applyTo: "**/*.ps1,**/*.psm1" -description: 'Automatic style guide enforcement' ---- - -# PowerShell Style Guide Enforcement - -Automatically enforce PowerShell community style guidelines in all code generation. - -> **Worked example**: every file under -> [powershell-standards/Examples](../../powershell-standards/Examples/) is written to these rules and passes the -> repository's own quality gates. When the wording here is ambiguous, match the examples. - -## Mandatory Style Patterns - -### Code Formatting - -- **Brace Style**: One True Brace Style (opening brace at end of line) -- **Indentation**: 4 spaces, never tabs -- **Line Length**: Maximum 115 characters -- **Blank Lines**: 2 blank lines before functions, 1 between methods - -A team that wants these checked mechanically does not need a settings file - PSScriptAnalyzer ships -`CodeFormattingOTBS`, which already configures the brace style, 4-space indentation, whitespace and -assignment alignment above: - -```powershell -Invoke-ScriptAnalyzer -Path . -Recurse -Settings CodeFormattingOTBS -``` - -The 115-character limit is the one rule it does not include; add `PSAvoidLongLines` if the team -wants it enforced. Adopting either is their choice - these standards describe the practices, not the -audit configuration. - -### Parameter Formatting - -```powershell -# Correct parameter block formatting -param( - [Parameter(Mandatory = $true, - ValueFromPipeline = $true, - ValueFromPipelineByPropertyName = $true)] - [ValidateNotNullOrEmpty()] - [string[]]$ComputerName, - - [Parameter()] - [System.Management.Automation.PSCredential] - [System.Management.Automation.Credential()] - $Credential = [System.Management.Automation.PSCredential]::Empty -) -``` - -### Operator Spacing - -```powershell -# Correct spacing around operators -$result = $value1 + $value2 -$condition = ($status -eq 'Running') -and ($service -ne $null) - -# Correct parameter spacing -Get-Process -Name "powershell" -ComputerName $servers -``` - -### Anti-Patterns to Avoid - -```powershell -# Avoid backticks for line continuation -# Instead of: -Get-WmiObject -Class Win32_LogicalDisk ` - -Filter "DriveType=3" ` - -ComputerName $server - -# Use splatting: -$params = @{ - Class = 'Win32_LogicalDisk' - Filter = 'DriveType=3' - ComputerName = $server -} -Get-WmiObject @params - -# Avoid Write-Host unless specifically needed for colored output -# Use Write-Output, Write-Verbose, Write-Information instead -``` - -## Automatic Style Corrections - -When generating code, automatically apply: - -1. Convert aliases to full command names -2. Add proper spacing around operators and parameters -3. Format parameter blocks with proper alignment -4. Use approved verbs and PascalCase naming -5. Add comprehensive comment-based help templates -6. Implement proper error handling patterns -7. Include correlation ID tracking in functions diff --git a/.github/prompts/README.md b/.github/prompts/README.md new file mode 100644 index 0000000..fb771f4 --- /dev/null +++ b/.github/prompts/README.md @@ -0,0 +1,17 @@ +# Prompt files were replaced by skills + +This folder is kept only so that a sync workflow installed before version 2.0 keeps running. That +workflow copies this folder into your repository, and it fails if the folder does not exist. + +Version 2.0 of the PowerShell standards has no prompt files. The tasks they covered are now skills, +which GitHub Copilot, Claude Code, and Codex load from `.github/skills`, `.claude/skills`, and +`.agents/skills`. + +If you are reading this in your own repository, the old sync workflow has updated your instruction +files but has not installed the skills or the files for Claude Code and Codex. To get them: + +1. Clone the standards repository. +2. Run `./Tools/Install-CopilotStandards.ps1 -ProjectPath <your repository> -RemoveLegacyFiles`. +3. Replace `.github/workflows/sync-copilot-standards.yml` in your repository with the current + template from `Templates/Workflows` in the standards repository. +4. Delete this folder. diff --git a/.github/prompts/code-analysis.prompt.md b/.github/prompts/code-analysis.prompt.md deleted file mode 100644 index 96a0bca..0000000 --- a/.github/prompts/code-analysis.prompt.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -agent: 'agent' -description: 'Comprehensive code quality analysis with expert-reviewed standards' -tools: ['search/codebase'] ---- - -Perform thorough analysis of this PowerShell code against modern best practices: - -**Selected Code:** - -```powershell -${selection} -``` - -**Analysis Framework:** - -**1. Modern PowerShell Patterns ✅** - -- Error handling: Verify $_ usage in catch blocks (not $Error[0]) -- Credential creation: Check for [PSCredential]::new() vs New-Object -- Parameter validation: Ensure appropriate validation without redundancy -- String operations: Context-appropriate concatenation vs StringBuilder - -**2. Comment-Based Help Quality ✅** - -- Proper block comment syntax with opening markers -- Complete parameter documentation -- Meaningful examples with descriptions -- Appropriate .INPUTS and .OUTPUTS sections -- Avoid maintenance-heavy versioning in .NOTES - -**3. Performance Patterns ✅** - -- Context-aware string operations (simple vs complex) -- Collection handling: flag `+=` only where the declared target is below 7.5, in which it is still - O(n²), or where the loop is unbounded. PowerShell 7.5 optimised it. Never suggest `ArrayList` -- Appropriate use of pipeline vs loops -- Memory-conscious patterns for large datasets - -**4. Output Type Design ✅** - -- Descriptive type names instead of misleading [PSCustomObject] -- Custom classes for complex objects -- Meaningful IntelliSense support -- Proper type declarations - -**5. Enterprise Standards ✅** - -- Correlation ID implementation -- Structured logging patterns -- Configuration-driven behavior -- Environment-appropriate error handling - -**6. Security & Compliance ✅** - -- Modern security patterns -- Input validation best practices -- Audit trail requirements -- Compliance framework alignment - -**7. Code Quality Metrics ✅** - -- Approved PowerShell verb usage -- Consistent style and formatting -- Appropriate function complexity -- Clear separation of concerns - -**Analysis Output:** -Provide prioritized recommendations with: - -- ❌ Issues found with severity rating -- ✅ Best practices already implemented -- 🔧 Specific code corrections -- 💡 Optimization opportunities -- 📋 Compliance gaps - -Include corrected code examples demonstrating proper modern PowerShell patterns. diff --git a/.github/prompts/create-module.prompt.md b/.github/prompts/create-module.prompt.md deleted file mode 100644 index f1ff4bd..0000000 --- a/.github/prompts/create-module.prompt.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -agent: 'agent' -description: 'Generates complete PowerShell module structure' -tools: ['search/codebase'] ---- - -Create a complete PowerShell module for ${workspaceFolderBasename} with enterprise standards: - -**Module Specifications:** - -- **Module Name**: ${input:moduleName:MyEnterpriseModule} -- **Primary Purpose**: ${input:purpose:Describe the main business function this module serves} -- **Target Audience**: ${input:audience:System Administrators,Developers,End Users,Automation Systems} -- **Complexity Level**: ${input:complexity:Simple (1-5 functions),Medium (5-15 functions),Complex (15+ functions)} - -**Module Structure to Generate:** - -```text -${input:moduleName}/ -├── ${input:moduleName}.psd1 # Module manifest -├── ${input:moduleName}.psm1 # Root module file -├── Public/ # Exported functions -├── Private/ # Internal functions -├── Classes/ # PowerShell classes -├── Tests/ # Pester test suite -├── Troubleshooting/ # Documentation -├── Configuration/ # Config templates -└── README.md # Documentation -``` - -**Requirements:** - -- Generate module manifest with proper metadata and versioning -- Create folder structure with sample function templates -- Include comprehensive README with installation instructions -- Generate basic Pester test framework -- Include troubleshooting documentation templates -- Follow semantic versioning and PowerShell Gallery compatibility diff --git a/.github/prompts/create-test.prompt.md b/.github/prompts/create-test.prompt.md deleted file mode 100644 index ca898ee..0000000 --- a/.github/prompts/create-test.prompt.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -agent: 'agent' -description: 'Generate comprehensive tests following modern PowerShell patterns' -tools: ['search/codebase'] ---- - -Create Pester tests for this PowerShell code: - -**Code to Test:** - -```powershell -${selection} -``` - -**Test Configuration:** - -- Test type: ${input:testType:Unit,Integration,Performance,Security:Unit} -- Coverage target: ${input:coverage:80%,90%,95%:90%} -- Environment: ${input:environment:Local,CI/CD,Both:Both} -- Pester version: ${input:pesterVersion:6.2+,5.x:6.2+} - -**Test Requirements:** - -**1. Modern Test Patterns ✅** - -- Use Pester 6.2+ syntax and features. Pester 6 requires Windows PowerShell 5.1 or PowerShell 7.4+; - target 7.6 (LTS) for new work, as 7.4 and 7.5 reach end of support on 10-Nov-2026 -- Prefer the `Should-*` assertions (dash, no space) for new test files; classic - `Should -Be` remains supported for existing suites -- Make every test file self-contained: Pester 6 discovers and runs one file at a time, - so each file imports its own modules and does its own `BeforeDiscovery` setup -- Build `-ForEach` / `-TestCases` data in `BeforeDiscovery`, never `BeforeAll` -- Do not use `Assert-MockCalled`, `Assert-VerifiableMock`, `-Focus`, or - `Set-ItResult -Pending` - all removed in Pester 6 -- Implement proper Arrange-Act-Assert structure -- Include parameterized tests where appropriate -- Use modern mocking techniques (`Should-Invoke` / `Should-NotInvoke`) - -**2. Comprehensive Coverage ✅** - -- Happy path scenarios -- Edge cases and boundary conditions -- Error handling verification (using $_ patterns) -- Parameter validation testing -- Pipeline input and output behaviour (ValueFromPipeline binding, per-item emission, and for a function - that reduces its input to one result, that `$collection | Verb-Noun` gives the same single answer as - `-Parameter $collection`) -- Every usage example in the README and in help, run as written - -**3. Enterprise Test Standards ✅** - -- Correlation ID tracking in tests -- Environment-specific test configurations -- Security validation tests -- Performance assertion tests - -**4. Mock Strategy ✅** - -- External dependencies isolation -- Credential handling tests (using modern patterns) -- Database/API interaction mocking -- File system operation mocking - -**5. Test Organization ✅** - -- Clear Describe/Context/It structure -- Meaningful test names and descriptions -- Proper test data management -- Setup and teardown patterns - -**Generate tests that:** - -- ✅ Validate modern PowerShell patterns (PSCredential::new(), $_ usage) -- ✅ Test error handling appropriately -- ✅ Include security scenario validation -- ✅ Provide clear failure diagnostics -- ✅ Support CI/CD pipeline execution -- ✅ Include performance benchmarks where relevant - -Provide complete test file with proper imports and configuration. diff --git a/.github/prompts/create-workflow.prompt.md b/.github/prompts/create-workflow.prompt.md deleted file mode 100644 index b5aede9..0000000 --- a/.github/prompts/create-workflow.prompt.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -agent: 'agent' -description: 'Generates business workflow automation' -tools: ['search/codebase'] ---- - -Create PowerShell workflow automation for ${workspaceFolderBasename}: - -**Workflow Details:** - -- **Business Process**: ${input:process:Describe the business process to automate} -- **Trigger Type**: ${input:trigger:Scheduled,Event-driven,Manual,API-triggered} -- **Integration Points**: ${input:integrations:Active Directory,Database,Email,REST APIs,File System} -- **Error Handling**: ${input:errorHandling:Email notifications,ServiceNow tickets,Database logging,All} - -**Workflow Components to Generate:** - -1. **Main orchestration function** with comprehensive error handling -2. **Individual process steps** as reusable functions -3. **Configuration management** for environment-specific settings -4. **Logging and monitoring** integration -5. **Rollback and recovery** procedures -6. **Testing framework** for workflow validation - -**Enterprise Requirements:** - -- Include correlation ID tracking throughout workflow -- Implement approval gates for production changes -- Generate audit trails for compliance requirements -- Include performance monitoring and alerting diff --git a/.github/prompts/new-function.prompt.md b/.github/prompts/new-function.prompt.md deleted file mode 100644 index 958d673..0000000 --- a/.github/prompts/new-function.prompt.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -agent: 'agent' -description: 'Creates enterprise-standard PowerShell function with modern best practices' -tools: ['search/codebase'] ---- - -Create a PowerShell function with these specifications: - -**Function Details:** - -- Function name: ${input:functionName:Verb-Noun} -- Purpose: ${input:purpose:Describe what this function accomplishes} -- Parameters needed: ${input:parameters:List the parameters and their types} -- Environment: ${input:environment:Development,Testing,Production:Development} - -**Context:** - -- Current file: ${fileBasename} -- Project: ${workspaceFolderBasename} -- PowerShell version: ${input:psVersion:7.6,5.1+7.6:7.6} - -**Requirements:** - -- Use modern PowerShell patterns (PSCredential::new(), $_ in catch blocks) -- Include proper comment-based help with complete syntax -- Implement appropriate parameter validation (avoid redundant validation) -- Use correlation IDs for enterprise logging -- Apply context-appropriate performance patterns -- Follow approved PowerShell verb usage -- Use descriptive output types instead of [PSCustomObject] - -**Standards Compliance:** - -- Error handling: Use $_ in catch blocks, not $Error[0] -- String operations: Context-appropriate (simple concatenation vs StringBuilder) -- Null handling: Simple null checks where appropriate, exceptions for operations that might fail -- Documentation: Complete comment-based help blocks -- Security: Modern credential handling patterns diff --git a/.github/prompts/optimize-performance.prompt.md b/.github/prompts/optimize-performance.prompt.md deleted file mode 100644 index 811fc94..0000000 --- a/.github/prompts/optimize-performance.prompt.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -agent: 'agent' -description: 'PowerShell performance optimization with specific targets' -tools: ['search/codebase'] ---- - -Analyze and optimize this PowerShell code from ${fileBasename} in the ${workspaceFolderBasename} project: - -**Performance Context:** - -- **Dataset Size**: ${input:datasetSize:Small (<100 items),Medium (100-1000 items),Large (1000+ items)} -- **Performance Target**: ${input:performanceTarget:Execution time,Memory usage,Throughput,All} -- **Current Environment**: ${input:environment:PowerShell 7.6,Windows PowerShell 5.1,Cross-platform} -- **Criticality**: ${input:criticality:Development,Production,Mission-critical} - -**Selected Code:** - -```powershell -${selection} -``` - -**Optimization Analysis:** - -1. **Memory Usage**: Resource disposal, StringBuilder usage, collection handling -2. **Pipeline Efficiency**: Pipeline vs. foreach loops for dataset size: ${input:datasetSize} -3. **String Operations**: Concatenation methods and efficiency -4. **Algorithm Complexity**: Identify O(n²) operations, inefficient filtering and searching, redundant - work, and poor data structure choices -5. **Resource Management**: COM objects, file handles, database connections, network call batching -6. **Parallel Processing**: `ForEach-Object -Parallel` opportunities (PowerShell 7.4+; 7.6 is the - current LTS - 7.0 through 7.3 are retired) - -**Deliverables:** - -- Before/after code examples with performance impact estimates -- Memory usage improvements for ${input:datasetSize} datasets -- Scalability recommendations for ${input:criticality} environments -- Benchmarking code for validation -- Reference to .\Troubleshooting\Performance\ documentation - -Focus on ${input:performanceTarget} optimization with measurable improvements. diff --git a/.github/prompts/performance-analysis.prompt.md b/.github/prompts/performance-analysis.prompt.md deleted file mode 100644 index 3af3196..0000000 --- a/.github/prompts/performance-analysis.prompt.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -agent: 'agent' -description: 'Detailed performance analysis and benchmarking' -tools: ['search/codebase'] ---- - -Perform comprehensive performance analysis of PowerShell code in ${fileBasename}: - -**Analysis Parameters:** - -- **Analysis Scope**: ${input:analysisScope:Single function,Module,Entire script} -- **Performance Metrics**: ${input:metrics:Execution time,Memory usage,CPU utilization,All} -- **Baseline Environment**: ${input:baseline:Development,Production,Benchmarking} -- **Comparison Target**: ${input:target:Current best practice,Industry standard,Previous version} - -**Code Under Analysis:** - -```powershell -${selection} -``` - -**Performance Assessment:** - -1. **Execution Profiling** - - Line-by-line execution time analysis - - Bottleneck identification with specific line numbers - - Algorithm complexity assessment (O-notation) - -2. **Memory Analysis** - - Memory allocation patterns - - Garbage collection impact - - Memory leak detection - - Object lifecycle management - -3. **Resource Utilization** - - CPU usage patterns - - I/O operation efficiency - - Network call optimization - - Database query performance (if applicable) - -4. **Scalability Testing** - - Performance with dataset sizes: 10, 100, 1000, 10000 items - - Concurrent execution capabilities - - Resource exhaustion thresholds - -**Deliverables:** - -- Performance benchmark results with specific metrics -- Optimization recommendations with priority ranking -- Code examples showing improvements with estimated gains -- Test scripts for ongoing performance monitoring -- Integration with .\Troubleshooting\Performance\ documentation - -**Metrics Focus**: Prioritize ${input:metrics} for ${input:baseline} environment against ${input:target} benchmarks. - -Generate actionable performance optimization plan for ${workspaceFolderBasename} project. diff --git a/.github/prompts/scaffold-project.prompt.md b/.github/prompts/scaffold-project.prompt.md deleted file mode 100644 index d1a111f..0000000 --- a/.github/prompts/scaffold-project.prompt.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -agent: 'agent' -description: 'Creates complete project scaffold with CI/CD' -tools: ['search/codebase', 'githubRepo'] ---- - -Generate complete project scaffold for ${input:projectName:PowerShell-Project}: - -**Project Type**: ${input:projectType:PowerShell Module,Script Collection,Enterprise Application} -**CI/CD Platform**: ${input:cicd:GitHub Actions,Azure DevOps,Jenkins,GitLab CI} -**Deployment Target**: ${input:deployment:PowerShell Gallery,Internal Repository,Direct Deployment} - -**Generate Complete Structure:** - -- Project folder organization following enterprise standards -- CI/CD pipeline configuration for ${input:cicd} -- Quality gates and security scanning integration -- Automated testing and deployment workflows -- Documentation templates and troubleshooting guides -- Configuration management setup -- License and governance files - -**Include Enterprise Integrations:** - -- Code signing setup for ${input:deployment} -- Security scanning and compliance validation -- Performance benchmarking and monitoring -- Automated release notes and versioning diff --git a/.github/prompts/security-review.prompt.md b/.github/prompts/security-review.prompt.md deleted file mode 100644 index 2d04afc..0000000 --- a/.github/prompts/security-review.prompt.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -agent: 'agent' -description: 'Security analysis with modern PowerShell patterns' ---- - -Perform comprehensive security analysis on this PowerShell code: - -**Selected Code:** - -```powershell -${selection} -``` - -**Analysis Context:** - -- Compliance framework: ${input:complianceFramework:SOX,GDPR,HIPAA,PCI-DSS,General:General} -- Environment: ${input:environment:Development,Testing,Production:Production} -- File: ${fileBasename} -- Project: ${workspaceFolderBasename} - -**Security Review Areas:** - -1. **Modern Credential Handling** - - Check for [PSCredential]::new() usage vs legacy New-Object - - Validate SecureString implementation - - Identify hardcoded credentials or API keys - -2. **Input Validation** - - Verify appropriate parameter validation (not over-validated) - - Check for SQL injection in dynamic queries - - Validate file path and command injection risks - -3. **Error Handling Security** - - Ensure $_ usage in catch blocks (not $Error manipulation) - - Check for information disclosure in error messages - - Validate proper exception propagation - -4. **Enterprise Security Patterns** - - Audit trail implementation with correlation IDs - - Access control and privilege verification - - Data encryption and protection patterns - -5. **Compliance Alignment** - - Framework-specific requirements validation - - Data handling and retention compliance - - Security logging and monitoring requirements - -Provide specific remediation recommendations with corrected code examples following modern PowerShell best practices. diff --git a/.github/prompts/validate-standards.prompt.md b/.github/prompts/validate-standards.prompt.md deleted file mode 100644 index c5bdab6..0000000 --- a/.github/prompts/validate-standards.prompt.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -agent: 'agent' -description: 'Validates code against PowerShell community standards' ---- - -Validate this PowerShell code against established community best practices and style guidelines: - -**Selected Code:** - -```powershell -${selection} -``` - -**Validation Areas:** - -## 🏗️ Best Practices Compliance - -- **Tool Design**: Verify functions are reusable with parameter input and pipeline output -- **Error Handling**: Check for -ErrorAction Stop usage and proper try/catch blocks -- **Performance**: String concatenation and pipeline efficiency. Flag `+=` only where the declared - target is below 7.5, in which it remains O(n²) - PowerShell 7.5 optimised it -- **Security**: Validate PSCredential usage and input sanitization -- **Modularity**: Assess function design and single responsibility principle - -## 🎨 Style Guide Compliance - -- **Code Layout**: One True Brace Style, 4-space indentation, 115-character lines -- **Naming**: Approved verbs, full command names, PascalCase conventions -- **Function Structure**: CmdletBinding, proper parameter validation, comment-based help -- **Formatting**: Operator spacing, parameter alignment, anti-pattern avoidance - -## 📊 Analysis Output - -Provide specific feedback on: - -1. **Standards Violations**: List specific issues with line numbers -2. **Style Issues**: Formatting and naming problems -3. **Performance Concerns**: Anti-patterns and optimization opportunities -4. **Security Gaps**: Input validation and credential handling issues -5. **Corrected Code**: Show properly formatted version following all standards - -**Focus on actionable recommendations** with before/after code examples that align with PowerShell community standards. diff --git a/powershell-standards/Examples/Basic-Function-Example.ps1 b/powershell-standards/Examples/Basic-Function-Example.ps1 index 000d7c4..2512d0f 100644 --- a/powershell-standards/Examples/Basic-Function-Example.ps1 +++ b/powershell-standards/Examples/Basic-Function-Example.ps1 @@ -1,250 +1,132 @@ -<# -.SYNOPSIS - Example of a basic enterprise-standard PowerShell function - -.DESCRIPTION - This function demonstrates all the key patterns and standards - required for enterprise PowerShell development using our - GitHub Copilot standards. - -.PARAMETER ComputerName - [String[]] (Mandatory: Yes, Pipeline: ByValue, ByPropertyName) - - One or more computer names to query for information. - - VALIDATION: - - Must be valid computer names (NetBIOS or FQDN) - - Pattern: Letters, numbers, hyphens, and dots only - - Length: 1-255 characters - - EXAMPLES: - - "SERVER01" - - "web01.contoso.com" - - @("APP01", "APP02", "DB01") - -.PARAMETER Credential - [PSCredential] (Mandatory: No, Pipeline: No) - - Credential to use for remote connections. If not provided, - uses current user context. - -.PARAMETER IncludeServices - [Switch] (Mandatory: No, Pipeline: No) - - Include running services information in the output. - -.EXAMPLE - PS> Get-BasicServerInfo -ComputerName "SERVER01" - - DESCRIPTION: Basic server information retrieval - OUTPUT: Server information object with OS and hardware details - USE CASE: Daily server health checks - -.EXAMPLE - PS> @("WEB01", "WEB02") | Get-BasicServerInfo -IncludeServices - - DESCRIPTION: Pipeline processing with service information - OUTPUT: Server info objects including running services - USE CASE: Comprehensive server inventory - -.EXAMPLE - PS> Get-BasicServerInfo -ComputerName "PROD-DB01" -Credential $cred | Export-Csv "server-info.csv" - - DESCRIPTION: Secure connection with credential and export - OUTPUT: CSV file with server information - USE CASE: Automated reporting for compliance - -.NOTES - Author: Jeffrey Stuhr - Blog: https://www.techbyjeff.net - LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/ - Version: 1.0.0 - Last Updated: 2024-01-15 - - DEPENDENCIES: - - PowerShell 7.6 (LTS) or Windows PowerShell 5.1 - - WinRM enabled on target computers - - Appropriate permissions on target systems - - PERFORMANCE: - - Execution time: ~10-30 seconds per server - - Memory usage: ~5MB per server - - Network bandwidth: Minimal (WMI queries only) - - TROUBLESHOOTING: - - Connection issues: .\Troubleshooting\Common\Function-Issues.md - - WinRM problems: .\Troubleshooting\Security\WinRM-Setup.md - - Performance: .\Troubleshooting\Performance\Server-Monitoring.md -#> - function Get-BasicServerInfo { - [CmdletBinding(SupportsShouldProcess = $true)] - # Quoted, and named. [OutputType([PSCustomObject])] is the anti-pattern the - # standards call out: it tells a caller nothing about the shape returned. - [OutputType('BasicServerInfo')] + <# + .SYNOPSIS + Gets operating system and hardware information from Windows computers. + + .DESCRIPTION + Opens a CIM session to each computer, reads its operating system and computer system + information, and emits one object for each computer. A computer that cannot be queried is + reported as a non-terminating error and the remaining computers are still processed. Each + session is closed before the next computer is queried. + + .PARAMETER ComputerName + One or more computer names, as NetBIOS names or fully qualified domain names. A name starts + with a letter or a digit and contains only letters, digits, hyphens, and dots. + + .PARAMETER Credential + Credential for the CIM sessions. Without it, the sessions use the identity of the current + user. + + .PARAMETER IncludeServices + Adds the running services of each computer to the RunningServices property. + + .EXAMPLE + Get-BasicServerInfo -ComputerName 'SERVER01' + + Gets operating system and hardware information from SERVER01. + + .EXAMPLE + 'WEB01', 'WEB02' | Get-BasicServerInfo -IncludeServices + + Takes the computer names from the pipeline and adds the running services of each computer. + + .EXAMPLE + Get-BasicServerInfo -ComputerName 'DB01' -Credential (Get-Credential) + + Asks for a credential and uses it to query DB01. + + .INPUTS + System.String. You can pipe computer names, or objects that have a ComputerName property, to + this function. + + .OUTPUTS + Example.ServerInfo. An object with ComputerName, OperatingSystem, Version, Architecture, + LastBootTime, UptimeDays, Manufacturer, Model, Domain, TotalMemoryGB, LogicalProcessors, and + RunningServices properties. RunningServices is empty unless IncludeServices is specified. + #> + [CmdletBinding()] + [OutputType('Example.ServerInfo')] param( - [Parameter(Mandatory = $true, - ValueFromPipeline = $true, - ValueFromPipelineByPropertyName = $true, - HelpMessage = "Enter one or more computer names")] - [ValidateNotNullOrEmpty()] - [ValidatePattern('^[a-zA-Z0-9\-\.]+$')] - [ValidateLength(1, 255)] - [Alias('CN', 'ServerName', 'Name')] + [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)] + [ValidatePattern('^[A-Za-z0-9][A-Za-z0-9.-]{0,254}$')] + [Alias('CN', 'ServerName')] [string[]]$ComputerName, - + [Parameter()] [System.Management.Automation.PSCredential] [System.Management.Automation.Credential()] - $Credential, - + $Credential = [System.Management.Automation.PSCredential]::Empty, + [Parameter()] [switch]$IncludeServices ) - + begin { - # Initialize correlation tracking for enterprise monitoring - $correlationId = [System.Guid]::NewGuid() - $startTime = Get-Date - - Write-Verbose "Starting $($MyInvocation.MyCommand.Name) - CorrelationId: $correlationId" - Write-Verbose "Parameters: ComputerName count = $($ComputerName.Count), IncludeServices = $IncludeServices" - - # Initialize counters for performance tracking - $processedCount = 0 - $successCount = 0 - $failureCount = 0 - - # Prepare credential for CIM sessions if provided - $cimSessionOptions = New-CimSessionOption -Protocol WSMan - $sessionParams = @{ - SessionOption = $cimSessionOptions + $sessionParameters = @{ ErrorAction = 'Stop' } - if ($Credential) { - $sessionParams.Credential = $Credential + if ($Credential -ne [System.Management.Automation.PSCredential]::Empty) { + $sessionParameters['Credential'] = $Credential } } - + process { foreach ($computer in $ComputerName) { - $processedCount++ - $computerStartTime = Get-Date - + $cimSession = $null try { - Write-Verbose "Processing computer: $computer (CorrelationId: $correlationId)" - - if ($PSCmdlet.ShouldProcess($computer, "Retrieve server information")) { - - # Test connectivity first - $connectionTest = Test-Connection -ComputerName $computer -Count 1 -Quiet -ErrorAction SilentlyContinue - if (-not $connectionTest) { - throw "Computer $computer is not reachable via ping" - } - - # Create CIM session for efficient querying - $sessionParams.ComputerName = $computer - $cimSession = New-CimSession @sessionParams - - try { - # Gather basic system information - Write-Verbose "Querying system information for $computer" - $os = Get-CimInstance -CimSession $cimSession -ClassName Win32_OperatingSystem - $computerSystem = Get-CimInstance -CimSession $cimSession -ClassName Win32_ComputerSystem - $processor = Get-CimInstance -CimSession $cimSession -ClassName Win32_Processor | Select-Object -First 1 - - # Calculate uptime - $uptime = (Get-Date) - $os.LastBootUpTime - - # Build result object with raw data for maximum reusability. - # PSTypeName gives the output a name that matches [OutputType]. - $result = [PSCustomObject]@{ - PSTypeName = 'BasicServerInfo' - ComputerName = $computer - OperatingSystem = $os.Caption - Version = $os.Version - ServicePackLevel = $os.ServicePackMajorVersion - Architecture = $os.OSArchitecture - LastBootTime = $os.LastBootUpTime - UptimeDays = [math]::Round($uptime.TotalDays, 2) - TotalMemoryGB = [math]::Round($computerSystem.TotalPhysicalMemory / 1GB, 2) - Manufacturer = $computerSystem.Manufacturer - Model = $computerSystem.Model - ProcessorName = $processor.Name - ProcessorCores = $processor.NumberOfCores - ProcessorLogicalProcessors = $processor.NumberOfLogicalProcessors - Domain = $computerSystem.Domain - Workgroup = $computerSystem.Workgroup - CorrelationId = $correlationId - QueryTime = Get-Date - QueryDurationMs = ((Get-Date) - $computerStartTime).TotalMilliseconds - } - - # Add services information if requested - if ($IncludeServices) { - Write-Verbose "Querying services information for $computer" - $runningServices = Get-CimInstance -CimSession $cimSession -ClassName Win32_Service | - Where-Object State -eq 'Running' | - Select-Object Name, DisplayName, StartMode - - $result | Add-Member -MemberType NoteProperty -Name 'RunningServices' -Value $runningServices - $result | Add-Member -MemberType NoteProperty -Name 'RunningServiceCount' -Value $runningServices.Count - } - - $successCount++ - Write-Verbose "Successfully processed $computer in $([math]::Round($result.QueryDurationMs, 0))ms" - - # Return the result object - $result - - } - finally { - # Clean up CIM session - if ($cimSession) { - Remove-CimSession -CimSession $cimSession -ErrorAction SilentlyContinue - } + Write-Verbose "Querying '$computer'." + $cimSession = New-CimSession -ComputerName $computer @sessionParameters + $queryParameters = @{ + CimSession = $cimSession + ErrorAction = 'Stop' + } + $operatingSystem = Get-CimInstance -ClassName 'Win32_OperatingSystem' @queryParameters + $computerSystem = Get-CimInstance -ClassName 'Win32_ComputerSystem' @queryParameters + + $runningServices = @() + if ($IncludeServices) { + $serviceParameters = @{ + ClassName = 'Win32_Service' + Filter = 'State = "Running"' } + $runningServices = @( + Get-CimInstance @serviceParameters @queryParameters | + Select-Object -Property Name, DisplayName, StartMode + ) } - - } - catch { - $failureCount++ - $errorDetails = @{ + + $uptime = (Get-Date) - $operatingSystem.LastBootUpTime + $serverInfo = [PSCustomObject]@{ + PSTypeName = 'Example.ServerInfo' ComputerName = $computer - CorrelationId = $correlationId - ErrorMessage = $_.Exception.Message - ErrorTime = Get-Date - Function = $MyInvocation.MyCommand.Name + OperatingSystem = $operatingSystem.Caption + Version = $operatingSystem.Version + Architecture = $operatingSystem.OSArchitecture + LastBootTime = $operatingSystem.LastBootUpTime + UptimeDays = [math]::Round($uptime.TotalDays, 2) + Manufacturer = $computerSystem.Manufacturer + Model = $computerSystem.Model + Domain = $computerSystem.Domain + TotalMemoryGB = [math]::Round($computerSystem.TotalPhysicalMemory / 1GB, 2) + LogicalProcessors = $computerSystem.NumberOfLogicalProcessors + RunningServices = $runningServices } - - Write-Error "Failed to process computer '$computer': $($_.Exception.Message) (CorrelationId: $correlationId)" - Write-Verbose "Error details: $($errorDetails | ConvertTo-Json -Compress)" - - # Continue processing other computers instead of terminating + } catch { + $message = "Server information could not be read from '$computer'. $($_.Exception.Message)" + $exception = [System.InvalidOperationException]::new($message, $_.Exception) + $errorRecord = [System.Management.Automation.ErrorRecord]::new( + $exception, 'ServerInfoQueryFailed', $_.CategoryInfo.Category, $computer) + $PSCmdlet.WriteError($errorRecord) continue + } finally { + if ($null -ne $cimSession) { + Remove-CimSession -CimSession $cimSession + } } - } - } - - end { - $endTime = Get-Date - $totalDuration = ($endTime - $startTime).TotalSeconds - - # Performance and summary logging - $summary = @{ - CorrelationId = $correlationId - TotalComputers = $processedCount - SuccessfulQueries = $successCount - FailedQueries = $failureCount - SuccessRate = if ($processedCount -gt 0) { [math]::Round(($successCount / $processedCount) * 100, 1) } else { 0 } - TotalDurationSeconds = [math]::Round($totalDuration, 2) - AverageTimePerServer = if ($successCount -gt 0) { [math]::Round($totalDuration / $successCount, 2) } else { 0 } - } - - Write-Verbose "Completed $($MyInvocation.MyCommand.Name) - Summary: $($summary | ConvertTo-Json -Compress)" - - if ($failureCount -gt 0) { - Write-Warning "Operation completed with $failureCount failures out of $processedCount computers. Check error messages above for details." + + # Emitted outside the try block. An exception thrown by a script block further down the + # pipeline would otherwise be caught above and reported as a failed query. + $serverInfo } } } diff --git a/powershell-standards/Examples/Configuration/DefaultConfiguration.psd1 b/powershell-standards/Examples/Configuration/DefaultConfiguration.psd1 index fc25a84..5d12554 100644 --- a/powershell-standards/Examples/Configuration/DefaultConfiguration.psd1 +++ b/powershell-standards/Examples/Configuration/DefaultConfiguration.psd1 @@ -1,154 +1,24 @@ +# Example of a settings file. Read it with Import-PowerShellDataFile, which returns the hashtable and +# does not run code, so every value in the file is a literal. Secrets do not belong in a settings +# file: read them at run time from a secret store. @{ - # Module Behavior Settings - ModuleSettings = @{ - EnableVerboseLogging = $true - RequireCorrelationIds = $true - EnforceParameterValidation = $true - EnablePerformanceMonitoring = $true - } - - # Environment-Specific Configuration Environments = @{ Development = @{ LogLevel = 'Verbose' TimeoutSeconds = 30 RetryCount = 3 - PerformanceThreshold = 5000 - AuditLevel = 'Full' - SecurityValidation = 'Relaxed' } Testing = @{ - LogLevel = 'Standard' + LogLevel = 'Information' TimeoutSeconds = 20 RetryCount = 2 - PerformanceThreshold = 3000 - AuditLevel = 'Standard' - SecurityValidation = 'Standard' } Production = @{ - LogLevel = 'Minimal' + LogLevel = 'Warning' TimeoutSeconds = 10 RetryCount = 1 - PerformanceThreshold = 1000 - AuditLevel = 'Required' - SecurityValidation = 'Strict' - } - } - - # Security Configuration - Security = @{ - RequireEncryption = $true - AllowBasicAuth = $false # Expert feedback: Basic auth not recommended - RequireSignedCertificates = $true - EnforceCredentialValidation = $true - AuditAllOperations = $true - - # Approved authentication methods - AuthenticationMethods = @('Kerberos', 'Certificate', 'Negotiate') - - # Security scanning patterns - ProhibitedPatterns = @( - 'password\s*[:=]\s*["\x27]\w{3,}["\x27]', - 'api[_-]?key\s*[:=]\s*["\x27]\w{10,}["\x27]', - 'ConvertTo-SecureString.*-AsPlainText.*-Force' - ) - } - - # Performance Optimization Settings - Performance = @{ - # String operation thresholds (expert feedback integration) - StringConcatenationThreshold = 100 # Use StringBuilder above this - # Above this, use direct loop assignment or List[T] - never ArrayList. - # On PowerShell 7.5+, += on object arrays is optimized and this threshold can be relaxed. - ArrayAppendThreshold = 50 - - # Memory management - MaxMemoryUsageMB = 512 - EnableGarbageCollection = $true - - # Pipeline optimization - PreferPipelineOperations = $true - BatchSizeLimit = 1000 - } - - # Compliance Framework Integration - Compliance = @{ - SOX = @{ - RequireAuditTrails = $true - RequireApprovalWorkflow = $true - MandatoryFields = @('CorrelationId', 'UserName', 'Timestamp', 'Operation') - } - - GDPR = @{ - EnableDataMinimization = $true - RequireConsentTracking = $true - AutoDeleteExpiredData = $true - DataRetentionDays = 2555 # 7 years - } - - HIPAA = @{ - RequireEncryption = $true - EnableAccessLogging = $true - RequireRoleBasedAccess = $true - AuditAccessAttempts = $true - } - } - - # Error Handling Configuration - ErrorHandling = @{ - # Expert feedback: Use Write-Error -ErrorAction Stop instead of bare throw - UseWriteErrorForTermination = $true - - # Correlation ID requirements - RequireCorrelationIds = $true - - # Error escalation thresholds - EscalationLevels = @{ - Low = @{ ThresholdCount = 10; EscalationTimeMinutes = 60 } - Medium = @{ ThresholdCount = 5; EscalationTimeMinutes = 30 } - High = @{ ThresholdCount = 2; EscalationTimeMinutes = 15 } - Critical = @{ ThresholdCount = 1; EscalationTimeMinutes = 5 } - } - } - - # Quality Standards Integration - QualityStandards = @{ - # PSScriptAnalyzer settings - EnableStrictMode = $true - RequireApprovedVerbs = $true - MaxComplexityScore = 15 - MinimumTestCoverage = 80 - - # Documentation requirements - RequireCommentBasedHelp = $true - RequireExamples = $true - RequireParameterDocumentation = $true - - # Parameter validation standards - ValidateParametersBeforeDownstreamUsage = $true # Expert feedback Part 2 - TrimStringParametersAutomatically = $true - } - - # Integration Endpoints - Integration = @{ - LoggingService = @{ - Endpoint = 'https://logs.yourorg.com/api/v1/logs' - RequireAuthentication = $true - TimeoutSeconds = 30 - } - - SecurityService = @{ - Endpoint = 'https://security.yourorg.com/api/v1/audit' - RequireAuthentication = $true - TimeoutSeconds = 15 - } - - ComplianceService = @{ - Endpoint = 'https://compliance.yourorg.com/api/v1/events' - RequireAuthentication = $true - TimeoutSeconds = 45 } } -} \ No newline at end of file +} diff --git a/powershell-standards/Examples/Module-Structure-Example/Classes/ExampleClass.ps1 b/powershell-standards/Examples/Module-Structure-Example/Classes/ExampleClass.ps1 index 3a8b2c3..2559657 100644 --- a/powershell-standards/Examples/Module-Structure-Example/Classes/ExampleClass.ps1 +++ b/powershell-standards/Examples/Module-Structure-Example/Classes/ExampleClass.ps1 @@ -1,29 +1,23 @@ +# A class gives the output of Get-ExampleData a type name that [OutputType()], the help, and the +# tests can refer to, and it keeps IsUsable() beside the data that the method reads. class ExampleServiceResult { - <# - Demonstrates a PowerShell class used as a descriptive output type. - - The standards discourage [OutputType([PSCustomObject])] because it tells a - caller nothing about the shape returned. A class names the shape, provides - IntelliSense, and lets behaviour live alongside the data. - #> - [string]$ServiceName [string]$Environment + [ValidateSet('Healthy', 'Degraded', 'Unavailable')] [string]$Status + [datetime]$CheckedAt - [guid]$CorrelationId - ExampleServiceResult([string]$ServiceName, [string]$Environment, [guid]$CorrelationId) { + ExampleServiceResult([string]$ServiceName, [string]$Environment, [string]$Status) { $this.ServiceName = $ServiceName $this.Environment = $Environment - $this.Status = 'Unavailable' + $this.Status = $Status $this.CheckedAt = Get-Date - $this.CorrelationId = $CorrelationId } [bool] IsUsable() { - return $this.Status -in @('Healthy', 'Degraded') + return $this.Status -in 'Healthy', 'Degraded' } [string] ToString() { diff --git a/powershell-standards/Examples/Module-Structure-Example/ModuleExample.psd1 b/powershell-standards/Examples/Module-Structure-Example/ModuleExample.psd1 index da1d07c..9d65bd1 100644 --- a/powershell-standards/Examples/Module-Structure-Example/ModuleExample.psd1 +++ b/powershell-standards/Examples/Module-Structure-Example/ModuleExample.psd1 @@ -1,34 +1,25 @@ @{ - # Module Information - RootModule = 'ModuleExample.psm1' - ModuleVersion = '1.0.0' - GUID = '8f2b1c9d-4e7a-4b3f-9c21-5d6e8a0f7b34' + RootModule = 'ModuleExample.psm1' + ModuleVersion = '1.0.0' + GUID = '8f2b1c9d-4e7a-4b3f-9c21-5d6e8a0f7b34' + Author = 'Example Author' + Description = 'Example module with Public, Private, and Classes folders and an explicit export list.' - # Author Information - Author = 'Jeffrey Stuhr' - CompanyName = 'YourOrg' - Copyright = '(c) 2026 YourOrg. All rights reserved.' - Description = 'Minimal reference module demonstrating the Public/Private/Classes layout and the export boundary described in the PowerShell Copilot Standards.' - - # PowerShell Requirements - # 7.6 is the current LTS. Use '5.1' with @('Desktop','Core') only when Windows - # PowerShell support is an explicit requirement. PowerShellVersion = '7.6' CompatiblePSEditions = @('Core') - # Only the public surface is exported. Connect-ExampleService stays internal, so - # it can change without a breaking release. + # Only Get-ExampleData is exported. The functions in Private stay internal, so they can change + # without breaking a caller of the module. FunctionsToExport = @('Get-ExampleData') - CmdletsToExport = @() + CmdletsToExport = @() VariablesToExport = @() - AliasesToExport = @() + AliasesToExport = @() PrivateData = @{ PSData = @{ - Tags = @('PowerShell', 'Example', 'Standards', 'Reference') - ProjectUri = 'https://github.com/fadwen/ai-powershell-standards' - LicenseUri = 'https://github.com/fadwen/ai-powershell-standards/blob/main/LICENSE' - ReleaseNotes = 'Reference implementation accompanying the PowerShell Copilot Standards.' + Tags = @('PowerShell', 'Example', 'Standards', 'Reference') + ProjectUri = 'https://github.com/fadwen/Powershell-Copilot-Standards' + LicenseUri = 'https://github.com/fadwen/Powershell-Copilot-Standards/blob/main/LICENSE' } } } diff --git a/powershell-standards/Examples/Module-Structure-Example/ModuleExample.psm1 b/powershell-standards/Examples/Module-Structure-Example/ModuleExample.psm1 index 36a7ca4..29cca86 100644 --- a/powershell-standards/Examples/Module-Structure-Example/ModuleExample.psm1 +++ b/powershell-standards/Examples/Module-Structure-Example/ModuleExample.psm1 @@ -1,56 +1,21 @@ -<# - ModuleExample root module. +# Root module. Files load in the order Classes, Private, Public, so that a type exists before a +# function that names it is defined. The manifest's FunctionsToExport decides what is exported. - Loads classes first, then private functions, then public ones - classes must be - available before any function that returns one is defined. Export is controlled - by the manifest's FunctionsToExport rather than a wildcard here, so the public - surface stays explicit. +Set-StrictMode -Version Latest - Quality Standards: https://github.com/fadwen/ai-powershell-standards -#> - -$ErrorActionPreference = 'Stop' - -#region Classes -# Classes load first: Get-ExampleData returns an ExampleServiceResult, so the type -# must exist before that function is dot-sourced. -$ClassFiles = Get-ChildItem -Path "$PSScriptRoot/Classes/*.ps1" -ErrorAction SilentlyContinue -foreach ($ClassFile in $ClassFiles) { - try { - . $ClassFile.FullName - Write-Verbose "Loaded class: $($ClassFile.BaseName)" - } - catch { - throw "Failed to load class $($ClassFile.BaseName): $($_.Exception.Message)" - } -} -#endregion - -#region Private Functions -# Internal helpers - deliberately not exported by the manifest. -$PrivateFunctions = Get-ChildItem -Path "$PSScriptRoot/Private/*.ps1" -ErrorAction SilentlyContinue -foreach ($Function in $PrivateFunctions) { - try { - . $Function.FullName - Write-Verbose "Loaded private function: $($Function.BaseName)" - } - catch { - throw "Failed to load private function $($Function.BaseName): $($_.Exception.Message)" +foreach ($folder in 'Classes', 'Private', 'Public') { + $folderPath = Join-Path -Path $PSScriptRoot -ChildPath $folder + if (-not (Test-Path -LiteralPath $folderPath)) { + continue } -} -#endregion -#region Public Functions -$PublicFunctions = Get-ChildItem -Path "$PSScriptRoot/Public/*.ps1" -ErrorAction SilentlyContinue -foreach ($Function in $PublicFunctions) { - try { - . $Function.FullName - Write-Verbose "Loaded public function: $($Function.BaseName)" - } - catch { - throw "Failed to load public function $($Function.BaseName): $($_.Exception.Message)" + foreach ($file in Get-ChildItem -LiteralPath $folderPath -Filter '*.ps1' -File) { + try { + . $file.FullName + } catch { + # A file that fails to load must fail the import. Without this, the loop would carry + # on and the module would import with commands missing. + throw + } } } -#endregion - -Write-Verbose "ModuleExample loaded: $($PublicFunctions.Count) public, $($PrivateFunctions.Count) private" diff --git a/powershell-standards/Examples/Module-Structure-Example/Private/Connect-ExampleService.ps1 b/powershell-standards/Examples/Module-Structure-Example/Private/Connect-ExampleService.ps1 index c43530d..8204f2e 100644 --- a/powershell-standards/Examples/Module-Structure-Example/Private/Connect-ExampleService.ps1 +++ b/powershell-standards/Examples/Module-Structure-Example/Private/Connect-ExampleService.ps1 @@ -1,58 +1,39 @@ function Connect-ExampleService { <# .SYNOPSIS - Opens a session against the example backing service. + Creates the session that the module uses to query the example service. .DESCRIPTION - Private helper, not exported by the manifest. Demonstrates the boundary the - standards draw between internal and public surface: callers depend on - Get-ExampleData, so this can change shape without a breaking release. + Returns a hashtable that names the environment and the endpoint of its service. There is no + real service behind this module, so no connection is opened. - Returns a session descriptor the public function passes back in. There is no - real service behind it; the sleep stands in for connection latency. + The manifest does not export this function, so its parameters and its output can change + without breaking a caller of the module. .PARAMETER Environment - Target environment for the connection. - - .PARAMETER CorrelationId - Correlation identifier propagated from the caller so a single operation can - be traced across functions. + Environment whose service the session targets. .EXAMPLE - PS> $session = Connect-ExampleService -Environment 'Test' -CorrelationId $id + $session = Connect-ExampleService -Environment 'Test' - DESCRIPTION: Opens a session against the test environment. - OUTPUT: A hashtable describing the session. - USE CASE: Called by Get-ExampleData before querying. + Creates a session for the Test environment and keeps it in a variable. - .NOTES - Author: Jeffrey Stuhr - Blog: https://www.techbyjeff.net - #> + .INPUTS + None. You cannot pipe objects to this function. + .OUTPUTS + System.Collections.Hashtable. A session with the keys Environment and Endpoint. + #> [CmdletBinding()] [OutputType([hashtable])] param( [Parameter(Mandatory)] [ValidateSet('Development', 'Test', 'Production')] - [string]$Environment, - - [Parameter(Mandatory)] - [guid]$CorrelationId + [string]$Environment ) - process { - Write-Verbose "Connecting to $Environment - CorrelationId: $CorrelationId" - - # Stand-in for real connection latency; a genuine implementation would open - # a session here and throw on failure so the caller's catch block runs. - Start-Sleep -Milliseconds 20 - - @{ - Environment = $Environment - CorrelationId = $CorrelationId - ConnectedAt = Get-Date - Endpoint = "https://example-service.yourorg.com/$($Environment.ToLower())" - } + @{ + Environment = $Environment + Endpoint = "https://service.example.com/$($Environment.ToLowerInvariant())" } } diff --git a/powershell-standards/Examples/Module-Structure-Example/Private/Get-ExampleServiceStatus.ps1 b/powershell-standards/Examples/Module-Structure-Example/Private/Get-ExampleServiceStatus.ps1 index b39b48a..b7988e2 100644 --- a/powershell-standards/Examples/Module-Structure-Example/Private/Get-ExampleServiceStatus.ps1 +++ b/powershell-standards/Examples/Module-Structure-Example/Private/Get-ExampleServiceStatus.ps1 @@ -1,37 +1,33 @@ function Get-ExampleServiceStatus { <# .SYNOPSIS - Returns the status of a single service. + Gets the status of one service. .DESCRIPTION - Private helper representing the one call in Get-ExampleData that can fail. + Looks the service name up in a fixed table that stands in for a real service, and returns + the status found there. A name that is not in the table is a terminating error with the + error ID ServiceNotFound. - It exists so the caller's per-item catch block is reachable. Without a - fallible call inside the loop, error handling in an example is decorative: - it looks like resilience but nothing can exercise it, and no test can prove - it works. - - There is no real service. Status is derived from the environment so a batch - returns a non-uniform result set. + Get-ExampleData calls this function once for each service name. It reports a failure as a + non-terminating error, so that the remaining names are still processed. .PARAMETER ServiceName - Service to query. + Name of the service to query. The names in the table are Billing, Identity, and Reporting. .PARAMETER Session - Session descriptor from Connect-ExampleService. + Session that Connect-ExampleService returned. .EXAMPLE - PS> Get-ExampleServiceStatus -ServiceName 'Billing' -Session $session + Get-ExampleServiceStatus -ServiceName 'Billing' -Session (Connect-ExampleService -Environment 'Test') - DESCRIPTION: Queries one service over an open session. - OUTPUT: One of Healthy, Degraded, Unavailable. - USE CASE: Called per item by Get-ExampleData. + Gets the status of the Billing service in the Test environment. - .NOTES - Author: Jeffrey Stuhr - Blog: https://www.techbyjeff.net - #> + .INPUTS + None. You cannot pipe objects to this function. + .OUTPUTS + System.String. One of Healthy, Degraded, or Unavailable. + #> [CmdletBinding()] [OutputType([string])] param( @@ -42,9 +38,24 @@ function Get-ExampleServiceStatus { [hashtable]$Session ) - process { - Write-Verbose "Querying $ServiceName via $($Session.Endpoint)" + # There is no real service. This table stands in for one, so that a batch returns different + # statuses and an unknown name gives the caller a real failure to handle. + $statusByService = @{ + Billing = 'Healthy' + Identity = 'Degraded' + Reporting = 'Unavailable' + } + + Write-Verbose "Querying '$ServiceName' at $($Session['Endpoint'])." - if ($Session.Environment -eq 'Production') { 'Degraded' } else { 'Healthy' } + if (-not $statusByService.ContainsKey($ServiceName)) { + $message = "Service '$ServiceName' was not found in the $($Session['Environment']) environment." + $exception = [System.Management.Automation.ItemNotFoundException]::new($message) + $category = [System.Management.Automation.ErrorCategory]::ObjectNotFound + $errorRecord = [System.Management.Automation.ErrorRecord]::new( + $exception, 'ServiceNotFound', $category, $ServiceName) + $PSCmdlet.ThrowTerminatingError($errorRecord) } + + $statusByService[$ServiceName] } diff --git a/powershell-standards/Examples/Module-Structure-Example/Public/Get-ExampleData.ps1 b/powershell-standards/Examples/Module-Structure-Example/Public/Get-ExampleData.ps1 index ac602a0..0d6ad9b 100644 --- a/powershell-standards/Examples/Module-Structure-Example/Public/Get-ExampleData.ps1 +++ b/powershell-standards/Examples/Module-Structure-Example/Public/Get-ExampleData.ps1 @@ -1,55 +1,35 @@ function Get-ExampleData { - # The full help for this command lives in docs/ModuleExample/Get-ExampleData.md and - # ships compiled as en-US/ModuleExample-Help.xml. See - # .github/instructions/platyps.instructions.md - <# .EXTERNALHELP ModuleExample-Help.xml .SYNOPSIS - Retrieves service status for one or more services. + Gets the status of one or more services. #> - [CmdletBinding()] [OutputType('ExampleServiceResult')] param( [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)] [string[]]$ServiceName, - [Parameter()] [ValidateSet('Development', 'Test', 'Production')] - [string]$Environment = 'Development', - - [Parameter()] - [guid]$CorrelationId = [guid]::NewGuid() + [string]$Environment = 'Development' ) begin { - Write-Verbose "Starting $($MyInvocation.MyCommand.Name) - CorrelationId: $CorrelationId" - $session = Connect-ExampleService -Environment $Environment -CorrelationId $CorrelationId - $failureCount = 0 + $session = Connect-ExampleService -Environment $Environment } process { foreach ($name in $ServiceName) { try { - $result = [ExampleServiceResult]::new($name, $Environment, $CorrelationId) - - # The one fallible call in the loop. Keeping it in a helper is what - # makes the catch below reachable - and therefore testable. - $result.Status = Get-ExampleServiceStatus -ServiceName $name -Session $session - - $result - } - catch { - # $_ in the catch block, per the standards - not $Error[0] - $failureCount++ - Write-Error "Failed to query '$name': $($_.Exception.Message) (CorrelationId: $CorrelationId)" + $status = Get-ExampleServiceStatus -ServiceName $name -Session $session -ErrorAction Stop + } catch { + # One service that cannot be queried must not end the batch. Passing the original + # error on as non-terminating lets the caller decide that with -ErrorAction. + $PSCmdlet.WriteError($_) continue } - } - } - end { - Write-Verbose "Completed with $failureCount failure(s) - CorrelationId: $CorrelationId" + [ExampleServiceResult]::new($name, $Environment, $status) + } } } diff --git a/powershell-standards/Examples/Module-Structure-Example/README.md b/powershell-standards/Examples/Module-Structure-Example/README.md index dbe7a87..383acb5 100644 --- a/powershell-standards/Examples/Module-Structure-Example/README.md +++ b/powershell-standards/Examples/Module-Structure-Example/README.md @@ -1,123 +1,121 @@ -# Module Structure Example +# ModuleExample -A minimal but working module showing the layout the standards expect, and - more importantly - the -export boundary that layout exists to create. +A small working module that shows how the PowerShell standards in this repository lay a module out. +It is an example to read and to copy from. There is no real service behind it: the statuses it +returns come from a fixed table that knows the services Billing, Identity, and Reporting. -Small enough to read in one sitting. For a fuller starting point to copy, use -[Templates/Powershell-Module](https://github.com/fadwen/ai-powershell-standards/tree/main/Templates/Powershell-Module). +## Requirements -## Layout +- PowerShell 7.6 or later, Core edition. The module calls no platform-specific commands. +- No other module is needed to use it. +- Pester 6.2.0 or later, to run the tests. +- Microsoft.PowerShell.PlatyPS 1.0.3 or later, to rebuild the help. -```text -Module-Structure-Example/ -├── ModuleExample.psd1 # Manifest. Declares the public surface explicitly -├── ModuleExample.psm1 # Loader. Classes, then private, then public -├── Classes/ -│ └── ExampleClass.ps1 # ExampleServiceResult - a named output type -├── Private/ -│ └── Connect-ExampleService.ps1 # Internal, never exported -├── Public/ -│ └── Get-ExampleData.ps1 # The only exported function -├── docs/ # PlatyPS Markdown - the help source you edit -│ └── ModuleExample/ -│ ├── ModuleExample.md # Module page -│ └── Get-ExampleData.md # Command help, canonical -└── en-US/ - ├── ModuleExample-Help.xml # Compiled MAML - what Get-Help reads - └── about_ModuleExample.help.txt # Hand-written; PlatyPS never touches it -``` +## Installation -## Why the folders exist +The module is not published. Import it from this folder: -**Load order is not arbitrary.** `ModuleExample.psm1` loads `Classes/` first, because -`Get-ExampleData` returns an `ExampleServiceResult` and the type must exist before the function -referencing it is defined. Private functions load next, so public functions can call them. - -**The manifest controls export, not the loader.** `FunctionsToExport = @('Get-ExampleData')` names -the public surface. `Connect-ExampleService` is dot-sourced and callable inside the module, but is -never exported - so its signature can change without a breaking release. A wildcard export would -remove that freedom and slow module autoloading. +```powershell +Import-Module -Name ./ModuleExample.psd1 -Force +``` -**A class replaces `[PSCustomObject]`.** `[OutputType('ExampleServiceResult')]` tells a caller what -they receive and gives them IntelliSense. The standards discourage `[OutputType([PSCustomObject])]` -because it communicates nothing. +## Usage -**Help is generated, not hand-written.** `Get-ExampleData.ps1` keeps only `.EXTERNALHELP` and a -one-line `.SYNOPSIS`; everything a user sees lives in `docs/ModuleExample/Get-ExampleData.md` and -compiles to `en-US/ModuleExample-Help.xml`. Import the module and run -`Get-Help Get-ExampleData -Full` to see the compiled help served. +```powershell +Get-ExampleData -ServiceName 'Billing' +``` -Rebuild after editing the Markdown: +Gets the status of the Billing service in the Development environment. The result is an +`ExampleServiceResult` object with `ServiceName`, `Environment`, `Status`, and `CheckedAt` properties. ```powershell -Import-Module Microsoft.PowerShell.PlatyPS +'Billing', 'Identity', 'Reporting' | Get-ExampleData -Environment 'Test' +``` -Measure-PlatyPSMarkdown -Path ./docs/ModuleExample/*.md | - Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - Export-MamlCommandHelp -OutputFolder ./maml -Force +Takes the service names from the pipeline and queries the Test environment. -Copy-Item ./maml/ModuleExample/ModuleExample-Help.xml ./en-US/ -Force +```powershell +Get-ExampleData -ServiceName 'Billing', 'Missing', 'Reporting' ``` -**`RELATED LINKS` uses two forms, and the choice is not stylistic.** `Get-Help` rejects a relative -path outright — it throws `The specified URI ... is not valid` and returns nothing — so a `.LINK` -value is either a bare topic name or an absolute URL: +Returns the results for Billing and Reporting, and writes a non-terminating error for Missing. Add +`-ErrorAction Stop` to end the command at the first error instead. -```markdown -- [about_ModuleExample]() <- bare topic: a command or about_ topic -- [Module structure standards](https://...) <- absolute URL: anything outside the module +Run `Get-Help Get-ExampleData -Full` for every parameter, and `Get-Help about_ModuleExample` for the +behaviour that the examples above rely on. + +## Layout + +```text +Module-Structure-Example/ + ModuleExample.psd1 manifest; names the one exported function + ModuleExample.psm1 root module; loads Classes, Private, Public in that order + Classes/ + ExampleClass.ps1 the ExampleServiceResult class + Private/ + Connect-ExampleService.ps1 not exported + Get-ExampleServiceStatus.ps1 not exported + Public/ + Get-ExampleData.ps1 the exported function + Tests/ + ModuleExample.Tests.ps1 + docs/ + ModuleExample/ + Get-ExampleData.md source of the help for Get-ExampleData + ModuleExample.md module page + en-US/ + ModuleExample-Help.xml compiled from docs; this is what Get-Help reads + about_ModuleExample.help.txt written by hand ``` -The empty parentheses are the PlatyPS form for a cross-reference `Get-Help` can resolve itself, and -they render as a plain name rather than a URL. Use them for sibling commands and about topics. -Absolute URLs are for documentation that lives outside the installed module — someone who installed -from the Gallery has no repository checkout, so a relative path to a repo file would be unusable -even if `Get-Help` accepted it. That is why the three standards links here are absolute rather than -relative: it is the correct form for their target, not a workaround. - -**An about topic covers what no single command owns.** `about_ModuleExample.help.txt` documents the -correlation-ID convention, the environment parameter, and partial-failure behaviour — concepts that -span commands. It is plain text, hand-written, and PlatyPS neither generates nor rewrites it. Run -`Get-Help about_ModuleExample` after importing. - -`.EXTERNALHELP` sits **inside** the `<# #>` block deliberately. As a bare `#` comment preceded by -ordinary prose it stops being recognized, and `Get-Help` silently falls back to the stub synopsis -instead of the compiled help. See -[platyps.instructions.md](../../../.github/instructions/platyps.instructions.md). - -## Patterns demonstrated - -| Pattern | Where | -| --- | --- | -| Approved verb, descriptive `[OutputType]` | `Public/Get-ExampleData.ps1` | -| Pipeline input via `ValueFromPipeline` | `Public/Get-ExampleData.ps1` | -| Correlation ID generated once, passed through | All three files | -| `$_` in `catch`, not `$Error[0]` | `Public/Get-ExampleData.ps1` | -| Per-item failure that does not abort the batch | `Public/Get-ExampleData.ps1` | -| Class with validation and behaviour | `Classes/ExampleClass.ps1` | -| A fallible call, so the catch is reachable | `Private/Get-ExampleServiceStatus.ps1` | +## What the example shows + +| Rule | File | What to look at | +| --- | --- | --- | +| MOD-02 | `ModuleExample.psd1` | `FunctionsToExport` names the one public function. The two functions in `Private` are loaded but not exported. | +| MOD-05 | `ModuleExample.psm1` | Strict mode, then `Classes`, `Private`, and `Public`. A file that fails to load fails the import. | +| FUN-10 | `Public/Get-ExampleData.ps1` | `[OutputType('ExampleServiceResult')]` names the class as a string. | +| FUN-21 | `Public/Get-ExampleData.ps1` | `ServiceName` is an array that the `process` block loops over, so the pipeline and an array argument behave the same way. | +| ERR-10 | `Private/Get-ExampleServiceStatus.ps1` | An unknown service becomes an `ErrorRecord` with the ID `ServiceNotFound`, passed to `$PSCmdlet.ThrowTerminatingError()`. | +| ERR-13 | `Public/Get-ExampleData.ps1` | The `catch` block passes that error to `$PSCmdlet.WriteError()` and continues with the next name. | +| DOC-09 | `Public/Get-ExampleData.ps1` | The exported function carries `.EXTERNALHELP` and a one-line synopsis. The private functions keep full comment-based help. | +| MOD-07 | `Tests/ModuleExample.Tests.ps1` | The private functions and the class are tested inside `InModuleScope`. | +| TST-17 | `Tests/ModuleExample.Tests.ps1` | The partial-failure tests merge the error stream and count the error records. | +| TST-20 | `Tests/ModuleExample.Tests.ps1` | The only mock is `Get-Date`, the clock. | + +The rules are in +[powershell-modules](../../../.github/instructions/powershell-modules.instructions.md), +[powershell-functions](../../../.github/instructions/powershell-functions.instructions.md), +[powershell-error-handling](../../../.github/instructions/powershell-error-handling.instructions.md), +[powershell-help](../../../.github/instructions/powershell-help.instructions.md), and +[powershell-pester](../../../.github/instructions/powershell-pester.instructions.md). ## Tests -[Tests/ModuleExample.Tests.ps1](./Tests/ModuleExample.Tests.ps1) covers the module contract, the -class, both private helpers via `InModuleScope`, and the per-item failure path. +Run the tests from this folder: + +```powershell +Invoke-Pester -Path ./Tests +``` -`Get-ExampleServiceStatus` exists so that failure path is real. Without a fallible call inside the -loop, a `catch` block in an example is decorative - it looks like resilience, but nothing can -exercise it and no test can prove it works. +## Help -## Trying it +The help for `Get-ExampleData` is written in `docs/ModuleExample/Get-ExampleData.md`. After editing +it, compile it again from this folder: ```powershell -Import-Module ./ModuleExample.psd1 -Force - -Get-ExampleData -ServiceName 'Billing' -'Billing', 'Identity' | Get-ExampleData -Environment Test -Verbose +Measure-PlatyPSMarkdown -Path ./docs/ModuleExample/*.md | + Where-Object Filetype -Match 'CommandHelp' | + Import-MarkdownCommandHelp -Path { $_.FilePath } | + Export-MamlCommandHelp -OutputFolder ./maml -Force -# The private helper is deliberately not available -Get-Command Connect-ExampleService -ErrorAction SilentlyContinue # returns nothing +Copy-Item -LiteralPath ./maml/ModuleExample/ModuleExample-Help.xml -Destination ./en-US -Force ``` -There is no real service behind this module. `Connect-ExampleService` sleeps briefly to stand in for -connection latency, and status is derived from the environment so the result set is not uniform. +The `maml` folder is a build intermediate, and the repository's `.gitignore` excludes it. The rules +for the Markdown are in +[powershell-platyps](../../../.github/instructions/powershell-platyps.instructions.md). + +## License + +MIT. See [LICENSE](../../../LICENSE). diff --git a/powershell-standards/Examples/Module-Structure-Example/Tests/ModuleExample.Tests.ps1 b/powershell-standards/Examples/Module-Structure-Example/Tests/ModuleExample.Tests.ps1 index c3c32e0..80034f3 100644 --- a/powershell-standards/Examples/Module-Structure-Example/Tests/ModuleExample.Tests.ps1 +++ b/powershell-standards/Examples/Module-Structure-Example/Tests/ModuleExample.Tests.ps1 @@ -1,230 +1,239 @@ -#Requires -Module Pester +#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } BeforeAll { - # The module contract test is the one file that imports with -Force: it asserts - # what a freshly imported module looks like. Other files import only when the - # module is not already loaded, and no file removes it afterwards. - $script:ManifestPath = Join-Path $PSScriptRoot '..' 'ModuleExample.psd1' | Resolve-Path - Import-Module $script:ManifestPath -Force + # This file holds the module's contract tests, so it is the one file that imports with -Force: + # it asserts what a newly imported module looks like. No file removes the module afterwards. + $moduleRoot = Split-Path -Path $PSScriptRoot -Parent + Import-Module -Name (Join-Path -Path $moduleRoot -ChildPath 'ModuleExample.psd1') -Force } -Describe 'ModuleExample' -Tag 'Unit', 'Example' { +Describe 'ModuleExample' -Tag 'Unit' { + Context 'The export list' { + It 'Exports Get-ExampleData and nothing else' { + $commands = @(Get-Command -Module ModuleExample) - Context 'Module contract' { - - It 'Has a valid manifest' { - $manifest = Test-ModuleManifest $script:ManifestPath - $manifest.Name | Should-Be 'ModuleExample' - $manifest.PowerShellVersion | Should-Be ([version]'7.6') + $commands | Should-BeCollection -Count 1 + $commands[0].Name | Should-Be 'Get-ExampleData' } - It 'Exports only the public function' { - (Get-Command -Module ModuleExample).Name | Should-BeCollection @('Get-ExampleData') - } + It 'Keeps <CommandName> private' -ForEach @( + @{ CommandName = 'Connect-ExampleService' } + @{ CommandName = 'Get-ExampleServiceStatus' } + ) { + $module = Get-Module -Name ModuleExample - It 'Keeps the private helper internal' { - # The point of the Public/Private split: the manifest does not export it, - # so it cannot be called from outside the module. - Get-Command Connect-ExampleService -ErrorAction SilentlyContinue | Should-BeNull + $module.ExportedCommands.ContainsKey($CommandName) | Should-BeFalse + InModuleScope ModuleExample -Parameters @{ CommandName = $CommandName } { + (Get-Command -Name $CommandName).CommandType | Should-Be 'Function' + } } - It 'Declares a descriptive output type rather than PSCustomObject' { - (Get-Command Get-ExampleData).OutputType.Name | Should-ContainCollection 'ExampleServiceResult' + It 'Declares ExampleServiceResult as the output type of Get-ExampleData' { + $outputTypes = @((Get-Command -Name Get-ExampleData).OutputType) + + $outputTypes | Should-BeCollection -Count 1 + $outputTypes[0].Name | Should-Be 'ExampleServiceResult' } } - Context 'Get-ExampleData' { + Context 'The root module' { + It 'Fails the import when a function file does not load' { + $brokenRoot = Join-Path -Path $TestDrive -ChildPath 'BrokenModule' + $publicPath = Join-Path -Path $brokenRoot -ChildPath 'Public' + $null = New-Item -Path $publicPath -ItemType Directory -Force + $sourcePath = Join-Path -Path $moduleRoot -ChildPath 'ModuleExample.psm1' + $rootModulePath = Join-Path -Path $brokenRoot -ChildPath 'BrokenModule.psm1' + Copy-Item -LiteralPath $sourcePath -Destination $rootModulePath + $brokenFilePath = Join-Path -Path $publicPath -ChildPath 'Get-Broken.ps1' + Set-Content -LiteralPath $brokenFilePath -Value 'function Get-Broken {' -Encoding ascii + $expectedErrorId = 'MissingEndCurlyBrace,Microsoft.PowerShell.Commands.ImportModuleCommand' + + { Import-Module -Name $rootModulePath -Force } | + Should-Throw -FullyQualifiedErrorId $expectedErrorId + Get-Module -Name BrokenModule | Should-BeNull + } + } +} - It 'Returns one result for one service' { - $result = Get-ExampleData -ServiceName 'Billing' +Describe 'Get-ExampleData' -Tag 'Unit' { + Context 'When the services exist' { + It 'Returns the status <Expected> for <ServiceName>' -ForEach @( + @{ ServiceName = 'Billing'; Expected = 'Healthy' } + @{ ServiceName = 'Identity'; Expected = 'Degraded' } + @{ ServiceName = 'Reporting'; Expected = 'Unavailable' } + ) { + $result = Get-ExampleData -ServiceName $ServiceName - $result | Should-NotBeNull - $result.ServiceName | Should-Be 'Billing' - $result.Environment | Should-Be 'Development' + $result | Should-HaveType 'ExampleServiceResult' + $result.ServiceName | Should-Be $ServiceName + $result.Status | Should-Be $Expected } - It 'Returns the class type the function declares' { + It 'Queries the Development environment by default' { $result = Get-ExampleData -ServiceName 'Billing' - $result.GetType().Name | Should-Be 'ExampleServiceResult' - } - - It 'Accepts pipeline input and emits one result per service' { - $results = 'Billing', 'Identity', 'Reporting' | Get-ExampleData - $results | Should-BeCollection -Count 3 - $results.ServiceName | Should-BeCollection @('Billing', 'Identity', 'Reporting') - } - - It 'Accepts an array parameter as well as the pipeline' { - (Get-ExampleData -ServiceName @('Billing', 'Identity')) | Should-BeCollection -Count 2 + $result.Environment | Should-Be 'Development' } - It 'Reports Healthy for non-production environments: <Environment>' -TestCases @( - @{ Environment = 'Development' } + It 'Records the environment <Environment> on the result' -ForEach @( @{ Environment = 'Test' } + @{ Environment = 'Production' } ) { - param($Environment) - (Get-ExampleData -ServiceName 'Billing' -Environment $Environment).Status | Should-Be 'Healthy' - } + $result = Get-ExampleData -ServiceName 'Billing' -Environment $Environment - It 'Reports Degraded for Production' { - (Get-ExampleData -ServiceName 'Billing' -Environment 'Production').Status | Should-Be 'Degraded' + $result.Environment | Should-Be $Environment } - It 'Rejects an environment outside the allowed set' { - { Get-ExampleData -ServiceName 'Billing' -Environment 'Staging' } | - Should-Throw -ExceptionMessage '*ValidateSet*' - } + It 'Emits one result for each name received from the pipeline, in order' { + $result = @('Reporting', 'Billing', 'Identity' | Get-ExampleData) - It 'Requires ServiceName' { - { Get-ExampleData -ServiceName '' } | Should-Throw + $result | Should-BeCollection -Count 3 + $result[0].ServiceName | Should-Be 'Reporting' + $result[1].ServiceName | Should-Be 'Billing' + $result[2].ServiceName | Should-Be 'Identity' } - It 'Generates a correlation id when none is supplied' { - $result = Get-ExampleData -ServiceName 'Billing' + It 'Emits one result for each name in an array argument, in order' { + $result = @(Get-ExampleData -ServiceName 'Identity', 'Billing') - $result.CorrelationId | Should-NotBe ([guid]::Empty) - $result.CorrelationId.ToString() | - Should-MatchString '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' + $result | Should-BeCollection -Count 2 + $result[0].ServiceName | Should-Be 'Identity' + $result[1].ServiceName | Should-Be 'Billing' } - It 'Uses the supplied correlation id for every service in the batch' { - $id = [guid]::NewGuid() - $results = 'Billing', 'Identity' | Get-ExampleData -CorrelationId $id + It 'Takes the name from the ServiceName property of a piped object' { + $result = @([PSCustomObject]@{ ServiceName = 'Identity' } | Get-ExampleData) - # One id per operation, not per item - that is what makes a batch traceable - $results | Should-All { $_.CorrelationId -eq $id } + $result | Should-BeCollection -Count 1 + $result[0].ServiceName | Should-Be 'Identity' } - It 'Stamps CheckedAt on each result' { - $before = Get-Date + It 'Records the time of the check on the result' { + $checkedAt = [datetime]::new(2001, 2, 3, 4, 5, 6) + Mock -CommandName Get-Date -ModuleName ModuleExample -MockWith { $checkedAt } + $result = Get-ExampleData -ServiceName 'Billing' - $result.CheckedAt | Should-HaveType ([datetime]) - $result.CheckedAt | Should-BeGreaterThanOrEqual $before.AddSeconds(-5) + $result.CheckedAt | Should-Be $checkedAt + Should-Invoke -CommandName Get-Date -ModuleName ModuleExample -Times 1 -Exactly } } - Context 'Per-item failure handling' { - - It 'Continues the batch when one service fails' { - InModuleScope ModuleExample { - Mock Get-ExampleServiceStatus { - if ($ServiceName -eq 'Broken') { throw 'service unreachable' } - 'Healthy' - } + Context 'When a service cannot be queried' { + # A module function reads $ErrorActionPreference from the global scope, which a CI runner + # sets to Stop. Each call below passes -ErrorAction Continue, so the outcome does not depend + # on where the tests run. + It 'Writes one non-terminating error and still returns the other services' { + $serviceNames = 'Billing', 'Missing', 'Reporting' + $output = Get-ExampleData -ServiceName $serviceNames -ErrorAction Continue 2>&1 + $errors = @($output | Where-Object { $_ -is [System.Management.Automation.ErrorRecord] }) + $results = @($output | Where-Object { $_ -isnot [System.Management.Automation.ErrorRecord] }) - $results = 'Billing', 'Broken', 'Identity' | - Get-ExampleData -ErrorAction SilentlyContinue - - # The failure must not abort the remaining items - $results | Should-BeCollection -Count 2 - $results.ServiceName | Should-BeCollection @('Billing', 'Identity') - } + $errors | Should-BeCollection -Count 1 + $errors[0].FullyQualifiedErrorId | Should-Be 'ServiceNotFound,Get-ExampleData' + $errors[0].TargetObject | Should-Be 'Missing' + $results | Should-BeCollection -Count 2 + $results[0].ServiceName | Should-Be 'Billing' + $results[1].ServiceName | Should-Be 'Reporting' } - It 'Reports the failing service by name and includes the correlation id' { - InModuleScope ModuleExample { - Mock Get-ExampleServiceStatus { throw 'service unreachable' } - $id = [guid]::NewGuid() - - Get-ExampleData -ServiceName 'Broken' -CorrelationId $id ` - -ErrorAction SilentlyContinue -ErrorVariable err - $null = $err + It 'Writes one error for each service when every service fails' { + $output = 'Missing', 'Absent' | Get-ExampleData -ErrorAction Continue 2>&1 + $errors = @($output | Where-Object { $_ -is [System.Management.Automation.ErrorRecord] }) - "$err" | Should-MatchString 'Broken' - "$err" | Should-MatchString ([regex]::Escape($id.ToString())) - } + $output | Should-BeCollection -Count 2 + $errors | Should-BeCollection -Count 2 + $errors[0].TargetObject | Should-Be 'Missing' + $errors[1].TargetObject | Should-Be 'Absent' } - It 'Emits nothing when every service fails' { - InModuleScope ModuleExample { - Mock Get-ExampleServiceStatus { throw 'service unreachable' } - - $results = 'A', 'B' | Get-ExampleData -ErrorAction SilentlyContinue - $results | Should-BeFalsy - } + It 'Throws when the caller passes -ErrorAction Stop' { + { Get-ExampleData -ServiceName 'Missing', 'Billing' -ErrorAction Stop } | + Should-Throw -FullyQualifiedErrorId 'ServiceNotFound,Get-ExampleData' } } - Context 'Module loader' { + Context 'When an argument is not valid' { + It 'Rejects an environment that is not in the allowed set' { + { Get-ExampleData -ServiceName 'Billing' -Environment 'Staging' } | + Should-Throw -FullyQualifiedErrorId 'ParameterArgumentValidationError,Get-ExampleData' + } - It 'Fails loudly when a source file cannot be dot-sourced' { - # The loader throws rather than warning: a module that half-loads is - # worse than one that refuses to. - # Built under $TestDrive so Pester disposes of it - see test-data-guide.md - $broken = Join-Path $TestDrive "mse-$([guid]::NewGuid().ToString('N'))" - foreach ($folder in 'Public', 'Private', 'Classes') { - New-Item -Path (Join-Path $broken $folder) -ItemType Directory -Force | Out-Null - } - Copy-Item (Join-Path $PSScriptRoot '..' 'ModuleExample.psm1') $broken - Set-Content -Path (Join-Path $broken 'Public\Broken.ps1') -Value 'function Get-Broken { this is not powershell {' + It 'Rejects an empty service name' { + $expectedErrorId = 'ParameterArgumentValidationErrorEmptyStringNotAllowed,Get-ExampleData' - { Import-Module (Join-Path $broken 'ModuleExample.psm1') -Force -ErrorAction Stop } | - Should-Throw -ExceptionMessage '*Failed to load public function*' + { Get-ExampleData -ServiceName '' } | Should-Throw -FullyQualifiedErrorId $expectedErrorId } } +} - Context 'ExampleServiceResult class' { +Describe 'ExampleServiceResult' -Tag 'Unit' { + It 'Reports the status <Status> as usable: <Expected>' -ForEach @( + @{ Status = 'Healthy'; Expected = $true } + @{ Status = 'Degraded'; Expected = $true } + @{ Status = 'Unavailable'; Expected = $false } + ) { + InModuleScope ModuleExample -Parameters @{ Status = $Status; Expected = $Expected } { + $result = [ExampleServiceResult]::new('Billing', 'Test', $Status) - It 'Initialises to Unavailable until a status is set' { - InModuleScope ModuleExample { - $r = [ExampleServiceResult]::new('Billing', 'Test', [guid]::NewGuid()) - $r.Status | Should-Be 'Unavailable' - } + $result.IsUsable() | Should-Be $Expected } + } - It 'Treats Healthy and Degraded as usable, Unavailable as not' { - InModuleScope ModuleExample { - $r = [ExampleServiceResult]::new('Billing', 'Test', [guid]::NewGuid()) + It 'Converts to a string that names the service, the environment, and the status' { + InModuleScope ModuleExample { + $result = [ExampleServiceResult]::new('Billing', 'Test', 'Healthy') - $r.Status = 'Healthy'; $r.IsUsable() | Should-BeTrue - $r.Status = 'Degraded'; $r.IsUsable() | Should-BeTrue - $r.Status = 'Unavailable'; $r.IsUsable() | Should-BeFalse - } + $result.ToString() | Should-Be 'Billing [Test]: Healthy' } + } - It 'Rejects a status outside the allowed set' { - InModuleScope ModuleExample { - $r = [ExampleServiceResult]::new('Billing', 'Test', [guid]::NewGuid()) - { $r.Status = 'Exploded' } | Should-Throw - } + It 'Rejects a status that is not in the allowed set' { + InModuleScope ModuleExample { + { [ExampleServiceResult]::new('Billing', 'Test', 'Exploded') } | + Should-Throw -ExceptionType ([System.Management.Automation.SetValueInvocationException]) } + } +} - It 'Renders a readable string' { - InModuleScope ModuleExample { - $r = [ExampleServiceResult]::new('Billing', 'Test', [guid]::NewGuid()) - $r.Status = 'Healthy' - $r.ToString() | Should-Be 'Billing [Test]: Healthy' - } +Describe 'Connect-ExampleService' -Tag 'Unit' { + It 'Returns a session for the <Environment> environment' -ForEach @( + @{ Environment = 'Development'; Endpoint = 'https://service.example.com/development' } + @{ Environment = 'Test'; Endpoint = 'https://service.example.com/test' } + @{ Environment = 'Production'; Endpoint = 'https://service.example.com/production' } + ) { + InModuleScope ModuleExample -Parameters @{ Environment = $Environment; Endpoint = $Endpoint } { + $session = Connect-ExampleService -Environment $Environment + + $session | Should-HaveType ([hashtable]) + $session['Environment'] | Should-Be $Environment + $session['Endpoint'] | Should-Be $Endpoint } } - Context 'Connect-ExampleService (internal)' { + It 'Rejects an environment that is not in the allowed set' { + InModuleScope ModuleExample { + { Connect-ExampleService -Environment 'Staging' } | + Should-Throw -FullyQualifiedErrorId 'ParameterArgumentValidationError,Connect-ExampleService' + } + } +} - It 'Returns a session describing the target environment' { - InModuleScope ModuleExample { - $session = Connect-ExampleService -Environment 'Test' -CorrelationId ([guid]::NewGuid()) +Describe 'Get-ExampleServiceStatus' -Tag 'Unit' { + It 'Returns the status of a service that exists' { + InModuleScope ModuleExample { + $session = Connect-ExampleService -Environment 'Test' - $session | Should-HaveType ([hashtable]) - $session.Environment | Should-Be 'Test' - $session.Endpoint | Should-MatchString 'test$' - } + Get-ExampleServiceStatus -ServiceName 'Identity' -Session $session | Should-Be 'Degraded' } + } - It 'Carries the caller correlation id through' { - InModuleScope ModuleExample { - $id = [guid]::NewGuid() - (Connect-ExampleService -Environment 'Development' -CorrelationId $id).CorrelationId | - Should-Be $id - } - } + It 'Throws ServiceNotFound for a service that does not exist' { + InModuleScope ModuleExample { + $session = Connect-ExampleService -Environment 'Test' - It 'Rejects an environment outside the allowed set' { - InModuleScope ModuleExample { - { Connect-ExampleService -Environment 'Staging' -CorrelationId ([guid]::NewGuid()) } | - Should-Throw -ExceptionMessage '*ValidateSet*' - } + { Get-ExampleServiceStatus -ServiceName 'Missing' -Session $session } | + Should-Throw -FullyQualifiedErrorId 'ServiceNotFound,Get-ExampleServiceStatus' } } } diff --git a/powershell-standards/Examples/Module-Structure-Example/docs/ModuleExample/Get-ExampleData.md b/powershell-standards/Examples/Module-Structure-Example/docs/ModuleExample/Get-ExampleData.md index a1e2e27..27fa06f 100644 --- a/powershell-standards/Examples/Module-Structure-Example/docs/ModuleExample/Get-ExampleData.md +++ b/powershell-standards/Examples/Module-Structure-Example/docs/ModuleExample/Get-ExampleData.md @@ -4,7 +4,7 @@ external help file: ModuleExample-Help.xml HelpUri: '' Locale: en-US Module Name: ModuleExample -ms.date: 08 29 2026 +ms.date: 11 15 2026 PlatyPS schema version: 2024-05-01 title: Get-ExampleData --- @@ -13,74 +13,53 @@ title: Get-ExampleData ## SYNOPSIS -Retrieves service status for one or more services. +Gets the status of one or more services. ## SYNTAX ### __AllParameterSets ``` -Get-ExampleData [-ServiceName] <string[]> [[-Environment] <string>] [[-CorrelationId] <guid>] +Get-ExampleData [-ServiceName] <string[]> [[-Environment] <string>] ``` ## DESCRIPTION -The exported surface of this example module. -Demonstrates the patterns the -standards require: +Emits one ExampleServiceResult object for each service name, in the order the names are received. A service that cannot be queried is reported as a non-terminating error, and the remaining names are still processed. -- An approved verb, with a descriptive [OutputType] rather than PSCustomObject -- Pipeline input, so the function composes -- A correlation ID generated once and carried through every call -- $_ in the catch block, and per-item failure that does not abort the batch +There is no real service behind this module. The statuses come from a fixed table that knows the services Billing, Identity, and Reporting. Every other name fails with the error ID ServiceNotFound. ## EXAMPLES -### EXAMPLE 1 +### Example 1: Get the status of one service +```powershell Get-ExampleData -ServiceName 'Billing' +``` -DESCRIPTION: Queries a single service in the default environment. -OUTPUT: One ExampleServiceResult. -USE CASE: Ad-hoc check of a single service. +Gets the status of the Billing service in the Development environment. -### EXAMPLE 2 +### Example 2: Take the service names from the pipeline -'Billing', 'Identity' | Get-ExampleData -Environment Test +```powershell +'Billing', 'Identity', 'Reporting' | Get-ExampleData -Environment 'Test' +``` -DESCRIPTION: Queries two services via the pipeline. -OUTPUT: One ExampleServiceResult per service. -USE CASE: Batch check where one failure must not stop the rest. +Gets the status of three services in the Test environment, taking the names from the pipeline. -## PARAMETERS +### Example 3: Continue after a service that cannot be queried -### -CorrelationId +```powershell +Get-ExampleData -ServiceName 'Billing', 'Missing', 'Reporting' +``` -Optional correlation identifier. -One is generated when not supplied, which is -why the parameter carries no ValidateNotNullOrEmpty - it is never empty. +Gets the status of Billing and Reporting, and writes a non-terminating error for Missing. -```yaml -Type: System.Guid -DefaultValue: '[guid]::NewGuid()' -SupportsWildcards: false -Aliases: [] -ParameterSets: -- Name: (All) - Position: 2 - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` +## PARAMETERS ### -Environment -Environment to query. -Defaults to Development so the example is safe to run. +Environment to query, which is recorded on each result. ```yaml Type: System.String @@ -101,8 +80,7 @@ HelpMessage: '' ### -ServiceName -One or more service names to query. -Accepts pipeline input. +One or more names of services to query. ```yaml Type: System.String[] @@ -132,31 +110,19 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] -One or more service names, bound from the pipeline by value or by property name. Piping a -collection queries each service in turn; a failure on one does not stop the rest. +You can pipe service names to this function, or objects that have a ServiceName property. ## OUTPUTS ### ExampleServiceResult -One object per service queried, carrying the service name, the environment, the resolved status, -and the correlation ID shared by every result in the batch. +One object for each service that was queried, with ServiceName, Environment, Status, and CheckedAt properties. ## NOTES -Author: Jeffrey Stuhr -Blog: https://www.techbyjeff.net -LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/ - -TROUBLESHOOTING: - -- Connection issues: .\Troubleshooting\Common\Function-Issues.md - +The error for a service that cannot be queried is non-terminating. To end the command at the first such service, pass -ErrorAction Stop. ## RELATED LINKS - [about_ModuleExample]() -- [Module structure standards](https://github.com/fadwen/ai-powershell-standards/blob/main/.github/instructions/module.instructions.md) -- [Help documentation standards](https://github.com/fadwen/ai-powershell-standards/blob/main/.github/instructions/platyps.instructions.md) -- [Function troubleshooting](https://github.com/fadwen/ai-powershell-standards/blob/main/Troubleshooting/Common/Function-Issues.md) - +- [PowerShell-Copilot-Standards](https://github.com/fadwen/Powershell-Copilot-Standards) diff --git a/powershell-standards/Examples/Module-Structure-Example/docs/ModuleExample/ModuleExample.md b/powershell-standards/Examples/Module-Structure-Example/docs/ModuleExample/ModuleExample.md index 654e429..dfdf2a8 100644 --- a/powershell-standards/Examples/Module-Structure-Example/docs/ModuleExample/ModuleExample.md +++ b/powershell-standards/Examples/Module-Structure-Example/docs/ModuleExample/ModuleExample.md @@ -5,7 +5,7 @@ HelpInfoUri: Locale: en-US Module Guid: 8f2b1c9d-4e7a-4b3f-9c21-5d6e8a0f7b34 Module Name: ModuleExample -ms.date: 08 29 2026 +ms.date: 11 15 2026 PlatyPS schema version: 2024-05-01 title: ModuleExample Module --- @@ -14,11 +14,11 @@ title: ModuleExample Module ## Description -Minimal reference module demonstrating the Public/Private/Classes layout and the export boundary described in the PowerShell Copilot Standards. +Example module with Public, Private, and Classes folders and an explicit export list. ## ModuleExample ### [Get-ExampleData](Get-ExampleData.md) -Retrieves service status for one or more services. +Gets the status of one or more services. diff --git a/powershell-standards/Examples/Module-Structure-Example/en-US/ModuleExample-Help.xml b/powershell-standards/Examples/Module-Structure-Example/en-US/ModuleExample-Help.xml index c0e10ff..c265907 100644 --- a/powershell-standards/Examples/Module-Structure-Example/en-US/ModuleExample-Help.xml +++ b/powershell-standards/Examples/Module-Structure-Example/en-US/ModuleExample-Help.xml @@ -4,20 +4,15 @@ <command:details> <command:name>Get-ExampleData</command:name> <maml:description> - <maml:para>Retrieves service status for one or more services.</maml:para> + <maml:para>Gets the status of one or more services.</maml:para> </maml:description> <command:verb>Get</command:verb> <command:noun>ExampleData</command:noun> </command:details> <maml:description> - <maml:para>The exported surface of this example module. -Demonstrates the patterns the -standards require: + <maml:para>Emits one ExampleServiceResult object for each service name, in the order the names are received. A service that cannot be queried is reported as a non-terminating error, and the remaining names are still processed. -- An approved verb, with a descriptive [OutputType] rather than PSCustomObject -- Pipeline input, so the function composes -- A correlation ID generated once and carried through every call -- $_ in the catch block, and per-item failure that does not abort the batch</maml:para> +There is no real service behind this module. The statuses come from a fixed table that knows the services Billing, Identity, and Reporting. Every other name fails with the error ID ServiceNotFound.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> @@ -38,34 +33,13 @@ standards require: <maml:name>System.String</maml:name> </dev:type> </command:parameter> - <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> - <maml:name>CorrelationId</maml:name> - <maml:description /> - <command:parameterValue required="true" variableLength="false">guid</command:parameterValue> - <dev:type> - <maml:name>System.Guid</maml:name> - </dev:type> - </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> - <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> - <maml:name>CorrelationId</maml:name> - <maml:description> - <maml:para>Optional correlation identifier. -One is generated when not supplied, which is -why the parameter carries no ValidateNotNullOrEmpty - it is never empty.</maml:para> - </maml:description> - <command:parameterValue required="true" variableLength="true">System.Guid</command:parameterValue> - <dev:type> - <maml:name>System.Guid</maml:name> - </dev:type> - </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Environment</maml:name> <maml:description> - <maml:para>Environment to query. -Defaults to Development so the example is safe to run.</maml:para> + <maml:para>Environment to query, which is recorded on each result.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue> <dev:type> @@ -75,8 +49,7 @@ Defaults to Development so the example is safe to run.</maml:para> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="0" aliases="none"> <maml:name>ServiceName</maml:name> <maml:description> - <maml:para>One or more service names to query. -Accepts pipeline input.</maml:para> + <maml:para>One or more names of services to query.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">System.String[]</command:parameterValue> <dev:type> @@ -90,8 +63,7 @@ Accepts pipeline input.</maml:para> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> - <maml:para>One or more service names, bound from the pipeline by value or by property name. Piping a -collection queries each service in turn; a failure on one does not stop the rest.</maml:para> + <maml:para>You can pipe service names to this function, or objects that have a ServiceName property.</maml:para> </maml:description> </command:inputType> </command:inputTypes> @@ -101,43 +73,48 @@ collection queries each service in turn; a failure on one does not stop the rest <maml:name>ExampleServiceResult</maml:name> </dev:type> <maml:description> - <maml:para>One object per service queried, carrying the service name, the environment, the resolved status, -and the correlation ID shared by every result in the batch.</maml:para> + <maml:para>One object for each service that was queried, with ServiceName, Environment, Status, and CheckedAt properties.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> - <maml:para>Author: Jeffrey Stuhr -Blog: https://www.techbyjeff.net -LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/ - -TROUBLESHOOTING: - -- Connection issues: .\Troubleshooting\Common\Function-Issues.md</maml:para> + <maml:para>The error for a service that cannot be queried is non-terminating. To end the command at the first such service, pass -ErrorAction Stop.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> - <maml:title>--------- EXAMPLE 1 ---------</maml:title> + <maml:title>--------- Example 1: Get the status of one service ---------</maml:title> <maml:introduction> - <maml:para>Get-ExampleData -ServiceName 'Billing'</maml:para> + <maml:para>```powershell +Get-ExampleData -ServiceName 'Billing' +```</maml:para> <maml:para>€</maml:para> - <maml:para>DESCRIPTION: Queries a single service in the default environment. -OUTPUT: One ExampleServiceResult. -USE CASE: Ad-hoc check of a single service.</maml:para> + <maml:para>Gets the status of the Billing service in the Development environment.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> - <maml:title>--------- EXAMPLE 2 ---------</maml:title> + <maml:title>--------- Example 2: Take the service names from the pipeline ---------</maml:title> <maml:introduction> - <maml:para>'Billing', 'Identity' | Get-ExampleData -Environment Test</maml:para> + <maml:para>```powershell +'Billing', 'Identity', 'Reporting' | Get-ExampleData -Environment 'Test' +```</maml:para> <maml:para>€</maml:para> - <maml:para>DESCRIPTION: Queries two services via the pipeline. -OUTPUT: One ExampleServiceResult per service. -USE CASE: Batch check where one failure must not stop the rest.</maml:para> + <maml:para>Gets the status of three services in the Test environment, taking the names from the pipeline.</maml:para> + </maml:introduction> + <dev:code /> + <dev:remarks /> + </command:example> + <command:example> + <maml:title>--------- Example 3: Continue after a service that cannot be queried ---------</maml:title> + <maml:introduction> + <maml:para>```powershell +Get-ExampleData -ServiceName 'Billing', 'Missing', 'Reporting' +```</maml:para> + <maml:para>€</maml:para> + <maml:para>Gets the status of Billing and Reporting, and writes a non-terminating error for Missing.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> @@ -153,16 +130,8 @@ USE CASE: Batch check where one failure must not stop the rest.</maml:para> <maml:uri /> </maml:navigationLink> <maml:navigationLink> - <maml:linkText>Module structure standards</maml:linkText> - <maml:uri>https://github.com/fadwen/ai-powershell-standards/blob/main/.github/instructions/module.instructions.md</maml:uri> - </maml:navigationLink> - <maml:navigationLink> - <maml:linkText>Help documentation standards</maml:linkText> - <maml:uri>https://github.com/fadwen/ai-powershell-standards/blob/main/.github/instructions/platyps.instructions.md</maml:uri> - </maml:navigationLink> - <maml:navigationLink> - <maml:linkText>Function troubleshooting</maml:linkText> - <maml:uri>https://github.com/fadwen/ai-powershell-standards/blob/main/Troubleshooting/Common/Function-Issues.md</maml:uri> + <maml:linkText>PowerShell-Copilot-Standards</maml:linkText> + <maml:uri>https://github.com/fadwen/Powershell-Copilot-Standards</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> diff --git a/powershell-standards/Examples/Module-Structure-Example/en-US/about_ModuleExample.help.txt b/powershell-standards/Examples/Module-Structure-Example/en-US/about_ModuleExample.help.txt index 5f0d8fb..f8f0189 100644 --- a/powershell-standards/Examples/Module-Structure-Example/en-US/about_ModuleExample.help.txt +++ b/powershell-standards/Examples/Module-Structure-Example/en-US/about_ModuleExample.help.txt @@ -2,68 +2,59 @@ TOPIC about_ModuleExample SHORT DESCRIPTION - Describes the conventions ModuleExample demonstrates, and the concepts that - span its commands rather than belonging to any one of them. + Describes the behaviour of the ModuleExample module that does not belong + to the help of one command. LONG DESCRIPTION - ModuleExample is a reference module. It exists to show the layout, export - boundary, and help pipeline the PowerShell Copilot Standards expect, in a - form small enough to read in one sitting. + ModuleExample is an example module. It shows a module laid out in Public, + Private, and Classes folders, with an explicit export list, a class as a + named output type, and command help that is built from Markdown. - This topic is hand-written plain text. PlatyPS does not generate about - topics, and never rewrites them. That is the point: a module with more than - a handful of commands needs somewhere to explain the ideas its commands - share, and per-command help is the wrong place for that. + There is no real service behind the module. The statuses it returns come + from a fixed table that knows three services: Billing, Identity, and + Reporting. - CORRELATION IDS - - Every command accepts a -CorrelationId parameter and generates one when it - is not supplied. The identifier is created once, in the begin block, and - carried through every downstream call and every log line for the duration of - the pipeline. - - The convention matters when a batch partially fails. Because one identifier - covers the whole invocation, the successful and failed items in a single run - share a key, and the logs for that run can be retrieved as a unit: + ENVIRONMENTS - 'Billing', 'Identity' | Get-ExampleData -Environment Test -Verbose + Get-ExampleData has an -Environment parameter that accepts Development, + Test, or Production. The default is Development. The value is recorded on + each result: - Passing your own identifier lets you correlate this module's activity with a - caller's trace: + Get-ExampleData -ServiceName 'Billing' -Environment 'Test' - $id = [guid]::NewGuid() - Get-ExampleData -ServiceName 'Billing' -CorrelationId $id + PARTIAL FAILURE - ENVIRONMENTS + A service that cannot be queried does not end the command. The command + writes a non-terminating error for that service and continues with the + next one, so the results for the other services are still returned: - Commands take an -Environment parameter constrained to Development, Test, - and Production. It defaults to Development so that every example in the help - is safe to run without touching a live system. + Get-ExampleData -ServiceName 'Billing', 'Missing', 'Reporting' - The environment selects the connection the private helper opens. It is not a - formatting or verbosity switch, and changing it changes what the command - talks to. + The error has the ID ServiceNotFound. To end the command at the first + service that cannot be queried, pass -ErrorAction Stop: - PARTIAL FAILURE + 'Billing', 'Missing' | Get-ExampleData -ErrorAction Stop - Commands that accept pipeline input do not abort the batch when one item - fails. The failing item writes a non-terminating error and the loop - continues, so a bad name in the middle of a list does not discard the - results either side of it. + OUTPUT - To make a batch stop on the first failure, opt in at the call site: + Get-ExampleData emits ExampleServiceResult objects. Each object has the + properties ServiceName, Environment, Status, and CheckedAt. Status is + Healthy, Degraded, or Unavailable. The IsUsable() method returns $true + when the status is Healthy or Degraded: - 'Billing', 'Identity' | Get-ExampleData -ErrorAction Stop + Get-ExampleData -ServiceName 'Billing', 'Reporting' | + Where-Object { $_.IsUsable() } - WHERE HELP LIVES + HELP - Command help is generated. The .ps1 files under Public/ carry only an - EXTERNALHELP keyword and a one-line synopsis; the content users read lives - in docs/ModuleExample/*.md and compiles to en-US/ModuleExample-Help.xml. + The help for Get-ExampleData is written as Markdown in + docs/ModuleExample/Get-ExampleData.md and compiled to + en-US/ModuleExample-Help.xml. The function file carries only an + .EXTERNALHELP keyword and a one-line synopsis. To change the help, edit + the Markdown and compile it again. Do not edit the XML file. - Edit the Markdown, never the XML and never the comment block. See - .github/instructions/platyps.instructions.md in the standards repository. + This topic is a plain text file that is written by hand. SEE ALSO Get-ExampleData - https://github.com/fadwen/ai-powershell-standards + https://github.com/fadwen/Powershell-Copilot-Standards diff --git a/powershell-standards/Examples/README.md b/powershell-standards/Examples/README.md index 47a26ae..58e6b9e 100644 --- a/powershell-standards/Examples/README.md +++ b/powershell-standards/Examples/README.md @@ -1,64 +1,93 @@ # Examples -Working code demonstrating the standards in this repository. Every file here runs and is covered by -tests. This folder is mirrored into consuming projects by the sync workflow. +Working code that follows the PowerShell standards in this repository, and one file that breaks them +on purpose. The function, the module, and the negative example have Pester tests. -## What is here +## Requirements -| Example | Demonstrates | +- PowerShell 7.6 or later. +- Windows, for `Basic-Function-Example.ps1`. It calls the CIM commands and queries computers over + WinRM. +- Pester 6.2.0 or later, to run the tests. +- PSScriptAnalyzer 1.25.0 or later, for `Test-QualityGates.Tests.ps1`. + +## Contents + +| Example | What it shows | | --- | --- | -| [Basic-Function-Example.ps1](./Basic-Function-Example.ps1) | A complete advanced function: pipeline input, parameter validation, correlation IDs, per-item error handling, and a named `[OutputType]` | -| [Module-Structure-Example/](./Module-Structure-Example/) | A minimal working module - the Public/Private/Classes layout and the export boundary it creates | -| [Testing-Examples/](./Testing-Examples/) | Pester 6 tests for `Basic-Function-Example.ps1`, including CIM mocking and `-RemoveParameterType` | -| [Configuration/DefaultConfiguration.psd1](./Configuration/DefaultConfiguration.psd1) | A configuration data file: environment settings, validation thresholds, and logging targets | +| [Basic-Function-Example.ps1](Basic-Function-Example.ps1) | One advanced function, `Get-BasicServerInfo`, with pipeline input, per-item errors, and a named output type. | +| [Testing-Examples/](Testing-Examples/) | The tests for `Get-BasicServerInfo`, with the CIM commands and the clock mocked. | +| [Module-Structure-Example/](Module-Structure-Example/) | A small working module. Its own [README](Module-Structure-Example/README.md) describes it. | +| [Configuration/DefaultConfiguration.psd1](Configuration/DefaultConfiguration.psd1) | A settings file that holds data only. | +| [Test-QualityGates.ps1](Test-QualityGates.ps1) | A negative example. It breaks the standards on purpose and is not code to copy. | -## Start with the function example +## Usage -[Basic-Function-Example.ps1](./Basic-Function-Example.ps1) is the densest single file: +Run the commands in this section from this folder. + +### The function example ```powershell -. .\Basic-Function-Example.ps1 +. ./Basic-Function-Example.ps1 + +Get-BasicServerInfo -ComputerName 'SERVER01' +'SERVER01', 'SERVER02' | Get-BasicServerInfo -IncludeServices +``` + +Replace the names with computers that accept WinRM connections. The first command returns one +`Example.ServerInfo` object. The second takes the names from the pipeline and fills the +`RunningServices` property of each object. A computer that cannot be queried produces a +non-terminating error, and the remaining computers are still processed. + +| Rule | What to look at in the file | +| --- | --- | +| DOC-02 | The help block is the first thing in the function body. | +| FUN-10 | `[OutputType('Example.ServerInfo')]` names the type, and the object carries the same name as `PSTypeName`. | +| FUN-21 | `ComputerName` is an array that the `process` block loops over. | +| FUN-31 | The function only reads, so it does not declare `SupportsShouldProcess`. | +| SEC-03 | `Credential` is a `PSCredential` with the `Credential()` attribute and an empty default. | +| SEC-11 | An anchored `ValidatePattern` rejects a bad computer name when the parameter is bound. | +| ERR-13, ERR-14 | The `catch` block wraps the failure in a new `ErrorRecord`, passes it to `$PSCmdlet.WriteError()`, and continues with the next computer. | +| ERR-22 | The CIM session is closed in `finally`. | + +### The settings file -Get-BasicServerInfo -ComputerName 'SERVER01' -WhatIf -'SERVER01', 'SERVER02' | Get-BasicServerInfo -Verbose +```powershell +$settings = Import-PowerShellDataFile -LiteralPath ./Configuration/DefaultConfiguration.psd1 +$settings['Environments']['Production']['TimeoutSeconds'] ``` -It shows: +Reads the file into a hashtable and returns `10`, the timeout of the Production environment. -- `[OutputType('BasicServerInfo')]` with a matching `PSTypeName` on the output, rather than - `[OutputType([PSCustomObject])]`, which tells a caller nothing about the shape returned -- A correlation ID generated once in `begin` and carried through every message -- `$_` in `catch`, and `continue` so one unreachable host does not abort the batch -- `ShouldProcess` support, so `-WhatIf` works +### The negative example -## Then the module +[Test-QualityGates.ps1](Test-QualityGates.ps1) exists so that the quality gates have something to +catch. Its header lists every rule it breaks, in two groups: the violations that PSScriptAnalyzer +reports, and the ones that it does not report. -[Module-Structure-Example/](./Module-Structure-Example/) is deliberately small. Its point is not the -code but the boundary: `FunctionsToExport` names the public surface, so the private helper stays -internal and can change without a breaking release. Classes load before the functions that return -them. +```powershell +Invoke-ScriptAnalyzer -Path ./Test-QualityGates.ps1 -Settings ../../PSScriptAnalyzerSettings.psd1 +``` -Its own tests live in [Module-Structure-Example/Tests/](./Module-Structure-Example/Tests/) and cover -the module contract, the class, the private helper via `InModuleScope`, and the per-item failure -path. Examples here are held to the same coverage bar as the tooling. +Shows the first group. An analysis run that has to pass must leave this file out by name. -## The anti-pattern file +## Tests -[Test-QualityGates.ps1](https://github.com/fadwen/ai-powershell-standards/blob/main/Documentation/Anti-Patterns/Test-QualityGates.ps1) -lives in the standards repository, outside this mirrored folder. It intentionally breaks the -standards - `Write-Host`, `$Error[0]` in a catch, a non-approved verb, string building in a loop. It -exists so the quality gates have something to catch, and the CI workflows exclude it from production -analysis by name for that reason. +```powershell +Invoke-Pester -Path ./Testing-Examples, ./Test-QualityGates.Tests.ps1 +``` -Its tests in [Test-QualityGates.Tests.ps1](https://github.com/fadwen/ai-powershell-standards/blob/main/Documentation/Anti-Patterns/Test-QualityGates.Tests.ps1) -document that behaviour -rather than endorsing it. +Runs the tests for the function example and for the negative example. The tests for the negative +example record what its functions do, and they fail when a violation is added to the file or removed +from it. The module example has its own tests; see its README. -## Related +## Related files -- [PowerShell Best Practices](https://github.com/fadwen/ai-powershell-standards/blob/main/Documentation/PowerShell-Best-Practices.md): - the reasoning behind these patterns -- [Templates/Powershell-Module](https://github.com/fadwen/ai-powershell-standards/tree/main/Templates/Powershell-Module): - a fuller starting point to copy -- [Version baseline](../../.github/instructions/powershell-version.instructions.md) - which PowerShell - version to target, and why +- [PSScriptAnalyzerSettings.psd1](../../PSScriptAnalyzerSettings.psd1): the analyzer settings that + check the layout rules. +- [Templates/Powershell-Module](../../Templates/Powershell-Module/): a module to copy and rename. +- The rules that the examples follow: + [powershell-functions](../../.github/instructions/powershell-functions.instructions.md), + [powershell-error-handling](../../.github/instructions/powershell-error-handling.instructions.md), + [powershell-help](../../.github/instructions/powershell-help.instructions.md), and + [powershell-pester](../../.github/instructions/powershell-pester.instructions.md). diff --git a/powershell-standards/Examples/Testing-Examples/Basic-Function-Example.Tests.ps1 b/powershell-standards/Examples/Testing-Examples/Basic-Function-Example.Tests.ps1 new file mode 100644 index 0000000..7562635 --- /dev/null +++ b/powershell-standards/Examples/Testing-Examples/Basic-Function-Example.Tests.ps1 @@ -0,0 +1,238 @@ +#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.2.0' } + +BeforeAll { + $examplesRoot = Split-Path -Path $PSScriptRoot -Parent + . (Join-Path -Path $examplesRoot -ChildPath 'Basic-Function-Example.ps1') +} + +Describe 'Get-BasicServerInfo' -Tag 'Unit' { + BeforeAll { + # The CIM commands reach the network and the clock decides the uptime, so every test replaces + # them. The stand-in session is not a CimSession. The two commands that receive it are + # therefore mocked with -RemoveParameterType, because parameter binding would otherwise + # reject the stand-in before the mock ran. + Mock -CommandName Get-Date -MockWith { [datetime]'2026-03-06T12:00:00' } + + Mock -CommandName New-CimSession -MockWith { + [PSCustomObject]@{ ComputerName = $ComputerName } + } + + Mock -CommandName Remove-CimSession -RemoveParameterType CimSession -MockWith { } + + Mock -CommandName Get-CimInstance -RemoveParameterType CimSession -MockWith { + switch ($ClassName) { + 'Win32_OperatingSystem' { + [PSCustomObject]@{ + Caption = 'Microsoft Windows Server 2022 Standard' + Version = '10.0.20348' + OSArchitecture = '64-bit' + LastBootUpTime = [datetime]'2026-03-01T00:00:00' + } + } + 'Win32_ComputerSystem' { + [PSCustomObject]@{ + Manufacturer = 'Contoso' + Model = 'Rack Server 1' + Domain = 'contoso.com' + TotalPhysicalMemory = 16GB + NumberOfLogicalProcessors = 8 + } + } + 'Win32_Service' { + [PSCustomObject]@{ Name = 'Spooler'; DisplayName = 'Print Spooler'; StartMode = 'Auto' } + [PSCustomObject]@{ Name = 'Themes'; DisplayName = 'Themes'; StartMode = 'Auto' } + } + default { + throw "The test does not expect a query for the class '$ClassName'." + } + } + } + } + + Context 'When the computers answer' { + It 'Returns one object with the values read from the computer' { + $result = @(Get-BasicServerInfo -ComputerName 'SERVER01') + + $result | Should-BeCollection -Count 1 + $result[0] | Should-HaveType 'Example.ServerInfo' + $result[0].ComputerName | Should-Be 'SERVER01' + $result[0].OperatingSystem | Should-Be 'Microsoft Windows Server 2022 Standard' + $result[0].Version | Should-Be '10.0.20348' + $result[0].Architecture | Should-Be '64-bit' + $result[0].Manufacturer | Should-Be 'Contoso' + $result[0].Model | Should-Be 'Rack Server 1' + $result[0].Domain | Should-Be 'contoso.com' + $result[0].TotalMemoryGB | Should-Be 16 + $result[0].LogicalProcessors | Should-Be 8 + } + + It 'Calculates the uptime from the last boot time' { + $result = Get-BasicServerInfo -ComputerName 'SERVER01' + + $result.LastBootTime | Should-Be ([datetime]'2026-03-01T00:00:00') + $result.UptimeDays | Should-Be 5.5 + } + + It 'Accepts the computer name <ValidName>' -ForEach @( + @{ ValidName = 'SERVER01' } + @{ ValidName = 'web01.contoso.com' } + @{ ValidName = 'DB-SERVER-01' } + ) { + $result = Get-BasicServerInfo -ComputerName $ValidName + + $result.ComputerName | Should-Be $ValidName + } + + It 'Emits one object for each computer name received from the pipeline, in order' { + $result = @('WEB01', 'WEB02' | Get-BasicServerInfo) + + $result | Should-BeCollection -Count 2 + $result[0].ComputerName | Should-Be 'WEB01' + $result[1].ComputerName | Should-Be 'WEB02' + } + + It 'Reads the computer name from the ComputerName property of a pipeline object' { + $server = [PSCustomObject]@{ ComputerName = 'APP01' } + + $result = @($server | Get-BasicServerInfo) + + $result | Should-BeCollection -Count 1 + $result[0].ComputerName | Should-Be 'APP01' + } + + It 'Closes the session of every computer' { + $null = Get-BasicServerInfo -ComputerName 'WEB01', 'WEB02' + + Should-Invoke -CommandName New-CimSession -Times 2 -Exactly + Should-Invoke -CommandName Remove-CimSession -Times 2 -Exactly + } + } + + Context 'When the running services are requested' { + It 'Leaves RunningServices empty and does not query the services by default' { + $result = Get-BasicServerInfo -ComputerName 'SERVER01' + + $result | Should-HaveType 'Example.ServerInfo' + $result.RunningServices | Should-BeCollection -Count 0 + Should-Invoke -CommandName Get-CimInstance -Times 0 -Exactly -ParameterFilter { + $ClassName -eq 'Win32_Service' + } + } + + It 'Adds the running services, in the order the computer returned them' { + $result = Get-BasicServerInfo -ComputerName 'SERVER01' -IncludeServices + + $result.RunningServices | Should-BeCollection -Count 2 + $result.RunningServices[0].Name | Should-Be 'Spooler' + $result.RunningServices[0].DisplayName | Should-Be 'Print Spooler' + $result.RunningServices[1].Name | Should-Be 'Themes' + } + + It 'Asks the computer for running services only' { + $null = Get-BasicServerInfo -ComputerName 'SERVER01' -IncludeServices + + Should-Invoke -CommandName Get-CimInstance -Times 1 -Exactly -ParameterFilter { + $ClassName -eq 'Win32_Service' -and $Filter -eq 'State = "Running"' + } + } + } + + Context 'When a credential is supplied' { + It 'Opens the session with that credential' { + # An empty SecureString keeps a password out of the test file. + $operatorCredential = [System.Management.Automation.PSCredential]::new( + 'CONTOSO\operator', [System.Security.SecureString]::new()) + + $null = Get-BasicServerInfo -ComputerName 'SERVER01' -Credential $operatorCredential + + Should-Invoke -CommandName New-CimSession -Times 1 -Exactly -ParameterFilter { + $PesterBoundParameters.ContainsKey('Credential') -and + $Credential.UserName -eq 'CONTOSO\operator' + } + } + + It 'Opens the session as the current user when no credential is supplied' { + $null = Get-BasicServerInfo -ComputerName 'SERVER01' + + Should-Invoke -CommandName New-CimSession -Times 1 -Exactly -ParameterFilter { + -not $PesterBoundParameters.ContainsKey('Credential') + } + } + } + + Context 'When a computer name is not valid' { + It 'Rejects a name that <Reason>' -ForEach @( + @{ InvalidName = 'SERVER_01'; Reason = 'contains an underscore' } + @{ InvalidName = 'SERVER 01'; Reason = 'contains a space' } + @{ InvalidName = '-SERVER01'; Reason = 'starts with a hyphen' } + @{ InvalidName = ''; Reason = 'is empty' } + ) { + { Get-BasicServerInfo -ComputerName $InvalidName } | + Should-Throw -FullyQualifiedErrorId 'ParameterArgumentValidationError,Get-BasicServerInfo' + + Should-Invoke -CommandName New-CimSession -Times 0 -Exactly + } + } + + Context 'When a computer cannot be reached' { + BeforeAll { + Mock -CommandName New-CimSession -ParameterFilter { $ComputerName -contains 'OFFLINE01' } -MockWith { + throw 'The WinRM client cannot complete the operation.' + } + } + + It 'Writes one non-terminating error and still returns the computers that answer' { + $output = Get-BasicServerInfo -ComputerName 'OFFLINE01', 'SERVER01' -ErrorAction Continue 2>&1 + $errors = @($output | Where-Object { $_ -is [System.Management.Automation.ErrorRecord] }) + $values = @($output | Where-Object { $_ -isnot [System.Management.Automation.ErrorRecord] }) + + $errors | Should-BeCollection -Count 1 + $errors[0].FullyQualifiedErrorId | Should-BeLikeString 'ServerInfoQueryFailed*' + $errors[0].TargetObject | Should-Be 'OFFLINE01' + $values | Should-BeCollection -Count 1 + $values[0].ComputerName | Should-Be 'SERVER01' + } + + It 'Keeps the original failure as the inner exception' { + $output = Get-BasicServerInfo -ComputerName 'OFFLINE01' -ErrorAction Continue 2>&1 + $errors = @($output | Where-Object { $_ -is [System.Management.Automation.ErrorRecord] }) + + $errors | Should-BeCollection -Count 1 + $errors[0].Exception | Should-HaveType ([System.InvalidOperationException]) + $errors[0].Exception.InnerException.Message | + Should-Be 'The WinRM client cannot complete the operation.' + } + + It 'Does not close a session that never opened' { + $null = Get-BasicServerInfo -ComputerName 'OFFLINE01' -ErrorAction Continue 2>&1 + + Should-Invoke -CommandName Remove-CimSession -Times 0 -Exactly + } + + It 'Stops at the failed computer when the caller passes -ErrorAction Stop' { + { Get-BasicServerInfo -ComputerName 'OFFLINE01', 'SERVER01' -ErrorAction Stop } | + Should-Throw -FullyQualifiedErrorId 'ServerInfoQueryFailed,Get-BasicServerInfo' + + Should-Invoke -CommandName New-CimSession -Times 1 -Exactly + } + } + + Context 'When a query fails after the session opened' { + BeforeAll { + Mock -CommandName Get-CimInstance -RemoveParameterType CimSession -ParameterFilter { + $ClassName -eq 'Win32_ComputerSystem' + } -MockWith { + throw 'Access is denied.' + } + } + + It 'Reports the failure, returns nothing for that computer, and closes the session' { + $output = @(Get-BasicServerInfo -ComputerName 'SERVER01' -ErrorAction Continue 2>&1) + + $output | Should-BeCollection -Count 1 + $output[0] | Should-HaveType ([System.Management.Automation.ErrorRecord]) + $output[0].FullyQualifiedErrorId | Should-BeLikeString 'ServerInfoQueryFailed*' + Should-Invoke -CommandName Remove-CimSession -Times 1 -Exactly + } + } +} diff --git a/powershell-standards/Examples/Testing-Examples/Basic-Function.Tests.ps1 b/powershell-standards/Examples/Testing-Examples/Basic-Function.Tests.ps1 deleted file mode 100644 index ec5e55c..0000000 --- a/powershell-standards/Examples/Testing-Examples/Basic-Function.Tests.ps1 +++ /dev/null @@ -1,181 +0,0 @@ -#Requires -Module Pester - -BeforeAll { - # Import the module containing the function to test - $ModulePath = Join-Path $PSScriptRoot '..\..\Examples\Basic-Function-Example.ps1' - . $ModulePath - - # Names the mocks answer to. Kept in variables rather than literals: consuming - # projects mirror this file and may analyse it with PSAvoidUsingComputerNameHardcoded - # enabled, which flags a string literal passed to -ComputerName. - $script:MockServer = 'MOCKSERVER' - $script:OfflineServer = 'OFFLINE' -} - -Describe "Get-BasicServerInfo" -Tag "Unit", "Example" { - - # Default mocks live at Describe level so every Context is hermetic - no test - # reaches a real network. Contexts below override individual mocks as needed. - # - # -RemoveParameterType CimSession is required: PowerShell binds parameters using - # the *original* command's metadata even when a command is mocked, so passing a - # PSCustomObject stub to -CimSession fails type coercion before the mock body runs. - BeforeEach { - Mock Test-Connection { $true } - - Mock New-CimSession { [PSCustomObject]@{ ComputerName = $ComputerName } } - - Mock Remove-CimSession -RemoveParameterType CimSession -MockWith { } - - Mock Get-CimInstance -RemoveParameterType CimSession -MockWith { - switch ($ClassName) { - 'Win32_OperatingSystem' { - [PSCustomObject]@{ - Caption = 'Microsoft Windows Server 2019' - Version = '10.0.17763' - ServicePackMajorVersion = 0 - OSArchitecture = '64-bit' - LastBootUpTime = (Get-Date).AddDays(-5) - } - } - 'Win32_ComputerSystem' { - [PSCustomObject]@{ - TotalPhysicalMemory = 17179869184 # 16 GB - Manufacturer = 'Dell Inc.' - Model = 'PowerEdge R740' - Domain = 'contoso.com' - Workgroup = $null - } - } - 'Win32_Processor' { - [PSCustomObject]@{ - Name = 'Intel(R) Xeon(R) Gold 6248 CPU @ 2.50GHz' - NumberOfCores = 8 - NumberOfLogicalProcessors = 16 - } - } - 'Win32_Service' { - @( - [PSCustomObject]@{ Name = 'Spooler'; DisplayName = 'Print Spooler'; StartMode = 'Auto'; State = 'Running' } - [PSCustomObject]@{ Name = 'Themes'; DisplayName = 'Themes'; StartMode = 'Auto'; State = 'Running' } - ) - } - } - } - } - - Context "Parameter Validation" { - It "Should accept valid computer names: <ComputerName>" -TestCases @( - @{ ComputerName = 'SERVER01' } - @{ ComputerName = 'web01.contoso.com' } - @{ ComputerName = 'DB-SERVER-01' } - ) { - # This should not throw - Get-BasicServerInfo -ComputerName $ComputerName -WhatIf - } - - # Expected messages are the ones PowerShell's validation attributes actually - # emit. ValidatePattern/ValidateLength do not produce friendly text; asserting - # invented wording here is what let these tests rot unnoticed. - It "Should reject invalid computer names: <InvalidName>" -TestCases @( - @{ InvalidName = 'SERVER_01'; ExpectedError = '*does not match the*pattern*' } - @{ InvalidName = 'SERVER 01'; ExpectedError = '*does not match the*pattern*' } - @{ InvalidName = ''; ExpectedError = '*length*is too short*' } - ) { - { Get-BasicServerInfo -ComputerName $InvalidName } | Should-Throw -ExceptionMessage $ExpectedError - } - - It "Should support pipeline input" { - $computerNames = @('SERVER01', 'SERVER02') - - # This should not throw and should accept pipeline input - $computerNames | Get-BasicServerInfo -WhatIf - } - } - - Context "Core Functionality" { - - It "Should return expected object structure" { - $result = Get-BasicServerInfo -ComputerName $script:MockServer - - # Verify object structure - $result | Should-NotBeNull - $result | Should-NotBeNull - - # Verify required properties - $result.ComputerName | Should-Be $script:MockServer - $result.OperatingSystem | Should-Be 'Microsoft Windows Server 2019' - $result.TotalMemoryGB | Should-Be 16 - $result.CorrelationId | Should-NotBeNull - } - - It "Should include services when IncludeServices switch is used" { - $result = Get-BasicServerInfo -ComputerName $script:MockServer -IncludeServices - - $result.RunningServices | Should-NotBeNull - $result.RunningServiceCount | Should-Be 2 - $result.RunningServices[0].Name | Should-Be 'Spooler' - } - - It "Should calculate uptime correctly" { - $result = Get-BasicServerInfo -ComputerName $script:MockServer - - $result.UptimeDays | Should-BeGreaterThan 4.9 - $result.UptimeDays | Should-BeLessThan 5.1 - } - } - - Context "Error Handling" { - - # NOTE: PowerShell 7 renamed Test-Connection's -ComputerName parameter to - # -TargetName, keeping ComputerName only as an alias. Pester binds mock - # variables by the *real* parameter name, so a filter written against - # $ComputerName never matches and the mock silently does nothing. Use - # $TargetName here. - # - # These overrides also live in BeforeEach rather than inside It, because a - # mock declared inside It does not reliably apply to a function that was - # dot-sourced in BeforeAll. - BeforeEach { - Mock Test-Connection { - if ($TargetName -eq $script:OfflineServer) { return $false } - return $true - } - Mock New-CimSession { - if ($ComputerName -eq $script:OfflineServer) { throw "Connection failed" } - [PSCustomObject]@{ ComputerName = $ComputerName } - } - } - - It "Should handle connection failures gracefully" { - Get-BasicServerInfo -ComputerName $script:OfflineServer -ErrorAction SilentlyContinue - } - - It "Should continue processing other computers when one fails" { - $results = Get-BasicServerInfo -ComputerName @($script:MockServer, $script:OfflineServer) -ErrorAction SilentlyContinue - - # Should get one successful result despite one failure - $results | Should-NotBeNull - $results.ComputerName | Should-ContainCollection $script:MockServer - } - } - - Context "Performance Requirements" { - It "Should complete within acceptable time limits" { - $stopwatch = [System.Diagnostics.Stopwatch]::StartNew() - - Get-BasicServerInfo -ComputerName $script:MockServer | Out-Null - - $stopwatch.Stop() - $stopwatch.ElapsedMilliseconds | Should-BeLessThan 5000 # 5 seconds max for mocked operations - } - - It "Should include performance metrics in output" { - $result = Get-BasicServerInfo -ComputerName $script:MockServer - - $result.QueryTime | Should-NotBeNull - $result.QueryDurationMs | Should-BeGreaterThan 0 - $result.CorrelationId | Should-NotBeNull - } - } -} \ No newline at end of file