Testing Overview
Relevant source files
The following files were used as context for generating this wiki page:
The PowerShell project utilizes a multi-layered testing strategy to ensure cross-platform stability, language accuracy, and infrastructure integrity. Tests are primarily organized by the implementation language and the specific subsystem they validate. This includes Pester tests for PowerShell-level logic and xUnit tests for the underlying C# codebase.
Sources: test/README.md:1-10
Testing Frameworks and Organization
Testing in PowerShell is categorized into three main areas based on the toolset and target language:
- Pester Tests: Written in the PowerShell language and located in
./test/powershell. These are used for validating cmdlets, the engine, and language features. - xUnit Tests: Written in C# and located in
./test/xUnit. These target the core framework components. - Specialized Tests: Includes third-party shebang tests and packaging validation scripts.
Sources: test/README.md:1-10, test/powershell/README.md:1-5
Pester Execution Workflow
The primary entry point for running PowerShell-based tests is the Start-PSPester command. This utility is executed within a self-hosted copy of PowerShell to validate current builds.
The diagram shows the standard flow for executing Pester tests, highlighting the requirement for using the development copy of PowerShell with profiles disabled.
Sources: test/powershell/README.md:7-12
Test Categories and Tags
Tests are categorized using tags to facilitate selective execution in different environments, such as Continuous Integration (CI) or local feature development.
| Tag | Purpose | Example File |
|---|---|---|
CI | Fast, reliable tests required for every pull request to ensure core functionality. | HelpSystem.Tests.ps1 |
Feature | Comprehensive functional tests for specific subsystems or cmdlets. | ConsoleHost.Tests.ps1 |
Slow | Resource-intensive tests, often involving UI or long-running processes. | ConsoleHost.Tests.ps1 |
RequireAdminOnWindows | Tests requiring elevated privileges to interact with system components like WinRM. | ConfigProvider.Tests.ps1 |
Sources: test/powershell/engine/Help/HelpSystem.Tests.ps1:41, test/powershell/Host/ConsoleHost.Tests.ps1:60, test/powershell/Host/ConsoleHost.Tests.ps1:621
Subsystem Validation
Console Host and Native Interop
The ConsoleHost tests validate the behavior of the PowerShell executable (pwsh). This includes verifying how PowerShell handles standard streams (StdIn, StdOut, StdErr) and how it interacts with native executables via "minishell" concepts.
This diagram illustrates the inter-process communication validated in host tests, where objects are marshaled between parent and child processes.
Sources: test/powershell/Host/ConsoleHost.Tests.ps1:10-58
Infrastructure and Package Testing
PowerShell includes infrastructure tests that run during the CI pipeline to maintain repository health:
- Merge Conflict Markers: A specialized function
Test-MergeConflictMarkerscans files for Git markers (e.g.,<<<<<<<,=======) to prevent broken merges from reaching the main branch. - SBOM (Software Bill of Materials): Verification tests ensure that every released package contains an accurate BOM manifest and that file hashes match the manifest records.
Sources: test/infrastructure/ciModule.Tests.ps1:10-50, tools/packaging/releaseTests/sbom.tests.ps1:1-30
Portability and Test Status
To support Windows, Linux, and macOS, the test suite utilizes Pester’s conditional skipping logic. This ensures that platform-specific features (like Windows-only WSMan or Unix-only login shells) do not cause false failures on incompatible systems.
- Skip Logic: Use
-Skip:($IsLinux -Or $IsMacOS)for Windows-only tests. - Pending Status: Tests that should pass but currently fail due to known bugs are marked with the
-Pendingparameter to track technical debt without breaking CI.
Sources: test/powershell/README.md:20-33, test/powershell/Host/ConsoleHost.Tests.ps1:665-680
Conclusion
The PowerShell testing infrastructure is designed to be as cross-platform as the tool itself. By leveraging Pester for cmdlet and language validation, and integrating specialized CI modules for infrastructure health and SBOM accuracy, the project ensures high reliability across diverse environments.
Sources: test/README.md, test/powershell/README.md