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
+42
-15
@@ -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 E3): every script-initiated
|
||||
/// Every script-initiated
|
||||
/// <c>ExternalSystem.CachedCall</c> emits exactly one <c>CachedSubmit</c>
|
||||
/// combined-telemetry packet at enqueue time, returns a fresh
|
||||
/// <see cref="TrackedOperationId"/>, and threads that id down to the
|
||||
@@ -24,9 +24,12 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
{
|
||||
private sealed class CapturingForwarder : ICachedCallTelemetryForwarder
|
||||
{
|
||||
/// <summary>Gets the telemetry packets the forwarder has received.</summary>
|
||||
public List<CachedCallTelemetry> Telemetry { get; } = new();
|
||||
/// <summary>Gets or sets a value indicating whether the forwarder should throw when forwarding.</summary>
|
||||
public Exception? ThrowOnForward { get; set; }
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task ForwardAsync(CachedCallTelemetry telemetry, CancellationToken ct = default)
|
||||
{
|
||||
if (ThrowOnForward != null)
|
||||
@@ -43,7 +46,7 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
private const string SourceScript = "ScriptActor:CheckPressure";
|
||||
|
||||
/// <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();
|
||||
@@ -57,7 +60,7 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
client,
|
||||
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,
|
||||
@@ -68,6 +71,8 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
parentExecutionId: parentExecutionId);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a cached call emits submit telemetry on enqueue.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_EmitsSubmitTelemetry_OnEnqueue()
|
||||
{
|
||||
@@ -98,7 +103,7 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
// 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);
|
||||
// C3 (Task 2.5): ForwardState is no longer a field on the canonical
|
||||
// ForwardState is no longer a field on the canonical
|
||||
// record — it is a site-storage-only concern (the SQLite writer defaults
|
||||
// it to Pending on insert), so the telemetry packet no longer carries it.
|
||||
|
||||
@@ -113,6 +118,8 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
Assert.Null(packet.Operational.TerminalAtUtc);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an immediately completed cached call captures the request arguments and the response body.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_ImmediateCompletion_CapturesRequestArgs_AndResponseBody()
|
||||
{
|
||||
@@ -150,6 +157,8 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
Assert.Equal("{\"ok\":true}", resolve.Audit.AsRow().ResponseSummary);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a cached call returns a tracked operation id.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_ReturnsTrackedOperationId()
|
||||
{
|
||||
@@ -194,7 +203,7 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Audit Log #23 (ExecutionId Task 4): the helper → gateway hop of the
|
||||
/// The helper → gateway hop of the
|
||||
/// threading chain. The cached-call helper must forward the runtime
|
||||
/// context's <c>ExecutionId</c> and <c>SourceScript</c> verbatim into
|
||||
/// <see cref="IExternalSystemClient.CachedCallAsync"/> — so the buffered
|
||||
@@ -202,6 +211,7 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
/// This 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 CachedCall_ThreadsExecutionIdAndSourceScript_IntoClient()
|
||||
{
|
||||
@@ -235,13 +245,14 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Audit Log #23 (ParentExecutionId Task 6): the helper → gateway hop for
|
||||
/// The helper → gateway hop for
|
||||
/// <c>ParentExecutionId</c>. A cached call enqueued from an inbound-API-
|
||||
/// routed script run must forward the runtime context's
|
||||
/// <c>ParentExecutionId</c> verbatim into
|
||||
/// <see cref="IExternalSystemClient.CachedCallAsync"/> 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 CachedCall_ThreadsParentExecutionId_IntoClient()
|
||||
{
|
||||
@@ -273,9 +284,10 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
}
|
||||
|
||||
/// <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 client — the additive default.
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_NonRoutedRun_ThreadsNullParentExecutionId_IntoClient()
|
||||
{
|
||||
@@ -305,6 +317,8 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
Times.Once);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a cached call still returns the tracked operation id and proceeds when the forwarder throws.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_ForwarderThrows_StillReturnsTrackedOperationId_OriginalCallProceeds()
|
||||
{
|
||||
@@ -340,6 +354,8 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
Times.Once);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that cached call provenance is populated from the context.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_Provenance_Populated_FromContext()
|
||||
{
|
||||
@@ -365,6 +381,8 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
Assert.Equal(SiteId, packet.Operational.SourceSite);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a cached call without a forwarder still returns the tracked operation id.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_NoForwarder_StillReturnsTrackedOperationId()
|
||||
{
|
||||
@@ -396,20 +414,21 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Audit Log #23 — M3 Bundle F (F2): when the underlying client call
|
||||
/// When the underlying client call
|
||||
/// completes immediately (no S&F buffering, <c>WasBuffered=false</c>),
|
||||
/// the S&F retry loop never engages and the
|
||||
/// <c>ICachedCallLifecycleObserver</c> hook never fires. The cached-call
|
||||
/// helper itself must therefore emit the terminal lifecycle rows —
|
||||
/// otherwise <c>Tracking.Status(id)</c> would return <c>Submitted</c>
|
||||
/// forever and the audit log would be missing the <c>Attempted</c> /
|
||||
/// <c>CachedResolve</c> pair the M3 contract requires.
|
||||
/// <c>CachedResolve</c> pair the contract requires.
|
||||
///
|
||||
/// Expected emissions on immediate success:
|
||||
/// 1. CachedSubmit / Submitted (already covered)
|
||||
/// 2. ApiCallCached / Attempted
|
||||
/// 3. CachedResolve / Delivered (TerminalAtUtc set)
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_ImmediateSuccess_EmitsAttemptedAndCachedResolve()
|
||||
{
|
||||
@@ -464,17 +483,19 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
// Terminal row carries TerminalAtUtc.
|
||||
Assert.NotNull(resolve.Operational.TerminalAtUtc);
|
||||
|
||||
// Audit Log #23 (ParentExecutionId): null on every script-side cached
|
||||
// ParentExecutionId: null on every script-side cached
|
||||
// row for a non-routed run.
|
||||
Assert.Null(submit.Audit.AsRow().ParentExecutionId);
|
||||
Assert.Null(attempted.Audit.AsRow().ParentExecutionId);
|
||||
Assert.Null(resolve.Audit.AsRow().ParentExecutionId);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a routed run stamps the parent execution id on all script-side rows.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_RoutedRun_StampsParentExecutionId_OnAllScriptSideRows()
|
||||
{
|
||||
// Audit Log #23 (ParentExecutionId, Task 5): an inbound-API-routed run
|
||||
// An inbound-API-routed run
|
||||
// carries the spawning execution's id; every script-side cached row
|
||||
// (CachedSubmit, ApiCallCached, CachedResolve) must stamp it in
|
||||
// ParentExecutionId.
|
||||
@@ -500,12 +521,13 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Audit Log #23 — M3 Bundle F (F2): the immediate-failure terminal
|
||||
/// The immediate-failure terminal
|
||||
/// path. When the client returns <c>Success=false</c> with
|
||||
/// <c>WasBuffered=false</c> (a permanent failure or a transient failure
|
||||
/// without an S&F engine to buffer it), the cached-call helper must
|
||||
/// still emit Attempted + CachedResolve with the failed status.
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_ImmediateFailure_EmitsAttemptedAndCachedResolveFailed()
|
||||
{
|
||||
@@ -543,12 +565,13 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Audit Log #23 — M3 Bundle F (F2): when the client reports
|
||||
/// When the client reports
|
||||
/// <c>WasBuffered=true</c>, the helper hands the operation to S&F and
|
||||
/// the retry-loop observer owns the Attempted + Resolve emissions. The
|
||||
/// helper must NOT emit those rows itself (otherwise we'd get duplicate
|
||||
/// Attempted + Resolve audit rows under the same tracking id).
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_BufferedPath_DoesNotEmitTerminalTelemetryFromHelper()
|
||||
{
|
||||
@@ -574,12 +597,14 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
Assert.Equal(AuditKind.CachedSubmit, only.Audit.AsRow().Kind);
|
||||
}
|
||||
|
||||
// ── SourceNode-stamping (Task 14) ──
|
||||
// ── SourceNode-stamping ──
|
||||
|
||||
/// <summary>Verifies that a cached call stamps the source node on every site call operational row.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_StampsSourceNode_OnEverySiteCallOperationalRow()
|
||||
{
|
||||
// SourceNode-stamping (Task 14): when the helper is constructed with
|
||||
// SourceNode stamping: when the helper is constructed with
|
||||
// a non-null sourceNode, every SiteCallOperational it produces
|
||||
// (CachedSubmit on enqueue + the immediate-completion Attempted/
|
||||
// CachedResolve pair when WasBuffered=false) carries that node name.
|
||||
@@ -614,6 +639,8 @@ public class ExternalSystemCachedCallEmissionTests
|
||||
Assert.All(forwarder.Telemetry, t => Assert.Equal("node-a", t.Operational.SourceNode));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a cached call with no source node wired leaves the source node null.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CachedCall_NoSourceNodeWired_LeavesSourceNodeNull()
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user