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.SiteRuntime.Tests/Scripts/DatabaseCachedWriteEmissionTests.cs
+46 -20
View File
@@ -11,7 +11,7 @@ using ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts;
namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests.Scripts;
/// <summary>
/// Audit Log #23 — M3 Bundle E (Task E6): every script-initiated
/// Every script-initiated
/// <c>Database.CachedWrite</c> emits exactly one <c>CachedSubmit</c>
/// combined-telemetry packet at enqueue time on the <c>DbOutbound</c>
/// channel, returns a fresh <see cref="TrackedOperationId"/>, and threads
@@ -22,9 +22,12 @@ public class DatabaseCachedWriteEmissionTests
{
private sealed class CapturingForwarder : ICachedCallTelemetryForwarder
{
/// <summary>Gets the telemetry packets captured so far.</summary>
public List<CachedCallTelemetry> Telemetry { get; } = new();
/// <summary>Gets or sets an exception to throw from <see cref="ForwardAsync"/> instead of capturing the packet.</summary>
public Exception? ThrowOnForward { get; set; }
/// <inheritdoc />
public Task ForwardAsync(CachedCallTelemetry telemetry, CancellationToken ct = default)
{
if (ThrowOnForward != null)
@@ -41,7 +44,7 @@ public class DatabaseCachedWriteEmissionTests
private const string SourceScript = "ScriptActor:WriteAudit";
/// <summary>
/// Audit Log #23: a fixed per-execution id so the cached-row tests can
/// A fixed per-execution id so the cached-row tests can
/// assert <see cref="AuditEvent.ExecutionId"/> against a known value.
/// </summary>
private static readonly Guid TestExecutionId = Guid.NewGuid();
@@ -55,7 +58,7 @@ public class DatabaseCachedWriteEmissionTests
gateway,
InstanceName,
NullLogger.Instance,
// Audit Log #23: the per-execution id stamped into ExecutionId on
// The per-execution id stamped into ExecutionId on
// every script-side row. Cached rows keep CorrelationId =
// TrackedOperationId (the per-operation lifecycle id).
TestExecutionId,
@@ -65,6 +68,8 @@ public class DatabaseCachedWriteEmissionTests
parentExecutionId: parentExecutionId);
}
/// <summary>Verifies that enqueueing a cached write emits a CachedSubmit telemetry packet on the DbOutbound channel.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_EmitsSubmitTelemetry_OnEnqueue_KindCachedSubmit_ChannelDbOutbound()
{
@@ -77,7 +82,7 @@ public class DatabaseCachedWriteEmissionTests
It.IsAny<CancellationToken>(),
It.IsAny<TrackedOperationId?>(),
It.IsAny<Guid?>(), It.IsAny<string?>(), It.IsAny<Guid?>()))
// M2.3 (#7): CachedWriteAsync now returns an ExternalCallResult. The
// CachedWriteAsync returns an ExternalCallResult. The
// buffered result (WasBuffered=true) models the transient-failure
// path these enqueue-telemetry tests exercise — only the CachedSubmit
// packet is emitted; the S&F retry loop (not the helper) owns the
@@ -99,7 +104,7 @@ public class DatabaseCachedWriteEmissionTests
// ExecutionId is the per-execution id from the runtime context.
Assert.Equal(trackedId.Value, packet.Audit.AsRow().CorrelationId);
Assert.Equal(TestExecutionId, packet.Audit.AsRow().ExecutionId);
// Audit Log #23 (ParentExecutionId): null for a non-routed run.
// ParentExecutionId is null for a non-routed run.
Assert.Null(packet.Audit.AsRow().ParentExecutionId);
Assert.Equal(trackedId, packet.Operational.TrackedOperationId);
@@ -111,6 +116,8 @@ public class DatabaseCachedWriteEmissionTests
Assert.Null(packet.Operational.TerminalAtUtc);
}
/// <summary>Verifies that the emitted telemetry carries populated provenance fields.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_ProvenancePopulated()
{
@@ -123,7 +130,7 @@ public class DatabaseCachedWriteEmissionTests
It.IsAny<CancellationToken>(),
It.IsAny<TrackedOperationId?>(),
It.IsAny<Guid?>(), It.IsAny<string?>(), It.IsAny<Guid?>()))
// M2.3 (#7): CachedWriteAsync now returns an ExternalCallResult. The
// CachedWriteAsync returns an ExternalCallResult. The
// buffered result (WasBuffered=true) models the transient-failure
// path these enqueue-telemetry tests exercise — only the CachedSubmit
// packet is emitted; the S&F retry loop (not the helper) owns the
@@ -141,10 +148,12 @@ public class DatabaseCachedWriteEmissionTests
Assert.Equal(SiteId, packet.Operational.SourceSite);
}
/// <summary>Verifies that a routed run stamps its parent execution id on the submit telemetry.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_RoutedRun_StampsParentExecutionId_OnSubmitTelemetry()
{
// Audit Log #23 (ParentExecutionId, Task 5): an inbound-API-routed run
// An inbound-API-routed run
// carries the spawning execution's id; the CachedSubmit telemetry row
// must stamp it in ParentExecutionId.
var parentExecutionId = Guid.NewGuid();
@@ -157,7 +166,7 @@ public class DatabaseCachedWriteEmissionTests
It.IsAny<CancellationToken>(),
It.IsAny<TrackedOperationId?>(),
It.IsAny<Guid?>(), It.IsAny<string?>(), It.IsAny<Guid?>()))
// M2.3 (#7): CachedWriteAsync now returns an ExternalCallResult. The
// CachedWriteAsync returns an ExternalCallResult. The
// buffered result (WasBuffered=true) models the transient-failure
// path these enqueue-telemetry tests exercise — only the CachedSubmit
// packet is emitted; the S&F retry loop (not the helper) owns the
@@ -172,6 +181,8 @@ public class DatabaseCachedWriteEmissionTests
Assert.Equal(parentExecutionId, packet.Audit.AsRow().ParentExecutionId);
}
/// <summary>Verifies that a cached write returns a tracked operation id and passes the same id to the gateway.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_ReturnsTrackedOperationId_ThreadsIdToGateway()
{
@@ -184,7 +195,7 @@ public class DatabaseCachedWriteEmissionTests
It.IsAny<CancellationToken>(),
It.IsAny<TrackedOperationId?>(),
It.IsAny<Guid?>(), It.IsAny<string?>(), It.IsAny<Guid?>()))
// M2.3 (#7): CachedWriteAsync now returns an ExternalCallResult. The
// CachedWriteAsync returns an ExternalCallResult. The
// buffered result (WasBuffered=true) models the transient-failure
// path these enqueue-telemetry tests exercise — only the CachedSubmit
// packet is emitted; the S&F retry loop (not the helper) owns the
@@ -207,7 +218,7 @@ public class DatabaseCachedWriteEmissionTests
}
/// <summary>
/// Audit Log #23 (ExecutionId Task 4): the helper → gateway hop of the
/// The helper → gateway hop of the
/// threading chain. The cached-write helper must forward the runtime
/// context's <c>ExecutionId</c> and <c>SourceScript</c> verbatim into
/// <see cref="IDatabaseGateway.CachedWriteAsync"/> — so the buffered retry
@@ -215,6 +226,7 @@ public class DatabaseCachedWriteEmissionTests
/// asserts the exact id/script (not <c>It.IsAny</c>), so a regression that
/// dropped the threading would fail here.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_ThreadsExecutionIdAndSourceScript_IntoGateway()
{
@@ -227,7 +239,7 @@ public class DatabaseCachedWriteEmissionTests
It.IsAny<CancellationToken>(),
It.IsAny<TrackedOperationId?>(),
It.IsAny<Guid?>(), It.IsAny<string?>(), It.IsAny<Guid?>()))
// M2.3 (#7): CachedWriteAsync now returns an ExternalCallResult. The
// CachedWriteAsync returns an ExternalCallResult. The
// buffered result (WasBuffered=true) models the transient-failure
// path these enqueue-telemetry tests exercise — only the CachedSubmit
// packet is emitted; the S&F retry loop (not the helper) owns the
@@ -253,13 +265,14 @@ public class DatabaseCachedWriteEmissionTests
}
/// <summary>
/// Audit Log #23 (ParentExecutionId Task 6): the helper → gateway hop for
/// The helper → gateway hop for
/// <c>ParentExecutionId</c>. A cached write enqueued from an inbound-API-
/// routed script run must forward the runtime context's
/// <c>ParentExecutionId</c> verbatim into
/// <see cref="IDatabaseGateway.CachedWriteAsync"/> so the buffered retry
/// loop later stamps it onto its audit rows.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_ThreadsParentExecutionId_IntoGateway()
{
@@ -273,7 +286,7 @@ public class DatabaseCachedWriteEmissionTests
It.IsAny<CancellationToken>(),
It.IsAny<TrackedOperationId?>(),
It.IsAny<Guid?>(), It.IsAny<string?>(), It.IsAny<Guid?>()))
// M2.3 (#7): CachedWriteAsync now returns an ExternalCallResult. The
// CachedWriteAsync returns an ExternalCallResult. The
// buffered result (WasBuffered=true) models the transient-failure
// path these enqueue-telemetry tests exercise — only the CachedSubmit
// packet is emitted; the S&F retry loop (not the helper) owns the
@@ -296,9 +309,10 @@ public class DatabaseCachedWriteEmissionTests
}
/// <summary>
/// Audit Log #23 (ParentExecutionId Task 6): a non-routed run threads a
/// A non-routed run threads a
/// <c>null</c> ParentExecutionId into the gateway — the additive default.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_NonRoutedRun_ThreadsNullParentExecutionId_IntoGateway()
{
@@ -311,7 +325,7 @@ public class DatabaseCachedWriteEmissionTests
It.IsAny<CancellationToken>(),
It.IsAny<TrackedOperationId?>(),
It.IsAny<Guid?>(), It.IsAny<string?>(), It.IsAny<Guid?>()))
// M2.3 (#7): CachedWriteAsync now returns an ExternalCallResult. The
// CachedWriteAsync returns an ExternalCallResult. The
// buffered result (WasBuffered=true) models the transient-failure
// path these enqueue-telemetry tests exercise — only the CachedSubmit
// packet is emitted; the S&F retry loop (not the helper) owns the
@@ -333,6 +347,8 @@ public class DatabaseCachedWriteEmissionTests
Times.Once);
}
/// <summary>Verifies that a cached write still returns a tracked operation id when the telemetry forwarder throws.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_ForwarderThrows_StillReturnsTrackedOperationId()
{
@@ -345,7 +361,7 @@ public class DatabaseCachedWriteEmissionTests
It.IsAny<CancellationToken>(),
It.IsAny<TrackedOperationId?>(),
It.IsAny<Guid?>(), It.IsAny<string?>(), It.IsAny<Guid?>()))
// M2.3 (#7): CachedWriteAsync now returns an ExternalCallResult. The
// CachedWriteAsync returns an ExternalCallResult. The
// buffered result (WasBuffered=true) models the transient-failure
// path these enqueue-telemetry tests exercise — only the CachedSubmit
// packet is emitted; the S&F retry loop (not the helper) owns the
@@ -370,8 +386,10 @@ public class DatabaseCachedWriteEmissionTests
Times.Once);
}
// ── SourceNode-stamping (Task 14) ──
// ── SourceNode-stamping ──
/// <summary>Verifies that the submit telemetry row is stamped with the source node.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_StampsSourceNode_OnSubmitTelemetryRow()
{
@@ -388,7 +406,7 @@ public class DatabaseCachedWriteEmissionTests
It.IsAny<CancellationToken>(),
It.IsAny<TrackedOperationId?>(),
It.IsAny<Guid?>(), It.IsAny<string?>(), It.IsAny<Guid?>()))
// M2.3 (#7): CachedWriteAsync now returns an ExternalCallResult. The
// CachedWriteAsync returns an ExternalCallResult. The
// buffered result (WasBuffered=true) models the transient-failure
// path these enqueue-telemetry tests exercise — only the CachedSubmit
// packet is emitted; the S&F retry loop (not the helper) owns the
@@ -414,6 +432,8 @@ public class DatabaseCachedWriteEmissionTests
Assert.Equal("node-a", packet.Operational.SourceNode);
}
/// <summary>Verifies that the source node stays null when no source node is wired.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_NoSourceNodeWired_LeavesSourceNodeNull()
{
@@ -429,7 +449,7 @@ public class DatabaseCachedWriteEmissionTests
It.IsAny<CancellationToken>(),
It.IsAny<TrackedOperationId?>(),
It.IsAny<Guid?>(), It.IsAny<string?>(), It.IsAny<Guid?>()))
// M2.3 (#7): CachedWriteAsync now returns an ExternalCallResult. The
// CachedWriteAsync returns an ExternalCallResult. The
// buffered result (WasBuffered=true) models the transient-failure
// path these enqueue-telemetry tests exercise — only the CachedSubmit
// packet is emitted; the S&F retry loop (not the helper) owns the
@@ -444,7 +464,7 @@ public class DatabaseCachedWriteEmissionTests
Assert.Null(packet.Operational.SourceNode);
}
// ── M2.3 (#7): immediate-completion lifecycle (WasBuffered=false) ──
// ── Immediate-completion lifecycle (WasBuffered=false) ──
private static Mock<IDatabaseGateway> GatewayReturning(ExternalCallResult result)
{
@@ -461,6 +481,8 @@ public class DatabaseCachedWriteEmissionTests
return gateway;
}
/// <summary>Verifies that an immediate success emits submit and attempted telemetry followed by a delivered resolve.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_ImmediateSuccess_EmitsSubmitAttemptedThenDeliveredResolve()
{
@@ -494,6 +516,8 @@ public class DatabaseCachedWriteEmissionTests
Assert.NotNull(resolve.Operational.TerminalAtUtc);
}
/// <summary>Verifies that an immediate permanent failure emits submit and attempted telemetry followed by a failed resolve.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_ImmediatePermanentFailure_EmitsSubmitAttemptedThenFailedResolve()
{
@@ -520,6 +544,8 @@ public class DatabaseCachedWriteEmissionTests
Assert.NotEqual(default, trackedId);
}
/// <summary>Verifies that a buffered transient failure emits only the submit telemetry and no terminal rows.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CachedWrite_BufferedTransient_EmitsOnlySubmit_NoTerminalRows()
{