MegaBites-AI/Windows-powershell

1---2applyTo:3  - "**/*.Tests.ps1"4---5 6# Pester Set-ItResult Pattern for Pending and Skipped Tests7 8## Purpose9 10This instruction explains when and how to use `Set-ItResult` in Pester tests to mark tests as Pending or Skipped dynamically within test execution.11 12## When to Use Set-ItResult13 14Use `Set-ItResult` when you need to conditionally mark a test as Pending or Skipped based on runtime conditions that can't be determined at test definition time.15 16### Pending vs Skipped17 18**Pending**: Use for tests that should be enabled but temporarily can't run due to:19- Intermittent external service failures (network, APIs)20- Known bugs being fixed21- Missing features being implemented22- Environmental issues that are being resolved23 24**Skipped**: Use for tests that aren't applicable to the current environment:25- Platform-specific tests running on wrong platform26- Tests requiring specific hardware/configuration not present27- Tests requiring elevated permissions when not available28- Feature-specific tests when feature is disabled29 30## Pattern31 32### Basic Usage33 34```powershell35It "Test description" {36    if ($shouldBePending) {37        Set-ItResult -Pending -Because "Explanation of why test is pending"38        return39    }40    41    if ($shouldBeSkipped) {42        Set-ItResult -Skipped -Because "Explanation of why test is skipped"43        return44    }45    46    # Test code here47}48```49 50### Important: Always Return After Set-ItResult51 52After calling `Set-ItResult`, you **must** return from the test to prevent further execution:53 54```powershell55It "Test that checks environment" {56    if ($env:SKIP_TESTS -eq 'true') {57        Set-ItResult -Skipped -Because "SKIP_TESTS environment variable is set"58        return  # This is required!59    }60    61    # Test assertions62    $result | Should -Be $expected63}64```65 66**Why?** Without `return`, the test continues executing and may fail with errors unrelated to the pending/skipped condition.67 68## Examples from the Codebase69 70### Example 1: Pending for Intermittent Network Issues71 72```powershell73It "Validate Update-Help for module" {74    if ($markAsPending) {75        Set-ItResult -Pending -Because "Update-Help from the web has intermittent connectivity issues. See issues #2807 and #6541."76        return77    }78    79    Update-Help -Module $moduleName -Force80    # validation code...81}82```83 84### Example 2: Skipped for Missing Environment85 86```powershell87It "Test requires CI environment" {88    if (-not $env:CI) {89        Set-ItResult -Skipped -Because "Test requires CI environment to safely install Pester"90        return91    }92    93    Install-CIPester -ErrorAction Stop94}95```96 97### Example 3: Pending for Platform-Specific Issue98 99```powershell100It "Clear-Host works correctly" {101    if ($IsARM64) {102        Set-ItResult -Pending -Because "ARM64 runs in non-interactively mode and Clear-Host does not work."103        return104    }105    106    & { Clear-Host; 'hi' } | Should -BeExactly 'hi'107}108```109 110### Example 4: Skipped for Missing Feature111 112```powershell113It "Test ACR authentication" {114    if ($env:ACRTESTS -ne 'true') {115        Set-ItResult -Skipped -Because "The tests require the ACRTESTS environment variable to be set to 'true' for ACR authentication."116        return117    }118    119    $psgetModuleInfo = Find-PSResource -Name $ACRTestModule -Repository $ACRRepositoryName120    # test assertions...121}122```123 124## Alternative: Static -Skip and -Pending Parameters125 126For conditions that can be determined at test definition time, use the static parameters instead:127 128```powershell129# Static skip - condition known at definition time130It "Windows-only test" -Skip:(-not $IsWindows) {131    # test code132}133 134# Static pending - always pending135It "Test for feature being implemented" -Pending {136    # test code that will fail until feature is done137}138```139 140**Use Set-ItResult when**:141- Condition depends on runtime state142- Condition is determined inside a helper function143- Need to check multiple conditions sequentially144 145**Use static parameters when**:146- Condition is known at test definition147- Condition doesn't change during test run148- Want Pester to show the condition in test discovery149 150## Best Practices151 1521. **Always include -Because parameter** with a clear explanation1532. **Always return after Set-ItResult** to prevent further execution1543. **Reference issues or documentation** when relevant (e.g., "See issue #1234")1554. **Be specific in the reason** - explain what's wrong and what's needed1565. **Use Pending sparingly** - it indicates a problem that should be fixed1576. **Prefer Skipped over Pending** when test truly isn't applicable158 159## Common Mistakes160 161### ❌ Mistake 1: Forgetting to Return162 163```powershell164It "Test" {165    if ($condition) {166        Set-ItResult -Pending -Because "Reason"167        # Missing return - test code will still execute!168    }169    $value | Should -Be $expected  # This runs and fails170}171```172 173### ❌ Mistake 2: Vague Reason174 175```powershell176Set-ItResult -Pending -Because "Doesn't work"  # Too vague177```178 179### ✅ Correct:180 181```powershell182It "Test" {183    if ($condition) {184        Set-ItResult -Pending -Because "Update-Help has intermittent network timeouts. See issue #2807."185        return186    }187    $value | Should -Be $expected188}189```190 191## See Also192 193- [Pester Documentation: Set-ItResult](https://pester.dev/docs/commands/Set-ItResult)194- [Pester Documentation: It](https://pester.dev/docs/commands/It)195- Examples in the codebase:196  - `test/powershell/Host/ConsoleHost.Tests.ps1`197  - `test/infrastructure/ciModule.Tests.ps1`198  - `tools/packaging/releaseTests/sbom.tests.ps1`199