Copilot instructions

1---
2applyTo:
3  - "**/*.Tests.ps1"
4---
5 
6# Pester Set-ItResult Pattern for Pending and Skipped Tests
7 
8## Purpose
9 
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-ItResult
13 
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 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
35It "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 
52After calling `Set-ItResult`, you **must** return from the test to prevent further execution:
53 
54```powershell
55It "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
73It "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
87It "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
100It "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
113It "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 
126For 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
130It "Windows-only test" -Skip:(-not $IsWindows) {
131    # test code
132}
133 
134# Static pending - always pending
135It "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 
1521. **Always include -Because parameter** with a clear explanation
1532. **Always return after Set-ItResult** to prevent further execution
1543. **Reference issues or documentation** when relevant (e.g., "See issue #1234")
1554. **Be specific in the reason** - explain what's wrong and what's needed
1565. **Use Pending sparingly** - it indicates a problem that should be fixed
1576. **Prefer Skipped over Pending** when test truly isn't applicable
158 
159## Common Mistakes
160 
161### ❌ Mistake 1: Forgetting to Return
162 
163```powershell
164It "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
176Set-ItResult -Pending -Because "Doesn't work"  # Too vague
177```
178 
179### ✅ Correct:
180 
181```powershell
182It "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`
199