personaEngine2/tests/Safety/WhatIfZeroWrites.Tests.ps1

#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }

<#
    SC-004: a preview run issues zero write requests across a full population.

    The assertion that matters is the call count on the write adapter, not the
    absence of an error. A run that never reached the write path because it crashed
    at user 3 would also record zero writes, so every test here checks the population
    was fully processed as well.
#>

BeforeAll {
    $repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
    . (Join-Path $repoRoot 'tests/TestHelpers.ps1')
    foreach ($file in (Get-PersonaSourceFile -RepoRoot $repoRoot)) { . $file }

    $script:target = 'extension_<EXTENSION-APP-ID>_<PERSONA>'

    $script:config = [pscustomobject]@{
        ConfigVersion              = '1.0.0'
        ConfigurationHash          = ('0' * 64)
        TargetAttribute            = $target
        ApprovedWritableAttributes = @($target)
        MaxConditionDepth          = 5
        SummaryInterval            = 0
        DefaultMembershipMode      = 'Direct'
        EvaluationErrorThreshold   = $null
        Rules                      = @(
            [pscustomobject]@{
                id = 'RULE-0010-GUEST'; name = 'Guests'; enabled = $true; priority = 10; persona = 'Guest'
                match = [pscustomobject]@{
                    operator = 'all'
                    conditions = @([pscustomobject]@{ type = 'property'; property = 'UserType'; operator = 'equals'; value = 'Guest' })
                }
            }
            [pscustomobject]@{
                id = 'RULE-0900-EMPLOYEE'; name = 'Employees'; enabled = $true; priority = 900; persona = 'Employee'
                match = [pscustomobject]@{
                    operator = 'all'
                    conditions = @([pscustomobject]@{ type = 'property'; property = 'Department'; operator = 'isNotNull' })
                }
            }
        )
    }

    $script:population = @(New-TestPopulation -Count 30 -TargetAttribute $target)
}

Describe 'Zero writes in preview mode (SC-004, FR-017)' -Tag 'Safety' {

    BeforeEach {
        Mock Get-PersonaUsers { $script:population }
        Mock Set-UserPersonaAttribute { throw 'The write adapter must never be reached in preview mode.' }
        Mock Write-Host { }
    }

    It 'issues no write request across the full population' {
        $outcome = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target `
            -Context (New-TestAuditContext -Mode 'Preview') `
            -ShouldProcessGate { param($t, $d) $false }

        Should -Invoke Set-UserPersonaAttribute -Times 0 -Exactly
    }

    It 'still processed every account, so the zero count is meaningful' {
        $outcome = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target `
            -Context (New-TestAuditContext -Mode 'Preview') `
            -ShouldProcessGate { param($t, $d) $false }

        $outcome.Counters.Processed | Should -Be 30
    }

    It 'reports the intended changes as WouldUpdate rather than hiding them' {
        $outcome = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target `
            -Context (New-TestAuditContext -Mode 'Preview') `
            -ShouldProcessGate { param($t, $d) $false }

        # Ten Guest accounts carry a stale stored value of 'Employee'.
        $outcome.Counters.WouldUpdate | Should -BeGreaterThan 0
    }

    It 'returns exit code 0 - a preview that changes nothing is a successful run' {
        $outcome = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target `
            -Context (New-TestAuditContext -Mode 'Preview') `
            -ShouldProcessGate { param($t, $d) $false }

        $outcome.ExitCode | Should -Be 0
    }

    It 'defaults to refusing writes when no gate is supplied' {
        # A caller that forgets the gate must preview, not write. The default is the
        # safe answer rather than the convenient one.
        $outcome = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target `
            -Context (New-TestAuditContext -Mode 'Preview')

        Should -Invoke Set-UserPersonaAttribute -Times 0 -Exactly
        $outcome.Counters.Updated | Should -Be 0
    }
}

Describe 'Writes do occur when the gate allows them' -Tag 'Safety' {

    BeforeEach {
        Mock Get-PersonaUsers { $script:population }
        Mock Write-Host { }
        Mock Set-UserPersonaAttribute {
            [pscustomobject]@{ Succeeded = $true; AccountObjectId = $UserObjectId; Value = $Value; PreviousValue = $PreviousValue }
        }
    }

    It 'writes exactly the accounts whose calculated value differs' {
        # The counterpart to the zero-write test. Without this, a run loop that never
        # writes under any circumstances would pass every assertion above.
        $outcome = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target `
            -Context (New-TestAuditContext -Mode 'Enforce') `
            -IsEnforcing `
            -ShouldProcessGate { param($t, $d) $true }

        $outcome.Counters.Updated | Should -BeGreaterThan 0
        Should -Invoke Set-UserPersonaAttribute -Times $outcome.Counters.Updated -Exactly
    }

    It 'never writes an account whose stored value already matches' {
        $outcome = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target `
            -Context (New-TestAuditContext -Mode 'Enforce') `
            -IsEnforcing `
            -ShouldProcessGate { param($t, $d) $true }

        $outcome.Counters.Unchanged | Should -BeGreaterThan 0
        ($outcome.Counters.Updated + $outcome.Counters.Unchanged + $outcome.Counters.Skipped + $outcome.Counters.UpdateFailed) |
            Should -Be $outcome.Counters.Processed
    }
}