如何使用PowerShell Pester测试ThrowTerminatingError及捕获块抛出场景

嘿，我来帮你解决这两个关于PowerShell Pester测试ThrowTerminatingError的问题，这俩场景我之前做脚本测试时都碰到过，分享下具体的实现方法：

当你的函数直接通过$PSCmdlet.ThrowTerminatingError()抛出终止错误时，Pester需要用脚本块包裹函数调用才能捕获到终止错误——因为终止错误会直接终止当前管道，直接写命令的话Should -Throw根本没机会执行。

先看一个简化的被测函数示例：

function Test-ServerOnline {
    [CmdletBinding()]
    param(
        [string]$ServerName
    )

    # 构造一个自定义错误记录
    $errorRecord = [System.Management.Automation.ErrorRecord]::new(
        [System.Exception]::new("Server $ServerName is unreachable"),
        "ServerUnreachable",
        [System.Management.Automation.ErrorCategory]::ConnectionError,
        $ServerName
    )

    $PSCmdlet.ThrowTerminatingError($errorRecord)
}

对应的Pester测试可以这么写：

Describe "Test-ServerOnline" {
    It "Throws a terminating error with correct ErrorId when server is unreachable" {
        # 必须把函数调用放在脚本块里！
        { Test-ServerOnline -ServerName "DeadServer" } | Should -Throw -ErrorId "ServerUnreachable"
    }

    It "Throws a terminating error with matching error message" {
        { Test-ServerOnline -ServerName "DeadServer" } | Should -Throw "Server DeadServer is unreachable"
    }

    # 进阶：验证错误的类别等属性
    It "Throws a terminating error with ConnectionError category" {
        $caughtError = $null
        # 用-PassThru捕获错误对象，后续断言细节
        { Test-ServerOnline -ServerName "DeadServer" } | Should -Throw -ErrorId "ServerUnreachable" -PassThru | Tee-Object -Variable caughtError | Out-Null
        
        $caughtError.CategoryInfo.Category | Should -Be [System.Management.Automation.ErrorCategory]::ConnectionError
    }
}

这种场景是函数内部用try/catch捕获异常，然后把捕获到的错误记录（$PSItem）转成终止错误抛出。测试的核心是先触发catch块的执行条件，再验证抛出的终止错误。

推荐用Mock来模拟依赖命令的异常，避免依赖真实环境（比如真实的网络连接）。看示例：

被测函数：

function Test-ServerOnline {
    [CmdletBinding()]
    param(
        [string]$ServerName
    )

    try {
        # 尝试连接服务器，失败时抛出异常（-ErrorAction Stop确保转成终止错误）
        Test-Connection -ComputerName $ServerName -Count 1 -ErrorAction Stop
    }
    catch {
        # 将捕获到的错误重新抛出为终止错误
        $PSCmdlet.ThrowTerminatingError($PSItem)
    }
}

对应的Pester测试：

Describe "Test-ServerOnline with try/catch error handling" {
    BeforeAll {
        # 提前Mock Test-Connection，避免真实调用
        Mock Test-Connection {}
    }

    It "Throws a terminating error when connection fails" {
        # 配置Mock，当传入BadServer时抛出指定异常
        Mock Test-Connection { 
            throw [System.Net.NetworkInformation.PingException]::new("Ping failed") 
        } -ParameterFilter { $ComputerName -eq "BadServer" }

        # 同样用脚本块包裹调用，捕获终止错误
        { Test-ServerOnline -ServerName "BadServer" } | Should -Throw -ExceptionType [System.Net.NetworkInformation.PingException]
    }

    It "Does not throw an error when server is reachable" {
        # 配置Mock，当传入GoodServer时返回成功
        Mock Test-Connection { return $true } -ParameterFilter { $ComputerName -eq "GoodServer" }

        { Test-ServerOnline -ServerName "GoodServer" } | Should -Not -Throw
    }
}

几个通用注意事项： #

• 永远用脚本块包裹要测试的命令：{ 你的命令 } | Should -Throw，否则终止错误会直接终止测试流程，Should根本执行不到。
• 用-ErrorId来匹配错误比匹配消息更可靠——消息可能会变，但ErrorId一般是固定的。
• 如果需要验证错误的细节（比如类别、目标对象），用-PassThru捕获错误对象后再做断言。

内容的提问来源于stack exchange，提问作者Eric Dunn