Document client stack XML docs progress

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();
     }
-}
+}