lmxopcua/scripts/e2e/_common.ps1

# Shared PowerShell helpers for the OtOpcUa end-to-end CLI test scripts.
#
# Every per-protocol script dot-sources this file and calls the Test-* functions
# below. Keeps the per-script code down to ~50 lines of parameterisation +
# bridging-tag identifiers.
#
# Conventions:
#   - All test helpers return a hashtable: @{ Passed=<bool>; Reason=<string> }
#   - Helpers never throw unless the test setup is itself broken (a crashed
#     CLI is a test failure, not an exception).
#   - Output is plain text with [PASS] / [FAIL] / [SKIP] / [INFO] prefixes so
#     grep/log-scraping works.

Set-StrictMode -Version 3.0

# ---------------------------------------------------------------------------
# Colouring + prefixes.
# ---------------------------------------------------------------------------

function Write-Header {
    param([string]$Title)
    Write-Host ""
    Write-Host "=== $Title ===" -ForegroundColor Cyan
}

function Write-Pass {
    param([string]$Message)
    Write-Host "[PASS] $Message" -ForegroundColor Green
}

function Write-Fail {
    param([string]$Message)
    Write-Host "[FAIL] $Message" -ForegroundColor Red
}

function Write-Skip {
    param([string]$Message)
    Write-Host "[SKIP] $Message" -ForegroundColor Yellow
}

function Write-Info {
    param([string]$Message)
    Write-Host "[INFO] $Message" -ForegroundColor Gray
}

# ---------------------------------------------------------------------------
# CLI invocation helpers.
# ---------------------------------------------------------------------------

# Resolve a CLI path from either a published binary OR a `dotnet run` fallback.
# Preferred order:
#   1. $env:OTOPCUA_CLI_BIN points at a publish/ folder → use <exe> there
#   2. Fall back to `dotnet run --project src/<ProjectFolder> --`
#
# $ProjectFolder = relative path from repo root
# $ExeName       = expected AssemblyName (no .exe)
function Get-CliInvocation {
    param(
        [Parameter(Mandatory)] [string]$ProjectFolder,
        [Parameter(Mandatory)] [string]$ExeName
    )

    if ($env:OTOPCUA_CLI_BIN) {
        $binPath = Join-Path $env:OTOPCUA_CLI_BIN "$ExeName.exe"
        if (Test-Path $binPath) {
            return @{ File = $binPath; PrefixArgs = @() }
        }
    }

    # Dotnet-run fallback. --no-build would be faster but not every CI step
    # has rebuilt; default to a full run so the script is forgiving.
    return @{
        File       = "dotnet"
        PrefixArgs = @("run", "--project", $ProjectFolder, "--")
    }
}

# Run a CLI and capture stdout+stderr+exitcode. Never throws.
function Invoke-Cli {
    param(
        [Parameter(Mandatory)] $Cli,            # output of Get-CliInvocation
        [Parameter(Mandatory)] [string[]]$Args, # CLI arguments (after `-- `)
        [int]$TimeoutSec = 30
    )

    $allArgs = @($Cli.PrefixArgs) + $Args
    $output = $null
    $exitCode = -1

    try {
        $output = & $Cli.File @allArgs 2>&1 | Out-String
        $exitCode = $LASTEXITCODE
    }
    catch {
        return @{
            Output   = $_.Exception.Message
            ExitCode = -1
        }
    }

    return @{
        Output   = $output
        ExitCode = $exitCode
    }
}

# ---------------------------------------------------------------------------
# Test helpers — reusable building blocks every per-protocol script calls.
# ---------------------------------------------------------------------------

# Test 1 — the driver CLI's probe command exits 0. Confirms the PLC / simulator
# is reachable and speaks the protocol. Prerequisite for everything else.
function Test-Probe {
    param(
        [Parameter(Mandatory)] $Cli,
        [Parameter(Mandatory)] [string[]]$ProbeArgs
    )
    Write-Header "Probe"
    $r = Invoke-Cli -Cli $Cli -Args $ProbeArgs
    if ($r.ExitCode -eq 0) {
        Write-Pass "driver CLI probe succeeded"
        return @{ Passed = $true }
    }
    Write-Fail "driver CLI probe exit=$($r.ExitCode)"
    Write-Host $r.Output
    return @{ Passed = $false; Reason = "probe exit $($r.ExitCode)" }
}

# Test 2 — driver-loopback. Write a value via the driver CLI, read it back via
# the same CLI, assert round-trip equality. Confirms the driver itself is
# functional without pulling the OtOpcUa server into the loop.
function Test-DriverLoopback {
    param(
        [Parameter(Mandatory)] $Cli,
        [Parameter(Mandatory)] [string[]]$WriteArgs,
        [Parameter(Mandatory)] [string[]]$ReadArgs,
        [Parameter(Mandatory)] [string]$ExpectedValue
    )
    Write-Header "Driver loopback"

    $w = Invoke-Cli -Cli $Cli -Args $WriteArgs
    if ($w.ExitCode -ne 0) {
        Write-Fail "write failed (exit=$($w.ExitCode))"
        Write-Host $w.Output
        return @{ Passed = $false; Reason = "write failed" }
    }
    Write-Info "write ok"

    $r = Invoke-Cli -Cli $Cli -Args $ReadArgs
    if ($r.ExitCode -ne 0) {
        Write-Fail "read failed (exit=$($r.ExitCode))"
        Write-Host $r.Output
        return @{ Passed = $false; Reason = "read failed" }
    }

    if ($r.Output -match "Value:\s+$([Regex]::Escape($ExpectedValue))\b") {
        Write-Pass "round-trip equals $ExpectedValue"
        return @{ Passed = $true }
    }
    Write-Fail "round-trip value mismatch — expected $ExpectedValue"
    Write-Host $r.Output
    return @{ Passed = $false; Reason = "value mismatch" }
}

# Test 3 — server bridge. Write via the driver CLI, read the corresponding
# OPC UA NodeId via the OPC UA client CLI. Confirms the full path:
#   driver CLI → PLC → OtOpcUa server (polling/subscription) → OPC UA client.
function Test-ServerBridge {
    param(
        [Parameter(Mandatory)] $DriverCli,
        [Parameter(Mandatory)] [string[]]$DriverWriteArgs,
        [Parameter(Mandatory)] $OpcUaCli,
        [Parameter(Mandatory)] [string]$OpcUaUrl,
        [Parameter(Mandatory)] [string]$OpcUaNodeId,
        [Parameter(Mandatory)] [string]$ExpectedValue,
        [int]$ServerPollDelaySec = 3
    )
    Write-Header "Server bridge"

    $w = Invoke-Cli -Cli $DriverCli -Args $DriverWriteArgs
    if ($w.ExitCode -ne 0) {
        Write-Fail "driver-side write failed (exit=$($w.ExitCode))"
        Write-Host $w.Output
        return @{ Passed = $false; Reason = "driver write failed" }
    }
    Write-Info "driver write ok, waiting ${ServerPollDelaySec}s for server-side poll"
    Start-Sleep -Seconds $ServerPollDelaySec

    $r = Invoke-Cli -Cli $OpcUaCli -Args @("read", "-u", $OpcUaUrl, "-n", $OpcUaNodeId)
    if ($r.ExitCode -ne 0) {
        Write-Fail "OPC UA client read failed (exit=$($r.ExitCode))"
        Write-Host $r.Output
        return @{ Passed = $false; Reason = "opc-ua read failed" }
    }

    if ($r.Output -match "Value:\s+$([Regex]::Escape($ExpectedValue))\b") {
        Write-Pass "server-side read equals $ExpectedValue"
        return @{ Passed = $true }
    }
    Write-Fail "server-side value mismatch — expected $ExpectedValue"
    Write-Host $r.Output
    return @{ Passed = $false; Reason = "bridge value mismatch" }
}

# ---------------------------------------------------------------------------
# Summary helper — caller passes an array of test results.
# ---------------------------------------------------------------------------

function Write-Summary {
    param(
        [Parameter(Mandatory)] [string]$Title,
        [Parameter(Mandatory)] [array]$Results
    )
    $passed = ($Results | Where-Object { $_.Passed }).Count
    $failed = ($Results | Where-Object { -not $_.Passed }).Count
    Write-Host ""
    Write-Host "=== $Title summary: $passed/$($Results.Count) passed ===" `
        -ForegroundColor $(if ($failed -eq 0) { "Green" } else { "Red" })
}