Document client stack XML docs progress

tests/ZB.MOM.WW.LmxOpcUa.Client.Shared.Tests/Fakes/FakeSessionAdapter.cs

@@ -3,12 +3,22 @@ using ZB.MOM.WW.LmxOpcUa.Client.Shared.Adapters;
 
 namespace ZB.MOM.WW.LmxOpcUa.Client.Shared.Tests.Fakes;
 
+/// <summary>
+/// Test double for <see cref="ISessionAdapter" /> used to simulate reads, writes, browsing, history, and failover callbacks.
+/// </summary>
 internal sealed class FakeSessionAdapter : ISessionAdapter
 {
     private readonly List<FakeSubscriptionAdapter> _createdSubscriptions = [];
     private Action<bool>? _keepAliveCallback;
 
+    /// <summary>
+    /// Gets a value indicating whether the fake session has been closed through the client disconnect path.
+    /// </summary>
     public bool Closed { get; private set; }
+
+    /// <summary>
+    /// Gets a value indicating whether the fake session has been disposed.
+    /// </summary>
     public bool Disposed { get; private set; }
     public int ReadCount { get; private set; }
     public int WriteCount { get; private set; }
@@ -38,27 +48,47 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
     public bool ThrowOnHistoryReadAggregate { get; set; }
 
     /// <summary>
-    ///     The next FakeSubscriptionAdapter to return from CreateSubscriptionAsync.
-    ///     If null, a new one is created automatically.
+    /// Gets or sets the next fake subscription returned when the client creates a monitored-item subscription.
+    /// If unset, the fake builds a new subscription automatically.
     /// </summary>
     public FakeSubscriptionAdapter? NextSubscription { get; set; }
 
+    /// <summary>
+    /// Gets the fake subscriptions created by this session so tests can inspect replay and cleanup behavior.
+    /// </summary>
     public IReadOnlyList<FakeSubscriptionAdapter> CreatedSubscriptions => _createdSubscriptions;
 
+    /// <inheritdoc />
     public bool Connected { get; set; } = true;
+
+    /// <inheritdoc />
     public string SessionId { get; set; } = "ns=0;i=12345";
+
+    /// <inheritdoc />
     public string SessionName { get; set; } = "FakeSession";
+
+    /// <inheritdoc />
     public string EndpointUrl { get; set; } = "opc.tcp://localhost:4840";
+
+    /// <inheritdoc />
     public string ServerName { get; set; } = "FakeServer";
+
+    /// <inheritdoc />
     public string SecurityMode { get; set; } = "None";
+
+    /// <inheritdoc />
     public string SecurityPolicyUri { get; set; } = "http://opcfoundation.org/UA/SecurityPolicy#None";
+
+    /// <inheritdoc />
     public NamespaceTable NamespaceUris { get; set; } = new();
 
+    /// <inheritdoc />
     public void RegisterKeepAliveHandler(Action<bool> callback)
     {
         _keepAliveCallback = callback;
     }
 
+    /// <inheritdoc />
     public Task<DataValue> ReadValueAsync(NodeId nodeId, CancellationToken ct)
     {
         ReadCount++;
@@ -71,6 +101,7 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
         return Task.FromResult(ReadResponse ?? new DataValue(new Variant(0), StatusCodes.Good));
     }
 
+    /// <inheritdoc />
     public Task<StatusCode> WriteValueAsync(NodeId nodeId, DataValue value, CancellationToken ct)
     {
         WriteCount++;
@@ -79,6 +110,7 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
         return Task.FromResult(WriteResponse);
     }
 
+    /// <inheritdoc />
     public Task<(byte[]? ContinuationPoint, ReferenceDescriptionCollection References)> BrowseAsync(
         NodeId nodeId, uint nodeClassMask, CancellationToken ct)
     {
@@ -88,6 +120,7 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
         return Task.FromResult((BrowseContinuationPoint, BrowseResponse));
     }
 
+    /// <inheritdoc />
     public Task<(byte[]? ContinuationPoint, ReferenceDescriptionCollection References)> BrowseNextAsync(
         byte[] continuationPoint, CancellationToken ct)
     {
@@ -95,12 +128,14 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
         return Task.FromResult((BrowseNextContinuationPoint, BrowseNextResponse));
     }
 
+    /// <inheritdoc />
     public Task<bool> HasChildrenAsync(NodeId nodeId, CancellationToken ct)
     {
         HasChildrenCount++;
         return Task.FromResult(HasChildrenResponse);
     }
 
+    /// <inheritdoc />
     public Task<IReadOnlyList<DataValue>> HistoryReadRawAsync(
         NodeId nodeId, DateTime startTime, DateTime endTime, int maxValues, CancellationToken ct)
     {
@@ -110,6 +145,7 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
         return Task.FromResult<IReadOnlyList<DataValue>>(HistoryReadRawResponse);
     }
 
+    /// <inheritdoc />
     public Task<IReadOnlyList<DataValue>> HistoryReadAggregateAsync(
         NodeId nodeId, DateTime startTime, DateTime endTime, NodeId aggregateId, double intervalMs,
         CancellationToken ct)
@@ -120,6 +156,7 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
         return Task.FromResult<IReadOnlyList<DataValue>>(HistoryReadAggregateResponse);
     }
 
+    /// <inheritdoc />
     public Task<ISubscriptionAdapter> CreateSubscriptionAsync(int publishingIntervalMs, CancellationToken ct)
     {
         var sub = NextSubscription ?? new FakeSubscriptionAdapter();
@@ -128,12 +165,14 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
         return Task.FromResult<ISubscriptionAdapter>(sub);
     }
 
+    /// <inheritdoc />
     public Task<IList<object>?> CallMethodAsync(NodeId objectId, NodeId methodId, object[] inputArguments,
         CancellationToken ct = default)
     {
         return Task.FromResult<IList<object>?>(null);
     }
 
+    /// <inheritdoc />
     public Task CloseAsync(CancellationToken ct)
     {
         Closed = true;
@@ -141,6 +180,9 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
         return Task.CompletedTask;
     }
 
+    /// <summary>
+    /// Marks the fake session as disposed so tests can verify cleanup after disconnect or failover.
+    /// </summary>
     public void Dispose()
     {
         Disposed = true;
@@ -154,4 +196,4 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
     {
         _keepAliveCallback?.Invoke(isGood);
     }
-}
+}

tests/ZB.MOM.WW.LmxOpcUa.Client.Shared.Tests/Fakes/FakeSubscriptionAdapter.cs

@@ -3,6 +3,9 @@ using ZB.MOM.WW.LmxOpcUa.Client.Shared.Adapters;
 
 namespace ZB.MOM.WW.LmxOpcUa.Client.Shared.Tests.Fakes;
 
+/// <summary>
+/// Test double for <see cref="ISubscriptionAdapter" /> used to drive monitored-item behavior in shared-client tests.
+/// </summary>
 internal sealed class FakeSubscriptionAdapter : ISubscriptionAdapter
 {
     private readonly
@@ -10,8 +13,19 @@ internal sealed class FakeSubscriptionAdapter : ISubscriptionAdapter
             )> _items = new();
 
     private uint _nextHandle = 100;
+    /// <summary>
+    /// Gets a value indicating whether the fake subscription has been deleted.
+    /// </summary>
     public bool Deleted { get; private set; }
+
+    /// <summary>
+    /// Gets a value indicating whether a condition refresh was requested by the client under test.
+    /// </summary>
     public bool ConditionRefreshCalled { get; private set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether condition refresh should throw to simulate unsupported servers.
+    /// </summary>
     public bool ThrowOnConditionRefresh { get; set; }
     public int AddDataChangeCount { get; private set; }
     public int AddEventCount { get; private set; }
@@ -22,8 +36,10 @@ internal sealed class FakeSubscriptionAdapter : ISubscriptionAdapter
     /// </summary>
     public IReadOnlyCollection<uint> ActiveHandles => _items.Keys.ToList();
 
+    /// <inheritdoc />
     public uint SubscriptionId { get; set; } = 42;
 
+    /// <inheritdoc />
     public Task<uint> AddDataChangeMonitoredItemAsync(NodeId nodeId, int samplingIntervalMs,
         Action<string, DataValue> onDataChange, CancellationToken ct)
     {
@@ -33,6 +49,7 @@ internal sealed class FakeSubscriptionAdapter : ISubscriptionAdapter
         return Task.FromResult(handle);
     }
 
+    /// <inheritdoc />
     public Task RemoveMonitoredItemAsync(uint clientHandle, CancellationToken ct)
     {
         RemoveCount++;
@@ -40,6 +57,7 @@ internal sealed class FakeSubscriptionAdapter : ISubscriptionAdapter
         return Task.CompletedTask;
     }
 
+    /// <inheritdoc />
     public Task<uint> AddEventMonitoredItemAsync(NodeId nodeId, int samplingIntervalMs, EventFilter filter,
         Action<EventFieldList> onEvent, CancellationToken ct)
     {
@@ -49,6 +67,7 @@ internal sealed class FakeSubscriptionAdapter : ISubscriptionAdapter
         return Task.FromResult(handle);
     }
 
+    /// <inheritdoc />
     public Task ConditionRefreshAsync(CancellationToken ct)
     {
         ConditionRefreshCalled = true;
@@ -57,6 +76,7 @@ internal sealed class FakeSubscriptionAdapter : ISubscriptionAdapter
         return Task.CompletedTask;
     }
 
+    /// <inheritdoc />
     public Task DeleteAsync(CancellationToken ct)
     {
         Deleted = true;
@@ -64,6 +84,9 @@ internal sealed class FakeSubscriptionAdapter : ISubscriptionAdapter
         return Task.CompletedTask;
     }
 
+    /// <summary>
+    /// Clears tracked monitored items when the fake subscription is disposed by the client under test.
+    /// </summary>
     public void Dispose()
     {
         _items.Clear();
@@ -85,4 +108,4 @@ internal sealed class FakeSubscriptionAdapter : ISubscriptionAdapter
     {
         if (_items.TryGetValue(handle, out var item) && item.EventCallback != null) item.EventCallback(eventFields);
     }
-}
+}

tests/ZB.MOM.WW.LmxOpcUa.Client.Shared.Tests/OpcUaClientServiceTests.cs

@@ -6,6 +6,9 @@ using ZB.MOM.WW.LmxOpcUa.Client.Shared.Tests.Fakes;
 
 namespace ZB.MOM.WW.LmxOpcUa.Client.Shared.Tests;
 
+/// <summary>
+/// Verifies the shared OPC UA client service behaviors for connection management, browsing, subscriptions, history, alarms, and redundancy.
+/// </summary>
 public class OpcUaClientServiceTests : IDisposable
 {
     private readonly FakeApplicationConfigurationFactory _configFactory = new();
@@ -18,6 +21,9 @@ public class OpcUaClientServiceTests : IDisposable
         _service = new OpcUaClientService(_configFactory, _endpointDiscovery, _sessionFactory);
     }
 
+    /// <summary>
+    /// Releases the shared client service after each test so session and subscription state do not leak between scenarios.
+    /// </summary>
     public void Dispose()
     {
         _service.Dispose();
@@ -34,6 +40,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Connection tests ---
 
+    /// <summary>
+    /// Verifies that a valid connection request returns populated connection metadata and marks the client as connected.
+    /// </summary>
     [Fact]
     public async Task ConnectAsync_ValidSettings_ReturnsConnectionInfo()
     {
@@ -45,6 +54,9 @@ public class OpcUaClientServiceTests : IDisposable
         _service.CurrentConnectionInfo.ShouldBe(info);
     }
 
+    /// <summary>
+    /// Verifies that invalid connection settings fail validation before any OPC UA session is created.
+    /// </summary>
     [Fact]
     public async Task ConnectAsync_InvalidSettings_ThrowsBeforeCreatingSession()
     {
@@ -55,6 +67,9 @@ public class OpcUaClientServiceTests : IDisposable
         _service.IsConnected.ShouldBeFalse();
     }
 
+    /// <summary>
+    /// Verifies that server and security details from the session are copied into the exposed connection info.
+    /// </summary>
     [Fact]
     public async Task ConnectAsync_PopulatesConnectionInfo()
     {
@@ -77,6 +92,9 @@ public class OpcUaClientServiceTests : IDisposable
         info.SessionName.ShouldBe("TestSession");
     }
 
+    /// <summary>
+    /// Verifies that connection-state transitions are raised for the connecting and connected phases.
+    /// </summary>
     [Fact]
     public async Task ConnectAsync_RaisesConnectionStateChangedEvents()
     {
@@ -92,6 +110,9 @@ public class OpcUaClientServiceTests : IDisposable
         events[1].NewState.ShouldBe(ConnectionState.Connected);
     }
 
+    /// <summary>
+    /// Verifies that a failed session creation leaves the client in the disconnected state.
+    /// </summary>
     [Fact]
     public async Task ConnectAsync_SessionFactoryFails_TransitionsToDisconnected()
     {
@@ -105,6 +126,9 @@ public class OpcUaClientServiceTests : IDisposable
         events.Last().NewState.ShouldBe(ConnectionState.Disconnected);
     }
 
+    /// <summary>
+    /// Verifies that username and password settings are passed through to the session-creation pipeline.
+    /// </summary>
     [Fact]
     public async Task ConnectAsync_WithUsername_PassesThroughToFactory()
     {
@@ -120,6 +144,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Disconnect tests ---
 
+    /// <summary>
+    /// Verifies that disconnect closes the active session and clears exposed connection state.
+    /// </summary>
     [Fact]
     public async Task DisconnectAsync_WhenConnected_ClosesSession()
     {
@@ -133,6 +160,9 @@ public class OpcUaClientServiceTests : IDisposable
         _service.CurrentConnectionInfo.ShouldBeNull();
     }
 
+    /// <summary>
+    /// Verifies that disconnect is safe to call when no server session is active.
+    /// </summary>
     [Fact]
     public async Task DisconnectAsync_WhenNotConnected_IsIdempotent()
     {
@@ -140,6 +170,9 @@ public class OpcUaClientServiceTests : IDisposable
         _service.IsConnected.ShouldBeFalse();
     }
 
+    /// <summary>
+    /// Verifies that repeated disconnect calls do not throw after cleanup has already run.
+    /// </summary>
     [Fact]
     public async Task DisconnectAsync_CalledTwice_IsIdempotent()
     {
@@ -150,6 +183,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Read tests ---
 
+    /// <summary>
+    /// Verifies that a connected client can read the current value of a node through the session adapter.
+    /// </summary>
     [Fact]
     public async Task ReadValueAsync_WhenConnected_ReturnsValue()
     {
@@ -166,6 +202,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.ReadCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that reads are rejected when the client is not connected to a server.
+    /// </summary>
     [Fact]
     public async Task ReadValueAsync_WhenDisconnected_Throws()
     {
@@ -173,6 +212,9 @@ public class OpcUaClientServiceTests : IDisposable
             _service.ReadValueAsync(new NodeId("ns=2;s=MyNode")));
     }
 
+    /// <summary>
+    /// Verifies that session-level read failures are surfaced to callers instead of being swallowed.
+    /// </summary>
     [Fact]
     public async Task ReadValueAsync_SessionThrows_PropagatesException()
     {
@@ -186,6 +228,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Write tests ---
 
+    /// <summary>
+    /// Verifies that writes succeed through the session adapter when the client is connected.
+    /// </summary>
     [Fact]
     public async Task WriteValueAsync_WhenConnected_WritesValue()
     {
@@ -203,6 +248,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.WriteCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that string inputs are coerced to the node's current data type before writing.
+    /// </summary>
     [Fact]
     public async Task WriteValueAsync_StringValue_CoercesToTargetType()
     {
@@ -219,6 +267,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.ReadCount.ShouldBe(1); // Read for type inference
     }
 
+    /// <summary>
+    /// Verifies that non-string values are written directly without an extra type-inference read.
+    /// </summary>
     [Fact]
     public async Task WriteValueAsync_NonStringValue_WritesDirectly()
     {
@@ -232,6 +283,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.ReadCount.ShouldBe(0); // No read for non-string values
     }
 
+    /// <summary>
+    /// Verifies that writes are rejected when the client is disconnected.
+    /// </summary>
     [Fact]
     public async Task WriteValueAsync_WhenDisconnected_Throws()
     {
@@ -241,6 +295,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Browse tests ---
 
+    /// <summary>
+    /// Verifies that browse results are mapped into the client browse model used by CLI and UI consumers.
+    /// </summary>
     [Fact]
     public async Task BrowseAsync_WhenConnected_ReturnsMappedResults()
     {
@@ -267,6 +324,9 @@ public class OpcUaClientServiceTests : IDisposable
         results[0].HasChildren.ShouldBeFalse(); // Variable nodes don't check HasChildren
     }
 
+    /// <summary>
+    /// Verifies that a null browse root defaults to the OPC UA Objects folder.
+    /// </summary>
     [Fact]
     public async Task BrowseAsync_NullParent_UsesObjectsFolder()
     {
@@ -282,6 +342,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.BrowseCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that object nodes trigger child-detection checks so the client can mark expandable branches.
+    /// </summary>
     [Fact]
     public async Task BrowseAsync_ObjectNode_ChecksHasChildren()
     {
@@ -307,6 +370,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.HasChildrenCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that browse continuation points are followed so multi-page address-space branches are fully returned.
+    /// </summary>
     [Fact]
     public async Task BrowseAsync_WithContinuationPoint_FollowsIt()
     {
@@ -342,6 +408,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.BrowseNextCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that browse requests are rejected when the client is disconnected.
+    /// </summary>
     [Fact]
     public async Task BrowseAsync_WhenDisconnected_Throws()
     {
@@ -350,6 +419,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Subscribe tests ---
 
+    /// <summary>
+    /// Verifies that subscribing to a node creates a monitored item on a data-change subscription.
+    /// </summary>
     [Fact]
     public async Task SubscribeAsync_CreatesSubscription()
     {
@@ -363,6 +435,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.CreatedSubscriptions[0].AddDataChangeCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that duplicate subscribe requests for the same node do not create duplicate monitored items.
+    /// </summary>
     [Fact]
     public async Task SubscribeAsync_DuplicateNode_IsIdempotent()
     {
@@ -376,6 +451,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.CreatedSubscriptions[0].AddDataChangeCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that data-change notifications from the subscription are raised through the shared client event.
+    /// </summary>
     [Fact]
     public async Task SubscribeAsync_RaisesDataChangedEvent()
     {
@@ -398,6 +476,9 @@ public class OpcUaClientServiceTests : IDisposable
         received.Value.Value.ShouldBe(99);
     }
 
+    /// <summary>
+    /// Verifies that unsubscribing removes the corresponding monitored item from the active subscription.
+    /// </summary>
     [Fact]
     public async Task UnsubscribeAsync_RemovesMonitoredItem()
     {
@@ -412,6 +493,9 @@ public class OpcUaClientServiceTests : IDisposable
         fakeSub.RemoveCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that unsubscribing an unknown node is treated as a safe no-op.
+    /// </summary>
     [Fact]
     public async Task UnsubscribeAsync_WhenNotSubscribed_DoesNotThrow()
     {
@@ -423,6 +507,9 @@ public class OpcUaClientServiceTests : IDisposable
         // Should not throw
     }
 
+    /// <summary>
+    /// Verifies that data subscriptions cannot be created while the client is disconnected.
+    /// </summary>
     [Fact]
     public async Task SubscribeAsync_WhenDisconnected_Throws()
     {
@@ -432,6 +519,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Alarm subscription tests ---
 
+    /// <summary>
+    /// Verifies that alarm subscription requests create an event monitored item on the session.
+    /// </summary>
     [Fact]
     public async Task SubscribeAlarmsAsync_CreatesEventSubscription()
     {
@@ -445,6 +535,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.CreatedSubscriptions[0].AddEventCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that duplicate alarm-subscription requests do not create duplicate event subscriptions.
+    /// </summary>
     [Fact]
     public async Task SubscribeAlarmsAsync_Duplicate_IsIdempotent()
     {
@@ -458,6 +551,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.CreatedSubscriptions.Count.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that OPC UA event notifications are mapped into the shared client alarm event model.
+    /// </summary>
     [Fact]
     public async Task SubscribeAlarmsAsync_RaisesAlarmEvent()
     {
@@ -503,6 +599,9 @@ public class OpcUaClientServiceTests : IDisposable
         received.AckedState.ShouldBeFalse();
     }
 
+    /// <summary>
+    /// Verifies that removing alarm monitoring deletes the underlying event subscription.
+    /// </summary>
     [Fact]
     public async Task UnsubscribeAlarmsAsync_DeletesSubscription()
     {
@@ -517,6 +616,9 @@ public class OpcUaClientServiceTests : IDisposable
         fakeSub.Deleted.ShouldBeTrue();
     }
 
+    /// <summary>
+    /// Verifies that removing alarms is safe even when no alarm subscription exists.
+    /// </summary>
     [Fact]
     public async Task UnsubscribeAlarmsAsync_WhenNoSubscription_DoesNotThrow()
     {
@@ -527,6 +629,9 @@ public class OpcUaClientServiceTests : IDisposable
         await _service.UnsubscribeAlarmsAsync(); // Should not throw
     }
 
+    /// <summary>
+    /// Verifies that condition refresh requests are forwarded to the active alarm subscription.
+    /// </summary>
     [Fact]
     public async Task RequestConditionRefreshAsync_CallsAdapter()
     {
@@ -541,6 +646,9 @@ public class OpcUaClientServiceTests : IDisposable
         fakeSub.ConditionRefreshCalled.ShouldBeTrue();
     }
 
+    /// <summary>
+    /// Verifies that condition refresh fails fast when no alarm subscription is active.
+    /// </summary>
     [Fact]
     public async Task RequestConditionRefreshAsync_NoAlarmSubscription_Throws()
     {
@@ -552,6 +660,9 @@ public class OpcUaClientServiceTests : IDisposable
             _service.RequestConditionRefreshAsync());
     }
 
+    /// <summary>
+    /// Verifies that alarm subscriptions cannot be created while disconnected.
+    /// </summary>
     [Fact]
     public async Task SubscribeAlarmsAsync_WhenDisconnected_Throws()
     {
@@ -561,6 +672,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- History read tests ---
 
+    /// <summary>
+    /// Verifies that raw history reads return the session-provided values.
+    /// </summary>
     [Fact]
     public async Task HistoryReadRawAsync_ReturnsValues()
     {
@@ -580,6 +694,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.HistoryReadRawCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that raw history reads are rejected while disconnected.
+    /// </summary>
     [Fact]
     public async Task HistoryReadRawAsync_WhenDisconnected_Throws()
     {
@@ -587,6 +704,9 @@ public class OpcUaClientServiceTests : IDisposable
             _service.HistoryReadRawAsync(new NodeId("ns=2;s=Temp"), DateTime.UtcNow.AddHours(-1), DateTime.UtcNow));
     }
 
+    /// <summary>
+    /// Verifies that raw-history failures from the session are propagated to callers.
+    /// </summary>
     [Fact]
     public async Task HistoryReadRawAsync_SessionThrows_PropagatesException()
     {
@@ -598,6 +718,9 @@ public class OpcUaClientServiceTests : IDisposable
             _service.HistoryReadRawAsync(new NodeId("ns=2;s=Temp"), DateTime.UtcNow.AddHours(-1), DateTime.UtcNow));
     }
 
+    /// <summary>
+    /// Verifies that aggregate history reads return the processed values from the session adapter.
+    /// </summary>
     [Fact]
     public async Task HistoryReadAggregateAsync_ReturnsValues()
     {
@@ -617,6 +740,9 @@ public class OpcUaClientServiceTests : IDisposable
         session.HistoryReadAggregateCount.ShouldBe(1);
     }
 
+    /// <summary>
+    /// Verifies that aggregate history reads are rejected while disconnected.
+    /// </summary>
     [Fact]
     public async Task HistoryReadAggregateAsync_WhenDisconnected_Throws()
     {
@@ -626,6 +752,9 @@ public class OpcUaClientServiceTests : IDisposable
                 AggregateType.Average));
     }
 
+    /// <summary>
+    /// Verifies that aggregate-history failures from the session are propagated to callers.
+    /// </summary>
     [Fact]
     public async Task HistoryReadAggregateAsync_SessionThrows_PropagatesException()
     {
@@ -641,6 +770,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Redundancy tests ---
 
+    /// <summary>
+    /// Verifies that redundancy mode, service level, and server URIs are read from the standard OPC UA redundancy nodes.
+    /// </summary>
     [Fact]
     public async Task GetRedundancyInfoAsync_ReturnsInfo()
     {
@@ -670,6 +802,9 @@ public class OpcUaClientServiceTests : IDisposable
         info.ApplicationUri.ShouldBe("urn:server1");
     }
 
+    /// <summary>
+    /// Verifies that missing optional redundancy arrays do not prevent a redundancy snapshot from being returned.
+    /// </summary>
     [Fact]
     public async Task GetRedundancyInfoAsync_MissingOptionalArrays_ReturnsGracefully()
     {
@@ -697,6 +832,9 @@ public class OpcUaClientServiceTests : IDisposable
         info.ApplicationUri.ShouldBeEmpty();
     }
 
+    /// <summary>
+    /// Verifies that redundancy inspection is rejected while disconnected.
+    /// </summary>
     [Fact]
     public async Task GetRedundancyInfoAsync_WhenDisconnected_Throws()
     {
@@ -706,6 +844,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Failover tests ---
 
+    /// <summary>
+    /// Verifies that a keep-alive failure moves the client to a configured failover endpoint.
+    /// </summary>
     [Fact]
     public async Task KeepAliveFailure_TriggersFailover()
     {
@@ -734,6 +875,9 @@ public class OpcUaClientServiceTests : IDisposable
                                         e.EndpointUrl == "opc.tcp://backup:4840");
     }
 
+    /// <summary>
+    /// Verifies that connection metadata is refreshed to reflect the newly active failover endpoint.
+    /// </summary>
     [Fact]
     public async Task KeepAliveFailure_UpdatesConnectionInfo()
     {
@@ -757,6 +901,9 @@ public class OpcUaClientServiceTests : IDisposable
         _service.CurrentConnectionInfo.ServerName.ShouldBe("BackupServer");
     }
 
+    /// <summary>
+    /// Verifies that the client falls back to disconnected when every failover endpoint is unreachable.
+    /// </summary>
     [Fact]
     public async Task KeepAliveFailure_AllEndpointsFail_TransitionsToDisconnected()
     {
@@ -775,6 +922,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Dispose tests ---
 
+    /// <summary>
+    /// Verifies that dispose releases the underlying session and clears exposed connection state.
+    /// </summary>
     [Fact]
     public async Task Dispose_CleansUpResources()
     {
@@ -788,12 +938,18 @@ public class OpcUaClientServiceTests : IDisposable
         _service.CurrentConnectionInfo.ShouldBeNull();
     }
 
+    /// <summary>
+    /// Verifies that dispose is safe to call even when no connection was established.
+    /// </summary>
     [Fact]
     public void Dispose_WhenNotConnected_DoesNotThrow()
     {
         _service.Dispose(); // Should not throw
     }
 
+    /// <summary>
+    /// Verifies that public operations reject use after the shared client has been disposed.
+    /// </summary>
     [Fact]
     public async Task OperationsAfterDispose_Throw()
     {
@@ -807,6 +963,9 @@ public class OpcUaClientServiceTests : IDisposable
 
     // --- Factory tests ---
 
+    /// <summary>
+    /// Verifies that the factory creates a usable shared OPC UA client service instance.
+    /// </summary>
     [Fact]
     public void OpcUaClientServiceFactory_CreatesService()
     {
@@ -816,4 +975,4 @@ public class OpcUaClientServiceTests : IDisposable
         service.ShouldBeAssignableTo<IOpcUaClientService>();
         service.Dispose();
     }
-}
+}