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
+63
-3
@@ -24,7 +24,7 @@ namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests.Scripts;
|
||||
/// emits <c>ScriptTrace</c> rows for attribute writes and waits (into the inline collector
|
||||
/// AND the audit writer), stamps <c>Trace</c> on the commands it sends, and inherits the flag
|
||||
/// into nested calls. An untraced context is byte-for-byte the pre-feature behaviour.
|
||||
/// Outbound-calls addendum (plan 2026-09-06 Task 3): the <c>ApiOutbound</c> /
|
||||
/// Outbound calls: the <c>ApiOutbound</c> /
|
||||
/// <c>DbOutbound</c> / <c>Notification</c> rows a run emits ride the same collector — the
|
||||
/// SAME <see cref="AuditEvent"/> instance the writer / telemetry forwarder receives — and
|
||||
/// nothing lands after the collector is <see cref="FlowTraceCollector.Complete"/>d.
|
||||
@@ -35,7 +35,9 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
|
||||
private sealed class CapturingAuditWriter : IAuditWriter
|
||||
{
|
||||
/// <summary>The audit events written so far.</summary>
|
||||
public List<AuditEvent> Events { get; } = new();
|
||||
/// <inheritdoc />
|
||||
public Task WriteAsync(AuditEvent evt, CancellationToken ct = default)
|
||||
{
|
||||
lock (Events) Events.Add(evt);
|
||||
@@ -45,7 +47,9 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
|
||||
private sealed class CapturingForwarder : ICachedCallTelemetryForwarder
|
||||
{
|
||||
/// <summary>The cached-call telemetry packets forwarded so far.</summary>
|
||||
public List<CachedCallTelemetry> Telemetry { get; } = new();
|
||||
/// <inheritdoc />
|
||||
public Task ForwardAsync(CachedCallTelemetry telemetry, CancellationToken ct = default)
|
||||
{
|
||||
Telemetry.Add(telemetry);
|
||||
@@ -58,6 +62,7 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
private sealed class TempStoreAndForward : IDisposable
|
||||
{
|
||||
private readonly TestLocalDb _localDb;
|
||||
/// <summary>The store-and-forward service under test.</summary>
|
||||
public StoreAndForwardService Service { get; }
|
||||
|
||||
private TempStoreAndForward(TestLocalDb localDb, StoreAndForwardService service)
|
||||
@@ -66,6 +71,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Service = service;
|
||||
}
|
||||
|
||||
/// <summary>Creates a store-and-forward service over a temporary LocalDb file.</summary>
|
||||
/// <returns>A task that resolves to the new temporary store-and-forward wrapper.</returns>
|
||||
public static async Task<TempStoreAndForward> CreateAsync()
|
||||
{
|
||||
var localDb = TestLocalDb.CreateTemp("TraceEmissionNotify");
|
||||
@@ -81,6 +88,7 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
new StoreAndForwardService(storage, options, NullLogger<StoreAndForwardService>.Instance));
|
||||
}
|
||||
|
||||
/// <summary>Releases the resources held by this test class.</summary>
|
||||
public void Dispose()
|
||||
{
|
||||
_localDb.Dispose();
|
||||
@@ -159,6 +167,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
isTraced: traced, traceCollector: collector,
|
||||
maxLogLinesPerRun: maxLogLinesPerRun);
|
||||
|
||||
/// <summary>Verifies that a traced SetAttribute emits an attribute-write row and passes the trace flag on the command.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SetAttribute_WhenTraced_EmitsAttributeWriteRow_AndPassesTraceOnCommand()
|
||||
{
|
||||
@@ -194,6 +204,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Same(evt, Assert.Single(collector.Snapshot()));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an untraced SetAttribute emits nothing and sends a command with the trace flag false.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SetAttribute_WhenNotTraced_EmitsNothing_AndCommandTraceFalse()
|
||||
{
|
||||
@@ -216,6 +228,7 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
/// carries is the FILTERED record — while the writer still receives the raw event and
|
||||
/// redacts it itself (redaction is idempotent, so the stored row is identical).
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SetAttribute_WhenTraced_InlineCopyIsRedacted_WriterStillSeesTheRawEvent()
|
||||
{
|
||||
@@ -240,10 +253,15 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
/// <summary>Upper-cases <c>DetailsJson</c> so a test can see the filtered copy land.</summary>
|
||||
private sealed class UpperRedactor : IAuditRedactor
|
||||
{
|
||||
/// <summary>Upper-cases the event details so tests can see the filtered copy.</summary>
|
||||
/// <param name="rawEvent">The audit event to apply.</param>
|
||||
/// <returns>The event with upper-cased details.</returns>
|
||||
public AuditEvent Apply(AuditEvent rawEvent)
|
||||
=> rawEvent with { DetailsJson = rawEvent.DetailsJson?.ToUpperInvariant() };
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a traced SetAttribute whose write fails emits a failed row and then throws.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SetAttribute_WhenTraced_FailedWrite_EmitsFailedRow_ThenThrows()
|
||||
{
|
||||
@@ -261,6 +279,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal("device rejected", row.ErrorMessage);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a traced wait emits an attribute-wait row with a satisfied outcome.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task WaitInternal_WhenTraced_EmitsAttributeWait_WithOutcomeSatisfied()
|
||||
{
|
||||
@@ -287,6 +307,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Single(collector.Snapshot());
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a traced wait that times out emits a failed row with a timeout outcome.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task WaitInternal_WhenTraced_Timeout_EmitsFailedRow_WithTimeoutOutcome()
|
||||
{
|
||||
@@ -305,6 +327,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal("timeout", ScriptTraceExtra.TryParse(row.Extra)!.WaitOutcome);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an untraced wait emits nothing.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task WaitInternal_WhenNotTraced_EmitsNothing()
|
||||
{
|
||||
@@ -320,6 +344,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Empty(writer.Events);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a traced CallScript propagates the trace flag on the script call request.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CallScript_WhenTraced_PropagatesTraceOnScriptCallRequest()
|
||||
{
|
||||
@@ -337,6 +363,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.False(CreateContext(probe.Ref, null, traced: false, null).CreateChildContextForSharedScript(1).IsTraced);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an untraced CallScript sends a request with the trace flag false.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task CallScript_WhenNotTraced_RequestTraceIsFalse()
|
||||
{
|
||||
@@ -350,8 +378,10 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
await call;
|
||||
}
|
||||
|
||||
// ---- Outbound rows ride the collector (plan 2026-09-06 Task 3) -------------------------
|
||||
// ---- Outbound rows ride the collector -------------------------
|
||||
|
||||
/// <summary>Verifies that a traced external system call collects the same API-call row that the writer receives.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task ExternalSystemCall_WhenTraced_CollectsTheSameApiCallRow_TheWriterReceives()
|
||||
{
|
||||
@@ -372,6 +402,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal(exec, Row(collected).ExecutionId);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a buffered cached external call collects only the cached-submit row, as the same instance the telemetry receives.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task ExternalSystemCachedCall_Buffered_CollectsCachedSubmitOnly_SameInstanceAsTelemetry()
|
||||
{
|
||||
@@ -390,6 +422,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal(trackedId.Value, Row(collected).CorrelationId);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an immediately completing cached external call collects the submit, attempted and resolve rows while the run is open.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task ExternalSystemCachedCall_ImmediateCompletion_CollectsSubmitAttemptedResolve_WhileRunIsOpen()
|
||||
{
|
||||
@@ -410,6 +444,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
snap.Select(e => Row(e).Kind));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that outbound rows emitted after the collector completed do not touch the collector but still reach telemetry.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task OutboundRows_AfterCollectorCompleted_DoNotTouchTheCollector_ButStillReachTelemetry()
|
||||
{
|
||||
@@ -439,6 +475,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal(snapshot.Select(e => e.EventId), collector.Snapshot().Select(e => e.EventId));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a traced database execute collects the same database-write row that the writer receives.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task DatabaseExecute_WhenTraced_CollectsTheSameDbWriteRow_TheWriterReceives()
|
||||
{
|
||||
@@ -464,6 +502,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Contains("\"rowsAffected\":1", Row(collected).Extra);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a buffered cached database write collects the cached-submit row, as the same instance the telemetry receives.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task DatabaseCachedWrite_Buffered_CollectsCachedSubmit_SameInstanceAsTelemetry()
|
||||
{
|
||||
@@ -490,6 +530,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal(trackedId.Value, Row(collected).CorrelationId);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a traced Notify.Send collects the same notification row that the writer receives.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task NotifySend_WhenTraced_CollectsTheSameNotifySendRow_TheWriterReceives()
|
||||
{
|
||||
@@ -510,6 +552,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal(Guid.Parse(notificationId), Row(collected).CorrelationId);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that without a collector the writer and telemetry still receive every outbound row.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task OutboundRows_WhenNoCollector_WriterAndTelemetryStillReceiveEveryRow()
|
||||
{
|
||||
@@ -543,6 +587,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal(AuditKind.CachedSubmit, Row(Assert.Single(forwarder.Telemetry).Audit).Kind);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a throwing trace sink never fails the call and the writer still gets the row.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task ThrowingTraceSink_NeverFailsTheCall_AndTheWriterStillGetsTheRow()
|
||||
{
|
||||
@@ -565,10 +611,12 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
/// the runtime line test (c) needs a genuine <c>_logger.LogWarning</c> inside a step body.</summary>
|
||||
private sealed class ThrowingAuditWriter : IAuditWriter
|
||||
{
|
||||
/// <inheritdoc />
|
||||
public Task WriteAsync(AuditEvent evt, CancellationToken ct = default)
|
||||
=> throw new InvalidOperationException("writer down");
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a traced Log call emits one script-log row to both the collector and the writer.</summary>
|
||||
[Fact]
|
||||
public void Log_WhenTraced_EmitsOneScriptLogRow_ToTheCollectorAndTheWriter()
|
||||
{
|
||||
@@ -598,6 +646,7 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal(1, extra.Seq);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an untraced Log call reaches neither the writer nor the collector.</summary>
|
||||
[Fact]
|
||||
public void Log_WhenNotTraced_ReachesNeitherTheWriterNorTheCollector()
|
||||
{
|
||||
@@ -614,6 +663,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.False(collector.LogsTruncated);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a trace write failure does not create diagnostic trace rows.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task TraceWriteFailure_DoesNotCreateDiagnosticTraceRows()
|
||||
{
|
||||
@@ -628,6 +679,7 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal(AuditKind.AttributeWrite, Row(collector.Snapshot().Single()).Kind);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the context caches its helpers per context.</summary>
|
||||
[Fact]
|
||||
public void Helpers_AreCachedPerContext()
|
||||
{
|
||||
@@ -642,6 +694,7 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.NotSame(ctx.Scripts, child.Scripts);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a Log call with an exception carries the message and the full exception detail.</summary>
|
||||
[Fact]
|
||||
public void Log_WithException_CarriesTheMessageAndTheFullDetail()
|
||||
{
|
||||
@@ -657,6 +710,8 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Equal("warn", ScriptTraceExtra.TryParse(row.Extra)!.LogLevel);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that log rows use the low-priority lane so that step rows keep their reserve.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task LogRows_RideTheLowPriorityLane_SoStepRowsKeepTheirReserve()
|
||||
{
|
||||
@@ -682,6 +737,7 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
Assert.Contains(collector.Snapshot(), e => Row(e).Kind == AuditKind.AttributeWrite);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that FlushDropped emits the closing row once the per-run cap is exceeded.</summary>
|
||||
[Fact]
|
||||
public void FlushDropped_EmitsTheClosingRow_OnceThePerRunCapIsExceeded()
|
||||
{
|
||||
@@ -709,6 +765,7 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
/// that node. Provoked the same way as the write case — a writer that throws makes the
|
||||
/// helper's own best-effort "audit write threw" warning fire inside the scope.
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task RuntimeWarning_InsideATracedExternalCall_IsAttributedToTheApiCallStep()
|
||||
{
|
||||
@@ -732,6 +789,7 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
/// inline collector — a traced run without one still writes durable <c>ScriptLog</c> rows that
|
||||
/// have to name their step.
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task TracedExternalCall_WithoutACollector_StillNamesTheApiCallStep()
|
||||
{
|
||||
@@ -786,6 +844,7 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
/// The batch and wait scopes unwind even when trace writes fail; their internal
|
||||
/// diagnostics stay out of the collector, and the later script line belongs to the run.
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task NestedStepScopes_IgnoreTraceDiagnostics_AndUnwind()
|
||||
{
|
||||
@@ -820,10 +879,11 @@ public class ScriptRuntimeContextTraceEmissionTests : TestKit
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gitea #36: the reset-aware handshake is four traced steps in leg order — reset write,
|
||||
/// The reset-aware handshake is four traced steps in leg order — reset write,
|
||||
/// reset-echo wait, batch write, response wait — each with its own row id, with no new
|
||||
/// audit kinds (the Flow Debugger projection needs no change).
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task WriteBatchResetAndWait_WhenTraced_EmitsFourStepRowsInLegOrder()
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user