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
2026-10-07 15:05:49 -04:00
parent 0ffd4bdbea
commit 513fa1aa16
998 changed files with 17896 additions and 2395 deletions
@@ -35,6 +35,7 @@ public static partial class CliRunner
/// teardown targets.
/// </summary>
/// <param name="kind">Short entity discriminator, e.g. <c>"tmpl"</c> or <c>"inst"</c>.</param>
/// <returns>The generated unique fixture name.</returns>
public static string UniqueName(string kind) =>
$"zztest-{kind}-{Guid.NewGuid().ToString("N")[..8]}";
@@ -78,6 +79,7 @@ public static partial class CliRunner
/// where <c>DataSourceReference</c> is non-empty, so an attribute that needs
/// to appear in the Connection Bindings panel MUST be created with this set.
/// </param>
/// <returns>A task that represents the asynchronous operation.</returns>
/// <exception cref="InvalidOperationException">The CLI failed.</exception>
public static async Task AddAttributeAsync(
int templateId, string name, string dataType = "Double",
@@ -112,6 +114,17 @@ public static partial class CliRunner
/// lets one helper provision both the fixture's HiLo alarm and a ValueMatch alarm
/// (<c>--match-value</c>) without a parallel helper.
/// </remarks>
/// <param name="templateId">Owning template id.</param>
/// <param name="name">Alarm name.</param>
/// <param name="triggerType">CLI alarm trigger-type token, e.g. <c>HiLo</c> or <c>ValueMatch</c>.</param>
/// <param name="priority">Alarm priority.</param>
/// <param name="attribute">Name of the monitored attribute, or null to omit it.</param>
/// <param name="hi">High setpoint, or null to omit it.</param>
/// <param name="hiHi">High-high setpoint, or null to omit it.</param>
/// <param name="lo">Low setpoint, or null to omit it.</param>
/// <param name="loLo">Low-low setpoint, or null to omit it.</param>
/// <param name="matchValue">Value to match for a ValueMatch trigger, or null to omit it.</param>
/// <returns>The id of the newly created alarm.</returns>
public static async Task<int> AddAlarmAsync(
int templateId, string name, string triggerType = "HiLo", int priority = 500,
string? attribute = null, double? hi = null, double? hiHi = null,
@@ -183,6 +196,7 @@ public static partial class CliRunner
/// the id, but teardown re-resolves defensively in case the test failed mid-flow).
/// </summary>
/// <param name="identifierPrefix">The <c>siteIdentifier</c> prefix to match.</param>
/// <returns>The ids of the matching sites.</returns>
public static async Task<IReadOnlyList<int>> ListSiteIdsByIdentifierPrefixAsync(string identifierPrefix)
{
using var doc = await RunJsonAsync("site", "list");
@@ -268,16 +282,19 @@ public static partial class CliRunner
/// <summary>Deploys an instance via <c>instance deploy</c>. Surfaces CLI errors.</summary>
/// <param name="id">Instance id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
/// <exception cref="InvalidOperationException">The CLI failed.</exception>
public static Task DeployInstanceAsync(int id) => RunInstanceVerbAsync("deploy", id);
/// <summary>Enables an instance via <c>instance enable</c>. Surfaces CLI errors.</summary>
/// <param name="id">Instance id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
/// <exception cref="InvalidOperationException">The CLI failed.</exception>
public static Task EnableInstanceAsync(int id) => RunInstanceVerbAsync("enable", id);
/// <summary>Disables an instance via <c>instance disable</c>. Surfaces CLI errors.</summary>
/// <param name="id">Instance id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
/// <exception cref="InvalidOperationException">The CLI failed.</exception>
public static Task DisableInstanceAsync(int id) => RunInstanceVerbAsync("disable", id);
@@ -286,6 +303,7 @@ public static partial class CliRunner
/// swallows any failure (the entity may already be gone).
/// </summary>
/// <param name="id">Instance id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public static Task DeleteInstanceAsync(int id) => BestEffortAsync("instance", "delete", id);
/// <summary>
@@ -293,6 +311,7 @@ public static partial class CliRunner
/// swallows any failure.
/// </summary>
/// <param name="id">Template id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public static Task DeleteTemplateAsync(int id) => BestEffortAsync("template", "delete", id);
/// <summary>
@@ -309,6 +328,7 @@ public static partial class CliRunner
/// The inline try/catch is kept here deliberately — if you need to fix teardown
/// logic, update both this method and any other three-word deletes together.
/// </remarks>
/// <returns>A task that represents the asynchronous operation.</returns>
public static async Task DeleteAreaAsync(int id)
{
try
@@ -374,11 +394,17 @@ public static partial class CliRunner
/// any failure.
/// </summary>
/// <param name="id">Site id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public static Task DeleteSiteAsync(int id) => BestEffortAsync("site", "delete", id);
/// <summary>
/// Creates a data connection on a site via <c>data-connection create</c> and returns its new <c>id</c>.
/// </summary>
/// <param name="siteId">Owning site id.</param>
/// <param name="name">Data connection name.</param>
/// <param name="protocol">Protocol token, e.g. <c>OpcUa</c>.</param>
/// <param name="primaryConfig">Optional primary configuration JSON.</param>
/// <returns>The id of the newly created data connection.</returns>
public static async Task<int> CreateDataConnectionAsync(int siteId, string name, string protocol = "OpcUa", string? primaryConfig = null)
{
var inv = System.Globalization.CultureInfo.InvariantCulture;
@@ -400,12 +426,18 @@ public static partial class CliRunner
}
/// <summary>Best-effort delete of a data connection via <c>data-connection delete</c> for teardown.</summary>
/// <param name="id">Data connection id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public static Task DeleteDataConnectionAsync(int id) => BestEffortAsync("data-connection", "delete", id);
/// <summary>
/// Creates an inbound API method via <c>api-method create</c> (so it appears as a checkbox in the
/// API-key form) and returns its new <c>id</c>.
/// </summary>
/// <param name="name">API method name.</param>
/// <param name="script">Method script body.</param>
/// <param name="parameters">Optional parameter definitions JSON.</param>
/// <returns>The id of the newly created API method.</returns>
public static async Task<int> CreateApiMethodAsync(string name, string script = "return null;", string? parameters = null)
{
var args = new List<string> { "api-method", "create", "--name", name, "--script", script };
@@ -420,6 +452,8 @@ public static partial class CliRunner
}
/// <summary>Best-effort delete of an API method via <c>api-method delete</c> for teardown.</summary>
/// <param name="id">API method id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public static Task DeleteApiMethodAsync(int id) => BestEffortAsync("api-method", "delete", id);
/// <summary>
@@ -452,6 +486,8 @@ public static partial class CliRunner
/// Resolves an API key's opaque string <c>keyId</c> from its display name via
/// <c>security api-key list</c>; returns <see langword="null"/> if no key matches.
/// </summary>
/// <param name="name">The key display name to look up.</param>
/// <returns>The key's opaque <c>keyId</c>, or <see langword="null"/> if no key matches.</returns>
public static async Task<string?> ResolveApiKeyIdByNameAsync(string name)
{
using var doc = await RunJsonAsync("security", "api-key", "list");
@@ -477,6 +513,8 @@ public static partial class CliRunner
/// Best-effort delete of an API key via <c>security api-key delete --key-id</c> for teardown.
/// The key id is an opaque string, so this cannot use the int-based <see cref="BestEffortAsync"/>.
/// </summary>
/// <param name="keyId">The opaque API key id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public static async Task DeleteApiKeyAsync(string keyId)
{
try
@@ -499,6 +537,8 @@ public static partial class CliRunner
/// scalars). The caller OWNS it and MUST wrap the call in <c>using var doc = …</c>; the
/// <c>Document</c> suffix is the signal that this returns a disposable resource, not plain data.
/// </remarks>
/// <param name="id">Instance id.</param>
/// <returns>A task whose result is the instance document; the caller owns it and must dispose it.</returns>
public static Task<JsonDocument> GetInstanceDocumentAsync(int id) =>
RunJsonAsync("instance", "get", "--id", id.ToString(System.Globalization.CultureInfo.InvariantCulture));
@@ -507,6 +547,7 @@ public static partial class CliRunner
/// <paramref name="prefix"/>, via <c>template list</c>.
/// </summary>
/// <param name="prefix">Name prefix to filter by (ordinal comparison).</param>
/// <returns>The ids of the matching templates.</returns>
public static async Task<IReadOnlyList<int>> ListTemplateIdsByNamePrefixAsync(string prefix)
{
using var doc = await RunJsonAsync("template", "list");
@@ -535,6 +576,7 @@ public static partial class CliRunner
/// <param name="name">External system name (typically from <see cref="UniqueName"/>).</param>
/// <param name="endpointUrl">Endpoint base URL (defaults to an unreachable placeholder).</param>
/// <param name="authType">Auth type token; one of <c>ApiKey</c> or <c>BasicAuth</c>.</param>
/// <returns>The id of the newly created external system.</returns>
/// <exception cref="InvalidOperationException">
/// The CLI failed, or the response did not carry an integer <c>id</c>.
/// </exception>
@@ -552,6 +594,7 @@ public static partial class CliRunner
/// </summary>
/// <param name="name">Notification list name (typically from <see cref="UniqueName"/>).</param>
/// <param name="emails">Comma-separated recipient emails.</param>
/// <returns>The id of the newly created notification list.</returns>
/// <exception cref="InvalidOperationException">
/// The CLI failed, or the response did not carry an integer <c>id</c>.
/// </exception>
@@ -566,6 +609,7 @@ public static partial class CliRunner
/// </summary>
/// <param name="name">Shared script name (typically from <see cref="UniqueName"/>).</param>
/// <param name="code">Script body.</param>
/// <returns>The id of the newly created shared script.</returns>
/// <exception cref="InvalidOperationException">
/// The CLI failed, or the response did not carry an integer <c>id</c>.
/// </exception>
@@ -586,6 +630,7 @@ public static partial class CliRunner
/// <param name="id">Shared script id.</param>
/// <param name="name">Shared script name (unchanged; the CLI requires it).</param>
/// <param name="code">The new script body.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
/// <exception cref="InvalidOperationException">The CLI failed.</exception>
public static async Task UpdateSharedScriptCodeAsync(int id, string name, string code)
{
@@ -601,6 +646,7 @@ public static partial class CliRunner
/// </summary>
/// <param name="ldapGroup">LDAP group name to map (typically from <see cref="UniqueName"/>).</param>
/// <param name="role">Role to grant members of the group; defaults to <c>Designer</c>.</param>
/// <returns>The id of the newly created role mapping.</returns>
/// <exception cref="InvalidOperationException">
/// The CLI failed, or the response did not carry an integer <c>id</c>.
/// </exception>
@@ -618,6 +664,7 @@ public static partial class CliRunner
/// external system a test created through the UI (where the new id is never surfaced).
/// </summary>
/// <param name="prefix">Name prefix to filter by (ordinal comparison).</param>
/// <returns>The ids of the matching external systems.</returns>
public static async Task<IReadOnlyList<int>> ListExternalSystemIdsByNamePrefixAsync(string prefix)
{
using var doc = await RunJsonAsync("external-system", "list");
@@ -630,6 +677,7 @@ public static partial class CliRunner
/// notification list a test created through the UI (where the new id is never surfaced).
/// </summary>
/// <param name="prefix">Name prefix to filter by (ordinal comparison).</param>
/// <returns>The ids of the matching notification lists.</returns>
public static async Task<IReadOnlyList<int>> ListNotificationListIdsByNamePrefixAsync(string prefix)
{
using var doc = await RunJsonAsync("notification", "list");
@@ -637,12 +685,18 @@ public static partial class CliRunner
}
/// <summary>Best-effort delete of an external system via <c>external-system delete</c> for teardown.</summary>
/// <param name="id">External system id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public static Task DeleteExternalSystemAsync(int id) => BestEffortAsync("external-system", "delete", id);
/// <summary>Best-effort delete of a notification list via <c>notification delete</c> for teardown.</summary>
/// <param name="id">Notification list id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public static Task DeleteNotificationListAsync(int id) => BestEffortAsync("notification", "delete", id);
/// <summary>Best-effort delete of a shared script via <c>shared-script delete</c> for teardown.</summary>
/// <param name="id">Shared script id.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public static Task DeleteSharedScriptAsync(int id) => BestEffortAsync("shared-script", "delete", id);
/// <summary>
@@ -667,6 +721,7 @@ public static partial class CliRunner
/// <see cref="DeleteAreaAsync"/>, <see cref="DeleteInstanceAlarmOverrideAsync"/>, and this method.
/// </para>
/// </remarks>
/// <returns>A task that represents the asynchronous operation.</returns>
public static async Task DeleteRoleMappingAsync(int id)
{
try
@@ -682,6 +737,9 @@ public static partial class CliRunner
}
/// <summary>Best-effort delete of an instance alarm override (teardown). Never throws.</summary>
/// <param name="instanceId">Instance id.</param>
/// <param name="alarmCanonicalName">Canonical name of the alarm whose override is removed.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public static async Task DeleteInstanceAlarmOverrideAsync(int instanceId, string alarmCanonicalName)
{
var inv = System.Globalization.CultureInfo.InvariantCulture;
@@ -711,6 +769,7 @@ public static partial class CliRunner
/// <param name="sourceEnvironment">
/// <c>SourceEnvironment</c> value stamped into the bundle manifest.
/// </param>
/// <returns>A task that represents the asynchronous operation.</returns>
/// <exception cref="InvalidOperationException">
/// The template id could not be resolved to a name, or the CLI failed.
/// </exception>
@@ -748,6 +807,7 @@ public static partial class CliRunner
/// <param name="siteIdentifier">The <c>SiteIdentifier</c> of the single site to export.</param>
/// <param name="passphrase">Encryption passphrase for the bundle.</param>
/// <param name="sourceEnvironment"><c>SourceEnvironment</c> value stamped into the bundle manifest.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
/// <exception cref="InvalidOperationException">The CLI failed.</exception>
public static async Task BundleExportSiteAsync(
string outputPath, string siteIdentifier, string passphrase, string sourceEnvironment)
@@ -771,6 +831,7 @@ public static partial class CliRunner
/// <param name="sharedScriptName">Name of the single shared script to export.</param>
/// <param name="passphrase">Encryption passphrase for the bundle.</param>
/// <param name="sourceEnvironment"><c>SourceEnvironment</c> value stamped into the bundle manifest.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
/// <exception cref="InvalidOperationException">
/// The shared-script name contains a comma (it would split the comma-separated
/// <c>--shared-scripts</c> selector), or the CLI failed.
@@ -62,6 +62,8 @@ public static partial class CliRunner
/// stdout. The connection flags (<c>--url</c>, <c>--username</c>,
/// <c>--password</c>, <c>--format json</c>) are prepended automatically.
/// </summary>
/// <param name="args">The CLI arguments to pass after the connection flags.</param>
/// <returns>The raw standard output of the CLI invocation.</returns>
/// <exception cref="TimeoutException">
/// The invocation exceeded the 60-second timeout; the process tree is killed.
/// </exception>
@@ -135,6 +137,8 @@ public static partial class CliRunner
/// as a <see cref="JsonDocument"/>. The caller owns the returned document and
/// must dispose it.
/// </summary>
/// <param name="args">The CLI arguments to pass after the connection flags.</param>
/// <returns>The parsed JSON output of the CLI invocation.</returns>
public static async Task<JsonDocument> RunJsonAsync(params string[] args) =>
JsonDocument.Parse(await RunAsync(args));
@@ -18,6 +18,7 @@ public class CliRunnerHelpersTests
/// <see cref="CliRunner.ListTemplateIdsByNamePrefixAsync"/>, and
/// <see cref="CliRunner.DeleteTemplateAsync"/> as a round-trip.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task CreateThenDeleteTemplate_RoundTrips()
{
@@ -37,6 +38,7 @@ public class CliRunnerHelpersTests
/// <c>site-a</c> seed site by its <c>siteIdentifier</c> and returns a
/// positive id.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task ResolveSiteA_ReturnsId()
{
@@ -49,6 +51,7 @@ public class CliRunnerHelpersTests
/// deleted in teardown, exercising <see cref="CliRunner.CreateDataConnectionAsync"/>
/// and <see cref="CliRunner.DeleteDataConnectionAsync"/> as a round-trip.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task CreateThenDeleteDataConnection_RoundTrips()
{
@@ -70,6 +73,7 @@ public class CliRunnerHelpersTests
/// teardown, exercising <see cref="CliRunner.CreateApiMethodAsync"/> and
/// <see cref="CliRunner.DeleteApiMethodAsync"/> as a round-trip.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task CreateThenDeleteApiMethod_RoundTrips()
{
@@ -93,6 +97,7 @@ public class CliRunnerHelpersTests
/// <see cref="CliRunner.ListAreaIdsByNamePrefixAsync"/>, and
/// <see cref="CliRunner.DeleteAreaAsync"/>.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task ListAreaIdsByNamePrefix_FindsCreatedArea()
{
@@ -118,6 +123,7 @@ public class CliRunnerHelpersTests
/// <see cref="CliRunner.ListExternalSystemIdsByNamePrefixAsync"/>, and
/// <see cref="CliRunner.DeleteExternalSystemAsync"/> as a round-trip.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task CreateThenDeleteExternalSystem_RoundTrips()
{
@@ -138,6 +144,7 @@ public class CliRunnerHelpersTests
/// <see cref="CliRunner.ListNotificationListIdsByNamePrefixAsync"/>, and
/// <see cref="CliRunner.DeleteNotificationListAsync"/> as a round-trip.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task CreateThenDeleteNotificationList_RoundTrips()
{
@@ -157,6 +164,7 @@ public class CliRunnerHelpersTests
/// teardown, exercising <see cref="CliRunner.CreateSharedScriptAsync"/> and
/// <see cref="CliRunner.DeleteSharedScriptAsync"/> as a round-trip.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task CreateThenDeleteSharedScript_RoundTrips()
{
@@ -172,6 +180,7 @@ public class CliRunnerHelpersTests
/// teardown, exercising <see cref="CliRunner.CreateRoleMappingAsync"/> and
/// <see cref="CliRunner.DeleteRoleMappingAsync"/> as a round-trip.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task CreateThenDeleteRoleMapping_RoundTrips()
{
@@ -194,6 +203,7 @@ public class CliRunnerHelpersTests
/// <see cref="CliRunner.AddAlarmAsync"/> with <c>--hi</c>/<c>--hihi</c> returns a
/// positive id, confirming the server accepted the serialized trigger-config JSON.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task AddAlarmWithTypedFlags_RoundTrips()
{
@@ -18,6 +18,7 @@ public class CliRunnerSmokeTests
/// <c>scadabridge site list</c> round-trips through the CLI and returns a
/// JSON document (the CLI emits a JSON array of sites in <c>--format json</c>).
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task SiteList_ReturnsJson()
{
@@ -5,7 +5,7 @@ namespace ZB.MOM.WW.ScadaBridge.CentralUI.PlaywrightTests.Cluster;
/// reachable through the CLI. State-changing E2E tests gate their setup on this so
/// a downed cluster surfaces as a Skipped fact (via <c>Skip.IfNot</c>) rather than
/// an opaque failure. The result is cached for the process; <see cref="SkippedCount"/>
/// is bumped each time a test would skip and is logged at suite teardown (Task 3).
/// is bumped each time a test would skip and is logged at suite teardown.
/// </summary>
public static class ClusterAvailability
{
@@ -18,7 +18,7 @@ public static class ClusterAvailability
/// <summary>
/// Number of times a test would have skipped because the cluster is
/// unavailable. Incremented on every <see cref="IsAvailableAsync"/> call that
/// returns <see langword="false"/>; logged at suite teardown (Task 3).
/// returns <see langword="false"/>; logged at suite teardown.
/// </summary>
public static int SkippedCount;
@@ -26,6 +26,7 @@ public static class ClusterAvailability
/// Returns whether the cluster is reachable, probing once (a <c>site list</c>
/// round-trip through the CLI) and caching the result for the process.
/// </summary>
/// <returns><see langword="true"/> when the cluster is reachable; otherwise <see langword="false"/>.</returns>
public static async Task<bool> IsAvailableAsync()
{
if (_cached is { } cached)
@@ -7,10 +7,11 @@ namespace ZB.MOM.WW.ScadaBridge.CentralUI.PlaywrightTests.Cluster;
/// line reporting how many cluster/DB-dependent test gates skipped because the
/// cluster was unavailable (see <see cref="ClusterAvailability.SkippedCount"/>).
/// Registered once via a <see cref="ModuleInitializerAttribute"/> so it runs
/// regardless of how the test host is launched (Task 3).
/// regardless of how the test host is launched.
/// </summary>
internal static class SkipSummaryReporter
{
/// <summary>Registers the skip-summary hook that runs when the process exits.</summary>
[ModuleInitializer]
internal static void Init() =>
AppDomain.CurrentDomain.ProcessExit += (_, _) =>