functions/Invoke-ArmDeployment.Tests.ps1

# <copyright file="Invoke-ArmDeployment.Tests.ps1" company="Endjin Limited">
# Copyright (c) Endjin Limited. All rights reserved.
# </copyright>

BeforeDiscovery {
    # Needed at discovery time to build the '-ForEach' test cases
    $discoveryCmdlets = @{
        resourceGroup   = 'New-AzResourceGroupDeployment'
        subscription    = 'New-AzSubscriptionDeployment'
        managementGroup = 'New-AzManagementGroupDeployment'
        tenant          = 'New-AzTenantDeployment'
    }
}

BeforeAll {
    # sut
    . $PSCommandPath.Replace('.Tests.ps1','.ps1')

    # Stubs for the external commands, so they can be mocked without Az.Resources or ZeroFailed.
    # Their parameters mirror the real cmdlets, so an unsupported parameter (e.g. 'Location' at
    # resource group scope) fails here as it would in a real deployment.
    function New-AzResourceGroupDeployment {
        [CmdletBinding()]
        param ($Name, $ResourceGroupName, $TemplateFile, $TemplateParameterFile, [hashtable] $TemplateParameterObject, [switch] $WhatIf)
    }
    function New-AzSubscriptionDeployment {
        [CmdletBinding()]
        param ($Name, $Location, $TemplateFile, $TemplateParameterFile, [hashtable] $TemplateParameterObject, [switch] $WhatIf)
    }
    function New-AzManagementGroupDeployment {
        [CmdletBinding()]
        param ($Name, $ManagementGroupId, $Location, $TemplateFile, $TemplateParameterFile, [hashtable] $TemplateParameterObject, [switch] $WhatIf)
    }
    function New-AzTenantDeployment {
        [CmdletBinding()]
        param ($Name, $Location, $TemplateFile, $TemplateParameterFile, [hashtable] $TemplateParameterObject, [switch] $WhatIf)
    }
    function Get-AzResourceGroup { [CmdletBinding()] param ($Name) }
    function New-AzResourceGroup { [CmdletBinding()] param ($Name, $Location) }
    function Get-AzContext { [CmdletBinding()] param () }
    function Set-AzContext { [CmdletBinding()] param ($Subscription, $Context, $Scope) }
    # Provided by the ZeroFailed module at runtime
    function Resolve-Value { param ($Value) if ($Value -is [scriptblock]) { & $Value } else { $Value } }

    $script:deploymentCmdlets = @{
        resourceGroup   = 'New-AzResourceGroupDeployment'
        subscription    = 'New-AzSubscriptionDeployment'
        managementGroup = 'New-AzManagementGroupDeployment'
        tenant          = 'New-AzTenantDeployment'
    }

    function New-TestDeployment {
        param ([string] $Scope, [string] $Extension = '.bicep')
        $entry = @{ scope = $Scope; templatePath = "main$Extension"; location = 'uksouth' }
        switch ($Scope) {
            'resourceGroup'   { $entry.resourceGroupName = 'rg-test' }
            'managementGroup' { $entry.managementGroupId = 'mg-test' }
        }
        return $entry
    }

    Set-StrictMode -Version Latest
}

Describe 'Invoke-ArmDeployment' {

    BeforeEach {
        $script:calls = [System.Collections.Generic.List[string]]::new()
        $successResult = [PSCustomObject]@{ ProvisioningState = 'Succeeded'; Outputs = @{ out1 = @{ Value = 'a' } } }

        # Not '$cmdlet': variable names are case-insensitive, and the test cases define '$Cmdlet'
        foreach ($deploymentCmdlet in $script:deploymentCmdlets.Values) {
            Mock $deploymentCmdlet { $script:calls.Add('deploy'); $successResult }
        }
        Mock Get-AzResourceGroup { $script:calls.Add('getResourceGroup'); [PSCustomObject]@{ ResourceGroupName = $Name } }
        Mock New-AzResourceGroup { [PSCustomObject]@{ ResourceGroupName = $Name } }
        Mock Get-AzContext { [PSCustomObject]@{ Name = 'original' } }
        Mock Set-AzContext { $script:calls.Add('setContext') }
        Mock Write-Host {}
        Mock Write-Warning {}
    }

    Context 'Scope routing' {

        It '<Scope> scope with a <Extension> file in <Mode> mode calls <Cmdlet>' -ForEach @(
            foreach ($scope in 'resourceGroup', 'subscription', 'managementGroup', 'tenant') {
                foreach ($extension in '.bicep', '.bicepparam') {
                    foreach ($mode in 'deploy', 'what-if') {
                        @{ Scope = $scope; Extension = $extension; Mode = $mode; Cmdlet = $discoveryCmdlets[$scope] }
                    }
                }
            }
        ) {
            $isWhatIf = $Mode -eq 'what-if'
            $entry = New-TestDeployment -Scope $Scope -Extension $Extension

            $result = Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{ p1 = 'v1' } -WhatIfMode:$isWhatIf

            Should -Invoke $Cmdlet -Times 1 -Exactly -ParameterFilter {
                # An unbound switch is $null in a parameter filter
                [bool] $WhatIf -eq $isWhatIf -and
                $(if ($Extension -eq '.bicepparam') {
                    $TemplateParameterFile -eq 'main.bicepparam' -and !$TemplateFile -and !$TemplateParameterObject
                } else {
                    $TemplateFile -eq 'main.bicep' -and $TemplateParameterObject.p1 -eq 'v1' -and !$TemplateParameterFile
                })
            }
            foreach ($other in ($script:deploymentCmdlets.Values | Where-Object { $_ -ne $Cmdlet })) {
                Should -Not -Invoke $other
            }
            if ($isWhatIf) {
                $result | Should -BeNullOrEmpty
            }
            else {
                @($result).Count | Should -Be 1
                $result.ProvisioningState | Should -Be 'Succeeded'
                $result.Outputs.out1.Value | Should -Be 'a'
            }
        }

        It 'Passes the management group id at management group scope' {
            Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope managementGroup) -DeploymentConfig @{}

            Should -Invoke New-AzManagementGroupDeployment -Times 1 -ParameterFilter { $ManagementGroupId -eq 'mg-test' -and $Location -eq 'uksouth' }
        }

        It 'Does not pass a location at resource group scope' {
            # The stub, like the real cmdlet, has no 'Location' parameter, so passing one would throw
            { Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope resourceGroup) -DeploymentConfig @{} } | Should -Not -Throw

            Should -Invoke New-AzResourceGroupDeployment -Times 1 -ParameterFilter { $ResourceGroupName -eq 'rg-test' }
        }

        It 'Defaults to resource group scope when no scope is given' {
            $entry = New-TestDeployment -Scope resourceGroup
            $entry.Remove('scope')

            Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{}

            Should -Invoke New-AzResourceGroupDeployment -Times 1
        }
    }

    Context 'Validation' {

        It 'Throws for an unknown scope' {
            $entry = New-TestDeployment -Scope resourceGroup
            $entry.scope = 'galaxy'

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} } | Should -Throw "*unsupported scope 'galaxy'*"
        }

        It 'Throws when <Missing> is missing at <Scope> scope' -ForEach @(
            @{ Scope = 'resourceGroup'; Missing = 'resourceGroupName' }
            @{ Scope = 'managementGroup'; Missing = 'managementGroupId' }
            @{ Scope = 'subscription'; Missing = 'templatePath' }
            @{ Scope = 'tenant'; Missing = 'location' }
        ) {
            $entry = New-TestDeployment -Scope $Scope
            $entry.Remove($Missing)

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} } | Should -Throw "*missing required properties: $Missing*"
        }

        It 'Throws for a subscriptionId at <Scope> scope' -ForEach @(
            @{ Scope = 'managementGroup' }
            @{ Scope = 'tenant' }
        ) {
            $entry = New-TestDeployment -Scope $Scope
            $entry.subscriptionId = '11111111-1111-1111-1111-111111111111'

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} } | Should -Throw "*'subscriptionId' is only supported*"
            Should -Not -Invoke Set-AzContext
        }
    }

    Context 'Template parameters' {

        It 'Merges the environment config with additionalParameters, and skips empty and ignored keys' {
            $entry = New-TestDeployment -Scope subscription
            $entry.additionalParameters = @{ p1 = 'override'; p3 = { 'deferred' } }
            $entry.configKeysToIgnore = @('ignored')

            Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{ p1 = 'v1'; p2 = 'v2'; empty = ''; ignored = 'x' }

            Should -Invoke New-AzSubscriptionDeployment -Times 1 -ParameterFilter {
                $TemplateParameterObject.p1 -eq 'override' -and
                $TemplateParameterObject.p2 -eq 'v2' -and
                $TemplateParameterObject.p3 -eq 'deferred' -and
                !$TemplateParameterObject.ContainsKey('empty') -and
                !$TemplateParameterObject.ContainsKey('ignored')
            }
        }

        It 'Passes a single-item array parameter as an array' {
            $entry = New-TestDeployment -Scope resourceGroup

            Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{ allowedIps = @('10.0.0.1'); tags = @{ env = 'dev' } }

            Should -Invoke New-AzResourceGroupDeployment -Times 1 -Exactly -ParameterFilter {
                $TemplateParameterObject.allowedIps -is [array] -and
                $TemplateParameterObject.allowedIps.Count -eq 1 -and
                $TemplateParameterObject.allowedIps[0] -eq '10.0.0.1' -and
                $TemplateParameterObject.tags -is [hashtable]
            }
        }

        It 'Keeps the parameters of two deployments separate' {
            $script:parameterSets = [System.Collections.Generic.List[hashtable]]::new()
            Mock New-AzSubscriptionDeployment { $script:parameterSets.Add($TemplateParameterObject); [PSCustomObject]@{ ProvisioningState = 'Succeeded' } }
            $first = New-TestDeployment -Scope subscription
            $first.additionalParameters = @{ onlyFirst = 'x' }

            Invoke-ArmDeployment -ArmDeployment $first -DeploymentConfig @{ p1 = 'v1' }
            Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{ p1 = 'v1' }

            $script:parameterSets[0].ContainsKey('onlyFirst') | Should -BeTrue
            $script:parameterSets[1].ContainsKey('onlyFirst') | Should -BeFalse
        }

        It 'Throws for additionalParameters with a .bicepparam file' {
            $entry = New-TestDeployment -Scope subscription -Extension '.bicepparam'
            $entry.additionalParameters = @{ p1 = 'x' }

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} } | Should -Throw "*'additionalParameters' are not supported with a '.bicepparam' file*"
            Should -Not -Invoke New-AzSubscriptionDeployment
        }
    }

    Context 'Missing resource group' {

        BeforeEach {
            Mock Get-AzResourceGroup { $null }
        }

        It 'Skips the what-if and creates nothing' {
            $result = Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope resourceGroup) -DeploymentConfig @{} -WhatIfMode

            $result | Should -BeNullOrEmpty
            Should -Not -Invoke New-AzResourceGroup
            Should -Not -Invoke New-AzResourceGroupDeployment
            Should -Invoke Write-Warning -Times 1 -ParameterFilter { $Message -like "*'rg-test' does not exist*" }
        }

        It 'Creates the resource group in a real run, and returns only the deployment result' {
            $result = Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope resourceGroup) -DeploymentConfig @{}

            Should -Invoke New-AzResourceGroup -Times 1 -ParameterFilter { $Name -eq 'rg-test' -and $Location -eq 'uksouth' }
            @($result).Count | Should -Be 1
            $result.ProvisioningState | Should -Be 'Succeeded'
        }
    }

    Context 'Subscription selection' {

        It 'Switches subscription before the resource group check at <Scope> scope, in <Mode> mode' -ForEach @(
            @{ Scope = 'resourceGroup'; Mode = 'deploy' }
            @{ Scope = 'resourceGroup'; Mode = 'what-if' }
            @{ Scope = 'subscription'; Mode = 'deploy' }
            @{ Scope = 'subscription'; Mode = 'what-if' }
        ) {
            $entry = New-TestDeployment -Scope $Scope
            $entry.subscriptionId = '11111111-1111-1111-1111-111111111111'

            Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} -WhatIfMode:($Mode -eq 'what-if')

            Should -Invoke Set-AzContext -Times 1 -Exactly -ParameterFilter { $Subscription -eq '11111111-1111-1111-1111-111111111111' -and $Scope -eq 'Process' }
            $script:calls[0] | Should -Be 'setContext'
            Should -Invoke Set-AzContext -Times 1 -Exactly -ParameterFilter { $Context.Name -eq 'original' -and $Scope -eq 'Process' }
        }

        It 'Evaluates deferred values after the subscription switch' {
            $entry = New-TestDeployment -Scope subscription
            $entry.subscriptionId = '11111111-1111-1111-1111-111111111111'
            $entry.templatePath = { $script:calls.Add('resolveTemplatePath'); 'main.bicep' }
            $entry.additionalParameters = @{ p1 = { $script:calls.Add('resolveParameter'); 'v' } }

            Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{}

            $script:calls[0] | Should -Be 'setContext'
            $script:calls | Should -Contain 'resolveTemplatePath'
            $script:calls | Should -Contain 'resolveParameter'
        }

        It 'Restores the context after a skipped what-if for a missing resource group' {
            Mock Get-AzResourceGroup { $null }
            $entry = New-TestDeployment -Scope resourceGroup
            $entry.subscriptionId = '11111111-1111-1111-1111-111111111111'

            Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} -WhatIfMode | Should -BeNullOrEmpty

            Should -Invoke Set-AzContext -Times 1 -Exactly -ParameterFilter { $Context.Name -eq 'original' }
        }

        It 'Makes no context switch without a subscriptionId' {
            Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{}

            Should -Not -Invoke Get-AzContext
            Should -Not -Invoke Set-AzContext
        }

        It 'Leaves a later deployment without a subscriptionId in the original context' {
            $first = New-TestDeployment -Scope subscription
            $first.subscriptionId = '11111111-1111-1111-1111-111111111111'

            Invoke-ArmDeployment -ArmDeployment $first -DeploymentConfig @{}
            Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{}

            # Only the switch and the restore of the first deployment
            Should -Invoke Set-AzContext -Times 2 -Exactly
            $script:calls | Select-Object -Last 1 | Should -Be 'deploy'
        }

        It 'Restores the context when the deployment fails' {
            Mock New-AzSubscriptionDeployment { throw 'Deployment failed' }
            $entry = New-TestDeployment -Scope subscription
            $entry.subscriptionId = '11111111-1111-1111-1111-111111111111'

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} } | Should -Throw '*Deployment failed*'

            Should -Invoke Set-AzContext -Times 1 -Exactly -ParameterFilter { $Context.Name -eq 'original' }
        }

        It 'Restores the context when the subscription switch itself fails' {
            Mock Set-AzContext { throw 'Subscription not found' } -ParameterFilter { $Subscription }
            $entry = New-TestDeployment -Scope subscription
            $entry.subscriptionId = '11111111-1111-1111-1111-111111111111'

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} } | Should -Throw '*Subscription not found*'

            Should -Not -Invoke New-AzSubscriptionDeployment
            Should -Invoke Set-AzContext -Times 1 -Exactly -ParameterFilter { $Context.Name -eq 'original' }
        }

        It 'Keeps the deployment error, and warns, when the restore also fails' {
            Mock New-AzSubscriptionDeployment { throw 'Deployment failed' }
            Mock Set-AzContext { throw 'Restore failed' } -ParameterFilter { $Context }
            $entry = New-TestDeployment -Scope subscription
            $entry.subscriptionId = '11111111-1111-1111-1111-111111111111'

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} } | Should -Throw '*Deployment failed*'

            Should -Invoke Write-Warning -Times 1 -ParameterFilter { $Message -like "*Unable to restore the previous Az context 'original'*Restore failed*" }
        }

        It 'Fails when the restore fails after a successful run, in <Mode> mode' -ForEach @(
            @{ Mode = 'deploy' }
            @{ Mode = 'what-if' }
        ) {
            Mock Set-AzContext { throw 'Restore failed' } -ParameterFilter { $Context }
            $entry = New-TestDeployment -Scope subscription
            $entry.subscriptionId = '11111111-1111-1111-1111-111111111111'

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} -WhatIfMode:($Mode -eq 'what-if') } |
                Should -Throw "*Unable to restore the previous Az context 'original'*Restore failed*"
        }

        It 'Fails when the restore fails after a what-if error with ContinueOnWhatIfError' {
            Mock New-AzSubscriptionDeployment { throw 'What-if failed' }
            Mock Set-AzContext { throw 'Restore failed' } -ParameterFilter { $Context }
            $entry = New-TestDeployment -Scope subscription
            $entry.subscriptionId = '11111111-1111-1111-1111-111111111111'

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} -WhatIfMode -ContinueOnWhatIfError } |
                Should -Throw "*Unable to restore the previous Az context 'original'*Restore failed*"
        }
    }

    Context 'What-if errors' {

        BeforeEach {
            Mock New-AzSubscriptionDeployment { throw 'What-if failed' }
        }

        It 'Reports a what-if error as a warning with ContinueOnWhatIfError' {
            $result = Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{} -WhatIfMode -ContinueOnWhatIfError

            $result | Should -BeNullOrEmpty
            Should -Invoke Write-Warning -Times 1 -ParameterFilter { $Message -like '*ARM what-if failed*What-if failed*' }
        }

        It 'Throws a what-if error without ContinueOnWhatIfError' {
            { Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{} -WhatIfMode } | Should -Throw '*What-if failed*'
        }

        It 'Throws a deployment error even with ContinueOnWhatIfError' {
            { Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{} -ContinueOnWhatIfError } | Should -Throw '*What-if failed*'
        }

        It 'Reports a template build error as a warning with ContinueOnWhatIfError, as HELP.md states' {
            Mock New-AzSubscriptionDeployment { throw 'Bicep build failed: BCP018' }

            $result = Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{} -WhatIfMode -ContinueOnWhatIfError

            $result | Should -BeNullOrEmpty
            Should -Invoke Write-Warning -Times 1 -ParameterFilter { $Message -like '*BCP018*' }
        }

        It 'Includes the error details that Az writes before a validation failure, in <Mode> mode' -ForEach @(
            @{ Mode = 'deploy' }
            @{ Mode = 'what-if' }
        ) {
            # The same pattern as Az.Resources: one error for each error and inner error, then a throw
            Mock New-AzSubscriptionDeployment {
                Write-Error 'Error: Code=InvalidTemplateDeployment; Message=See inner errors for details.'
                Write-Error 'Error: Code=PreflightValidationCheckFailed; Message=Preflight validation failed.'
                Write-Error "Error: Code=AccountNameInvalid; Message='bad_name' is not a valid storage account name."
                throw 'The deployment validation failed'
            }

            { Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{} -WhatIfMode:($Mode -eq 'what-if') } |
                Should -Throw '*InvalidTemplateDeployment*PreflightValidationCheckFailed*AccountNameInvalid*The deployment validation failed*'
        }

        It 'Reports the validation error details as a warning with ContinueOnWhatIfError' {
            Mock New-AzSubscriptionDeployment {
                Write-Error 'Error: Code=InvalidTemplateDeployment; Message=See inner errors for details.'
                Write-Error 'Error: Code=AccountNameInvalid; Message=Bad name.'
                throw 'The deployment validation failed'
            }

            Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{} -WhatIfMode -ContinueOnWhatIfError |
                Should -BeNullOrEmpty
            Should -Invoke Write-Warning -Times 1 -ParameterFilter { $Message -like '*InvalidTemplateDeployment*AccountNameInvalid*' }
        }

        It 'Throws for a failed deployment that Az reports only as a non-terminating error' {
            Mock New-AzSubscriptionDeployment {
                Write-Error "Error: Code=Conflict; Message=Operation failed. (Code: Conflict, Target: '/subscriptions/x')"
                [PSCustomObject]@{ ProvisioningState = 'Failed'; Outputs = $null }
            }

            { Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{} } |
                Should -Throw '*Code=Conflict*Operation failed*'
        }

        It 'Keeps the original exception as the inner exception' {
            $thrown = $null
            try { Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope subscription) -DeploymentConfig @{} -WhatIfMode }
            catch { $thrown = $_ }

            $thrown.Exception.InnerException.Message | Should -Be 'What-if failed'
        }

        It 'Throws a configuration error even with ContinueOnWhatIfError' {
            $entry = New-TestDeployment -Scope subscription
            $entry.scope = 'galaxy'

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} -WhatIfMode -ContinueOnWhatIfError } | Should -Throw '*unsupported scope*'
        }
    }

    Context 'SecureString template parameters' {

        It 'Passes a SecureString from <Source> to the cmdlet as plain text' -ForEach @(
            @{ Source = 'the environment config' }
            @{ Source = 'additionalParameters' }
        ) {
            $secret = ConvertTo-SecureString 's3cret' -AsPlainText -Force
            $entry = New-TestDeployment -Scope resourceGroup
            $config = @{ plain = 'v1' }
            if ($Source -eq 'additionalParameters') { $entry.additionalParameters = @{ secret = { $secret } } }
            else { $config.secret = $secret }

            Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig $config

            Should -Invoke New-AzResourceGroupDeployment -Times 1 -Exactly -ParameterFilter {
                $TemplateParameterObject.secret -is [string] -and
                $TemplateParameterObject.secret -eq 's3cret' -and
                $TemplateParameterObject.plain -eq 'v1'
            }
        }

        It 'Leaves the SecureString in the caller''s configuration' {
            $config = @{ secret = (ConvertTo-SecureString 's3cret' -AsPlainText -Force) }

            Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope resourceGroup) -DeploymentConfig $config

            $config.secret | Should -BeOfType [System.Security.SecureString]
        }

        It 'Does not write the secret value to the log' {
            $config = @{ secret = (ConvertTo-SecureString 's3cret' -AsPlainText -Force) }

            Invoke-ArmDeployment -ArmDeployment (New-TestDeployment -Scope resourceGroup) -DeploymentConfig $config

            Should -Invoke Write-Host -ParameterFilter { "$Object" -like '*System.Security.SecureString*' }
            Should -Not -Invoke Write-Host -ParameterFilter { "$Object" -like '*s3cret*' }
        }
    }

    Context 'Retrying transient errors' {

        BeforeAll {
            # A resource group deployment entry with the given retry settings; omitted settings are not set
            function New-RetryDeployment {
                param ($Patterns, $MaxAttempts, $DelaySeconds)
                $entry = New-TestDeployment -Scope resourceGroup
                if ($PSBoundParameters.ContainsKey('Patterns')) { $entry.retryErrorPatterns = $Patterns }
                if ($PSBoundParameters.ContainsKey('MaxAttempts')) { $entry.retryMaxAttempts = $MaxAttempts }
                if ($PSBoundParameters.ContainsKey('DelaySeconds')) { $entry.retryDelaySeconds = $DelaySeconds }
                return $entry
            }
        }

        BeforeEach {
            Mock Start-Sleep {}
            $script:attempts = 0
            # Fails like Az does for a failed deployment: a non-terminating error beside a 'Failed' result
            Mock New-AzResourceGroupDeployment {
                $script:attempts++
                if ($script:attempts -le $script:failuresBeforeSuccess) {
                    Write-Error $script:failureMessage
                    return [PSCustomObject]@{ ProvisioningState = 'Failed'; Outputs = $null }
                }
                [PSCustomObject]@{ ProvisioningState = 'Succeeded'; Outputs = @{} }
            }
            $script:failureMessage = "Error: Code=InvalidParameterValueInContainerTemplate; Message=Unable to get value using Managed identity for secret 'x'"
        }

        It 'Retries an error that matches a pattern, and returns the successful result' {
            $script:failuresBeforeSuccess = 2
            $entry = New-RetryDeployment -Patterns 'Unable to get value using Managed identity' -MaxAttempts 4 -DelaySeconds 10

            $result = Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{}

            $result.ProvisioningState | Should -Be 'Succeeded'
            @($result).Count | Should -Be 1
            Should -Invoke New-AzResourceGroupDeployment -Times 3 -Exactly
            Should -Invoke Start-Sleep -Times 1 -Exactly -ParameterFilter { $Seconds -eq 10 }
            Should -Invoke Start-Sleep -Times 1 -Exactly -ParameterFilter { $Seconds -eq 20 }
            Should -Invoke Write-Warning -Times 2 -Exactly -ParameterFilter { $Message -like '*ARM deployment attempt * of 4 failed*retrying*' }
        }

        It 'Uses 3 attempts and a 15 second delay by default' {
            $script:failuresBeforeSuccess = 99

            { Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment -Patterns 'Managed identity') -DeploymentConfig @{} } | Should -Throw

            Should -Invoke New-AzResourceGroupDeployment -Times 3 -Exactly
            Should -Invoke Start-Sleep -Times 1 -Exactly -ParameterFilter { $Seconds -eq 15 }
            Should -Invoke Start-Sleep -Times 1 -Exactly -ParameterFilter { $Seconds -eq 30 }
        }

        It 'Applies the retry settings only to their own deployment' {
            $script:failuresBeforeSuccess = 99

            { Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment -Patterns 'Managed identity' -MaxAttempts 2) -DeploymentConfig @{} } | Should -Throw
            Should -Invoke New-AzResourceGroupDeployment -Times 2 -Exactly

            $script:attempts = 0
            { Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment) -DeploymentConfig @{} } | Should -Throw
            Should -Invoke New-AzResourceGroupDeployment -Times 3 -Exactly
        }

        It 'Uses the same deployment name for every attempt' {
            $script:failuresBeforeSuccess = 1
            $script:names = [System.Collections.Generic.List[string]]::new()
            Mock New-AzResourceGroupDeployment {
                $script:names.Add($Name)
                $script:attempts++
                if ($script:attempts -le 1) { Write-Error $script:failureMessage }
            }

            Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment -Patterns 'Managed identity') -DeploymentConfig @{}

            $script:names.Count | Should -Be 2
            $script:names[1] | Should -Be $script:names[0]
        }

        It 'Throws all the errors after the last attempt' {
            $script:failuresBeforeSuccess = 99

            { Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment -Patterns 'Managed identity' -MaxAttempts 3) -DeploymentConfig @{} } |
                Should -Throw '*ARM deployment failed*Unable to get value using Managed identity*'

            Should -Invoke New-AzResourceGroupDeployment -Times 3 -Exactly
            Should -Invoke Start-Sleep -Times 2 -Exactly
        }

        It 'Does not retry an error that matches no pattern' {
            $script:failuresBeforeSuccess = 1
            $script:failureMessage = 'Error: Code=AccountNameInvalid; Message=Bad name.'

            { Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment -Patterns 'Managed identity') -DeploymentConfig @{} } |
                Should -Throw '*AccountNameInvalid*'

            Should -Invoke New-AzResourceGroupDeployment -Times 1 -Exactly
            Should -Not -Invoke Start-Sleep
        }

        It 'Does not retry without any patterns' {
            $script:failuresBeforeSuccess = 1

            { Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment -MaxAttempts 5) -DeploymentConfig @{} } | Should -Throw '*Managed identity*'

            Should -Invoke New-AzResourceGroupDeployment -Times 1 -Exactly
        }

        It 'Retries an error that Az throws as a terminating error' {
            $script:failuresBeforeSuccess = 1
            Mock New-AzResourceGroupDeployment {
                $script:attempts++
                if ($script:attempts -le 1) { throw 'The deployment validation failed: Code=Conflict; a transient conflict' }
                [PSCustomObject]@{ ProvisioningState = 'Succeeded' }
            }

            $result = Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment -Patterns 'transient conflict') -DeploymentConfig @{}

            $result.ProvisioningState | Should -Be 'Succeeded'
            Should -Invoke New-AzResourceGroupDeployment -Times 2 -Exactly
        }

        It 'Requires every pattern of an array entry to match: <Description>' -ForEach @(
            @{ Description = 'all match'; Patterns = @('Managed identity', 'InvalidParameterValueInContainerTemplate'); ExpectedCalls = 2 }
            @{ Description = 'one does not match'; Patterns = @('Managed identity', 'SomethingElse'); ExpectedCalls = 1 }
        ) {
            $script:failuresBeforeSuccess = 1
            $entry = New-TestDeployment -Scope resourceGroup
            # The comma keeps the array as a single entry
            $entry.retryErrorPatterns = @(, $Patterns)

            try { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} } catch {}

            Should -Invoke New-AzResourceGroupDeployment -Times $ExpectedCalls -Exactly
        }

        It 'Keeps the only array entry as one entry, written as in a config file' {
            $script:failuresBeforeSuccess = 1
            # If the outer array were unwrapped, each pattern would become an entry of its own, and the first would match
            $entry = New-TestDeployment -Scope resourceGroup
            $entry.retryErrorPatterns = @(
                , @('Managed identity', 'SomethingElse')
            )

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} } | Should -Throw '*Managed identity*'

            Should -Invoke New-AzResourceGroupDeployment -Times 1 -Exactly
        }

        It 'Matches patterns as case-insensitive regular expressions' {
            $script:failuresBeforeSuccess = 1

            Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment -Patterns 'unable to get value using managed\s+IDENTITY') -DeploymentConfig @{}

            Should -Invoke New-AzResourceGroupDeployment -Times 2 -Exactly
        }

        It 'Passes plain-text secrets to every attempt' {
            $script:failuresBeforeSuccess = 1
            $config = @{ secret = (ConvertTo-SecureString 's3cret' -AsPlainText -Force) }

            Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment -Patterns 'Managed identity') -DeploymentConfig $config

            Should -Invoke New-AzResourceGroupDeployment -Times 2 -Exactly -ParameterFilter { $TemplateParameterObject.secret -eq 's3cret' }
        }

        It 'Retries a what-if before reporting it as a warning with ContinueOnWhatIfError' {
            $script:failuresBeforeSuccess = 99

            Invoke-ArmDeployment -ArmDeployment (New-RetryDeployment -Patterns 'Managed identity' -MaxAttempts 2) -DeploymentConfig @{} `
                -WhatIfMode -ContinueOnWhatIfError | Should -BeNullOrEmpty

            Should -Invoke New-AzResourceGroupDeployment -Times 2 -Exactly -ParameterFilter { $WhatIf }
            Should -Invoke Write-Warning -Times 1 -Exactly -ParameterFilter { $Message -like '*ARM what-if failed*' }
        }

        It 'Throws for <Key> = <Value>, before deploying' -ForEach @(
            @{ Key = 'retryMaxAttempts'; Value = 0 }
            @{ Key = 'retryMaxAttempts'; Value = 101 }
            @{ Key = 'retryMaxAttempts'; Value = 'abc' }
            @{ Key = 'retryMaxAttempts'; Value = 1.5 }
            @{ Key = 'retryDelaySeconds'; Value = -1 }
            @{ Key = 'retryDelaySeconds'; Value = 3601 }
        ) {
            $entry = New-RetryDeployment -Patterns 'Managed identity'
            $entry[$Key] = $Value

            { Invoke-ArmDeployment -ArmDeployment $entry -DeploymentConfig @{} } | Should -Throw "*'$Key' must be an integer*"

            Should -Not -Invoke New-AzResourceGroupDeployment
        }
    }
}

Describe 'Module wiring' {

    BeforeAll {
        $moduleRoot = Split-Path -Parent $PSScriptRoot
        $module = Import-Module (Join-Path $moduleRoot 'ZeroFailed.Deploy.Azure.psd1') -Force -PassThru
        $armTasks = Get-Content -Raw (Join-Path $moduleRoot 'tasks' 'arm.tasks.ps1')
    }

    AfterAll {
        # The module's copy cannot see the stubs above, so never leave it loaded for later tests
        Remove-Module $module -Force
    }

    It 'Exports Invoke-ArmDeployment, so that the task can call it' {
        $module.ExportedFunctions.Keys | Should -Contain 'Invoke-ArmDeployment'
    }

    It 'Calls Invoke-ArmDeployment from the deployArmTemplates task' {
        $armTasks | Should -Match 'Invoke-ArmDeployment\s+-ArmDeployment'
    }

    It 'Leaves the retry settings to each deployment entry, with no global setting in the task' {
        $armTasks | Should -Not -Match '-Retry'
        $armTasks | Should -Not -Match 'ArmDeploymentRetry'
    }

    It 'Treats <Description> as a Bicep deployment in ensureBicepVersion: <Expected>' -ForEach @(
        @{ Description = 'main.bicep'; Path = 'main.bicep'; Expected = $true }
        @{ Description = 'main.bicepparam'; Path = 'main.bicepparam'; Expected = $true }
        @{ Description = 'main.json'; Path = 'main.json'; Expected = $false }
        @{ Description = 'a scriptblock that returns main.bicep'; Path = { 'main.bicep' }; Expected = $true }
    ) {
        # Run the task's own filter against a deployment entry
        $line = ($armTasks -split "`r?`n") | Where-Object { $_ -match '\$deploymentRequiresBicep\s*=' }
        $filterText = [regex]::Match($line, 'Where-Object \{ (?<filter>.+) \}\s*$').Groups['filter'].Value
        $filterText | Should -Not -BeNullOrEmpty
        $filter = [scriptblock]::Create($filterText)

        $matched = @(@{ templatePath = $Path } | Where-Object $filter)

        ($matched.Count -eq 1) | Should -Be $Expected
    }
}