{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"powershell-pester-5","version":"0.1.0"},"spec":{"agents_md":"---\napplyTo: '**/*.Tests.ps1'\ndescription: 'PowerShell Pester testing best practices based on Pester v5 conventions'\n---\n\n# PowerShell Pester v5 Testing Guidelines\n\nThis guide provides PowerShell-specific instructions for creating automated tests using PowerShell Pester v5 module. Follow PowerShell cmdlet development guidelines in [powershell.instructions.md](./powershell.instructions.md) for general PowerShell scripting best practices.\n\n## File Naming and Structure\n\n- **File Convention:** Use `*.Tests.ps1` naming pattern\n- **Placement:** Place test files next to tested code or in dedicated test directories\n- **Import Pattern:** Use `BeforeAll { . $PSScriptRoot/FunctionName.ps1 }` to import tested functions\n- **No Direct Code:** Put ALL code inside Pester blocks (`BeforeAll`, `Describe`, `Context`, `It`, etc.)\n\n## Test Structure Hierarchy\n\n```powershell\nBeforeAll { # Import tested functions }\nDescribe 'FunctionName' {\n    Context 'When condition' {\n        BeforeAll { # Setup for context }\n        It 'Should behavior' { # Individual test }\n        AfterAll { # Cleanup for context }\n    }\n}\n```\n\n## Core Keywords\n\n- **`Describe`**: Top-level grouping, typically named after function being tested\n- **`Context`**: Sub-grouping within Describe for specific scenarios\n- **`It`**: Individual test cases, use descriptive names\n- **`Should`**: Assertion keyword for test validation\n- **`BeforeAll/AfterAll`**: Setup/teardown once per block\n- **`BeforeEach/AfterEach`**: Setup/teardown before/after each test\n\n## Setup and Teardown\n\n- **`BeforeAll`**: Runs once at start of containing block, use for expensive operations\n- **`BeforeEach`**: Runs before every `It` in block, use for test-specific setup\n- **`AfterEach`**: Runs after every `It`, guaranteed even if test fails\n- **`AfterAll`**: Runs once at end of block, use for cleanup\n- **Variable Scoping**: `BeforeAll` variables available to child blocks (read-only), `BeforeEach/It/AfterEach` share same scope\n\n## Assertions (Should)\n\n- **Basic Comparisons**: `-Be`, `-BeExactly`, `-Not -Be`\n- **Collections**: `-Contain`, `-BeIn`, `-HaveCount`\n- **Numeric**: `-BeGreaterThan`, `-BeLessThan`, `-BeGreaterOrEqual`\n- **Strings**: `-Match`, `-Like`, `-BeNullOrEmpty`\n- **Types**: `-BeOfType`, `-BeTrue`, `-BeFalse`\n- **Files**: `-Exist`, `-FileContentMatch`\n- **Exceptions**: `-Throw`, `-Not -Throw`\n\n## Mocking\n\n- **`Mock CommandName { ScriptBlock }`**: Replace command behavior\n- **`-ParameterFilter`**: Mock only when parameters match condition\n- **`-Verifiable`**: Mark mock as requiring verification\n- **`Should -Invoke`**: Verify mock was called specific number of times\n- **`Should -InvokeVerifiable`**: Verify all verifiable mocks were called\n- **Scope**: Mocks default to containing block scope\n\n```powershell\nMock Get-Service { @{ Status = 'Running' } } -ParameterFilter { $Name -eq 'TestService' }\nShould -Invoke Get-Service -Exactly 1 -ParameterFilter { $Name -eq 'TestService' }\n```\n\n## Test Cases (Data-Driven Tests)\n\nUse `-TestCases` or `-ForEach` for parameterized tests:\n\n```powershell\nIt 'Should return \u003cExpected\u003e for \u003cInput\u003e' -TestCases @(\n    @{ Input = 'value1'; Expected = 'result1' }\n    @{ Input = 'value2'; Expected = 'result2' }\n) {\n    Get-Function $Input | Should -Be $Expected\n}\n```\n\n## Data-Driven Tests\n\n- **`-ForEach`**: Available on `Describe`, `Context`, and `It` for generating multiple tests from data\n- **`-TestCases`**: Alias for `-ForEach` on `It` blocks (backwards compatibility)\n- **Hashtable Data**: Each item defines variables available in test (e.g., `@{ Name = 'value'; Expected = 'result' }`)\n- **Array Data**: Uses `$_` variable for current item\n- **Templates**: Use `\u003cvariablename\u003e` in test names for dynamic expansion\n\n```powershell\n# Hashtable approach\nIt 'Returns \u003cExpected\u003e for \u003cName\u003e' -ForEach @(\n    @{ Name = 'test1'; Expected = 'result1' }\n    @{ Name = 'test2'; Expected = 'result2' }\n) { Get-Function $Name | Should -Be $Expected }\n\n# Array approach\nIt 'Contains \u003c_\u003e' -ForEach 'item1', 'item2' { Get-Collection | Should -Contain $_ }\n```\n\n## Tags\n\n- **Available on**: `Describe`, `Context`, and `It` blocks\n- **Filtering**: Use `-TagFilter` and `-ExcludeTagFilter` with `Invoke-Pester`\n- **Wildcards**: Tags support `-like` wildcards for flexible filtering\n\n```powershell\nDescribe 'Function' -Tag 'Unit' {\n    It 'Should work' -Tag 'Fast', 'Stable' { }\n    It 'Should be slow' -Tag 'Slow', 'Integration' { }\n}\n\n# Run only fast unit tests\nInvoke-Pester -TagFilter 'Unit' -ExcludeTagFilter 'Slow'\n```\n\n## Skip\n\n- **`-Skip`**: Available on `Describe`, `Context`, and `It` to skip tests\n- **Conditional**: Use `-Skip:$condition` for dynamic skipping\n- **Runtime Skip**: Use `Set-ItResult -Skipped` during test execution (setup/teardown still run)\n\n```powershell\nIt 'Should work on Windows' -Skip:(-not $IsWindows) { }\nContext 'Integration tests' -Skip { }\n```\n\n## Error Handling\n\n- **Continue on Failure**: Use `Should.ErrorAction = 'Continue'` to collect multiple failures\n- **Stop on Critical**: Use `-ErrorAction Stop` for pre-conditions\n- **Test Exceptions**: Use `{ Code } | Should -Throw` for exception testing\n\n## Best Practices\n\n- **Descriptive Names**: Use clear test descriptions that explain behavior\n- **AAA Pattern**: Arrange (setup), Act (execute), Assert (verify)\n- **Isolated Tests**: Each test should be independent\n- **Avoid Aliases**: Use full cmdlet names (`Where-Object` not `?`)\n- **Single Responsibility**: One assertion per test when possible\n- **Test File Organization**: Group related tests in Context blocks. Context blocks can be nested.\n\n## Example Test Pattern\n\n```powershell\nBeforeAll {\n    . $PSScriptRoot/Get-UserInfo.ps1\n}\n\nDescribe 'Get-UserInfo' {\n    Context 'When user exists' {\n        BeforeAll {\n            Mock Get-ADUser { @{ Name = 'TestUser'; Enabled = $true } }\n        }\n\n        It 'Should return user object' {\n            $result = Get-UserInfo -Username 'TestUser'\n            $result | Should -Not -BeNullOrEmpty\n            $result.Name | Should -Be 'TestUser'\n        }\n\n        It 'Should call Get-ADUser once' {\n            Get-UserInfo -Username 'TestUser'\n            Should -Invoke Get-ADUser -Exactly 1\n        }\n    }\n\n    Context 'When user does not exist' {\n        BeforeAll {\n            Mock Get-ADUser { throw \"User not found\" }\n        }\n\n        It 'Should throw exception' {\n            { Get-UserInfo -Username 'NonExistent' } | Should -Throw \"*not found*\"\n        }\n    }\n}\n```\n\n## Configuration\n\nConfiguration is defined **outside** test files when calling `Invoke-Pester` to control execution behavior.\n\n```powershell\n# Create configuration (Pester 5.2+)\n$config = New-PesterConfiguration\n$config.Run.Path = './Tests'\n$config.Output.Verbosity = 'Detailed'\n$config.TestResult.Enabled = $true\n$config.TestResult.OutputFormat = 'NUnitXml'\n$config.Should.ErrorAction = 'Continue'\nInvoke-Pester -Configuration $config\n```\n\n**Key Sections**: Run (Path, Exit), Filter (Tag, ExcludeTag), Output (Verbosity), TestResult (Enabled, OutputFormat), CodeCoverage (Enabled, Path), Should (ErrorAction), Debug\n","description":"PowerShell Pester testing best practices based on Pester v5 conventions","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/powershell-pester-5.instructions.md"},"manifest":{}},"content_hash":[164,63,26,95,181,102,159,236,69,184,235,18,254,146,209,55,23,1,119,236,5,194,46,61,157,93,83,89,132,23,180,49],"trust_level":"unsigned","yanked":false}