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
@@ -4,6 +4,7 @@ namespace ZB.MOM.WW.ScadaBridge.DelmiaNotifier.Tests;

 public class ArgParserTests
 {
+    /// <summary>Verifies that all short flags are parsed into the payload.</summary>
    [Fact]
    public void Parses_all_flags()
    {
@@ -17,6 +18,7 @@ public class ArgParserTests
        Assert.Equal("op", r.Payload.Username);
    }

+    /// <summary>Verifies that long-form flags are parsed into the payload.</summary>
    [Fact]
    public void Parses_long_flags()
    {
@@ -26,6 +28,7 @@ public class ArgParserTests
        Assert.Equal("x", r.Payload.DownloadPath);
    }

+    /// <summary>Verifies that omitting a required flag returns an error.</summary>
    [Fact]
    public void Missing_required_returns_error()
    {
@@ -34,6 +37,7 @@ public class ArgParserTests
        Assert.Contains("partnumber", r.Error, System.StringComparison.OrdinalIgnoreCase);
    }

+    /// <summary>Verifies that optional flags may be omitted without error.</summary>
    [Fact]
    public void Optional_flags_may_be_omitted()
    {
@@ -43,6 +47,7 @@ public class ArgParserTests
        Assert.Null(r.Payload.JobStepNumber);
    }

+    /// <summary>Verifies that an unknown flag returns an error.</summary>
    [Fact]
    public void Unknown_flag_returns_error()
    {
@@ -50,6 +55,7 @@ public class ArgParserTests
        Assert.False(r.Ok);
    }

+    /// <summary>Verifies that a flag without a value returns an error.</summary>
    [Fact]
    public void Flag_without_value_returns_error()
    {
@@ -4,6 +4,8 @@ namespace ZB.MOM.WW.ScadaBridge.DelmiaNotifier.Tests;

 public class ConfigLoaderTests
 {
+    /// <summary>Verifies that invalid endpoint lists are rejected when the configuration loads.</summary>
+    /// <param name="urls">The base URL list to load.</param>
    [Theory]
    [InlineData("relative")]
    [InlineData("ftp://example.com")]
@@ -17,6 +19,7 @@ public class ConfigLoaderTests
        Assert.Contains("HTTP", error.Message);
    }

+    /// <summary>Verifies that splitting base URLs trims entries and drops empty ones.</summary>
    [Fact]
    public void SplitBaseUrls_trims_and_drops_empties()
    {
@@ -24,6 +27,7 @@ public class ConfigLoaderTests
        Assert.Equal(new[] { "a", "b", "c" }, urls);
    }

+    /// <summary>Verifies that a null or whitespace base URL list yields no URLs.</summary>
    [Fact]
    public void SplitBaseUrls_null_or_whitespace_returns_empty()
    {
@@ -31,6 +35,7 @@ public class ConfigLoaderTests
        Assert.Empty(ConfigLoader.SplitBaseUrls("   "));
    }

+    /// <summary>Verifies that the timeout defaults to 30 seconds when it is omitted.</summary>
    [Fact]
    public void Load_defaults_timeout_to_30_when_omitted()
    {
@@ -39,6 +44,7 @@ public class ConfigLoaderTests
        Assert.Equal("http://x", cfg.ScadaBridge.BaseUrls);
    }

+    /// <summary>Verifies that loading reads every configured field.</summary>
    [Fact]
    public void Load_reads_all_fields()
    {
@@ -48,6 +54,7 @@ public class ConfigLoaderTests
        Assert.Equal("l.log", cfg.ScadaBridge.LogPath);
    }

+    /// <summary>Verifies that an unset or whitespace environment key resolves to null.</summary>
    [Fact]
    public void ResolveApiKey_returns_null_when_unset_or_whitespace()
    {
@@ -55,12 +62,14 @@ public class ConfigLoaderTests
        Assert.Null(ConfigLoader.ResolveApiKey(_ => "   ", new NotifierConfig()));
    }

+    /// <summary>Verifies that a key present in the environment is returned.</summary>
    [Fact]
    public void ResolveApiKey_returns_value_when_present()
    {
        Assert.Equal("sbk_x", ConfigLoader.ResolveApiKey(n => n == "SCADABRIDGE_API_KEY" ? "sbk_x" : null, new NotifierConfig()));
    }

+    /// <summary>Verifies that the API key is read from the ScadaBridge configuration section.</summary>
    [Fact]
    public void Load_reads_ApiKey_from_ScadaBridge_section()
    {
@@ -68,6 +77,7 @@ public class ConfigLoaderTests
        Assert.Equal("sbk_file", cfg.ScadaBridge.ApiKey);
    }

+    /// <summary>Verifies that the environment key takes precedence over the configured key.</summary>
    [Fact]
    public void ResolveApiKey_prefers_env_over_config()
    {
@@ -75,6 +85,7 @@ public class ConfigLoaderTests
        Assert.Equal("sbk_env", ConfigLoader.ResolveApiKey(n => n == "SCADABRIDGE_API_KEY" ? "sbk_env" : null, cfg));
    }

+    /// <summary>Verifies that the configured key is used when the environment key is unset or blank.</summary>
    [Fact]
    public void ResolveApiKey_falls_back_to_config_when_env_unset_or_blank()
    {
@@ -83,12 +94,14 @@ public class ConfigLoaderTests
        Assert.Equal("sbk_file", ConfigLoader.ResolveApiKey(_ => "   ", cfg));
    }

+    /// <summary>Verifies that the environment key is trimmed the same way as the configured key.</summary>
    [Fact]
    public void ResolveApiKey_trims_env_value_like_the_file_value()
    {
        Assert.Equal("sbk_env", ConfigLoader.ResolveApiKey(_ => "  sbk_env \t", new NotifierConfig()));
    }

+    /// <summary>Verifies that key resolution reports whether the environment or the file supplied the key.</summary>
    [Fact]
    public void ResolveApiKey_reports_which_source_supplied_the_key()
    {
@@ -101,6 +114,7 @@ public class ConfigLoaderTests
        Assert.Null(none);
    }

+    /// <summary>Verifies that the API key stays null when the configuration omits it.</summary>
    [Fact]
    public void Load_leaves_ApiKey_null_when_absent()
    {
@@ -108,6 +122,7 @@ public class ConfigLoaderTests
        Assert.Null(cfg.ScadaBridge.ApiKey);
    }

+    /// <summary>Verifies that key resolution returns null when neither source supplies a key.</summary>
    [Fact]
    public void ResolveApiKey_returns_null_when_neither_source_set()
    {
@@ -6,6 +6,8 @@ namespace ZB.MOM.WW.ScadaBridge.DelmiaNotifier.Tests;

 public class HttpRecipeSenderTests
 {
+    /// <summary>Verifies the case: DC7, explicit Standby Refusal, tries Second Url, but Generic503 Does Not.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task DC7_ExplicitStandbyRefusal_TriesSecondUrl_ButGeneric503DoesNot()
    {
@@ -27,6 +29,8 @@ public class HttpRecipeSenderTests
        }
    }

+    /// <summary>Verifies the case: DC7, applied Then Response Lost, does Not Replay.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task DC7_AppliedThenResponseLost_DoesNotReplay()
    {
@@ -39,8 +43,10 @@ public class HttpRecipeSenderTests

    private sealed class StubHandler(Func<HttpRequestMessage, HttpResponseMessage> responder) : HttpMessageHandler
    {
+        /// <summary>Gets the last HTTP request seen by this handler.</summary>
        public HttpRequestMessage? LastRequest { get; private set; }

+        /// <inheritdoc />
        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        {
            LastRequest = request;
@@ -51,6 +57,8 @@ public class HttpRecipeSenderTests
    private static readonly RecipeDownload Payload =
        new() { MachineCode = "Z", DownloadPath = "x", WorkOrderNumber = "W", PartNumber = "P" };

+    /// <summary>Verifies the case: connect Failure, maps, to, connect Failed.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ConnectFailure_maps_to_ConnectFailed()
    {
@@ -62,6 +70,8 @@ public class HttpRecipeSenderTests
        Assert.Equal(0, outcome.StatusCode);
    }

+    /// <summary>Verifies the case: success, 200, parses, body, and, sends, header, and, path.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Success_200_parses_body_and_sends_header_and_path()
    {
@@ -80,6 +90,8 @@ public class HttpRecipeSenderTests
        Assert.Equal("http://a/api/DelmiaRecipeDownload", handler.LastRequest.RequestUri!.ToString());
    }

+    /// <summary>Verifies the case: non2xx, is, connected, with, status.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Non2xx_is_Connected_with_status()
    {
@@ -5,6 +5,7 @@ namespace ZB.MOM.WW.ScadaBridge.DelmiaNotifier.Tests;

 public class JsonContractTests
 {
+    /// <summary>Verifies that recipe download serializes pascalcase.</summary>
    [Fact]
    public void RecipeDownload_serializes_pascalcase()
    {
@@ -16,6 +17,7 @@ public class JsonContractTests
        Assert.Contains("\"DownloadPath\"", json);
    }

+    /// <summary>Verifies that recipe download result deserializes pascalcase.</summary>
    [Fact]
    public void RecipeDownloadResult_deserializes_pascalcase()
    {
@@ -7,8 +7,10 @@ public class NotifierTests
    private sealed class FakeSender(params AttemptOutcome[] outcomes) : IRecipeSender
    {
        private readonly Queue<AttemptOutcome> _outcomes = new(outcomes);
+        /// <summary>Gets the calls recorded by this fake.</summary>
        public int Calls { get; private set; }

+        /// <inheritdoc />
        public Task<AttemptOutcome> SendAsync(string baseUrl, RecipeDownload payload, CancellationToken ct)
        {
            Calls++;
@@ -20,6 +22,8 @@ public class NotifierTests
    private static readonly RecipeDownload Payload =
        new() { MachineCode = "Z", DownloadPath = "x", WorkOrderNumber = "W", PartNumber = "P" };

+    /// <summary>Verifies that a connection failure advances to the next URL.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ConnectFailure_advances_to_next_url()
    {
@@ -31,6 +35,8 @@ public class NotifierTests
        Assert.Equal(2, sender.Calls);
    }

+    /// <summary>Verifies that a connected response with a false result is final and does not fail over.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Connected_result_false_is_final_no_failover()
    {
@@ -43,6 +49,8 @@ public class NotifierTests
        Assert.Equal(1, sender.Calls);
    }

+    /// <summary>Verifies that a connected response with a 5xx status is final and does not fail over.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Connected_5xx_is_final_no_failover()
    {
@@ -55,6 +63,8 @@ public class NotifierTests
        Assert.Equal(1, sender.Calls);
    }

+    /// <summary>Verifies that when every URL fails to connect the notifier reports unreachable with the last error.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task All_connect_failures_report_unreachable_with_last_error()
    {
@@ -4,6 +4,7 @@ namespace ZB.MOM.WW.ScadaBridge.DelmiaNotifier.Tests;

 public class ReporterTests
 {
+    /// <summary>Verifies that success writes YES and returns 0.</summary>
    [Fact]
    public void Success_writes_YES_and_returns_0()
    {
@@ -13,6 +14,7 @@ public class ReporterTests
        Assert.Equal(0, code);
    }

+    /// <summary>Verifies that failure writes NO then reason and returns minus 1.</summary>
    [Fact]
    public void Failure_writes_NO_then_reason_and_returns_minus1()
    {