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.SiteCallAudit.Tests/SiteCallRelayTests.cs
+33 -2
View File
@@ -12,7 +12,7 @@ using ZB.MOM.WW.ScadaBridge.Communication;
namespace ZB.MOM.WW.ScadaBridge.SiteCallAudit.Tests;
/// <summary>
/// Task 5 (#22 Retry/Discard relay): tests for <see cref="SiteCallAuditActor"/>
/// Tests for <see cref="SiteCallAuditActor"/>
/// relaying operator Retry/Discard on a parked Site Call down to the owning
/// site. The relay routes a <see cref="RetryParkedOperation"/> /
/// <see cref="DiscardParkedOperation"/> command via a <see cref="SiteEnvelope"/>
@@ -30,27 +30,34 @@ public class SiteCallRelayTests : TestKit
/// </summary>
private sealed class ThrowingRepository : ISiteCallAuditRepository
{
/// <inheritdoc />
public Task UpsertAsync(SiteCall siteCall, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not write the SiteCalls row");
/// <inheritdoc />
public Task<SiteCall?> GetAsync(TrackedOperationId id, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not read the SiteCalls row");
/// <inheritdoc />
public Task<IReadOnlyList<SiteCall>> QueryAsync(
SiteCallQueryFilter filter, SiteCallPaging paging, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not query the SiteCalls table");
/// <inheritdoc />
public Task<int> PurgeTerminalAsync(DateTime olderThanUtc, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not purge");
/// <inheritdoc />
public Task<SiteCallKpiSnapshot> ComputeKpisAsync(
DateTime stuckCutoff, DateTime intervalSince, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not compute KPIs");
/// <inheritdoc />
public Task<IReadOnlyList<SiteCallSiteKpiSnapshot>> ComputePerSiteKpisAsync(
DateTime stuckCutoff, DateTime intervalSince, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not compute per-site KPIs");
/// <inheritdoc />
public Task<IReadOnlyList<SiteCallNodeKpiSnapshot>> ComputePerNodeKpisAsync(
DateTime stuckCutoff, DateTime intervalSince, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not compute per-node KPIs");
@@ -74,6 +81,7 @@ public class SiteCallRelayTests : TestKit
return actor;
}
/// <summary>Verifies that retrying a site call routes a RetryParkedOperation command to the owning site.</summary>
[Fact]
public void RetrySiteCall_RoutesRetryParkedOperation_ToOwningSite()
{
@@ -101,6 +109,7 @@ public class SiteCallRelayTests : TestKit
Assert.Null(response.ErrorMessage);
}
/// <summary>Verifies that discarding a site call routes a DiscardParkedOperation command to the owning site.</summary>
[Fact]
public void DiscardSiteCall_RoutesDiscardParkedOperation_ToOwningSite()
{
@@ -122,6 +131,7 @@ public class SiteCallRelayTests : TestKit
Assert.True(response.Success);
}
/// <summary>Verifies that a site reply of not applied is reported as the call not being parked.</summary>
[Fact]
public void RetrySiteCall_SiteRepliesNotApplied_ReportsNotParked()
{
@@ -141,6 +151,7 @@ public class SiteCallRelayTests : TestKit
Assert.True(response.SiteReachable);
}
/// <summary>Verifies that a site error reply is reported as a failed operation.</summary>
[Fact]
public void RetrySiteCall_SiteRepliesError_ReportsOperationFailed()
{
@@ -162,6 +173,7 @@ public class SiteCallRelayTests : TestKit
Assert.NotNull(response.ErrorMessage);
}
/// <summary>Verifies that a retry to a site that never replies is reported as site unreachable.</summary>
[Fact]
public void RetrySiteCall_SiteNeverReplies_ReportsSiteUnreachable()
{
@@ -183,6 +195,7 @@ public class SiteCallRelayTests : TestKit
Assert.NotNull(response.ErrorMessage);
}
/// <summary>Verifies that a discard to a site that never replies is reported as site unreachable.</summary>
[Fact]
public void DiscardSiteCall_SiteNeverReplies_ReportsSiteUnreachable()
{
@@ -198,6 +211,7 @@ public class SiteCallRelayTests : TestKit
Assert.False(response.SiteReachable);
}
/// <summary>Verifies that a retry issued before central communication is registered is reported as site unreachable.</summary>
[Fact]
public void RetrySiteCall_BeforeCentralCommunicationRegistered_ReportsSiteUnreachable()
{
@@ -217,13 +231,18 @@ public class SiteCallRelayTests : TestKit
Assert.False(response.SiteReachable);
}
// ── Task 14: operator-identity audit on a successful relay ──
// ── Operator-identity audit on a successful relay ──
/// <summary>Captures the central direct-write audit events emitted by the relay.</summary>
private sealed class RecordingCentralAuditWriter : ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services.ICentralAuditWriter
{
/// <summary>The central direct-write audit rows captured so far.</summary>
public List<AuditRowProjection.AuditRowValues> Events { get; } = new();
/// <summary>Records the audit event for later assertions.</summary>
/// <param name="evt">The audit event to record.</param>
/// <param name="ct">A token to cancel the operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public Task WriteAsync(ZB.MOM.WW.Audit.AuditEvent evt, CancellationToken ct = default)
{
lock (Events)
@@ -243,29 +262,38 @@ public class SiteCallRelayTests : TestKit
private sealed class RowReturningRepository : ISiteCallAuditRepository
{
private readonly SiteCall _row;
/// <summary>Creates the repository around the fixed row it returns from <c>GetAsync</c>.</summary>
/// <param name="row">The site call row returned for its own tracked operation ID.</param>
public RowReturningRepository(SiteCall row) { _row = row; }
/// <inheritdoc />
public Task<SiteCall?> GetAsync(TrackedOperationId id, CancellationToken ct = default) =>
Task.FromResult<SiteCall?>(_row.TrackedOperationId == id ? _row : null);
/// <inheritdoc />
public Task UpsertAsync(SiteCall siteCall, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not write the SiteCalls row");
/// <inheritdoc />
public Task<IReadOnlyList<SiteCall>> QueryAsync(
SiteCallQueryFilter filter, SiteCallPaging paging, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not query the SiteCalls table");
/// <inheritdoc />
public Task<int> PurgeTerminalAsync(DateTime olderThanUtc, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not purge");
/// <inheritdoc />
public Task<SiteCallKpiSnapshot> ComputeKpisAsync(
DateTime stuckCutoff, DateTime intervalSince, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not compute KPIs");
/// <inheritdoc />
public Task<IReadOnlyList<SiteCallSiteKpiSnapshot>> ComputePerSiteKpisAsync(
DateTime stuckCutoff, DateTime intervalSince, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not compute per-site KPIs");
/// <inheritdoc />
public Task<IReadOnlyList<SiteCallNodeKpiSnapshot>> ComputePerNodeKpisAsync(
DateTime stuckCutoff, DateTime intervalSince, CancellationToken ct = default) =>
throw new InvalidOperationException("relay must not compute per-node KPIs");
@@ -302,6 +330,7 @@ public class SiteCallRelayTests : TestKit
return (actor, writer);
}
/// <summary>Verifies that a retry that the site applied emits a cached-resolve submitted audit row that records the operator.</summary>
[Fact]
public void RetrySiteCall_WhenApplied_EmitsCachedResolveSubmitted_WithOperator()
{
@@ -330,6 +359,7 @@ public class SiteCallRelayTests : TestKit
});
}
/// <summary>Verifies that a retry that the site did not apply emits no audit row.</summary>
[Fact]
public void RetrySiteCall_WhenNotApplied_EmitsNoAuditRow()
{
@@ -350,6 +380,7 @@ public class SiteCallRelayTests : TestKit
lock (writer.Events) { Assert.Empty(writer.Events); }
}
/// <summary>Verifies that a discard that the site applied emits a cached-resolve discarded audit row that records the operator.</summary>
[Fact]
public void DiscardSiteCall_WhenApplied_EmitsCachedResolveDiscarded_WithOperator()
{