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.
2026-10-07 15:05:49 -04:00
parent 0ffd4bdbea
commit 513fa1aa16
998 changed files with 17896 additions and 2395 deletions
@@ -50,12 +50,17 @@ public class DebugViewTests : IClassFixture<DeploymentFixture>
    private readonly PlaywrightFixture _pw;
    private readonly DeploymentFixture _cluster;

+    /// <summary>Initializes the test class with the shared Playwright and cluster fixtures.</summary>
+    /// <param name="pw">The shared Playwright browser fixture.</param>
+    /// <param name="cluster">The shared deployment cluster fixture.</param>
    public DebugViewTests(PlaywrightFixture pw, DeploymentFixture cluster)
    {
        _pw = pw;
        _cluster = cluster;
    }

+    /// <summary>Verifies that the Debug View controls render and the Connect button is gated on an instance selection.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task DebugView_ControlsRender_ConnectGatedOnSelection()
    {
@@ -66,7 +71,7 @@ public class DebugViewTests : IClassFixture<DeploymentFixture>
        await page.WaitForLoadStateAsync(LoadState.NetworkIdle);

        await Assertions.Expect(page.Locator("h4:has-text('Debug View')")).ToBeVisibleAsync();
-        // The data-test hooks from Task 4 must be served (proves the rebuild took).
+        // The data-test hooks must be served (proves the rebuild took).
        await Assertions.Expect(page.Locator("[data-test='debug-site-select']")).ToHaveCountAsync(1);
        await Assertions.Expect(page.Locator("[data-test='debug-instance-picker']")).ToHaveCountAsync(1);

@@ -77,6 +82,8 @@ public class DebugViewTests : IClassFixture<DeploymentFixture>
            .ToBeVisibleAsync();
    }

+    /// <summary>Verifies that a connect-enabled instance resolves and can be disconnected.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task DebugView_ConnectEnabledInstance_ResolvesAndDisconnect()
    {
@@ -53,12 +53,17 @@ public class DebugViewTreeTests : IClassFixture<DeploymentFixture>
    private readonly PlaywrightFixture _pw;
    private readonly DeploymentFixture _cluster;

+    /// <summary>Initializes the test class with the shared Playwright and deployment fixtures.</summary>
+    /// <param name="pw">The shared Playwright fixture.</param>
+    /// <param name="cluster">The shared deployment fixture.</param>
    public DebugViewTreeTests(PlaywrightFixture pw, DeploymentFixture cluster)
    {
        _pw = pw;
        _cluster = cluster;
    }

+    /// <summary>Verifies that a connected debug view renders tabbed trees and that the alarms tab can be switched to.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task DebugView_Connected_RendersTabbedTrees_AndAlarmsTabSwitches()
    {
@@ -41,12 +41,17 @@ public class DeploymentActionTests : IClassFixture<DeploymentFixture>
    private readonly PlaywrightFixture _pw;
    private readonly DeploymentFixture _cluster;

+    /// <summary>Initializes a new instance of the <c>DeploymentActionTests</c> class.</summary>
+    /// <param name="pw">The pw.</param>
+    /// <param name="cluster">The cluster.</param>
    public DeploymentActionTests(PlaywrightFixture pw, DeploymentFixture cluster)
    {
        _pw = pw;
        _cluster = cluster;
    }

+    /// <summary>Helper: deploy instance shows outcome toast.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task Deploy_Instance_ShowsOutcomeToast()
    {
@@ -80,6 +85,8 @@ public class DeploymentActionTests : IClassFixture<DeploymentFixture>
        }
    }

+    /// <summary>Helper: disable instance shows outcome toast.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task Disable_Instance_ShowsOutcomeToast()
    {
@@ -113,6 +120,8 @@ public class DeploymentActionTests : IClassFixture<DeploymentFixture>
        }
    }

+    /// <summary>Helper: enable instance shows outcome toast.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task Enable_Instance_ShowsOutcomeToast()
    {
@@ -141,6 +150,8 @@ public class DeploymentActionTests : IClassFixture<DeploymentFixture>
        }
    }

+    /// <summary>Helper: delete instance removes from tree.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task Delete_Instance_RemovesFromTree()
    {
@@ -69,6 +69,7 @@ public sealed class DeploymentFixture : IAsyncLifetime
    /// is unavailable, sets <see cref="Available"/> to <see langword="false"/> and
    /// returns without touching the cluster.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task InitializeAsync()
    {
        Available = await ClusterAvailability.IsAvailableAsync();
@@ -148,6 +149,7 @@ public sealed class DeploymentFixture : IAsyncLifetime
    /// <see cref="InstanceNamePrefix"/>, then deletes the fixture's area and
    /// template. Swallows every error so a teardown hiccup never fails the suite.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task DisposeAsync()
    {
        if (!Available)
@@ -39,12 +39,17 @@ public class DeploymentsRealtimeTests : IClassFixture<DeploymentFixture>
    private readonly PlaywrightFixture _pw;
    private readonly DeploymentFixture _cluster;

+    /// <summary>Initializes the tests with the shared Playwright and deployment fixtures.</summary>
+    /// <param name="pw">The shared Playwright browser fixture.</param>
+    /// <param name="cluster">The fixture that provides access to the running cluster.</param>
    public DeploymentsRealtimeTests(PlaywrightFixture pw, DeploymentFixture cluster)
    {
        _pw = pw;
        _cluster = cluster;
    }

+    /// <summary>Verifies that deploying an instance pushes its row to the deployments page without a manual refresh.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task DeployingInstance_PushesRowWithoutManualRefresh()
    {
@@ -73,6 +78,8 @@ public class DeploymentsRealtimeTests : IClassFixture<DeploymentFixture>
        }
    }

+    /// <summary>Verifies that pausing updates suppresses the pushed row and that refreshing restores it.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task PausedUpdates_SuppressPush_RefreshRestoresRow()
    {
@@ -39,7 +39,8 @@ public sealed class FlowDebuggerFixture : IAsyncLifetime
    /// <summary>Name of the ephemeral inbound method (its <c>POST /api/{name}</c> segment).</summary>
    public string MethodName { get; private set; } = string.Empty;

-    /// <inheritdoc/>
+    /// <summary>Probes cluster availability and, when available, creates the ephemeral inbound method used by the tests.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task InitializeAsync()
    {
        Available = await ClusterAvailability.IsAvailableAsync();
@@ -69,7 +70,8 @@ public sealed class FlowDebuggerFixture : IAsyncLifetime
        }
    }

-    /// <inheritdoc/>
+    /// <summary>Deletes the ephemeral inbound method if one was created.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public Task DisposeAsync() =>
        MethodId > 0 ? CliRunner.DeleteApiMethodAsync(MethodId) : Task.CompletedTask;
 }
@@ -7,7 +7,7 @@ using Xunit;
 namespace ZB.MOM.WW.ScadaBridge.CentralUI.PlaywrightTests.Deployment;

 /// <summary>
-/// Real-browser coverage for the Flow Debugger page (follow-ups plan 2026-09-06, Task 9):
+/// Real-browser coverage for the Flow Debugger page (follow-ups plan 2026-09-06):
 /// a Live run of an inbound method completes and draws a graph, and the method choice survives
 /// a reload through the page's <c>localStorage</c> restore path. Both go through the same
 /// prediction path that used to deadlock the circuit (see <see cref="FlowDebuggerFixture"/>) —
@@ -15,7 +15,7 @@ namespace ZB.MOM.WW.ScadaBridge.CentralUI.PlaywrightTests.Deployment;
 /// so these tests are the browser-level guard for that fix as well.
 ///
 /// <para>
-/// The script entry (design 2026-09-08, Task 11) adds two more: a Live direct call of the rig's
+/// The script entry (design 2026-09-08) adds two more: a Live direct call of the rig's
 /// <c>OutboundDemo</c> Call script on <c>DelmiaSim01</c>, and the write-kind Inputs card naming the
 /// trigger's own attribute. Unlike the method tests those drive RIG-SEEDED objects the fixture does
 /// not provision, so each picker step skips with a "run docker/seed-…" message when it is absent.
@@ -29,12 +29,17 @@ public class FlowDebuggerTests : IClassFixture<FlowDebuggerFixture>
    private readonly PlaywrightFixture _pw;
    private readonly FlowDebuggerFixture _flow;

+    /// <summary>Initializes a new instance of the <c>FlowDebuggerTests</c> class.</summary>
+    /// <param name="pw">The shared Playwright fixture.</param>
+    /// <param name="flow">The Flow Debugger fixture.</param>
    public FlowDebuggerTests(PlaywrightFixture pw, FlowDebuggerFixture flow)
    {
        _pw = pw;
        _flow = flow;
    }

+    /// <summary>Verifies that a live run in the browser completes and draws the flow graph.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task LiveRun_InBrowser_CompletesAndDrawsTheGraph()
    {
@@ -47,7 +52,7 @@ public class FlowDebuggerTests : IClassFixture<FlowDebuggerFixture>
        await SelectMethodAsync(page);

        // The prediction (a Roslyn walk + the route-target resolve) finished: the state chip flips
-        // to Predicted and the method's ParameterValueForm (#37: the same typed form the script
+        // to Predicted and the method's ParameterValueForm (the same typed form the script
        // pane uses, inputs addressed by field id) appears.
        await Assertions.Expect(page.Locator("[data-test='flow-state']")).ToHaveTextAsync("Predicted", new() { Timeout = 15_000 });
        var input = page.Locator("#param-Text");
@@ -72,6 +77,8 @@ public class FlowDebuggerTests : IClassFixture<FlowDebuggerFixture>
        Assert.DoesNotContain(consoleErrors, e => e.Contains("JSInterop", StringComparison.OrdinalIgnoreCase));
    }

+    /// <summary>Verifies that the chosen inbound API method survives a page reload through local storage.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task MethodChoice_SurvivesReload_ViaLocalStorage()
    {
@@ -100,6 +107,8 @@ public class FlowDebuggerTests : IClassFixture<FlowDebuggerFixture>
        Assert.DoesNotContain(consoleErrors, e => e.Contains("JSInterop", StringComparison.OrdinalIgnoreCase));
    }

+    /// <summary>Verifies that a live run of a call script from the script entry completes in the browser.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task ScriptEntry_LiveRunOfACallScript_InBrowser_Completes()
    {
@@ -151,6 +160,8 @@ public class FlowDebuggerTests : IClassFixture<FlowDebuggerFixture>
        Assert.DoesNotContain(consoleErrors, e => e.Contains("JSInterop", StringComparison.OrdinalIgnoreCase));
    }

+    /// <summary>Verifies that selecting a write-kind script shows the value field for its trigger attribute.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task ScriptEntry_WriteKindScript_ShowsTheValueFieldForTheTriggerAttribute()
    {
@@ -27,10 +27,15 @@ public sealed class InstanceConfigureFixture : IAsyncLifetime
 {
    private const string SiteAIdentifier = "site-a";

+    /// <summary>Gets the database id of the site-a site resolved for the fixture.</summary>
    public int SiteAId { get; private set; }
+    /// <summary>Gets the id of the fixture template.</summary>
    public int TemplateId { get; private set; }
+    /// <summary>Gets the id of the fixture data connection.</summary>
    public int ConnectionId { get; private set; }
+    /// <summary>Gets the id of the fixture area.</summary>
    public int AreaId { get; private set; }
+    /// <summary>Gets the id of the fixture instance.</summary>
    public int InstanceId { get; private set; }

    /// <summary>The single bindable/overridable attribute name on the fixture template.</summary>
@@ -57,8 +62,11 @@ public sealed class InstanceConfigureFixture : IAsyncLifetime
    /// <summary>The fixture data-connection name (for locating it in the bindings UI dropdown).</summary>
    public string ConnectionName { get; private set; } = string.Empty;

+    /// <summary>Gets a value indicating whether the live cluster was reachable and the fixture data was created.</summary>
    public bool Available { get; private set; }

+    /// <summary>Checks cluster availability and creates the fixture site, template, connection, area and instance.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task InitializeAsync()
    {
        Available = await ClusterAvailability.IsAvailableAsync();
@@ -95,6 +103,8 @@ public sealed class InstanceConfigureFixture : IAsyncLifetime
        }
    }

+    /// <summary>Releases the resources held by this fixture asynchronously.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task DisposeAsync()
    {
        if (!Available)
@@ -29,12 +29,17 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    private readonly PlaywrightFixture _fixture;
    private readonly InstanceConfigureFixture _cfg;

+    /// <summary>Initializes the tests with the shared Playwright and instance configuration fixtures.</summary>
+    /// <param name="fixture">The shared Playwright browser fixture.</param>
+    /// <param name="cfg">The fixture that provides the instance under test.</param>
    public InstanceConfigureTests(PlaywrightFixture fixture, InstanceConfigureFixture cfg)
    {
        _fixture = fixture;
        _cfg = cfg;
    }

+    /// <summary>Verifies that binding all attributes through the bulk select saves and persists the bindings.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task BindAllAttributes_SavesAndPersists()
    {
@@ -81,6 +86,7 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    /// exactly one toast, then verifies the override persisted via a CLI <c>instance get</c>
    /// read-back (not just the toast).
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task SaveOverride_RoundTrips()
    {
@@ -124,6 +130,7 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    /// mutates the shared fixture instance's area, but is independent of the other tests (each
    /// gets a fresh page and asserts only on its own effect).
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task SetArea_RoundTrips()
    {
@@ -156,6 +163,7 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    /// page's error alert (<c>data-test='instance-error-alert'</c>) carrying the
    /// <c>$"Instance #{Id} not found."</c> message built in <c>InstanceConfigure.OnInitializedAsync</c>.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task NotFoundInstance_ShowsErrorAlert()
    {
@@ -191,6 +199,7 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    /// <c>finally</c>, leaving the instance override-free as found.
    /// </para>
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task AlarmOverride_SetPriority_ThenClear_RoundTrips()
    {
@@ -265,6 +274,7 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    /// is intentionally left blank so the only delta is the setpoint.
    /// </para>
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task AlarmOverride_HiLoSetpoint_Merges()
    {
@@ -323,6 +333,7 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    /// per-key diff. ValueMatch / RangeViolation / RateOfChange overrides whole-replace the inherited
    /// trigger config (unlike HiLo, which merges).
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task AlarmOverride_NonHiLo_WholeReplaces()
    {
@@ -384,6 +395,7 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    /// branch in <c>SaveOverrideFromModal</c> that fires before any server round-trip.
    /// </para>
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task AlarmOverride_InvalidValue_ShowsError_StaysOpen()
    {
@@ -431,6 +443,7 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    /// gone), no toast/badge appears, and CLI read-back confirms NO override was written for the alarm
    /// — the in-flight edit was discarded.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task AlarmOverride_Cancel_DiscardsChanges()
    {
@@ -474,6 +487,7 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    /// own clear path (distinct from the row-level Clear button covered by
    /// <see cref="AlarmOverride_SetPriority_ThenClear_RoundTrips"/>).
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task AlarmOverride_ClearFromModal_RemovesOverride()
    {
@@ -537,6 +551,7 @@ public sealed class InstanceConfigureTests : IClassFixture<InstanceConfigureFixt
    /// <c>finally</c>, exactly as <see cref="AlarmOverride_SetPriority_ThenClear_RoundTrips"/> does.
    /// </para>
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task AlarmOverride_MesReportable_RoundTrips()
    {
@@ -71,12 +71,17 @@ public class TopologyAreaTests : IClassFixture<DeploymentFixture>
    private readonly PlaywrightFixture _pw;
    private readonly DeploymentFixture _cluster;

+    /// <summary>Initializes the test class with the Playwright and deployment cluster fixtures.</summary>
+    /// <param name="pw">The Playwright browser fixture.</param>
+    /// <param name="cluster">The deployment cluster fixture.</param>
    public TopologyAreaTests(PlaywrightFixture pw, DeploymentFixture cluster)
    {
        _pw = pw;
        _cluster = cluster;
    }

+    /// <summary>Verifies that an area created from the toolbar appears in the topology tree and persists.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task CreateArea_ViaToolbar_AppearsInTreeAndPersists()
    {
@@ -114,6 +119,8 @@ public class TopologyAreaTests : IClassFixture<DeploymentFixture>
        }
    }

+    /// <summary>Verifies that pressing Enter while renaming an area commits and persists the new name.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task RenameArea_EnterCommits_PersistsNewName()
    {
@@ -153,6 +160,8 @@ public class TopologyAreaTests : IClassFixture<DeploymentFixture>
        }
    }

+    /// <summary>Verifies that pressing Escape while renaming an area reverts to the original label.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task RenameArea_Escape_RevertsToOriginalLabel()
    {
@@ -183,6 +192,8 @@ public class TopologyAreaTests : IClassFixture<DeploymentFixture>
        }
    }

+    /// <summary>Verifies that moving an area under another area shows a moved toast.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task MoveArea_UnderAnotherArea_ShowsMovedToast()
    {
@@ -221,6 +232,8 @@ public class TopologyAreaTests : IClassFixture<DeploymentFixture>
        }
    }

+    /// <summary>Verifies that moving an instance to an area shows a moved toast.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task MoveInstance_ToArea_ShowsMovedToast()
    {
@@ -255,6 +268,8 @@ public class TopologyAreaTests : IClassFixture<DeploymentFixture>
        }
    }

+    /// <summary>Verifies that the diff action on a deployed instance opens the diff dialog.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [SkippableFact]
    public async Task Diff_OnDeployedInstance_OpensDialog()
    {