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.CentralUI.Tests/Services/FlowDebugServiceTests.cs
+84
View File
@@ -65,6 +65,7 @@ public sealed class FlowDebugServiceTests : IDisposable
private bool _siteReachable = true;
private string? _siteCallError;
/// <summary>Releases the resources held by this test class.</summary>
public void Dispose() => _system.Terminate().Wait(TimeSpan.FromSeconds(5));
private FlowDebugService CreateService(object? reply, string role = "Deployer", string? permittedSite = null)
@@ -113,6 +114,10 @@ public sealed class FlowDebugServiceTests : IDisposable
null, null, null, siteId, "node-a", "Sim01", "ERP.GetOrder", null,
Lifecycle: null, CorrelationId: correlationId);
/// <summary>Verifies that a scoped caller can relay only for the sites it has been granted.</summary>
/// <param name="siteId">The resolved site id of the step.</param>
/// <param name="expected">Whether the relay is expected to be sent.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(42, true)]
[InlineData(99, false)]
@@ -128,6 +133,9 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Equal(expected ? 1 : 0, _siteCallRequests.Count);
}
/// <summary>Verifies that a scoped caller cannot relay for a site that cannot be resolved.</summary>
/// <param name="retry">True to retry the outbound call, false to discard it.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(true)]
[InlineData(false)]
@@ -140,6 +148,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Empty(_siteCallRequests);
}
/// <summary>Verifies that retrying a parked API call relays a retry site call carrying the correlation id and site.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RetryOutbound_ApiCallParked_RelaysRetrySiteCallWithCorrelationAndSite()
{
@@ -158,6 +168,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Empty(_outboxRequests);
}
/// <summary>Verifies that retrying a notification relays a retry notification request.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RetryOutbound_Notify_RelaysRetryNotification()
{
@@ -174,6 +186,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Empty(_siteCallRequests);
}
/// <summary>Verifies that discarding a database call relays a discard site call.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task DiscardOutbound_DbCall_RelaysDiscardSiteCall()
{
@@ -191,6 +205,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Equal("tester", request.RequestedBy);
}
/// <summary>Verifies that retrying a step that is not parked is refused without relaying.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RetryOutbound_NotParked_RefusesWithoutRelay()
{
@@ -204,6 +220,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Empty(_outboxRequests);
}
/// <summary>Verifies that retrying a step with no correlation id is refused.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RetryOutbound_NoCorrelation_Refuses()
{
@@ -217,6 +235,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Empty(_outboxRequests);
}
/// <summary>Verifies that retrying a site-kind step without a site id is refused.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RetryOutbound_SiteKindWithoutSiteId_Refuses()
{
@@ -230,6 +250,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Empty(_outboxRequests);
}
/// <summary>Verifies that retrying a step that is not an outbound call is refused.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RetryOutbound_NonOutboundStep_Refuses()
{
@@ -243,6 +265,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Empty(_outboxRequests);
}
/// <summary>Verifies that an unreachable site maps to a failure message on retry.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RetryOutbound_SiteUnreachable_MapsToFailureMessage()
{
@@ -257,6 +281,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Single(_siteCallRequests);
}
/// <summary>Verifies that an operation that is not parked at the site maps to a failure message on retry.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RetryOutbound_NotParkedAtSite_MapsToFailureMessage()
{
@@ -269,6 +295,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Contains("no longer parked", result.Message);
}
/// <summary>Verifies that a failed discard surfaces the site's own error message.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task DiscardOutbound_OperationFailed_UsesTheSitesOwnErrorMessage()
{
@@ -307,6 +335,8 @@ public sealed class FlowDebugServiceTests : IDisposable
return JsonSerializer.Serialize(result, ServerJson);
}
/// <summary>Verifies that the logs-truncated flag is carried onto both the outcome and the graph.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RunMethod_LogsTruncated_RidesOntoTheOutcomeAndTheGraph()
{
@@ -322,6 +352,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.True(outcome.Raw!.LogsTruncated);
}
/// <summary>Verifies that a run without log truncation leaves the flag false.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RunMethod_NoLogTruncation_LeavesTheFlagFalse()
{
@@ -333,6 +365,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.False(outcome.Graph!.LogsTruncated);
}
/// <summary>Verifies that running a method with no management actor holder reports the service as unavailable.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RunMethod_HolderNull_ReportsServiceUnavailable()
{
@@ -346,6 +380,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Empty(_received);
}
/// <summary>Verifies that a management error is mapped with its code and message unchanged.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RunMethod_ManagementError_MapsCodeAndMessageVerbatim()
{
@@ -358,6 +394,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Equal("This node is standby.", outcome.Error);
}
/// <summary>Verifies that an unauthorized management reply maps to the unauthorized code.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RunMethod_Unauthorized_MapsToUnauthorizedCode()
{
@@ -369,6 +407,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Equal("Deployer role required.", outcome.Error);
}
/// <summary>Verifies that a successful run builds the graph from the returned steps and sends the typed command for the calling principal.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RunMethod_Success_BuildsGraphWithTheReturnedSteps_AndSendsTheTypedCommandForThePrincipal()
{
@@ -393,6 +433,9 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Contains("Deployer", envelope.User.Roles);
}
/// <summary>Verifies that the run ask timeout is the method timeout plus the run grace and client slack, floored at the minimum.</summary>
/// <param name="timeoutSeconds">The method timeout in seconds.</param>
/// <param name="expectedSeconds">The expected ask timeout in seconds.</param>
[Theory]
[InlineData(180, 205)]
[InlineData(1, 30)]
@@ -403,6 +446,7 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Equal(TimeSpan.FromSeconds(expectedSeconds), timeout);
}
/// <summary>Verifies that the value-change ask timeout is the wait seconds plus the client slack.</summary>
[Fact]
public void ValueChangeAskTimeoutFor_IsWaitSecondsPlusClientSlack()
{
@@ -411,6 +455,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Equal(TimeSpan.FromSeconds(60), timeout);
}
/// <summary>Verifies that running a write-kind script and replaying a run each send their commands.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RunWriteKindScript_AndReplay_SendTheirCommands()
{
@@ -433,6 +479,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Equal(exec, rpCmd.ExecutionId);
}
/// <summary>Verifies that a truncated run result flags the graph.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Run_TruncatedResult_FlagsTheGraph()
{
@@ -444,6 +492,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.True(outcome.Graph!.Truncated);
}
/// <summary>Verifies that predicting a method resolves constant route targets through the instance template chain.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task PredictMethod_ResolvesConstantRouteTargets_ThroughInstanceTemplateChain()
{
@@ -522,6 +572,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Contains(flow.Nodes, n => n.Kind == FlowStepKind.AttributeWrite && n.Title == "Sim01.Cmd");
}
/// <summary>Verifies that nested route targets are resolved across successive prediction passes.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task PredictMethod_NestedRouteTargets_ResolveAcrossPasses()
{
@@ -560,10 +612,16 @@ public sealed class FlowDebugServiceTests : IDisposable
{
private readonly System.Collections.Concurrent.BlockingCollection<(SendOrPostCallback Callback, object? State)> _queue = new();
/// <inheritdoc />
public override void Post(SendOrPostCallback d, object? state) => _queue.Add((d, state));
/// <inheritdoc />
public override void Send(SendOrPostCallback d, object? state) => throw new NotSupportedException();
/// <summary>Runs the given asynchronous body on this pump, draining posted callbacks until it completes.</summary>
/// <typeparam name="T">The result type of the body.</typeparam>
/// <param name="body">The asynchronous body to run.</param>
/// <returns>The result of the body.</returns>
public T Run<T>(Func<Task<T>> body)
{
var previous = Current;
@@ -586,6 +644,8 @@ public sealed class FlowDebugServiceTests : IDisposable
}
}
/// <summary>Verifies that predicting an unknown method yields an empty result.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task PredictMethod_UnknownMethod_IsEmpty()
{
@@ -597,6 +657,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Empty(flow.Nodes);
}
/// <summary>Verifies that instance scripts are projected from the flattened configuration with their trigger attribute and kind, ordered by name.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task GetInstanceScripts_ProjectsFlattenedScripts_WithTriggerAttributeAndKind_OrderedByName()
{
@@ -615,12 +677,16 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.False(options.Single(o => o.CanonicalName == "Mod.Tick").IsWriteKind);
}
/// <summary>Verifies that requesting scripts for an unknown instance yields an empty result.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task GetInstanceScripts_UnknownInstance_IsEmpty()
{
Assert.Empty(await CreateService(reply: null).GetInstanceScriptsAsync(404));
}
/// <summary>Verifies that predicting a write-kind script roots at the write and appends the script.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task PredictScript_WriteKind_RootsAtTheWrite_AndAppendsTheScript()
{
@@ -637,6 +703,8 @@ public sealed class FlowDebugServiceTests : IDisposable
], flow.Nodes.Select(n => (n.Kind, n.Title)).ToList());
}
/// <summary>Verifies that predicting a call-kind script roots at a route call followed by the script.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task PredictScript_CallKind_RootsAtARouteCall_ThenTheScript()
{
@@ -652,6 +720,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.True(flow.Edges[0].CrossesBoundary);
}
/// <summary>Verifies that predicting an unknown script yields an empty result.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task PredictScript_UnknownScript_IsEmpty()
{
@@ -659,6 +729,8 @@ public sealed class FlowDebugServiceTests : IDisposable
Assert.Same(PredictedFlow.Empty, await CreateService(reply: null).PredictScriptAsync(9, "Nope"));
}
/// <summary>Verifies that running a script sends the command carrying the script shape.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RunScript_SendsTheCommand_WithTheScriptShape()
{
@@ -683,6 +755,7 @@ public sealed class FlowDebugServiceTests : IDisposable
/// entry <see cref="IFlowDebugService.GetInstanceScriptsAsync"/> just refreshed (design
/// 2026-09-08 §5). A regression here means every keystroke re-walks the template chain.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task GetInstanceScripts_ThenPredict_ThenRun_FlattenOnce()
{
@@ -702,6 +775,7 @@ public sealed class FlowDebugServiceTests : IDisposable
/// re-flatten — otherwise a template edit or a redeploy mid-session leaves the picker, the
/// parameter form and the Ask sizing stale for the rest of the session.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task GetInstanceScripts_CalledAgain_ReflattensAndRefreshes()
{
@@ -729,12 +803,18 @@ public sealed class FlowDebugServiceTests : IDisposable
private sealed class StubAuth : AuthenticationStateProvider
{
private readonly ClaimsPrincipal _user;
/// <summary>Initializes the provider with the principal to report.</summary>
/// <param name="user">The principal reported as the authenticated user.</param>
public StubAuth(ClaimsPrincipal user) => _user = user;
/// <inheritdoc />
public override Task<AuthenticationState> GetAuthenticationStateAsync() => Task.FromResult(new AuthenticationState(_user));
}
private sealed class ScriptedManagementActor : ReceiveActor
{
/// <summary>Initializes the actor with the reply to send and the list that records received envelopes.</summary>
/// <param name="reply">The reply sent back for every received envelope.</param>
/// <param name="received">The list that collects each received envelope.</param>
public ScriptedManagementActor(object reply, List<ManagementEnvelope> received)
{
Receive<ManagementEnvelope>(env =>
@@ -748,6 +828,8 @@ public sealed class FlowDebugServiceTests : IDisposable
/// <summary>Stands in for the Site Call Audit singleton proxy: records the relay request, replies as scripted.</summary>
private sealed class ScriptedSiteCallAuditActor : ReceiveActor
{
/// <summary>Initializes the actor to record and answer site call audit requests on the owning test.</summary>
/// <param name="test">The owning test whose recorded requests and scripted outcome the actor uses.</param>
public ScriptedSiteCallAuditActor(FlowDebugServiceTests test)
{
Receive<RetrySiteCallRequest>(r =>
@@ -768,6 +850,8 @@ public sealed class FlowDebugServiceTests : IDisposable
/// <summary>Stands in for the Notification Outbox singleton proxy: records the request, replies success.</summary>
private sealed class ScriptedOutboxActor : ReceiveActor
{
/// <summary>Initializes the actor to record and answer notification outbox requests on the owning test.</summary>
/// <param name="test">The owning test whose recorded requests the actor appends to.</param>
public ScriptedOutboxActor(FlowDebugServiceTests test)
{
Receive<RetryNotificationRequest>(r =>