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/Actors/ScriptRunLauncherParityTests.cs
+27 -9
View File
@@ -18,10 +18,10 @@ using ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests.TestSupport;
namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests.Actors;
/// <summary>
/// WP3.1 supervision-parity set (design memo §4, seven pins) — the reworked successor to
/// Supervision-parity set (design memo §4, seven pins) — the reworked successor to
/// <c>ExecutionActorTests</c>.
///
/// <para>WP3.1 eliminated the short-lived <c>ScriptExecutionActor</c> and
/// <para>The refactor eliminated the short-lived <c>ScriptExecutionActor</c> and
/// <c>AlarmExecutionActor</c>: neither had a <c>Receive</c> handler, a <c>PostStop</c>, or any
/// state, and neither's <c>IActorRef</c> was ever a message target — the entire lifecycle lived
/// in a detached task. Runs are now launched directly by the coordinator via
@@ -35,9 +35,10 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
private readonly SharedScriptLibrary _sharedLibrary;
private readonly ScriptCompilationService _compilationService;
/// <summary>Own pool per test class (#18 seam), so a wedged body cannot strand the process-wide one.</summary>
/// <summary>Own pool per test class, so a wedged body cannot strand the process-wide one.</summary>
private readonly ScriptExecutionScheduler _scheduler = new(4);
/// <summary>Initializes the test with a compilation service and shared script library.</summary>
public ScriptRunLauncherParityTests()
{
_compilationService = new ScriptCompilationService(
@@ -46,6 +47,7 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
_compilationService, NullLogger<SharedScriptLibrary>.Instance);
}
/// <inheritdoc />
void IDisposable.Dispose()
{
Shutdown();
@@ -72,7 +74,7 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
MaxScriptCallDepth = 10,
ScriptExecutionTimeoutSeconds = timeoutSeconds,
StuckScriptGraceMs = graceMs,
// WP3.2: per-run Started/Completed Info events default OFF; tests that pin the
// Per-run Started/Completed Info events default OFF; tests that pin the
// legacy per-run event shape opt back in explicitly via this flag.
PerRunScriptEvents = perRunScriptEvents
};
@@ -104,6 +106,7 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
// ── Pin 1: throwing body — coordinator survives, everything is reported ───────
/// <summary>Verifies that a throwing script body leaves the script actor alive and reports everything.</summary>
[Fact]
public void ThrowingScriptBody_LeavesScriptActorAliveAndReportsEverything()
{
@@ -150,7 +153,7 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
/// The only failure the removed per-run child could surface was a constructor throw —
/// e.g. queueing onto a disposed <see cref="ScriptExecutionScheduler"/>. The old
/// <c>OneForOneStrategy</c> logged it and stopped the child, leaving the Ask caller to
/// hang with no reply at all. WP3.1 folds that into a launch-path catch that replies, an
/// hang with no reply at all. The launcher folds that into a launch-path catch that replies, an
/// intentional improvement pinned here so it is explicit rather than accidental.
/// </summary>
[Fact]
@@ -182,6 +185,9 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
// ── Pin 3: exactly one DI scope per run, disposed on every path ───────────────
/// <summary>Verifies that each run creates one DI scope and disposes it exactly once.</summary>
/// <param name="code">The script source to run.</param>
/// <param name="timeoutSeconds">The script timeout in seconds.</param>
[Theory]
[InlineData("return 1;", 30)] // success
[InlineData("throw new InvalidOperationException(\"boom\");", 30)] // failure
@@ -240,6 +246,9 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
// ── Pin 5: timeout resolution parity (perScript ?? global, <= 0 => global) ────
/// <summary>Verifies that timeout resolution matches the behavior of the removed execution actor.</summary>
/// <param name="globalSeconds">The global script timeout in seconds.</param>
/// <param name="perScriptSeconds">The per-script timeout in seconds, or null to use the global timeout.</param>
[Theory]
[InlineData(300, 1)] // per-script override wins over a much longer global
[InlineData(1, null)] // null per-script falls back to the global
@@ -377,6 +386,7 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
// ── Retargeted from ExecutionActorTests: success path + operational events ────
/// <summary>Verifies that a successful run replies with the return value.</summary>
[Fact]
public void SuccessfulRun_RepliesWithTheReturnValue()
{
@@ -391,11 +401,12 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
Assert.Equal(42, result.ReturnValue);
}
/// <summary>Verifies that a successful run emits Started then Completed info events.</summary>
[Fact]
public void SuccessfulRun_EmitsStartedThenCompletedInfoEvents()
{
var siteLog = new FakeSiteEventLogger();
// WP3.2: per-run Info events are opt-in now (default off, interval summary instead) —
// Per-run Info events are opt-in now (default off, interval summary instead) —
// this test pins the legacy per-run shape, so it opts back in explicitly.
var actor = BuildScriptActor(
CompileScript("return 7 * 6;"), Options(perRunScriptEvents: true), new SingleServiceProvider(siteLog));
@@ -419,11 +430,12 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
}, TimeSpan.FromSeconds(5));
}
/// <summary>Verifies that a failing run emits a Started info event then an Error event.</summary>
[Fact]
public void FailingRun_EmitsStartedInfoThenErrorEvent()
{
var siteLog = new FakeSiteEventLogger();
// WP3.2: the started Info event is opt-in (default off); the Error event on failure
// The started Info event is opt-in (default off); the Error event on failure
// stays unconditional regardless. This test pins the opted-in shape explicitly.
var actor = BuildScriptActor(
CompileScript("throw new InvalidOperationException(\"boom\");"),
@@ -443,11 +455,12 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
}, TimeSpan.FromSeconds(5));
}
/// <summary>Verifies that a fire-and-forget run needs no reply target.</summary>
[Fact]
public void FireAndForgetRun_NeedsNoReplyTarget()
{
var siteLog = new FakeSiteEventLogger();
// WP3.2: opted in so the completed Info event (the observable proof the
// Opted in so the completed Info event (the observable proof the
// fire-and-forget run actually ran to completion) is emitted; the policy itself is
// covered separately by ScriptRunEventPolicyTests.
var actor = BuildScriptActor(
@@ -463,7 +476,7 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
TimeSpan.FromSeconds(10));
}
// ── WP3.2: site_events volume policy — actor-level integration ────────────────
// ── site_events volume policy — actor-level integration ────────────────
//
// The pure ScriptRunEventPolicy matching rules (exact/wildcard/global/non-matching) are
// unit-tested directly in ScriptRunEventPolicyTests; these prove the policy is actually
@@ -471,6 +484,8 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
// the aggregate still sees the run, per-script opt-in works end to end, and the
// IOptionsMonitor read makes the switch hot-togglable without an actor restart.
/// <summary>Verifies that with default options a successful run emits no per-run events but the summary recorder still sees it.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task DefaultOptions_SuccessfulRun_EmitsNoPerRunEvents_ButTheSummaryRecorderSeesIt()
{
@@ -499,6 +514,7 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
flushLog.OfType("script").Single().Message);
}
/// <summary>Verifies that opting in a script by exact match restores per-run events for that script only.</summary>
[Fact]
public void PerScriptOptIn_ExactMatch_RestoresPerRunEventsForThatScriptOnly()
{
@@ -515,6 +531,7 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
AwaitAssert(() => Assert.Equal(2, siteLog.OfType("script").Count), TimeSpan.FromSeconds(5));
}
/// <summary>Verifies that opting in with an instance wildcard restores per-run events.</summary>
[Fact]
public void PerScriptOptIn_InstanceWildcard_RestoresPerRunEvents()
{
@@ -531,6 +548,7 @@ public class ScriptRunLauncherParityTests : TestKit, IDisposable
AwaitAssert(() => Assert.Equal(2, siteLog.OfType("script").Count), TimeSpan.FromSeconds(5));
}
/// <summary>Verifies that flipping the options monitor changes the next run with no actor restart.</summary>
[Fact]
public void HotToggle_FlippingTheOptionsMonitor_ChangesTheNextRunWithNoActorRestart()
{