fix(twincat): warn once per bad tag; a device refusal is not a comms fault (P10)

CompleteRead logged a Warning for every non-Good status on every poll and latched Degraded for all of them. Now a bad tag warns once per bad episode (re-armed when it reads Good, and on re-initialise), a comms-class status (BadCommunicationError / BadTimeout) degrades with LastSuccessfulRead preserved, and any other status - the device answered and refused this tag - advances LastSuccessfulRead with no state change. Read-path exception handlers now go through MarkCommsFault, so they never downgrade Faulted. Refs #739 Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
2026-10-22 14:07:03 -04:00
parent ecdd6dbecb
commit 4083b4aada
3 changed files with 175 additions and 13 deletions
@@ -0,0 +1,26 @@
+using Microsoft.Extensions.Logging;
+using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
+
+/// <summary>Collects the driver's Warning-level messages (thread-safe) for once-per-X assertions.</summary>
+internal sealed class TwinCATCapturingLogger : ILogger<TwinCATDriver>
+{
+    private readonly List<string> _warnings = [];
+
+    /// <summary>Gets a snapshot of the formatted Warning messages logged so far.</summary>
+    public IReadOnlyList<string> Warnings { get { lock (_warnings) return [.. _warnings]; } }
+
+    /// <inheritdoc />
+    public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
+
+    /// <inheritdoc />
+    public bool IsEnabled(LogLevel logLevel) => true;
+
+    /// <inheritdoc />
+    public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception,
+        Func<TState, Exception?, string> formatter)
+    {
+        if (logLevel == LogLevel.Warning) lock (_warnings) _warnings.Add(formatter(state, exception));
+    }
+}
@@ -0,0 +1,103 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
+
+/// <summary>
+///     #739 P10: a bad tag warns ONCE (not once per poll — 50 typo'd symbols on a 500 ms poll used to be 100
+///     Warnings/s forever), re-arms when it reads Good, and a device refusal leaves driver health alone while a
+///     comms-class status degrades.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class TwinCATReadWarningTests
+{
+    private const string Host = "ads://5.23.91.23.1.1:851";
+
+    private static (TwinCATDriver drv, FakeTwinCATClient fake, TwinCATCapturingLogger log) NewDriver()
+    {
+        var fake = new FakeTwinCATClient();
+        var log = new TwinCATCapturingLogger();
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions(Host)],
+            RawTags = TwinCATRawTags.Entries(
+            [
+                new TwinCATTagDefinition("Typo", Host, "MAIN.Typo", TwinCATDataType.DInt),
+                new TwinCATTagDefinition("Other", Host, "MAIN.Other", TwinCATDataType.DInt),
+            ]),
+            Probe = new TwinCATProbeOptions { Enabled = false },
+        }, "drv-1", new FakeTwinCATClientFactory { Customise = () => fake }, log);
+        return (drv, fake, log);
+    }
+
+    private static int WarningsFor(TwinCATCapturingLogger log, string reference) =>
+        log.Warnings.Count(w => w.Contains($"'{reference}'", StringComparison.Ordinal));
+
+    /// <summary>Repeated bad reads of one tag log one Warning; a second bad tag gets its own (positive control).</summary>
+    [Fact]
+    public async Task A_bad_tag_warns_once_across_polls_and_rearms_after_Good()
+    {
+        var (drv, fake, log) = NewDriver();
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        fake.ReadStatuses["MAIN.Typo"] = TwinCATStatusMapper.BadNodeIdUnknown;
+
+        for (var i = 0; i < 5; i++)
+            (await drv.ReadAsync(["Typo"], TestContext.Current.CancellationToken))
+                .Single().StatusCode.ShouldBe(TwinCATStatusMapper.BadNodeIdUnknown);
+        WarningsFor(log, "Typo").ShouldBe(1);
+
+        fake.ReadStatuses["MAIN.Other"] = TwinCATStatusMapper.BadNodeIdUnknown;
+        _ = await drv.ReadAsync(["Other"], TestContext.Current.CancellationToken);
+        WarningsFor(log, "Other").ShouldBe(1);
+
+        // Fixed, then broken again: a new episode warns again.
+        fake.ReadStatuses.Remove("MAIN.Typo");
+        _ = await drv.ReadAsync(["Typo"], TestContext.Current.CancellationToken);
+        fake.ReadStatuses["MAIN.Typo"] = TwinCATStatusMapper.BadNodeIdUnknown;
+        _ = await drv.ReadAsync(["Typo"], TestContext.Current.CancellationToken);
+        _ = await drv.ReadAsync(["Typo"], TestContext.Current.CancellationToken);
+        WarningsFor(log, "Typo").ShouldBe(2);
+    }
+
+    /// <summary>A re-initialise re-arms the warning.</summary>
+    [Fact]
+    public async Task A_reinitialise_rearms_the_warning()
+    {
+        var (drv, fake, log) = NewDriver();
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        fake.ReadStatuses["MAIN.Typo"] = TwinCATStatusMapper.BadNodeIdUnknown;
+        _ = await drv.ReadAsync(["Typo"], TestContext.Current.CancellationToken);
+
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        _ = await drv.ReadAsync(["Typo"], TestContext.Current.CancellationToken);
+
+        WarningsFor(log, "Typo").ShouldBe(2);
+    }
+
+    /// <summary>
+    ///     A status proving the device answered (symbol not found) keeps the driver Healthy and advances the
+    ///     stamp; a comms-class status (timeout) degrades with the stamp preserved.
+    /// </summary>
+    [Fact]
+    public async Task A_refusal_status_does_not_degrade_but_a_comms_status_does()
+    {
+        var (drv, fake, _) = NewDriver();
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        var initStamp = drv.GetHealth().LastSuccessfulRead!.Value;
+        fake.ReadStatuses["MAIN.Typo"] = TwinCATStatusMapper.BadNodeIdUnknown;
+        await Task.Delay(300, TestContext.Current.CancellationToken);
+
+        _ = await drv.ReadAsync(["Typo"], TestContext.Current.CancellationToken);
+        var afterRefusal = drv.GetHealth();
+        afterRefusal.State.ShouldBe(DriverState.Healthy);
+        afterRefusal.LastSuccessfulRead!.Value.ShouldBeGreaterThan(initStamp);
+
+        fake.ReadStatuses["MAIN.Other"] = TwinCATStatusMapper.BadTimeout;
+        _ = await drv.ReadAsync(["Other"], TestContext.Current.CancellationToken);
+        var afterTimeout = drv.GetHealth();
+        afterTimeout.State.ShouldBe(DriverState.Degraded);
+        afterTimeout.LastSuccessfulRead.ShouldBe(afterRefusal.LastSuccessfulRead);
+    }
+}