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.Host.Tests/GrpcCentralTransportTests.cs
+59 -2
View File
@@ -38,7 +38,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
private CentralNode _nodeA = null!;
private CentralNode _nodeB = null!;
/// <inheritdoc />
/// <summary>Starts the actor system and two in-process central nodes serving the same site key.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task InitializeAsync()
{
_system = ActorSystem.Create("grpc-central-transport-test");
@@ -46,7 +47,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
_nodeB = await CentralNode.StartAsync(_system, "B", SiteA, SiteAKey, repliesToSubmit: true);
}
/// <inheritdoc />
/// <summary>Disposes both central nodes and terminates the actor system.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task DisposeAsync()
{
await _nodeA.DisposeAsync();
@@ -81,6 +83,7 @@ public class GrpcCentralTransportTests : IAsyncLifetime
private GrpcCentralTransport NewTransport(CentralChannelProvider provider, CommunicationOptions? options = null)
=> new(provider, options ?? new CommunicationOptions(), NullLogger<GrpcCentralTransport>.Instance);
/// <summary>Verifies that a reconcile whose response is lost after it was applied fails as outcome-unknown instead of being re-sent to the peer.</summary>
[Fact]
public void ReconcileAppliedThenResponseLost_DoesNotMintAgainOnPeer()
{
@@ -96,6 +99,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
Assert.Equal(0, _nodeB.ReconcileCount);
}
/// <summary>Verifies that a submit reaches the preferred node and the ack is routed back to the caller.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task HappyPath_ReachesThePreferredNode_AndRoutesTheAckBack()
{
@@ -113,6 +118,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
Assert.Equal(0, _nodeB.SubmitCount);
}
/// <summary>Verifies that the transport stays on the preferred node while it remains healthy.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Sticky_StaysOnThePreferredNode_WhileHealthy()
{
@@ -131,6 +138,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
Assert.Equal(0, _nodeB.SubmitCount);
}
/// <summary>Verifies that the transport fails over to the peer when the preferred node is unavailable.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Failover_FlipsToThePeer_WhenThePreferredIsUnavailable()
{
@@ -148,6 +157,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
Assert.Equal(1, _nodeB.SubmitCount);
}
/// <summary>Verifies that the transport returns to the preferred node once it is reachable again.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Failback_ReturnsToThePreferred_OnceItIsReachableAgain()
{
@@ -173,6 +184,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
Assert.True(_nodeA.SubmitCount >= 1);
}
/// <summary>Verifies that the pre-shared key and site header are attached so the gated call reaches the service.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task PskAndSiteHeader_AreAttached_SoTheGatedCallReachesTheService()
{
@@ -188,6 +201,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
Assert.True(ack.Accepted);
}
/// <summary>Verifies that a wrong pre-shared key is rejected and not retried on the peer.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task WrongPsk_IsRejected_AndNotRetriedOnThePeer()
{
@@ -204,6 +219,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
Assert.Equal(0, _nodeB.SubmitCount); // peer never tried
}
/// <summary>Verifies that a deadline-exceeded failure is not retried on the peer.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task DeadlineExceeded_IsNotRetriedOnThePeer()
{
@@ -231,6 +248,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
Assert.Equal(0, _nodeB.SubmitCount); // peer never tried
}
/// <summary>Verifies that a black-holed node does not hang the caller because a per-call deadline is applied.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task BlackHoledNode_DoesNotHang_APerCallDeadlineIsApplied()
{
@@ -298,13 +317,19 @@ public class GrpcCentralTransportTests : IAsyncLifetime
{
private readonly BlockingCollection<object> _messages = new();
/// <summary>Initializes a new instance of the <see cref="Capture"/> class and starts its capture actor.</summary>
/// <param name="system">The actor system that hosts the capture actor.</param>
public Capture(ActorSystem system)
{
Ref = system.ActorOf(Props.Create(() => new CaptureActor(_messages)));
}
/// <summary>Gets the actor reference that tests pass as the reply target.</summary>
public IActorRef Ref { get; }
/// <summary>Waits for the next captured message.</summary>
/// <param name="timeout">The maximum time to wait for a message.</param>
/// <returns>The next captured message.</returns>
public object Receive(TimeSpan timeout)
=> _messages.TryTake(out var message, timeout)
? message
@@ -312,6 +337,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
private sealed class CaptureActor : ReceiveActor
{
/// <summary>Initializes a new instance of the <see cref="CaptureActor"/> class that forwards every message to the collection.</summary>
/// <param name="messages">The collection that receives every message.</param>
public CaptureActor(BlockingCollection<object> messages) => ReceiveAny(messages.Add);
}
}
@@ -329,12 +356,16 @@ public class GrpcCentralTransportTests : IAsyncLifetime
{
private readonly Func<Grpc.Core.StatusCode?> _forced;
/// <summary>Initializes a new instance of the <see cref="GrpcStatusHandler"/> class.</summary>
/// <param name="inner">The handler to delegate to when no status is forced.</param>
/// <param name="forced">Returns the gRPC status to force, or null to pass through.</param>
public GrpcStatusHandler(HttpMessageHandler inner, Func<Grpc.Core.StatusCode?> forced)
{
InnerHandler = inner;
_forced = forced;
}
/// <inheritdoc />
protected override async Task<HttpResponseMessage> SendAsync(
HttpRequestMessage request, CancellationToken cancellationToken)
{
@@ -362,6 +393,7 @@ public class GrpcCentralTransportTests : IAsyncLifetime
/// <summary>A gRPC channel handler that throws (a refused connection) while its node is "down".</summary>
private sealed class LostReconcileResponseHandler(HttpMessageHandler inner, Func<bool> lose) : DelegatingHandler(inner)
{
/// <inheritdoc />
protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct)
{
var response = await base.SendAsync(request, ct);
@@ -379,12 +411,16 @@ public class GrpcCentralTransportTests : IAsyncLifetime
{
private readonly Func<bool> _isUp;
/// <summary>Initializes a new instance of the <see cref="ToggleHandler"/> class.</summary>
/// <param name="inner">The handler to delegate to while the endpoint is up.</param>
/// <param name="isUp">Returns whether the endpoint should currently appear up.</param>
public ToggleHandler(HttpMessageHandler inner, Func<bool> isUp)
{
InnerHandler = inner;
_isUp = isUp;
}
/// <inheritdoc />
protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
{
if (!_isUp())
@@ -398,9 +434,11 @@ public class GrpcCentralTransportTests : IAsyncLifetime
private sealed class FixedPskProvider(string? key) : ISitePskProvider
{
/// <inheritdoc />
public ValueTask<string> GetAsync(string siteId, CancellationToken ct)
=> key is null ? throw new InvalidOperationException("no key") : new ValueTask<string>(key);
/// <inheritdoc />
public void Invalidate(string siteId) { }
}
@@ -411,11 +449,21 @@ public class GrpcCentralTransportTests : IAsyncLifetime
private IActorRef _stub = null!;
private readonly StubCounters _counters = new();
/// <summary>Gets the in-process test server hosting the central control service.</summary>
public TestServer Server { get; private set; } = null!;
public volatile bool IsUp = true;
/// <summary>Gets the number of notification submits the stub actor has received.</summary>
public int SubmitCount => _counters.Submits;
/// <summary>Gets the number of reconcile requests the stub actor has received.</summary>
public int ReconcileCount => Volatile.Read(ref _counters.Reconciles);
/// <summary>Starts an in-process central node with a stub actor behind the gRPC control service.</summary>
/// <param name="system">The actor system that hosts the stub actor.</param>
/// <param name="label">A label that makes the stub actor name unique.</param>
/// <param name="site">The site id the node accepts.</param>
/// <param name="key">The pre-shared key for that site.</param>
/// <param name="repliesToSubmit">Whether the stub acknowledges notification submits.</param>
/// <returns>The started central node.</returns>
public static async Task<CentralNode> StartAsync(
ActorSystem system, string label, string site, string key, bool repliesToSubmit)
{
@@ -453,6 +501,8 @@ public class GrpcCentralTransportTests : IAsyncLifetime
/// <summary>Switches the node's actor to a black hole that counts but never replies.</summary>
public void SetBlackHole() => _counters.BlackHole = true;
/// <summary>Releases the resources held by this test class asynchronously.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
public async ValueTask DisposeAsync()
{
await _host.StopAsync();
@@ -463,13 +513,18 @@ public class GrpcCentralTransportTests : IAsyncLifetime
{
private int _submits;
public int Reconciles;
/// <summary>Gets the number of notification submits received.</summary>
public int Submits => Volatile.Read(ref _submits);
/// <summary>Records one received notification submit.</summary>
public void IncrementSubmits() => Interlocked.Increment(ref _submits);
public volatile bool BlackHole;
}
private sealed class StubCentralActor : ReceiveActor
{
/// <summary>Initializes a new instance of the <see cref="StubCentralActor"/> class.</summary>
/// <param name="counters">The counters the actor increments as it receives messages.</param>
/// <param name="repliesToSubmit">Whether the actor replies to submit requests.</param>
public StubCentralActor(StubCounters counters, bool repliesToSubmit)
{
Receive<NotificationSubmit>(msg =>
@@ -494,11 +549,13 @@ public class GrpcCentralTransportTests : IAsyncLifetime
private sealed class MapPskProvider(IReadOnlyDictionary<string, string> keys) : ISitePskProvider
{
/// <inheritdoc />
public ValueTask<string> GetAsync(string siteId, CancellationToken ct)
=> keys.TryGetValue(siteId, out var key)
? new ValueTask<string>(key)
: throw new InvalidOperationException($"no key for '{siteId}'");
/// <inheritdoc />
public void Invalidate(string siteId) { }
}
}