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.HealthMonitoring.Tests/HealthReportSenderTests.cs
+41 -8
View File
@@ -12,7 +12,9 @@ public class HealthReportSenderTests
{
private class FakeTransport : IHealthReportTransport
{
/// <summary>Gets the reports captured by <c>SendAsync</c>, in send order.</summary>
public List<SiteHealthReport> SentReports { get; } = [];
/// <inheritdoc />
public Task SendAsync(SiteHealthReport report, CancellationToken cancellationToken)
{
SentReports.Add(report);
@@ -22,22 +24,38 @@ public class HealthReportSenderTests
private class FakeSiteIdentityProvider : ISiteIdentityProvider
{
/// <inheritdoc />
public string SiteId { get; set; } = "test-site";
}
/// <summary>
/// Captures emitted log entries so tests can assert that non-fatal failures
/// are surfaced (HealthMonitoring-010) rather than silently swallowed.
/// are surfaced rather than silently swallowed.
/// </summary>
private sealed class CapturingLogger<T> : ILogger<T>
{
public sealed record Entry(LogLevel Level, string Message, Exception? Exception);
/// <summary>Gets the log entries captured so far.</summary>
public List<Entry> Entries { get; } = [];
/// <summary>Returns no scope; the fake logger does not track scopes.</summary>
/// <typeparam name="TState">The type of the scope state.</typeparam>
/// <param name="state">The scope state, ignored.</param>
/// <returns>Always null or a no-op scope.</returns>
public IDisposable BeginScope<TState>(TState state) where TState : notnull => NullScope.Instance;
/// <summary>Reports every log level as enabled.</summary>
/// <param name="logLevel">The log level being queried.</param>
/// <returns>Always true.</returns>
public bool IsEnabled(LogLevel logLevel) => true;
/// <summary>Records the log entry for later assertions.</summary>
/// <typeparam name="TState">The type of the log state.</typeparam>
/// <param name="logLevel">The severity of the entry.</param>
/// <param name="eventId">The event identifier.</param>
/// <param name="state">The log state.</param>
/// <param name="exception">The associated exception, if any.</param>
/// <param name="formatter">Formats the state and exception into the message.</param>
public void Log<TState>(
LogLevel logLevel, EventId eventId, TState state, Exception? exception,
Func<TState, Exception?, string> formatter)
@@ -51,6 +69,7 @@ public class HealthReportSenderTests
private sealed class NullScope : IDisposable
{
public static readonly NullScope Instance = new();
/// <summary>Releases the resources held by this test class.</summary>
public void Dispose() { }
}
}
@@ -58,11 +77,15 @@ public class HealthReportSenderTests
/// <summary>An <see cref="IClusterNodeProvider"/> whose query always throws.</summary>
private sealed class ThrowingClusterNodeProvider : IClusterNodeProvider
{
/// <inheritdoc />
public bool SelfIsPrimary => true;
/// <inheritdoc />
public IReadOnlyList<NodeStatus> GetClusterNodes() =>
throw new InvalidOperationException("cluster query failed");
}
/// <summary>Verifies that successive reports are sent with monotonically increasing sequence numbers.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task SendsReportsWithMonotonicSequenceNumbers()
{
@@ -107,6 +130,8 @@ public class HealthReportSenderTests
}
}
/// <summary>Verifies that the first report sequence number exceeds the startup Unix time in milliseconds.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task FirstReportSequenceExceedsStartupUnixMs()
{
@@ -144,6 +169,8 @@ public class HealthReportSenderTests
$"First sequence {transport.SentReports[0].SequenceNumber} should be >= startup epoch {beforeCtor}");
}
/// <summary>Verifies that each report carries a UTC timestamp.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ReportsIncludeUtcTimestamp()
{
@@ -182,12 +209,13 @@ public class HealthReportSenderTests
}
/// <summary>
/// HealthMonitoring-001 regression: the documented "store-and-forward buffer
/// Regression: the documented "store-and-forward buffer
/// depth" metric (pending messages by category) must actually be populated in
/// the emitted report. Previously SetStoreAndForwardDepths had no callers, so
/// StoreAndForwardBufferDepths was always empty. The sender must query the S&amp;F
/// engine's per-category depth API and include it alongside the parked count.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ReportsIncludeStoreAndForwardBufferDepthsFromStorage()
{
@@ -256,6 +284,7 @@ public class HealthReportSenderTests
Status = StoreAndForwardMessageStatus.Pending
};
/// <summary>Verifies that the initial sequence number is seeded from the current Unix time in milliseconds.</summary>
[Fact]
public void InitialSequenceNumberSeededWithUnixMs()
{
@@ -276,11 +305,12 @@ public class HealthReportSenderTests
}
/// <summary>
/// HealthMonitoring-010 regression: a failure refreshing cluster nodes is
/// Regression: a failure refreshing cluster nodes is
/// non-fatal (the report still ships) but must no longer be swallowed by a
/// bare <c>catch {}</c> — it must be logged as a warning with the exception so
/// persistent degradation is diagnosable.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ClusterNodeRefreshFailure_IsLoggedNotSwallowed()
{
@@ -325,7 +355,7 @@ public class HealthReportSenderTests
}
/// <summary>
/// HealthMonitoring-017 regression: when the transport's <c>Send</c> throws,
/// Regression: when the transport's <c>Send</c> throws,
/// the per-interval counters that <see cref="SiteHealthCollector.CollectReport"/>
/// just drained via <c>Interlocked.Exchange</c> must be restored back into the
/// collector so they roll forward into the next interval rather than being
@@ -334,8 +364,8 @@ public class HealthReportSenderTests
/// counters at zero.
/// </summary>
/// <remarks>
/// Extended for arch-review 2026-08-19 P8-1: <c>ScriptRunShedCount</c> is drained
/// by <c>CollectReport</c> the exact same way as the five counters above, but
/// Also covers <c>ScriptRunShedCount</c>, which is drained
/// by <c>CollectReport</c> in the exact same way as the five counters above, but
/// <c>AddIntervalCounters</c> used to take only those five — a failed send
/// destructively lost the shed count forever. <c>DetachedScriptThreads</c> and
/// <c>SiteStreamAlarmDropCount</c> are deliberately NOT exercised here: they are
@@ -343,6 +373,7 @@ public class HealthReportSenderTests
/// never zeroed by <c>CollectReport</c>), so a failed send loses nothing for them
/// to restore.
/// </remarks>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task SendFailure_PreservesIntervalCountersForNextReport()
{
@@ -404,13 +435,15 @@ public class HealthReportSenderTests
/// <see cref="IHealthReportTransport"/> that throws on the first
/// <c>Send</c> call (and only the first), then succeeds. Used by
/// <see cref="SendFailure_PreservesIntervalCountersForNextReport"/> to
/// verify the HealthMonitoring-017 restore-on-failure path.
/// verify the restore-on-failure path.
/// </summary>
private sealed class FailingThenSucceedingTransport : IHealthReportTransport
{
private int _callCount;
/// <summary>Gets the reports captured by <c>SendAsync</c>, in send order.</summary>
public List<SiteHealthReport> SentReports { get; } = [];
/// <inheritdoc />
public Task SendAsync(SiteHealthReport report, CancellationToken cancellationToken)
{
var n = Interlocked.Increment(ref _callCount);
@@ -424,7 +457,7 @@ public class HealthReportSenderTests
}
/// <summary>
/// HealthMonitoring-006 regression: the sequence-number seed must be derived
/// Regression: the sequence-number seed must be derived
/// from the injected <see cref="TimeProvider"/> so the Unix-ms seeding strategy
/// is deterministically testable and the clock dependency is explicit, rather
/// than reading <c>DateTimeOffset.UtcNow</c> directly at field initialization.