docs(mqttrelay-tests): author XML doc comments on test surface

ottobolyos · ottobolyos · commit 4fe414f81777 · 2026-06-01T12:32:18.000+02:00
diff --git a/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/AsyncVoidGuardTests.cs b/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/AsyncVoidGuardTests.cs
@@ -33,6 +33,8 @@ namespace MTConnect.AgentModule.MqttRelay.Tests
     [TestFixture]
     public class AsyncVoidGuardTests
     {
+        /// <summary>Pins the behaviour expressed by the test name: run completes normally when body succeeds.</summary>
+        /// <returns>The result of the operation.</returns>
         [Test]
         public async Task Run_completes_normally_when_body_succeeds()
         {
@@ -46,6 +48,8 @@ await AsyncVoidGuard.Run(
                 "Successful body must not invoke the fault logger.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: run routes synchronous throw to logger.</summary>
+        /// <returns>The result of the operation.</returns>
         [Test]
         public async Task Run_routes_synchronous_throw_to_logger()
         {
@@ -58,6 +62,8 @@ await AsyncVoidGuard.Run(
             Assert.That(loggedFault, Is.EqualTo("sync throw"));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: run routes async throw to logger.</summary>
+        /// <returns>The result of the operation.</returns>
         [Test]
         public async Task Run_routes_async_throw_to_logger()
         {
@@ -70,6 +76,8 @@ await AsyncVoidGuard.Run(
             Assert.That(loggedFault, Is.EqualTo("async throw"));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: run does not rethrow when logger is null.</summary>
+        /// <returns>The result of the operation.</returns>
         [Test]
         public async Task Run_does_not_rethrow_when_logger_is_null()
         {
@@ -82,6 +90,8 @@ await AsyncVoidGuard.Run(
             Assert.Pass();
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: run does not rethrow when logger itself throws.</summary>
+        /// <returns>The result of the operation.</returns>
         [Test]
         public async Task Run_does_not_rethrow_when_logger_itself_throws()
         {
@@ -94,6 +104,8 @@ await AsyncVoidGuard.Run(
             Assert.Pass();
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: run no ops when body is null.</summary>
+        /// <returns>The result of the operation.</returns>
         [Test]
         public async Task Run_no_ops_when_body_is_null()
         {
diff --git a/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/AvailabilityTopicRegressionTests.cs b/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/AvailabilityTopicRegressionTests.cs
@@ -29,6 +29,7 @@ namespace MTConnect.AgentModule.MqttRelay.Tests
     [TestFixture]
     public class AvailabilityTopicRegressionTests
     {
+        /// <summary>Pins the behaviour expressed by the test name: topic never contains probe segment for any inputs.</summary>
         [Test]
         public void Topic_never_contains_probe_segment_for_any_inputs()
         {
@@ -75,6 +76,7 @@ public void Topic_never_contains_probe_segment_for_any_inputs()
             }
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: agent segment is distinct from probe constant.</summary>
         [Test]
         public void Agent_segment_is_distinct_from_probe_constant()
         {
diff --git a/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/AvailabilityTopicTests.cs b/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/AvailabilityTopicTests.cs
@@ -32,6 +32,7 @@ namespace MTConnect.AgentModule.MqttRelay.Tests
     [TestFixture]
     public class AvailabilityTopicTests
     {
+        /// <summary>Pins the behaviour expressed by the test name: build returns topic outside probe wildcard.</summary>
         [Test]
         public void Build_returns_topic_outside_probe_wildcard()
         {
@@ -43,6 +44,7 @@ public void Build_returns_topic_outside_probe_wildcard()
                 "MqttRelay availability topic must not fall under the Probe/# wildcard.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: build uses dedicated agent segment.</summary>
         [Test]
         public void Build_uses_dedicated_agent_segment()
         {
@@ -57,6 +59,7 @@ public void Build_uses_dedicated_agent_segment()
             Assert.That(topic, Is.EqualTo("MTConnect/Agent/agent-uuid-1/Available"));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: build preserves multi segment topic prefix.</summary>
         [Test]
         public void Build_preserves_multi_segment_topic_prefix()
         {
@@ -72,30 +75,35 @@ public void Build_preserves_multi_segment_topic_prefix()
             Assert.That(topic, Does.Not.Contain("/Probe/"));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: build returns null when topic prefix is null.</summary>
         [Test]
         public void Build_returns_null_when_topic_prefix_is_null()
         {
             Assert.That(AvailabilityTopic.Build(null, "agent-uuid-1"), Is.Null);
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: build returns null when topic prefix is empty.</summary>
         [Test]
         public void Build_returns_null_when_topic_prefix_is_empty()
         {
             Assert.That(AvailabilityTopic.Build(string.Empty, "agent-uuid-1"), Is.Null);
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: build returns null when agent uuid is null.</summary>
         [Test]
         public void Build_returns_null_when_agent_uuid_is_null()
         {
             Assert.That(AvailabilityTopic.Build("MTConnect", null), Is.Null);
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: build returns null when agent uuid is empty.</summary>
         [Test]
         public void Build_returns_null_when_agent_uuid_is_empty()
         {
             Assert.That(AvailabilityTopic.Build("MTConnect", string.Empty), Is.Null);
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: available segment constant pins trailing topic segment.</summary>
         [Test]
         public void AvailableSegment_constant_pins_trailing_topic_segment()
         {
diff --git a/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/AvailabilityTopicValidationTests.cs b/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/AvailabilityTopicValidationTests.cs
@@ -26,6 +26,9 @@ namespace MTConnect.AgentModule.MqttRelay.Tests
     [TestFixture]
     public class AvailabilityTopicValidationTests
     {
+        /// <summary>Pins the behaviour expressed by the test name: build returns null when reserved character present.</summary>
+        /// <param name="topicPrefix">The topic prefix.</param>
+        /// <param name="agentUuid">The agent uuid.</param>
         [TestCase("MTConnect+", "agent-uuid-1")]
         [TestCase("MTConnect#", "agent-uuid-1")]
         [TestCase("MTConnect\0", "agent-uuid-1")]
@@ -41,6 +44,9 @@ public void Build_returns_null_when_reserved_character_present(
                 $"Build({topicPrefix}, {agentUuid}) should reject MQTT-reserved characters.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: build returns null when input is whitespace only.</summary>
+        /// <param name="topicPrefix">The topic prefix.</param>
+        /// <param name="agentUuid">The agent uuid.</param>
         [TestCase("   ", "agent-uuid-1")]
         [TestCase("MTConnect", "   ")]
         public void Build_returns_null_when_input_is_whitespace_only(
@@ -56,6 +62,7 @@ public void Build_returns_null_when_input_is_whitespace_only(
                 $"Build({topicPrefix}, {agentUuid}) should reject whitespace-only input.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: build rejects slash inside agent uuid segment.</summary>
         [Test]
         public void Build_rejects_slash_inside_agent_uuid_segment()
         {
@@ -67,6 +74,7 @@ public void Build_rejects_slash_inside_agent_uuid_segment()
                 Is.Null);
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: build strips leading slash from topic prefix.</summary>
         [Test]
         public void Build_strips_leading_slash_from_topic_prefix()
         {
@@ -79,6 +87,7 @@ public void Build_strips_leading_slash_from_topic_prefix()
                 Is.EqualTo("MTConnect/Agent/agent-1/Available"));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: build strips trailing slash from topic prefix.</summary>
         [Test]
         public void Build_strips_trailing_slash_from_topic_prefix()
         {
diff --git a/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/LastSentSequencePersisterTests.cs b/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/LastSentSequencePersisterTests.cs
@@ -23,6 +23,7 @@ namespace MTConnect.AgentModule.MqttRelay.Tests
     [TestFixture]
     public class LastSentSequencePersisterTests
     {
+        /// <summary>Pins the behaviour expressed by the test name: update marks dirty and round trips through read.</summary>
         [Test]
         public void Update_marks_dirty_and_round_trips_through_read()
         {
@@ -35,6 +36,7 @@ public void Update_marks_dirty_and_round_trips_through_read()
                 "An in-memory update must mark the persister dirty so the caller knows to flush.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: read does not clear dirty bit.</summary>
         [Test]
         public void Read_does_not_clear_dirty_bit()
         {
@@ -47,6 +49,7 @@ public void Read_does_not_clear_dirty_bit()
                 "Read must not clear dirty: only Flush establishes durable persistence.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: try flush writes only when dirty and clears dirty on success.</summary>
         [Test]
         public void TryFlush_writes_only_when_dirty_and_clears_dirty_on_success()
         {
@@ -63,6 +66,7 @@ public void TryFlush_writes_only_when_dirty_and_clears_dirty_on_success()
                 "After a successful flush the persister must be clean so the next timer tick does not redundantly write.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: try flush no ops when not dirty.</summary>
         [Test]
         public void TryFlush_no_ops_when_not_dirty()
         {
@@ -76,6 +80,7 @@ public void TryFlush_no_ops_when_not_dirty()
                 "A clean persister must not invoke the writer; that would burn IOPS for no progress.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: try flush keeps dirty when writer throws.</summary>
         [Test]
         public void TryFlush_keeps_dirty_when_writer_throws()
         {
@@ -92,6 +97,7 @@ public void TryFlush_keeps_dirty_when_writer_throws()
             Assert.That(persister.Read(), Is.EqualTo(123UL));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: update is a last write wins overwrite.</summary>
         [Test]
         public void Update_is_a_last_write_wins_overwrite()
         {
@@ -103,6 +109,7 @@ public void Update_is_a_last_write_wins_overwrite()
                 "Last write wins; the persister is not a max-watermark.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: initialize seeds value without marking dirty.</summary>
         [Test]
         public void Initialize_seeds_value_without_marking_dirty()
         {
@@ -118,6 +125,7 @@ public void Initialize_seeds_value_without_marking_dirty()
                 "Initialize seeds the in-memory value from disk and must not request a redundant flush.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: try flush no ops when writer is null.</summary>
         [Test]
         public void TryFlush_no_ops_when_writer_is_null()
         {
diff --git a/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/MqttRelayLifecycleDisconnectTests.cs b/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/MqttRelayLifecycleDisconnectTests.cs
@@ -29,6 +29,7 @@ namespace MTConnect.AgentModule.MqttRelay.Tests
     [TestFixture]
     public class MqttRelayLifecycleDisconnectTests
     {
+        /// <summary>Pins the behaviour expressed by the test name: disconnect with timeout returns when disconnect completes.</summary>
         [Test]
         public void DisconnectWithTimeout_returns_when_disconnect_completes()
         {
@@ -45,6 +46,7 @@ public void DisconnectWithTimeout_returns_when_disconnect_completes()
                 "Successful disconnect must not invoke the fault logger.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: disconnect with timeout logs fault when disconnect throws.</summary>
         [Test]
         public void DisconnectWithTimeout_logs_fault_when_disconnect_throws()
         {
@@ -59,6 +61,7 @@ public void DisconnectWithTimeout_logs_fault_when_disconnect_throws()
                 "A faulted disconnect Task must surface its exception to the logger.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: disconnect with timeout returns after timeout when disconnect hangs.</summary>
         [Test]
         public void DisconnectWithTimeout_returns_after_timeout_when_disconnect_hangs()
         {
@@ -77,6 +80,7 @@ public void DisconnectWithTimeout_returns_after_timeout_when_disconnect_hangs()
                 "Hung disconnect must bail out near the configured timeout.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: disconnect with timeout does not throw when disconnect factory throws synchronously.</summary>
         [Test]
         public void DisconnectWithTimeout_does_not_throw_when_disconnect_factory_throws_synchronously()
         {
@@ -93,6 +97,7 @@ public void DisconnectWithTimeout_does_not_throw_when_disconnect_factory_throws_
             Assert.That(loggedFault, Is.EqualTo("sync throw"));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: disconnect with timeout no ops when disconnect factory is null.</summary>
         [Test]
         public void DisconnectWithTimeout_no_ops_when_disconnect_factory_is_null()
         {
diff --git a/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/MqttRelayLifecycleStopTests.cs b/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/MqttRelayLifecycleStopTests.cs
@@ -24,6 +24,7 @@ namespace MTConnect.AgentModule.MqttRelay.Tests
     [TestFixture]
     public class MqttRelayLifecycleStopTests
     {
+        /// <summary>Pins the behaviour expressed by the test name: stop servers does not throw when both servers null.</summary>
         [Test]
         public void StopServers_does_not_throw_when_both_servers_null()
         {
@@ -34,6 +35,7 @@ public void StopServers_does_not_throw_when_both_servers_null()
                 () => MqttRelayLifecycle.StopServers(documentStop: null, entityStop: null));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: stop servers invokes document stop when provided.</summary>
         [Test]
         public void StopServers_invokes_document_stop_when_provided()
         {
@@ -46,6 +48,7 @@ public void StopServers_invokes_document_stop_when_provided()
                 "Document-mode shutdown must invoke the document-server stop action.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: stop servers invokes entity stop when provided.</summary>
         [Test]
         public void StopServers_invokes_entity_stop_when_provided()
         {
@@ -58,6 +61,7 @@ public void StopServers_invokes_entity_stop_when_provided()
                 "Entity-mode shutdown must invoke the entity-server stop action.");
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: stop servers invokes both when both provided.</summary>
         [Test]
         public void StopServers_invokes_both_when_both_provided()
         {
@@ -72,6 +76,7 @@ public void StopServers_invokes_both_when_both_provided()
             Assert.That(entityStopped, Is.True);
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: stop servers swallows document stop exception and runs entity stop.</summary>
         [Test]
         public void StopServers_swallows_document_stop_exception_and_runs_entity_stop()
         {
diff --git a/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/ObservationGrouperTests.cs b/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/ObservationGrouperTests.cs
@@ -38,12 +38,14 @@ namespace MTConnect.AgentModule.MqttRelay.Tests
     [TestFixture]
     public class ObservationGrouperTests
     {
+        /// <summary>Pins the behaviour expressed by the test name: group by data item returns empty when input null.</summary>
         [Test]
         public void GroupByDataItem_returns_empty_when_input_null()
         {
             Assert.That(ObservationGrouper.GroupByDataItem(null), Is.Empty);
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: group by data item returns empty when input empty.</summary>
         [Test]
         public void GroupByDataItem_returns_empty_when_input_empty()
         {
@@ -52,6 +54,7 @@ public void GroupByDataItem_returns_empty_when_input_empty()
                 Is.Empty);
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: group by data item groups observations by data item id.</summary>
         [Test]
         public void GroupByDataItem_groups_observations_by_data_item_id()
         {
@@ -78,6 +81,7 @@ public void GroupByDataItem_groups_observations_by_data_item_id()
             Assert.That(groupC.Select(o => o.Sequence), Is.EquivalentTo(new ulong[] { 4 }));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: group by data item iterates source exactly once.</summary>
         [Test]
         public void GroupByDataItem_iterates_source_exactly_once()
         {
@@ -103,6 +107,7 @@ IEnumerable<IObservationOutput> Source()
             Assert.That(groups, Has.Count.EqualTo(2));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: group by data item preserves first seen order per group.</summary>
         [Test]
         public void GroupByDataItem_preserves_first_seen_order_per_group()
         {
@@ -121,6 +126,7 @@ public void GroupByDataItem_preserves_first_seen_order_per_group()
                 Is.EqualTo(new ulong[] { 10, 11, 12 }));
         }
 
+        /// <summary>Pins the behaviour expressed by the test name: group by data item handles null data item id as distinct group.</summary>
         [Test]
         public void GroupByDataItem_handles_null_data_item_id_as_distinct_group()
         {
diff --git a/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/RelayBufferDiagnosticsTests.cs b/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/RelayBufferDiagnosticsTests.cs
diff --git a/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/WorkerLoopExceptionLoggerTests.cs b/tests/MTConnect.NET-AgentModule-MqttRelay-Tests/WorkerLoopExceptionLoggerTests.cs

Original file line number	Diff line number	Diff line change
`@@ -33,6 +33,8 @@ namespace MTConnect.AgentModule.MqttRelay.Tests`
`33`	`33`	`[TestFixture]`
`34`	`34`	`public class AsyncVoidGuardTests`
`35`	`35`	`{`
	`36`	`+ /// <summary>Pins the behaviour expressed by the test name: run completes normally when body succeeds.</summary>`
	`37`	`+ /// <returns>The result of the operation.</returns>`
`36`	`38`	`[Test]`
`37`	`39`	`public async Task Run_completes_normally_when_body_succeeds()`
`38`	`40`	`{`
`@@ -46,6 +48,8 @@ await AsyncVoidGuard.Run(`
`46`	`48`	`"Successful body must not invoke the fault logger.");`
`47`	`49`	`}`
`48`	`50`
	`51`	`+ /// <summary>Pins the behaviour expressed by the test name: run routes synchronous throw to logger.</summary>`
	`52`	`+ /// <returns>The result of the operation.</returns>`
`49`	`53`	`[Test]`
`50`	`54`	`public async Task Run_routes_synchronous_throw_to_logger()`
`51`	`55`	`{`
`@@ -58,6 +62,8 @@ await AsyncVoidGuard.Run(`
`58`	`62`	`Assert.That(loggedFault, Is.EqualTo("sync throw"));`
`59`	`63`	`}`
`60`	`64`
	`65`	`+ /// <summary>Pins the behaviour expressed by the test name: run routes async throw to logger.</summary>`
	`66`	`+ /// <returns>The result of the operation.</returns>`
`61`	`67`	`[Test]`
`62`	`68`	`public async Task Run_routes_async_throw_to_logger()`
`63`	`69`	`{`
`@@ -70,6 +76,8 @@ await AsyncVoidGuard.Run(`
`70`	`76`	`Assert.That(loggedFault, Is.EqualTo("async throw"));`
`71`	`77`	`}`
`72`	`78`
	`79`	`+ /// <summary>Pins the behaviour expressed by the test name: run does not rethrow when logger is null.</summary>`
	`80`	`+ /// <returns>The result of the operation.</returns>`
`73`	`81`	`[Test]`
`74`	`82`	`public async Task Run_does_not_rethrow_when_logger_is_null()`
`75`	`83`	`{`
`@@ -82,6 +90,8 @@ await AsyncVoidGuard.Run(`
`82`	`90`	`Assert.Pass();`
`83`	`91`	`}`
`84`	`92`
	`93`	`+ /// <summary>Pins the behaviour expressed by the test name: run does not rethrow when logger itself throws.</summary>`
	`94`	`+ /// <returns>The result of the operation.</returns>`
`85`	`95`	`[Test]`
`86`	`96`	`public async Task Run_does_not_rethrow_when_logger_itself_throws()`
`87`	`97`	`{`
`@@ -94,6 +104,8 @@ await AsyncVoidGuard.Run(`
`94`	`104`	`Assert.Pass();`
`95`	`105`	`}`
`96`	`106`
	`107`	`+ /// <summary>Pins the behaviour expressed by the test name: run no ops when body is null.</summary>`
	`108`	`+ /// <returns>The result of the operation.</returns>`
`97`	`109`	`[Test]`
`98`	`110`	`public async Task Run_no_ops_when_body_is_null()`
`99`	`111`	`{`
Original file line number	Diff line number	Diff line change
`@@ -29,6 +29,7 @@ namespace MTConnect.AgentModule.MqttRelay.Tests`
`29`	`29`	`[TestFixture]`
`30`	`30`	`public class AvailabilityTopicRegressionTests`
`31`	`31`	`{`
	`32`	`+ /// <summary>Pins the behaviour expressed by the test name: topic never contains probe segment for any inputs.</summary>`
`32`	`33`	`[Test]`
`33`	`34`	`public void Topic_never_contains_probe_segment_for_any_inputs()`
`34`	`35`	`{`
`@@ -75,6 +76,7 @@ public void Topic_never_contains_probe_segment_for_any_inputs()`
`75`	`76`	`}`
`76`	`77`	`}`
`77`	`78`
	`79`	`+ /// <summary>Pins the behaviour expressed by the test name: agent segment is distinct from probe constant.</summary>`
`78`	`80`	`[Test]`
`79`	`81`	`public void Agent_segment_is_distinct_from_probe_constant()`
`80`	`82`	`{`
Original file line number	Diff line number	Diff line change
`@@ -32,6 +32,7 @@ namespace MTConnect.AgentModule.MqttRelay.Tests`
`32`	`32`	`[TestFixture]`
`33`	`33`	`public class AvailabilityTopicTests`
`34`	`34`	`{`
	`35`	`+ /// <summary>Pins the behaviour expressed by the test name: build returns topic outside probe wildcard.</summary>`
`35`	`36`	`[Test]`
`36`	`37`	`public void Build_returns_topic_outside_probe_wildcard()`
`37`	`38`	`{`
`@@ -43,6 +44,7 @@ public void Build_returns_topic_outside_probe_wildcard()`
`43`	`44`	`"MqttRelay availability topic must not fall under the Probe/# wildcard.");`
`44`	`45`	`}`
`45`	`46`
	`47`	`+ /// <summary>Pins the behaviour expressed by the test name: build uses dedicated agent segment.</summary>`
`46`	`48`	`[Test]`
`47`	`49`	`public void Build_uses_dedicated_agent_segment()`
`48`	`50`	`{`
`@@ -57,6 +59,7 @@ public void Build_uses_dedicated_agent_segment()`
`57`	`59`	`Assert.That(topic, Is.EqualTo("MTConnect/Agent/agent-uuid-1/Available"));`
`58`	`60`	`}`
`59`	`61`
	`62`	`+ /// <summary>Pins the behaviour expressed by the test name: build preserves multi segment topic prefix.</summary>`
`60`	`63`	`[Test]`
`61`	`64`	`public void Build_preserves_multi_segment_topic_prefix()`
`62`	`65`	`{`
`@@ -72,30 +75,35 @@ public void Build_preserves_multi_segment_topic_prefix()`
`72`	`75`	`Assert.That(topic, Does.Not.Contain("/Probe/"));`
`73`	`76`	`}`
`74`	`77`
	`78`	`+ /// <summary>Pins the behaviour expressed by the test name: build returns null when topic prefix is null.</summary>`
`75`	`79`	`[Test]`
`76`	`80`	`public void Build_returns_null_when_topic_prefix_is_null()`
`77`	`81`	`{`
`78`	`82`	`Assert.That(AvailabilityTopic.Build(null, "agent-uuid-1"), Is.Null);`
`79`	`83`	`}`
`80`	`84`
	`85`	`+ /// <summary>Pins the behaviour expressed by the test name: build returns null when topic prefix is empty.</summary>`
`81`	`86`	`[Test]`
`82`	`87`	`public void Build_returns_null_when_topic_prefix_is_empty()`
`83`	`88`	`{`
`84`	`89`	`Assert.That(AvailabilityTopic.Build(string.Empty, "agent-uuid-1"), Is.Null);`
`85`	`90`	`}`
`86`	`91`
	`92`	`+ /// <summary>Pins the behaviour expressed by the test name: build returns null when agent uuid is null.</summary>`
`87`	`93`	`[Test]`
`88`	`94`	`public void Build_returns_null_when_agent_uuid_is_null()`
`89`	`95`	`{`
`90`	`96`	`Assert.That(AvailabilityTopic.Build("MTConnect", null), Is.Null);`
`91`	`97`	`}`
`92`	`98`
	`99`	`+ /// <summary>Pins the behaviour expressed by the test name: build returns null when agent uuid is empty.</summary>`
`93`	`100`	`[Test]`
`94`	`101`	`public void Build_returns_null_when_agent_uuid_is_empty()`
`95`	`102`	`{`
`96`	`103`	`Assert.That(AvailabilityTopic.Build("MTConnect", string.Empty), Is.Null);`
`97`	`104`	`}`
`98`	`105`
	`106`	`+ /// <summary>Pins the behaviour expressed by the test name: available segment constant pins trailing topic segment.</summary>`
`99`	`107`	`[Test]`
`100`	`108`	`public void AvailableSegment_constant_pins_trailing_topic_segment()`
`101`	`109`	`{`
Original file line number	Diff line number	Diff line change
`@@ -26,6 +26,9 @@ namespace MTConnect.AgentModule.MqttRelay.Tests`
`26`	`26`	`[TestFixture]`
`27`	`27`	`public class AvailabilityTopicValidationTests`
`28`	`28`	`{`
	`29`	`+ /// <summary>Pins the behaviour expressed by the test name: build returns null when reserved character present.</summary>`
	`30`	`+ /// <param name="topicPrefix">The topic prefix.</param>`
	`31`	`+ /// <param name="agentUuid">The agent uuid.</param>`
`29`	`32`	`[TestCase("MTConnect+", "agent-uuid-1")]`
`30`	`33`	`[TestCase("MTConnect#", "agent-uuid-1")]`
`31`	`34`	`[TestCase("MTConnect\0", "agent-uuid-1")]`
`@@ -41,6 +44,9 @@ public void Build_returns_null_when_reserved_character_present(`
`41`	`44`	`$"Build({topicPrefix}, {agentUuid}) should reject MQTT-reserved characters.");`
`42`	`45`	`}`
`43`	`46`
	`47`	`+ /// <summary>Pins the behaviour expressed by the test name: build returns null when input is whitespace only.</summary>`
	`48`	`+ /// <param name="topicPrefix">The topic prefix.</param>`
	`49`	`+ /// <param name="agentUuid">The agent uuid.</param>`
`44`	`50`	`[TestCase(" ", "agent-uuid-1")]`
`45`	`51`	`[TestCase("MTConnect", " ")]`
`46`	`52`	`public void Build_returns_null_when_input_is_whitespace_only(`
`@@ -56,6 +62,7 @@ public void Build_returns_null_when_input_is_whitespace_only(`
`56`	`62`	`$"Build({topicPrefix}, {agentUuid}) should reject whitespace-only input.");`
`57`	`63`	`}`
`58`	`64`
	`65`	`+ /// <summary>Pins the behaviour expressed by the test name: build rejects slash inside agent uuid segment.</summary>`
`59`	`66`	`[Test]`
`60`	`67`	`public void Build_rejects_slash_inside_agent_uuid_segment()`
`61`	`68`	`{`
`@@ -67,6 +74,7 @@ public void Build_rejects_slash_inside_agent_uuid_segment()`
`67`	`74`	`Is.Null);`
`68`	`75`	`}`
`69`	`76`
	`77`	`+ /// <summary>Pins the behaviour expressed by the test name: build strips leading slash from topic prefix.</summary>`
`70`	`78`	`[Test]`
`71`	`79`	`public void Build_strips_leading_slash_from_topic_prefix()`
`72`	`80`	`{`
`@@ -79,6 +87,7 @@ public void Build_strips_leading_slash_from_topic_prefix()`
`79`	`87`	`Is.EqualTo("MTConnect/Agent/agent-1/Available"));`
`80`	`88`	`}`
`81`	`89`
	`90`	`+ /// <summary>Pins the behaviour expressed by the test name: build strips trailing slash from topic prefix.</summary>`
`82`	`91`	`[Test]`
`83`	`92`	`public void Build_strips_trailing_slash_from_topic_prefix()`
`84`	`93`	`{`
Original file line number	Diff line number	Diff line change
`@@ -23,6 +23,7 @@ namespace MTConnect.AgentModule.MqttRelay.Tests`
`23`	`23`	`[TestFixture]`
`24`	`24`	`public class LastSentSequencePersisterTests`
`25`	`25`	`{`
	`26`	`+ /// <summary>Pins the behaviour expressed by the test name: update marks dirty and round trips through read.</summary>`
`26`	`27`	`[Test]`
`27`	`28`	`public void Update_marks_dirty_and_round_trips_through_read()`
`28`	`29`	`{`
`@@ -35,6 +36,7 @@ public void Update_marks_dirty_and_round_trips_through_read()`
`35`	`36`	`"An in-memory update must mark the persister dirty so the caller knows to flush.");`
`36`	`37`	`}`
`37`	`38`
	`39`	`+ /// <summary>Pins the behaviour expressed by the test name: read does not clear dirty bit.</summary>`
`38`	`40`	`[Test]`
`39`	`41`	`public void Read_does_not_clear_dirty_bit()`
`40`	`42`	`{`
`@@ -47,6 +49,7 @@ public void Read_does_not_clear_dirty_bit()`
`47`	`49`	`"Read must not clear dirty: only Flush establishes durable persistence.");`
`48`	`50`	`}`
`49`	`51`
	`52`	`+ /// <summary>Pins the behaviour expressed by the test name: try flush writes only when dirty and clears dirty on success.</summary>`
`50`	`53`	`[Test]`
`51`	`54`	`public void TryFlush_writes_only_when_dirty_and_clears_dirty_on_success()`
`52`	`55`	`{`
`@@ -63,6 +66,7 @@ public void TryFlush_writes_only_when_dirty_and_clears_dirty_on_success()`
`63`	`66`	`"After a successful flush the persister must be clean so the next timer tick does not redundantly write.");`
`64`	`67`	`}`
`65`	`68`
	`69`	`+ /// <summary>Pins the behaviour expressed by the test name: try flush no ops when not dirty.</summary>`
`66`	`70`	`[Test]`
`67`	`71`	`public void TryFlush_no_ops_when_not_dirty()`
`68`	`72`	`{`
`@@ -76,6 +80,7 @@ public void TryFlush_no_ops_when_not_dirty()`
`76`	`80`	`"A clean persister must not invoke the writer; that would burn IOPS for no progress.");`
`77`	`81`	`}`
`78`	`82`
	`83`	`+ /// <summary>Pins the behaviour expressed by the test name: try flush keeps dirty when writer throws.</summary>`
`79`	`84`	`[Test]`
`80`	`85`	`public void TryFlush_keeps_dirty_when_writer_throws()`
`81`	`86`	`{`
`@@ -92,6 +97,7 @@ public void TryFlush_keeps_dirty_when_writer_throws()`
`92`	`97`	`Assert.That(persister.Read(), Is.EqualTo(123UL));`
`93`	`98`	`}`
`94`	`99`
	`100`	`+ /// <summary>Pins the behaviour expressed by the test name: update is a last write wins overwrite.</summary>`
`95`	`101`	`[Test]`
`96`	`102`	`public void Update_is_a_last_write_wins_overwrite()`
`97`	`103`	`{`
`@@ -103,6 +109,7 @@ public void Update_is_a_last_write_wins_overwrite()`
`103`	`109`	`"Last write wins; the persister is not a max-watermark.");`
`104`	`110`	`}`
`105`	`111`
	`112`	`+ /// <summary>Pins the behaviour expressed by the test name: initialize seeds value without marking dirty.</summary>`
`106`	`113`	`[Test]`
`107`	`114`	`public void Initialize_seeds_value_without_marking_dirty()`
`108`	`115`	`{`
`@@ -118,6 +125,7 @@ public void Initialize_seeds_value_without_marking_dirty()`
`118`	`125`	`"Initialize seeds the in-memory value from disk and must not request a redundant flush.");`
`119`	`126`	`}`
`120`	`127`
	`128`	`+ /// <summary>Pins the behaviour expressed by the test name: try flush no ops when writer is null.</summary>`
`121`	`129`	`[Test]`
`122`	`130`	`public void TryFlush_no_ops_when_writer_is_null()`
`123`	`131`	`{`
Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,7 @@ namespace MTConnect.AgentModule.MqttRelay.Tests`
`24`	`24`	`[TestFixture]`
`25`	`25`	`public class MqttRelayLifecycleStopTests`
`26`	`26`	`{`
	`27`	`+ /// <summary>Pins the behaviour expressed by the test name: stop servers does not throw when both servers null.</summary>`
`27`	`28`	`[Test]`
`28`	`29`	`public void StopServers_does_not_throw_when_both_servers_null()`
`29`	`30`	`{`
`@@ -34,6 +35,7 @@ public void StopServers_does_not_throw_when_both_servers_null()`
`34`	`35`	`() => MqttRelayLifecycle.StopServers(documentStop: null, entityStop: null));`
`35`	`36`	`}`
`36`	`37`
	`38`	`+ /// <summary>Pins the behaviour expressed by the test name: stop servers invokes document stop when provided.</summary>`
`37`	`39`	`[Test]`
`38`	`40`	`public void StopServers_invokes_document_stop_when_provided()`
`39`	`41`	`{`
`@@ -46,6 +48,7 @@ public void StopServers_invokes_document_stop_when_provided()`
`46`	`48`	`"Document-mode shutdown must invoke the document-server stop action.");`
`47`	`49`	`}`
`48`	`50`
	`51`	`+ /// <summary>Pins the behaviour expressed by the test name: stop servers invokes entity stop when provided.</summary>`
`49`	`52`	`[Test]`
`50`	`53`	`public void StopServers_invokes_entity_stop_when_provided()`
`51`	`54`	`{`
`@@ -58,6 +61,7 @@ public void StopServers_invokes_entity_stop_when_provided()`
`58`	`61`	`"Entity-mode shutdown must invoke the entity-server stop action.");`
`59`	`62`	`}`
`60`	`63`
	`64`	`+ /// <summary>Pins the behaviour expressed by the test name: stop servers invokes both when both provided.</summary>`
`61`	`65`	`[Test]`
`62`	`66`	`public void StopServers_invokes_both_when_both_provided()`
`63`	`67`	`{`
`@@ -72,6 +76,7 @@ public void StopServers_invokes_both_when_both_provided()`
`72`	`76`	`Assert.That(entityStopped, Is.True);`
`73`	`77`	`}`
`74`	`78`
	`79`	`+ /// <summary>Pins the behaviour expressed by the test name: stop servers swallows document stop exception and runs entity stop.</summary>`
`75`	`80`	`[Test]`
`76`	`81`	`public void StopServers_swallows_document_stop_exception_and_runs_entity_stop()`
`77`	`82`	`{`
Original file line number	Diff line number	Diff line change
`@@ -38,12 +38,14 @@ namespace MTConnect.AgentModule.MqttRelay.Tests`
`38`	`38`	`[TestFixture]`
`39`	`39`	`public class ObservationGrouperTests`
`40`	`40`	`{`
	`41`	`+ /// <summary>Pins the behaviour expressed by the test name: group by data item returns empty when input null.</summary>`
`41`	`42`	`[Test]`
`42`	`43`	`public void GroupByDataItem_returns_empty_when_input_null()`
`43`	`44`	`{`
`44`	`45`	`Assert.That(ObservationGrouper.GroupByDataItem(null), Is.Empty);`
`45`	`46`	`}`
`46`	`47`
	`48`	`+ /// <summary>Pins the behaviour expressed by the test name: group by data item returns empty when input empty.</summary>`
`47`	`49`	`[Test]`
`48`	`50`	`public void GroupByDataItem_returns_empty_when_input_empty()`
`49`	`51`	`{`
`@@ -52,6 +54,7 @@ public void GroupByDataItem_returns_empty_when_input_empty()`
`52`	`54`	`Is.Empty);`
`53`	`55`	`}`
`54`	`56`
	`57`	`+ /// <summary>Pins the behaviour expressed by the test name: group by data item groups observations by data item id.</summary>`
`55`	`58`	`[Test]`
`56`	`59`	`public void GroupByDataItem_groups_observations_by_data_item_id()`
`57`	`60`	`{`
`@@ -78,6 +81,7 @@ public void GroupByDataItem_groups_observations_by_data_item_id()`
`78`	`81`	`Assert.That(groupC.Select(o => o.Sequence), Is.EquivalentTo(new ulong[] { 4 }));`
`79`	`82`	`}`
`80`	`83`
	`84`	`+ /// <summary>Pins the behaviour expressed by the test name: group by data item iterates source exactly once.</summary>`
`81`	`85`	`[Test]`
`82`	`86`	`public void GroupByDataItem_iterates_source_exactly_once()`
`83`	`87`	`{`
`@@ -103,6 +107,7 @@ IEnumerable<IObservationOutput> Source()`
`103`	`107`	`Assert.That(groups, Has.Count.EqualTo(2));`
`104`	`108`	`}`
`105`	`109`
	`110`	`+ /// <summary>Pins the behaviour expressed by the test name: group by data item preserves first seen order per group.</summary>`
`106`	`111`	`[Test]`
`107`	`112`	`public void GroupByDataItem_preserves_first_seen_order_per_group()`
`108`	`113`	`{`
`@@ -121,6 +126,7 @@ public void GroupByDataItem_preserves_first_seen_order_per_group()`
`121`	`126`	`Is.EqualTo(new ulong[] { 10, 11, 12 }));`
`122`	`127`	`}`
`123`	`128`
	`129`	`+ /// <summary>Pins the behaviour expressed by the test name: group by data item handles null data item id as distinct group.</summary>`
`124`	`130`	`[Test]`
`125`	`131`	`public void GroupByDataItem_handles_null_data_item_id_as_distinct_group()`
`126`	`132`	`{`