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
+28
-4
@@ -11,8 +11,8 @@ using ZB.MOM.WW.ScadaBridge.SiteCallAudit.Kpi;
|
||||
namespace ZB.MOM.WW.ScadaBridge.SiteCallAudit.Tests.Kpi;
|
||||
|
||||
/// <summary>
|
||||
/// Unit tests for <see cref="SiteCallAuditKpiSampleSource"/> (M6 KPI History,
|
||||
/// #K7). A hand-rolled <see cref="ISiteCallAuditRepository"/> fake (matching the
|
||||
/// Unit tests for <see cref="SiteCallAuditKpiSampleSource"/> (KPI history).
|
||||
/// A hand-rolled <see cref="ISiteCallAuditRepository"/> fake (matching the
|
||||
/// project's existing test-double style — no mocking library) returns known
|
||||
/// global + per-site + per-node snapshots; the assertions pin the exact
|
||||
/// <c>(Metric, Scope, ScopeKey, Value)</c> tuples the recorder will persist, the
|
||||
@@ -54,6 +54,7 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
// 1. Source identifier is the canonical SiteCallAudit constant.
|
||||
// ---------------------------------------------------------------------
|
||||
|
||||
/// <summary>Verifies that the source identifier is the SiteCallAudit constant.</summary>
|
||||
[Fact]
|
||||
public void Source_IsSiteCallAuditConstant()
|
||||
{
|
||||
@@ -65,6 +66,8 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
// 2. Full snapshot: global + per-site + per-node, exact tuples.
|
||||
// ---------------------------------------------------------------------
|
||||
|
||||
/// <summary>Verifies that the expected tuples are emitted for the global, per-site and per-node KPIs.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CollectAsync_EmitsExpectedTuples_ForGlobalSiteAndNode()
|
||||
{
|
||||
@@ -142,6 +145,8 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
// 3. Null oldest-pending-age is omitted (not written as zero).
|
||||
// ---------------------------------------------------------------------
|
||||
|
||||
/// <summary>Verifies that the oldest pending age is omitted when it is null.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CollectAsync_OmitsOldestPendingAge_WhenNull()
|
||||
{
|
||||
@@ -173,6 +178,8 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
// 4. Empty per-site/per-node: only the global six metrics emitted.
|
||||
// ---------------------------------------------------------------------
|
||||
|
||||
/// <summary>Verifies that only global tuples are emitted when there are no per-site or per-node rows.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CollectAsync_GlobalOnly_WhenNoPerSiteOrPerNodeRows()
|
||||
{
|
||||
@@ -193,6 +200,8 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
// 5. Cutoffs are anchored on capturedAtUtc using the options windows.
|
||||
// ---------------------------------------------------------------------
|
||||
|
||||
/// <summary>Verifies that the cutoffs are derived from the options, anchored on the captured-at time.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CollectAsync_DerivesCutoffs_FromOptionsAnchoredOnCapturedAt()
|
||||
{
|
||||
@@ -219,17 +228,19 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------
|
||||
// P5-5 (arch-review Low): failedLastInterval/deliveredLastInterval are rescaled onto
|
||||
// Rescaling: failedLastInterval/deliveredLastInterval are rescaled onto
|
||||
// KpiHistoryOptions.SampleInterval before recording, so the central hourly rollup fold's
|
||||
// per-hour Sum stays correct regardless of how KpiInterval is tuned. Before the fix, this
|
||||
// class recorded the RAW KpiInterval-windowed counts verbatim; with a 20-minute
|
||||
// KpiInterval sampled every 1-minute SampleInterval, summing 60 overlapping 20-minute
|
||||
// counts across an hour would over-count ~20x. Proven against the unfixed computation:
|
||||
// temporarily short-circuiting IntervalScaleFactor to always return 1.0 (i.e. "record the
|
||||
// raw count verbatim", the pre-P5-5 behavior) makes this test fail (40/1 != 2/0.05);
|
||||
// raw count verbatim", the pre-fix behavior) makes this test fail (40/1 != 2/0.05);
|
||||
// restoring the real scale factor passes it.
|
||||
// ---------------------------------------------------------------------
|
||||
|
||||
/// <summary>Verifies that the failed and delivered last-interval counts are rescaled onto the KPI history sample interval.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CollectAsync_RescalesFailedAndDeliveredLastInterval_OntoKpiHistorySampleInterval()
|
||||
{
|
||||
@@ -264,6 +275,8 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
// 6. Multiple sites/nodes are all emitted with distinct ScopeKeys.
|
||||
// ---------------------------------------------------------------------
|
||||
|
||||
/// <summary>Verifies that tuples are emitted for all sites and nodes.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CollectAsync_EmitsAllSitesAndNodes()
|
||||
{
|
||||
@@ -316,15 +329,20 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
/// </summary>
|
||||
private sealed class StubRepo : ISiteCallAuditRepository
|
||||
{
|
||||
/// <summary>Gets or sets the global KPI snapshot returned by the stub.</summary>
|
||||
public SiteCallKpiSnapshot Global { get; set; } =
|
||||
new(0, 0, 0, 0, null, 0);
|
||||
/// <summary>Gets or sets the per-site KPI snapshots returned by the stub.</summary>
|
||||
public IReadOnlyList<SiteCallSiteKpiSnapshot> PerSite { get; set; } =
|
||||
Array.Empty<SiteCallSiteKpiSnapshot>();
|
||||
/// <summary>Gets or sets the per-node KPI snapshots returned by the stub.</summary>
|
||||
public IReadOnlyList<SiteCallNodeKpiSnapshot> PerNode { get; set; } =
|
||||
Array.Empty<SiteCallNodeKpiSnapshot>();
|
||||
|
||||
/// <summary>Gets the recorded KPI calls in the order they were made.</summary>
|
||||
public List<KpiCall> Calls { get; } = new();
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task<SiteCallKpiSnapshot> ComputeKpisAsync(
|
||||
DateTime stuckCutoff, DateTime intervalSince, CancellationToken ct = default)
|
||||
{
|
||||
@@ -332,6 +350,7 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
return Task.FromResult(Global);
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task<IReadOnlyList<SiteCallSiteKpiSnapshot>> ComputePerSiteKpisAsync(
|
||||
DateTime stuckCutoff, DateTime intervalSince, CancellationToken ct = default)
|
||||
{
|
||||
@@ -339,6 +358,7 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
return Task.FromResult(PerSite);
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task<IReadOnlyList<SiteCallNodeKpiSnapshot>> ComputePerNodeKpisAsync(
|
||||
DateTime stuckCutoff, DateTime intervalSince, CancellationToken ct = default)
|
||||
{
|
||||
@@ -347,16 +367,20 @@ public class SiteCallAuditKpiSampleSourceTests
|
||||
}
|
||||
|
||||
// ── Inert non-KPI members ──
|
||||
/// <inheritdoc />
|
||||
public Task UpsertAsync(SiteCall siteCall, CancellationToken ct = default) =>
|
||||
Task.CompletedTask;
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task<SiteCall?> GetAsync(TrackedOperationId id, CancellationToken ct = default) =>
|
||||
Task.FromResult<SiteCall?>(null);
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task<IReadOnlyList<SiteCall>> QueryAsync(
|
||||
SiteCallQueryFilter filter, SiteCallPaging paging, CancellationToken ct = default) =>
|
||||
Task.FromResult<IReadOnlyList<SiteCall>>(Array.Empty<SiteCall>());
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task<int> PurgeTerminalAsync(DateTime olderThanUtc, CancellationToken ct = default) =>
|
||||
Task.FromResult(0);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user