|
| 1 | +--- |
| 2 | +applyTo: |
| 3 | + - "**/*.Tests.ps1" |
| 4 | +--- |
| 5 | + |
| 6 | +# Pester Set-ItResult Pattern for Pending and Skipped Tests |
| 7 | + |
| 8 | +## Purpose |
| 9 | + |
| 10 | +This 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-ItResult |
| 13 | + |
| 14 | +Use `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 Skipped |
| 17 | + |
| 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 fixed |
| 21 | +- Missing features being implemented |
| 22 | +- Environmental issues that are being resolved |
| 23 | + |
| 24 | +**Skipped**: Use for tests that aren't applicable to the current environment: |
| 25 | +- Platform-specific tests running on wrong platform |
| 26 | +- Tests requiring specific hardware/configuration not present |
| 27 | +- Tests requiring elevated permissions when not available |
| 28 | +- Feature-specific tests when feature is disabled |
| 29 | + |
| 30 | +## Pattern |
| 31 | + |
| 32 | +### Basic Usage |
| 33 | + |
| 34 | +```powershell |
| 35 | +It "Test description" { |
| 36 | + if ($shouldBePending) { |
| 37 | + Set-ItResult -Pending -Because "Explanation of why test is pending" |
| 38 | + return |
| 39 | + } |
| 40 | + |
| 41 | + if ($shouldBeSkipped) { |
| 42 | + Set-ItResult -Skipped -Because "Explanation of why test is skipped" |
| 43 | + return |
| 44 | + } |
| 45 | + |
| 46 | + # Test code here |
| 47 | +} |
| 48 | +``` |
| 49 | + |
| 50 | +### Important: Always Return After Set-ItResult |
| 51 | + |
| 52 | +After calling `Set-ItResult`, you **must** return from the test to prevent further execution: |
| 53 | + |
| 54 | +```powershell |
| 55 | +It "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 assertions |
| 62 | + $result | Should -Be $expected |
| 63 | +} |
| 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 Codebase |
| 69 | + |
| 70 | +### Example 1: Pending for Intermittent Network Issues |
| 71 | + |
| 72 | +```powershell |
| 73 | +It "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 | + return |
| 77 | + } |
| 78 | + |
| 79 | + Update-Help -Module $moduleName -Force |
| 80 | + # validation code... |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +### Example 2: Skipped for Missing Environment |
| 85 | + |
| 86 | +```powershell |
| 87 | +It "Test requires CI environment" { |
| 88 | + if (-not $env:CI) { |
| 89 | + Set-ItResult -Skipped -Because "Test requires CI environment to safely install Pester" |
| 90 | + return |
| 91 | + } |
| 92 | + |
| 93 | + Install-CIPester -ErrorAction Stop |
| 94 | +} |
| 95 | +``` |
| 96 | + |
| 97 | +### Example 3: Pending for Platform-Specific Issue |
| 98 | + |
| 99 | +```powershell |
| 100 | +It "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 | + return |
| 104 | + } |
| 105 | + |
| 106 | + & { Clear-Host; 'hi' } | Should -BeExactly 'hi' |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +### Example 4: Skipped for Missing Feature |
| 111 | + |
| 112 | +```powershell |
| 113 | +It "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 | + return |
| 117 | + } |
| 118 | + |
| 119 | + $psgetModuleInfo = Find-PSResource -Name $ACRTestModule -Repository $ACRRepositoryName |
| 120 | + # test assertions... |
| 121 | +} |
| 122 | +``` |
| 123 | + |
| 124 | +## Alternative: Static -Skip and -Pending Parameters |
| 125 | + |
| 126 | +For conditions that can be determined at test definition time, use the static parameters instead: |
| 127 | + |
| 128 | +```powershell |
| 129 | +# Static skip - condition known at definition time |
| 130 | +It "Windows-only test" -Skip:(-not $IsWindows) { |
| 131 | + # test code |
| 132 | +} |
| 133 | +
|
| 134 | +# Static pending - always pending |
| 135 | +It "Test for feature being implemented" -Pending { |
| 136 | + # test code that will fail until feature is done |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +**Use Set-ItResult when**: |
| 141 | +- Condition depends on runtime state |
| 142 | +- Condition is determined inside a helper function |
| 143 | +- Need to check multiple conditions sequentially |
| 144 | + |
| 145 | +**Use static parameters when**: |
| 146 | +- Condition is known at test definition |
| 147 | +- Condition doesn't change during test run |
| 148 | +- Want Pester to show the condition in test discovery |
| 149 | + |
| 150 | +## Best Practices |
| 151 | + |
| 152 | +1. **Always include -Because parameter** with a clear explanation |
| 153 | +2. **Always return after Set-ItResult** to prevent further execution |
| 154 | +3. **Reference issues or documentation** when relevant (e.g., "See issue #1234") |
| 155 | +4. **Be specific in the reason** - explain what's wrong and what's needed |
| 156 | +5. **Use Pending sparingly** - it indicates a problem that should be fixed |
| 157 | +6. **Prefer Skipped over Pending** when test truly isn't applicable |
| 158 | + |
| 159 | +## Common Mistakes |
| 160 | + |
| 161 | +### ❌ Mistake 1: Forgetting to Return |
| 162 | + |
| 163 | +```powershell |
| 164 | +It "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 fails |
| 170 | +} |
| 171 | +``` |
| 172 | + |
| 173 | +### ❌ Mistake 2: Vague Reason |
| 174 | + |
| 175 | +```powershell |
| 176 | +Set-ItResult -Pending -Because "Doesn't work" # Too vague |
| 177 | +``` |
| 178 | + |
| 179 | +### ✅ Correct: |
| 180 | + |
| 181 | +```powershell |
| 182 | +It "Test" { |
| 183 | + if ($condition) { |
| 184 | + Set-ItResult -Pending -Because "Update-Help has intermittent network timeouts. See issue #2807." |
| 185 | + return |
| 186 | + } |
| 187 | + $value | Should -Be $expected |
| 188 | +} |
| 189 | +``` |
| 190 | + |
| 191 | +## See Also |
| 192 | + |
| 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` |
0 commit comments