dohertj2/ScadaBridge
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(tests): fix CommentChecker findings across tests/ — 13,392 → 0 (repo-wide scan clean)

Browse Source 
Comment/XML-doc changes only:
- add summaries to ~10k test methods, fixtures, fakes and helpers
  (+ <param> on theories, <returns> on async Task methods,
  <inheritdoc/> on interface implementations the checker can resolve)
- strip ~2.6k project-tracking references (WP*, P*-*, row-NN, Task N,
  #NN, Component-0NN) from comments, keeping the explanatory text;
  reword false positives in comments only
- real docs on fakes implementing BCL/library interfaces
  (IDisposable, ILogger, IOptionsMonitor, IAsyncLifetime)
- reword the last 5 src/ false positives (CWE-1236, failures-1,
  year-0001, M365)

Only non-comment edits: four one-line nested classes split across lines
so members can carry docs. Build 0 errors / 0 warnings.
This commit is contained in:
Joseph Doherty
2026-10-07 15:05:49 -04:00
parent 0ffd4bdbea
commit 513fa1aa16
998 changed files with 17896 additions and 2395 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/ZB.MOM.WW.ScadaBridge.Communication.Tests/Grpc/SiteStreamGrpcClientTests.cs
+62 -5
View File
@@ -8,6 +8,7 @@ namespace ZB.MOM.WW.ScadaBridge.Communication.Tests.Grpc;
public class SiteStreamGrpcClientTests
{
/// <summary>Verifies that the connected-header timeout is fixed for the lifetime of a client.</summary>
[Fact]
public void ConnectedHeaderTimeout_IsImmutablePerClient()
{
@@ -17,6 +18,7 @@ public class SiteStreamGrpcClientTests
Assert.Null(property.SetMethod);
}
/// <summary>Verifies that an attribute-changed stream event converts to the matching domain event.</summary>
[Fact]
public void ConvertToDomainEvent_AttributeChanged_MapsCorrectly()
{
@@ -46,6 +48,7 @@ public class SiteStreamGrpcClientTests
Assert.Equal(ts, attr.Timestamp);
}
/// <summary>Verifies that an alarm-changed stream event converts to the matching domain event.</summary>
[Fact]
public void ConvertToDomainEvent_AlarmChanged_MapsCorrectly()
{
@@ -104,6 +107,7 @@ public class SiteStreamGrpcClientTests
Assert.Equal("100", alarm.LimitValue);
}
/// <summary>Verifies that an unknown stream event converts to null.</summary>
[Fact]
public void ConvertToDomainEvent_UnknownEvent_ReturnsNull()
{
@@ -118,6 +122,9 @@ public class SiteStreamGrpcClientTests
Assert.Null(result);
}
/// <summary>Verifies that each gRPC quality value maps to the expected quality string.</summary>
/// <param name="input">The gRPC quality value.</param>
/// <param name="expected">The expected quality string.</param>
[Theory]
[InlineData(Quality.Good, "Good")]
[InlineData(Quality.Uncertain, "Uncertain")]
@@ -129,6 +136,9 @@ public class SiteStreamGrpcClientTests
Assert.Equal(expected, result);
}
/// <summary>Verifies that each gRPC alarm state maps to the expected domain alarm state.</summary>
/// <param name="input">The gRPC alarm state.</param>
/// <param name="expected">The expected domain alarm state.</param>
[Theory]
[InlineData(AlarmStateEnum.AlarmStateNormal, AlarmState.Normal)]
[InlineData(AlarmStateEnum.AlarmStateActive, AlarmState.Active)]
@@ -139,6 +149,9 @@ public class SiteStreamGrpcClientTests
Assert.Equal(expected, result);
}
/// <summary>Verifies that each gRPC alarm level maps to the expected domain alarm level.</summary>
/// <param name="input">The gRPC alarm level.</param>
/// <param name="expected">The expected domain alarm level.</param>
[Theory]
[InlineData(AlarmLevelEnum.AlarmLevelNone, AlarmLevel.None)]
[InlineData(AlarmLevelEnum.AlarmLevelLow, AlarmLevel.Low)]
@@ -151,6 +164,7 @@ public class SiteStreamGrpcClientTests
Assert.Equal(expected, result);
}
/// <summary>Verifies that converting an alarm-changed event preserves the alarm level.</summary>
[Fact]
public void ConvertToDomainEvent_AlarmChanged_PreservesLevel()
{
@@ -177,6 +191,7 @@ public class SiteStreamGrpcClientTests
Assert.Equal(900, domain.Priority);
}
/// <summary>Verifies that unsubscribing cancels the subscription.</summary>
[Fact]
public void Unsubscribe_CancelsSubscription()
{
@@ -195,6 +210,7 @@ public class SiteStreamGrpcClientTests
Assert.True(cts.IsCancellationRequested);
}
/// <summary>Verifies that unsubscribing from a nonexistent subscription does not throw.</summary>
[Fact]
public void Unsubscribe_NonExistent_DoesNotThrow()
{
@@ -202,6 +218,8 @@ public class SiteStreamGrpcClientTests
client.Unsubscribe("does-not-exist"); // Should not throw
}
/// <summary>Verifies that disposing the client cancels all subscriptions.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task DisposeAsync_CancelsAllSubscriptions()
{
@@ -218,8 +236,9 @@ public class SiteStreamGrpcClientTests
Assert.True(cts2.IsCancellationRequested);
}
// --- Site-wide (SubscribeSite) alarm-only stream (plan #10 T3) ---
// --- Site-wide (SubscribeSite) alarm-only stream ---
/// <summary>Verifies that an alarm-changed event converts to the mapped alarm event.</summary>
[Fact]
public void ConvertToAlarmEvent_AlarmChanged_ReturnsMappedAlarm()
{
@@ -251,6 +270,7 @@ public class SiteStreamGrpcClientTests
Assert.Equal("T01.Hi", alarm.SourceReference);
}
/// <summary>Verifies that an attribute-changed event converts to no alarm event.</summary>
[Fact]
public void ConvertToAlarmEvent_AttributeChanged_ReturnsNull()
{
@@ -273,6 +293,7 @@ public class SiteStreamGrpcClientTests
Assert.Null(SiteStreamGrpcClient.ConvertToAlarmEvent(evt));
}
/// <summary>Verifies that an unknown event converts to no alarm event.</summary>
[Fact]
public void ConvertToAlarmEvent_UnknownEvent_ReturnsNull()
{
@@ -280,6 +301,8 @@ public class SiteStreamGrpcClientTests
Assert.Null(SiteStreamGrpcClient.ConvertToAlarmEvent(evt));
}
/// <summary>Verifies that subscribing a site on a test-only client throws.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task SubscribeSiteAsync_OnTestOnlyClient_Throws()
{
@@ -290,8 +313,10 @@ public class SiteStreamGrpcClientTests
client.SubscribeSiteAsync("corr", _ => { }, _ => { }, () => { }, CancellationToken.None));
}
// --- WP1.1: graceful (status OK) stream completion is reported, not swallowed ---
// --- Graceful (status OK) stream completion is reported, not swallowed ---
/// <summary>Verifies that a stream the server ends with an OK status invokes the completed callback and not the error callback.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConsumeStream_ServerEndsStreamWithOk_InvokesOnCompleted_NotOnError()
{
@@ -316,6 +341,8 @@ public class SiteStreamGrpcClientTests
Assert.Equal(1, completed);
}
/// <summary>Verifies that a faulting stream invokes the error callback and not the completed callback.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConsumeStream_StreamFaults_InvokesOnError_NotOnCompleted()
{
@@ -337,6 +364,8 @@ public class SiteStreamGrpcClientTests
Assert.Equal(0, completed);
}
/// <summary>Verifies that cancelling the client's own token invokes neither the error nor the completed callback.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConsumeStream_OwnCancellation_InvokesNeitherCallback()
{
@@ -362,6 +391,8 @@ public class SiteStreamGrpcClientTests
// --- Foreign vs. own Cancelled (review F2) ---
/// <summary>Verifies that a cancellation not initiated by the client invokes the error callback.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConsumeStream_ForeignCancelled_InvokesOnError()
{
@@ -390,6 +421,8 @@ public class SiteStreamGrpcClientTests
Assert.False(cts.IsCancellationRequested);
}
/// <summary>Verifies that a cancelled RPC exception caused by the client's own cancellation invokes neither callback.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConsumeStream_OwnCancelledRpcException_InvokesNeitherCallback()
{
@@ -415,6 +448,8 @@ public class SiteStreamGrpcClientTests
// --- onConnected is only ever raised on real proof of a live peer (review F3) ---
/// <summary>Verifies that the connected callback is invoked exactly once when the response headers arrive.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConsumeStream_HeadersArrive_InvokesOnConnectedOnce()
{
@@ -439,6 +474,8 @@ public class SiteStreamGrpcClientTests
Assert.Equal(1, connected);
}
/// <summary>Verifies that a header timeout on a dead site never reports a connected state.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConsumeStream_HeaderTimeoutOnADeadSite_NeverReportsConnected()
{
@@ -464,6 +501,8 @@ public class SiteStreamGrpcClientTests
Assert.Equal(0, connected);
}
/// <summary>Verifies that a header timeout followed by an event reports connected exactly once, triggered by the event.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConsumeStream_HeaderTimeoutThenEvent_ReportsConnectedOnceFromTheEvent()
{
@@ -514,6 +553,7 @@ public class SiteStreamGrpcClientTests
}
};
/// <summary>Verifies that a plain frame is delivered unchanged.</summary>
[Fact]
public void ForEachEvent_PlainFrame_IsDeliveredAsIs()
{
@@ -528,6 +568,7 @@ public class SiteStreamGrpcClientTests
Assert.Same(frame, Assert.Single(seen));
}
/// <summary>Verifies that a batch frame is unpacked in order with each event's own timestamp preserved.</summary>
[Fact]
public void ForEachEvent_BatchFrame_UnpacksInOrderPreservingPerEventTimestamps()
{
@@ -558,6 +599,7 @@ public class SiteStreamGrpcClientTests
seen.Select(e => e.AttributeChanged.Timestamp.ToDateTimeOffset()));
}
/// <summary>Verifies that nested batches and unknown inner cases are ignored.</summary>
[Fact]
public void ForEachEvent_IgnoresNestedAndUnknownInnerCases()
{
@@ -585,6 +627,8 @@ public class SiteStreamGrpcClientTests
Assert.Equal(["0", "1"], seen.Select(e => e.AttributeChanged.Value));
}
/// <summary>Verifies that a stream mixing batched and plain frames delivers every event in order.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConsumeStream_MixedBatchedAndPlainFrames_DeliverEveryEventInOrder()
{
@@ -638,19 +682,27 @@ public class SiteStreamGrpcClientTests
private readonly Queue<SiteStreamEvent> _events;
private readonly Exception? _fault;
/// <summary>Initializes the reader to yield the given events and then end the stream.</summary>
/// <param name="events">The events to yield.</param>
public StubStreamReader(params SiteStreamEvent[] events)
{
_events = new Queue<SiteStreamEvent>(events);
}
/// <summary>Initializes the reader to throw the given fault when read.</summary>
/// <param name="fault">The exception to throw.</param>
public StubStreamReader(Exception fault)
: this()
{
_fault = fault;
}
/// <summary>Gets the event most recently read.</summary>
public SiteStreamEvent Current { get; private set; } = null!;
/// <summary>Advances to the next queued event, or faults or completes as configured.</summary>
/// <param name="cancellationToken">A token to cancel the operation.</param>
/// <returns>A task whose result is <see langword="true"/> if an event was read; otherwise <see langword="false"/>.</returns>
public Task<bool> MoveNext(CancellationToken cancellationToken)
{
cancellationToken.ThrowIfCancellationRequested();
@@ -665,14 +717,15 @@ public class SiteStreamGrpcClientTests
}
}
// --- Communication-003 regression tests ---
// --- Subscription registration regression tests ---
/// <summary>Verifies that reusing a correlation id cancels the prior token source without disposing it.</summary>
[Fact]
public void RegisterSubscription_ReusedCorrelationId_CancelsPriorCts_WithoutDisposingIt()
{
// Two SubscribeAsync calls briefly sharing a correlation ID (reconnect race).
// Inserting the second must CANCEL the first — and must NOT dispose it (arch-review
// 2026-08-19 P3-1, re-pinning the earlier cancel-AND-dispose contract): the prior
// Inserting the second must CANCEL the first — and must NOT dispose it (re-pinning the earlier
// cancel-AND-dispose contract): the prior
// handler's ConsumeStreamAsync is still running and still reads prior.Token, so
// disposing from the replacing path throws ObjectDisposedException inside that loop.
// The owning SubscribeAsync/SubscribeSiteAsync disposes it as its loop unwinds.
@@ -692,6 +745,7 @@ public class SiteStreamGrpcClientTests
Assert.False(second.IsCancellationRequested);
}
/// <summary>Verifies that replacing an already-disposed prior token source does not throw into the new subscription.</summary>
[Fact]
public void RegisterSubscription_ReplacingAnAlreadyDisposedPriorCts_DoesNotThrowIntoTheNewSubscription()
{
@@ -714,6 +768,7 @@ public class SiteStreamGrpcClientTests
Assert.True(replacement.IsCancellationRequested);
}
/// <summary>Verifies that unsubscribing after the client is disposed does nothing.</summary>
[Fact]
public void Unsubscribe_AfterClientDisposal_IsANoOp()
{
@@ -731,6 +786,7 @@ public class SiteStreamGrpcClientTests
client.Unsubscribe("never-registered");
}
/// <summary>Verifies that disposing the client still cancels the remaining subscriptions when one token source is already disposed.</summary>
[Fact]
public void Dispose_WithAnAlreadyDisposedSubscriptionCts_StillCancelsTheRest()
{
@@ -753,6 +809,7 @@ public class SiteStreamGrpcClientTests
Assert.True(live.IsCancellationRequested);
}
/// <summary>Verifies that removing a subscription removes only its own token source and not a replacement registered under the same id.</summary>
[Fact]
public void RemoveSubscription_OnlyRemovesOwnCts_NotAReplacement()
{