docs(tests): fix CommentChecker findings across tests/ — 13,392 → 0 (repo-wide scan clean)
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
@@ -13,7 +13,7 @@ using ZB.MOM.WW.ScadaBridge.Communication.Grpc;
|
||||
namespace ZB.MOM.WW.ScadaBridge.Communication.Tests;
|
||||
|
||||
/// <summary>
|
||||
/// Tests for <see cref="SiteAlarmLiveCacheService"/> (plan #10, Task 4) — the DI singleton
|
||||
/// Tests for <see cref="SiteAlarmLiveCacheService"/> — the DI singleton
|
||||
/// that reference-counts Alarm Summary viewers over one shared per-site aggregator. Covers
|
||||
/// shared start (one aggregator for many viewers), last-out linger stop, and re-subscribe
|
||||
/// cancelling a pending stop. Uses a real (in-memory) ActorSystem and a mock gRPC factory
|
||||
@@ -30,6 +30,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
private readonly List<Action> _connects = new();
|
||||
private readonly List<Action> _completions = new();
|
||||
|
||||
/// <summary>Initializes a hanging client with no pending subscriptions.</summary>
|
||||
public HangingClient() : base() { }
|
||||
|
||||
/// <summary>When false the site never accepts the subscription (no connect signal).</summary>
|
||||
@@ -44,7 +45,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
private int _streamEnds;
|
||||
|
||||
/// <summary>
|
||||
/// Register row 40: how many site-wide subscriptions have been torn down (their
|
||||
/// How many site-wide subscriptions have been torn down (their
|
||||
/// cancellation token fired). This is the aggregator-stop observable — the linger
|
||||
/// stop cancels the aggregator's token, which ends the hanging subscribe below.
|
||||
/// Tests that must show an aggregator was NOT stopped assert on this rather than
|
||||
@@ -52,6 +53,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
/// </summary>
|
||||
public int StreamEndCount => Volatile.Read(ref _streamEnds);
|
||||
|
||||
/// <inheritdoc />
|
||||
public override Task SubscribeSiteAsync(
|
||||
string correlationId, Action<Commons.Messages.Streaming.AlarmStateChanged> onAlarmEvent,
|
||||
Action<Exception> onError, Action onCompleted, CancellationToken ct,
|
||||
@@ -73,6 +75,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
});
|
||||
return tcs.Task;
|
||||
}
|
||||
/// <inheritdoc />
|
||||
public override void Unsubscribe(string correlationId) { }
|
||||
}
|
||||
|
||||
@@ -84,14 +87,17 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
/// <summary>The single client this factory hands out, for connect/complete control.</summary>
|
||||
public HangingClient Client => _client;
|
||||
|
||||
/// <summary>Initializes a counting factory backed by a single hanging client.</summary>
|
||||
public CountingFactory() : base(NullLoggerFactory.Instance) { }
|
||||
|
||||
/// <inheritdoc />
|
||||
public override SiteStreamGrpcClient GetOrCreate(string siteIdentifier, string grpcEndpoint)
|
||||
{
|
||||
Interlocked.Increment(ref GetOrCreateCount);
|
||||
return _client;
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
public override SiteStreamGrpcClient? TryGet(string siteIdentifier, string grpcEndpoint) => _client;
|
||||
}
|
||||
|
||||
@@ -137,7 +143,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Row-40 house pattern for an ABSENCE assertion (mirrors the Medium-wave
|
||||
/// House pattern for an ABSENCE assertion (mirrors the
|
||||
/// <c>SiteAlarmAggregatorActorTests.AssertHoldsFor</c> treatment in this same test
|
||||
/// project): proves every check in <paramref name="checks"/> keeps holding throughout
|
||||
/// <paramref name="window"/> by polling, rather than a single blind
|
||||
@@ -160,10 +166,11 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the seed fan-out publishes the instances that failed to answer.</summary>
|
||||
[Fact]
|
||||
public void Seed_FanOut_Publishes_The_Instances_That_Failed_To_Answer()
|
||||
{
|
||||
// Arch-review phase-2 residual #4: the seed/reconcile fan-out already knows which
|
||||
// The seed/reconcile fan-out already knows which
|
||||
// Enabled instances failed to answer and used to discard it, forcing the Alarm Summary
|
||||
// page to run a SECOND identical fan-out purely to rebuild that list. It is now
|
||||
// published alongside the snapshot.
|
||||
@@ -191,6 +198,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
Assert.Equal(new[] { "inst-a", "inst-b" }, service.GetNotReportingInstances(SiteId));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the not-reporting set is empty for an unknown site.</summary>
|
||||
[Fact]
|
||||
public void NotReporting_Is_Empty_For_An_Unknown_Site()
|
||||
{
|
||||
@@ -199,6 +207,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
Assert.Empty(service.GetNotReportingInstances(SiteId));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the first subscriber starts one aggregator that is shared by multiple viewers.</summary>
|
||||
[Fact]
|
||||
public void First_Subscriber_Starts_One_Aggregator_Shared_By_Multiple_Viewers()
|
||||
{
|
||||
@@ -220,6 +229,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
AwaitCondition(() => changes1 >= 1 && changes2 >= 1, TimeSpan.FromSeconds(3));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the aggregator stops after the linger period once the last viewer leaves.</summary>
|
||||
[Fact]
|
||||
public void Last_Viewer_Leaving_Stops_Aggregator_After_Linger()
|
||||
{
|
||||
@@ -232,7 +242,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
|
||||
sub1.Dispose();
|
||||
|
||||
// Register row 40: one viewer remains, so the aggregator must NOT be stopped. The old
|
||||
// One viewer remains, so the aggregator must NOT be stopped. The old
|
||||
// test slept 300 ms and sampled IsLive once — a teardown that happened at any other
|
||||
// instant (or one that stopped and restarted the stream) was invisible to it. Poll
|
||||
// CONTINUOUSLY across three linger windows instead, bailing out the moment either
|
||||
@@ -259,6 +269,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
Assert.Empty(service.GetCurrentAlarms(SiteId));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that resubscribing within the linger period cancels the pending stop.</summary>
|
||||
[Fact]
|
||||
public void Resubscribe_Within_Linger_Cancels_The_Pending_Stop()
|
||||
{
|
||||
@@ -271,7 +282,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
sub1.Dispose(); // schedules linger stop
|
||||
var sub2 = service.Subscribe(SiteId, () => { }); // returns within the linger window → cancels it
|
||||
|
||||
// Register row 40: the pending stop must be CANCELLED, not merely outrun. The old test
|
||||
// The pending stop must be CANCELLED, not merely outrun. The old test
|
||||
// slept 700 ms and sampled once — it could not see a stream that was torn down and
|
||||
// silently replaced inside that window, because GetOrCreateCount is checked only at the
|
||||
// end and the mock hands back the same client object either way. Poll continuously past
|
||||
@@ -295,6 +306,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
AwaitCondition(() => factory.Client.StreamEndCount > 0, TimeSpan.FromSeconds(5));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that disposing the service more than once is safe.</summary>
|
||||
[Fact]
|
||||
public void Dispose_Is_Idempotent()
|
||||
{
|
||||
@@ -308,6 +320,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
AwaitCondition(() => !service.IsLive(SiteId), TimeSpan.FromSeconds(3));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a transient aggregator start failure self-heals on retry while the viewer cohort is stable.</summary>
|
||||
[Fact]
|
||||
public void Transient_Start_Failure_Self_Heals_On_Retry_For_A_Stable_Viewer_Cohort()
|
||||
{
|
||||
@@ -355,6 +368,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
AwaitCondition(() => service.IsLive(SiteId), TimeSpan.FromSeconds(5));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a viewer over the per-site cap is rejected safely and not counted.</summary>
|
||||
[Fact]
|
||||
public void Viewer_Over_The_Per_Site_Cap_Is_Rejected_Safely_And_Not_Counted()
|
||||
{
|
||||
@@ -387,6 +401,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
AwaitCondition(() => !service.IsLive(SiteId), TimeSpan.FromSeconds(3));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an unknown site registers the viewer but never goes live.</summary>
|
||||
[Fact]
|
||||
public void Unknown_Site_Registers_Viewer_But_Never_Goes_Live()
|
||||
{
|
||||
@@ -400,6 +415,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
|
||||
// ── R2 T15: single-endpoint sites can go live (N9) ──
|
||||
|
||||
/// <summary>Verifies that a site with only a node A endpoint starts an aggregator against that endpoint.</summary>
|
||||
[Fact]
|
||||
public void SiteWithOnlyNodeAEndpoint_StartsAnAggregator_AgainstThatEndpoint()
|
||||
{
|
||||
@@ -444,6 +460,8 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
|
||||
// ── R2 T10: deathwatch un-sticks IsLive on aggregator death (N6) ──
|
||||
|
||||
/// <summary>Verifies that the death of the aggregator resets the live flag and clears the snapshot.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task Aggregator_Death_Resets_IsLive_And_Clears_The_Snapshot()
|
||||
{
|
||||
@@ -463,6 +481,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
}, TimeSpan.FromSeconds(10));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a linger stop does not resurrect the aggregator.</summary>
|
||||
[Fact]
|
||||
public void Linger_Stop_Does_Not_Resurrect_The_Aggregator()
|
||||
{
|
||||
@@ -478,8 +497,9 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
(() => factory.GetOrCreateCount == startsAfterStop, "no self-heal restart fired"));
|
||||
}
|
||||
|
||||
// ── WP2.3: IsLive tracks the STREAM, not merely "a snapshot was published once" ──
|
||||
// ── IsLive tracks the STREAM, not merely "a snapshot was published once" ──
|
||||
|
||||
/// <summary>Verifies that the live flag stays false until the site accepts the stream.</summary>
|
||||
[Fact]
|
||||
public void IsLive_StaysFalse_UntilTheSiteAcceptsTheStream()
|
||||
{
|
||||
@@ -501,6 +521,7 @@ public class SiteAlarmLiveCacheServiceTests : TestKit
|
||||
AwaitCondition(() => service.IsLive(SiteId), TimeSpan.FromSeconds(5));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the live flag drops when the stream completes.</summary>
|
||||
[Fact]
|
||||
public void IsLive_DropsWhenTheStreamCompletes()
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user