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
@@ -8,7 +8,7 @@ using ZB.MOM.WW.ScadaBridge.CLI.Commands;
|
||||
namespace ZB.MOM.WW.ScadaBridge.CLI.Tests.Commands;
|
||||
|
||||
/// <summary>
|
||||
/// Tests for the <c>scadabridge audit query</c> subcommand (Audit Log #23 M8-T2):
|
||||
/// Tests for the <c>scadabridge audit query</c> subcommand:
|
||||
/// time-spec resolution, query-string construction, formatter selection, error
|
||||
/// handling, and keyset-cursor paging via <c>--all</c>.
|
||||
/// </summary>
|
||||
@@ -17,6 +17,7 @@ public class AuditQueryCommandTests
|
||||
{
|
||||
// ---- Time-spec parsing -------------------------------------------------
|
||||
|
||||
/// <summary>Verifies that a relative hours time spec resolves to the current time minus that offset.</summary>
|
||||
[Fact]
|
||||
public void ResolveTimeSpec_RelativeHours_ResolvesToNowMinusOffset()
|
||||
{
|
||||
@@ -25,6 +26,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal(DateTimeOffset.Parse("2026-05-20T11:00:00Z"), resolved);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a relative days time spec resolves to the current time minus that offset.</summary>
|
||||
[Fact]
|
||||
public void ResolveTimeSpec_RelativeDays_ResolvesToNowMinusOffset()
|
||||
{
|
||||
@@ -33,6 +35,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal(DateTimeOffset.Parse("2026-05-13T12:00:00Z"), resolved);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an absolute ISO 8601 time spec is parsed verbatim.</summary>
|
||||
[Fact]
|
||||
public void ResolveTimeSpec_AbsoluteIso8601_ParsedVerbatim()
|
||||
{
|
||||
@@ -41,6 +44,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal(DateTimeOffset.Parse("2026-01-02T03:04:05Z"), resolved);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an unparseable time spec throws.</summary>
|
||||
[Fact]
|
||||
public void ResolveTimeSpec_Garbage_Throws()
|
||||
{
|
||||
@@ -50,6 +54,7 @@ public class AuditQueryCommandTests
|
||||
|
||||
// ---- Query string construction ----------------------------------------
|
||||
|
||||
/// <summary>Verifies that a fully populated flag set produces the expected query-string parameters.</summary>
|
||||
[Fact]
|
||||
public void BuildQueryString_FullFlagSet_ProducesExpectedParameters()
|
||||
{
|
||||
@@ -90,6 +95,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal("2026-05-20T12:00:00.0000000+00:00", parsed["toUtc"]);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the errors-only flag maps to the failed status filter.</summary>
|
||||
[Fact]
|
||||
public void BuildQueryString_ErrorsOnly_MapsToFailedStatus()
|
||||
{
|
||||
@@ -100,6 +106,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal("Failed", parsed["status"]);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a multi-value channel filter emits one query key per value.</summary>
|
||||
[Fact]
|
||||
public void BuildQueryString_MultiValueChannel_EmitsOneKeyPerValue()
|
||||
{
|
||||
@@ -119,6 +126,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal(new[] { "site-1", "site-2" }, parsed.GetValues("sourceSiteId"));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the errors-only flag overrides any explicit status values.</summary>
|
||||
[Fact]
|
||||
public void BuildQueryString_ErrorsOnly_OverridesExplicitStatusValues()
|
||||
{
|
||||
@@ -137,6 +145,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal(new[] { "Failed" }, parsed.GetValues("status"));
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the paging cursor is appended after the filter parameters.</summary>
|
||||
[Fact]
|
||||
public void BuildQueryString_Cursor_AppendsAfterParameters()
|
||||
{
|
||||
@@ -149,6 +158,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal("2026-05-20T10:00:00.0000000+00:00", parsed["afterOccurredAtUtc"]);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that unset filters are omitted from the query string.</summary>
|
||||
[Fact]
|
||||
public void BuildQueryString_OmitsUnsetFilters()
|
||||
{
|
||||
@@ -165,6 +175,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal("100", parsed["pageSize"]);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an execution id filter emits the execution id parameter.</summary>
|
||||
[Fact]
|
||||
public void BuildQueryString_ExecutionId_EmitsExecutionIdParameter()
|
||||
{
|
||||
@@ -176,6 +187,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal("11111111-1111-1111-1111-111111111111", parsed["executionId"]);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a parent execution id filter emits the parent execution id parameter.</summary>
|
||||
[Fact]
|
||||
public void BuildQueryString_ParentExecutionId_EmitsParentExecutionIdParameter()
|
||||
{
|
||||
@@ -192,13 +204,17 @@ public class AuditQueryCommandTests
|
||||
private sealed class RecordingHandler : HttpMessageHandler
|
||||
{
|
||||
private readonly Queue<string> _bodies;
|
||||
/// <summary>The request URIs received by the handler, in order.</summary>
|
||||
public List<string> RequestUris { get; } = new();
|
||||
|
||||
/// <summary>Creates a handler that replies with the given JSON bodies in sequence.</summary>
|
||||
/// <param name="bodies">The response bodies to return, one per request.</param>
|
||||
public RecordingHandler(params string[] bodies)
|
||||
{
|
||||
_bodies = new Queue<string>(bodies);
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
protected override Task<HttpResponseMessage> SendAsync(
|
||||
HttpRequestMessage request, CancellationToken cancellationToken)
|
||||
{
|
||||
@@ -211,6 +227,8 @@ public class AuditQueryCommandTests
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a single page of results is written as JSON lines.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task RunQuery_SinglePage_WritesEventsAsJsonLines()
|
||||
{
|
||||
@@ -231,6 +249,8 @@ public class AuditQueryCommandTests
|
||||
Assert.Single(handler.RequestUris);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the all flag follows the next cursor across pages.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task RunQuery_WithAll_FollowsNextCursorAcrossPages()
|
||||
{
|
||||
@@ -251,6 +271,8 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal(2, lines.Length);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that without the all flag only the first page is fetched even when a cursor is present.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task RunQuery_WithoutAll_StopsAfterFirstPageEvenWhenCursorPresent()
|
||||
{
|
||||
@@ -267,6 +289,8 @@ public class AuditQueryCommandTests
|
||||
Assert.Single(handler.RequestUris);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a server error returns a non-zero exit code.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task RunQuery_ServerError_ReturnsNonZeroExit()
|
||||
{
|
||||
@@ -281,12 +305,14 @@ public class AuditQueryCommandTests
|
||||
Assert.NotEqual(0, exit);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an HTTP 403 response returns exit code 2.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task RunQuery_Http403_ReturnsExitCode2()
|
||||
{
|
||||
// CLI-018: an authorization failure on /api/audit/query (HTTP 403) must
|
||||
// An authorization failure on /api/audit/query (HTTP 403) must
|
||||
// produce exit code 2 per the documented CLI exit-code contract — the
|
||||
// legacy bare-1 return masked auth failures as generic command failures.
|
||||
// legacy bare exit code 1 return masked auth failures as generic command failures.
|
||||
var handler = new StatusHandler(HttpStatusCode.Forbidden, "{\"error\":\"nope\",\"code\":\"UNAUTHORIZED\"}");
|
||||
var client = new ManagementHttpClient(new HttpClient(handler), "http://localhost:9001", "u", "p");
|
||||
var output = new StringWriter();
|
||||
@@ -298,11 +324,13 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal(2, exit);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that an UNAUTHORIZED error code on a status other than 403 returns exit code 2.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task RunQuery_UnauthorizedCodeOnNon403_ReturnsExitCode2()
|
||||
{
|
||||
// The server may signal authorization failure via the error code on a
|
||||
// non-403 status (e.g. 400 + code=UNAUTHORIZED). Honour both channels.
|
||||
// status other than 403 (e.g. 400 + code=UNAUTHORIZED). Honour both channels.
|
||||
var handler = new StatusHandler(HttpStatusCode.BadRequest, "{\"error\":\"nope\",\"code\":\"UNAUTHORIZED\"}");
|
||||
var client = new ManagementHttpClient(new HttpClient(handler), "http://localhost:9001", "u", "p");
|
||||
var output = new StringWriter();
|
||||
@@ -314,10 +342,12 @@ public class AuditQueryCommandTests
|
||||
Assert.Equal(2, exit);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a generic server error returns exit code 1.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task RunQuery_GenericServerError_ReturnsExitCode1()
|
||||
{
|
||||
// Authentication / internal errors (non-403, no auth code) must remain
|
||||
// Authentication / internal errors (status other than 403, no auth code) must remain
|
||||
// exit code 1 — exit 2 is reserved for authorization failures.
|
||||
var handler = new StatusHandler(HttpStatusCode.InternalServerError, "{\"error\":\"boom\",\"code\":\"INTERNAL\"}");
|
||||
var client = new ManagementHttpClient(new HttpClient(handler), "http://localhost:9001", "u", "p");
|
||||
@@ -332,6 +362,7 @@ public class AuditQueryCommandTests
|
||||
|
||||
private sealed class ErrorHandler : HttpMessageHandler
|
||||
{
|
||||
/// <inheritdoc />
|
||||
protected override Task<HttpResponseMessage> SendAsync(
|
||||
HttpRequestMessage request, CancellationToken cancellationToken)
|
||||
=> Task.FromResult(new HttpResponseMessage(HttpStatusCode.InternalServerError)
|
||||
@@ -344,7 +375,11 @@ public class AuditQueryCommandTests
|
||||
{
|
||||
private readonly HttpStatusCode _status;
|
||||
private readonly string _body;
|
||||
/// <summary>Creates a handler that always replies with the given status and body.</summary>
|
||||
/// <param name="status">The HTTP status code to return.</param>
|
||||
/// <param name="body">The response body to return.</param>
|
||||
public StatusHandler(HttpStatusCode status, string body) { _status = status; _body = body; }
|
||||
/// <inheritdoc />
|
||||
protected override Task<HttpResponseMessage> SendAsync(
|
||||
HttpRequestMessage request, CancellationToken cancellationToken)
|
||||
=> Task.FromResult(new HttpResponseMessage(_status) { Content = new StringContent(_body) });
|
||||
@@ -352,6 +387,7 @@ public class AuditQueryCommandTests
|
||||
|
||||
// ---- CLI parsing -------------------------------------------------------
|
||||
|
||||
/// <summary>Verifies that an unknown flag produces a parse error and a non-zero exit code.</summary>
|
||||
[Fact]
|
||||
public void Query_UnknownFlag_ProducesParseErrorAndNonZeroExit()
|
||||
{
|
||||
@@ -361,6 +397,7 @@ public class AuditQueryCommandTests
|
||||
Assert.NotEqual("", err);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the table output format is accepted.</summary>
|
||||
[Fact]
|
||||
public void Query_FormatTable_IsAccepted()
|
||||
{
|
||||
@@ -369,6 +406,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Empty(parse.Errors);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the execution id option is accepted.</summary>
|
||||
[Fact]
|
||||
public void Query_ExecutionIdOption_IsAccepted()
|
||||
{
|
||||
@@ -381,6 +419,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Empty(parse.Errors);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the parent execution id option is accepted.</summary>
|
||||
[Fact]
|
||||
public void Query_ParentExecutionIdOption_IsAccepted()
|
||||
{
|
||||
@@ -395,6 +434,7 @@ public class AuditQueryCommandTests
|
||||
|
||||
// ---- Enum-name validation (fast-fail) ----------------------------------
|
||||
|
||||
/// <summary>Verifies that a channel option using a real enum name is accepted.</summary>
|
||||
[Fact]
|
||||
public void Query_ChannelWithRealEnumName_IsAccepted()
|
||||
{
|
||||
@@ -403,6 +443,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Empty(parse.Errors);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that multiple channel values in a single token are accepted.</summary>
|
||||
[Fact]
|
||||
public void Query_MultipleChannelValues_SingleToken_AreAccepted()
|
||||
{
|
||||
@@ -412,6 +453,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Empty(parse.Errors);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that multiple channel values given by repeating the flag are accepted.</summary>
|
||||
[Fact]
|
||||
public void Query_MultipleChannelValues_RepeatedFlag_AreAccepted()
|
||||
{
|
||||
@@ -438,6 +480,9 @@ public class AuditQueryCommandTests
|
||||
// carried through to the request rather than rejected locally.
|
||||
// ========================================================================
|
||||
|
||||
/// <summary>Verifies that an unrecognised filter value is not rejected at the parse layer.</summary>
|
||||
/// <param name="option">The filter option name.</param>
|
||||
/// <param name="value">The filter value to pass.</param>
|
||||
[Theory]
|
||||
[InlineData("--channel", "OutboundApi")] // old (non-existent) name; the real enum is "ApiOutbound"
|
||||
[InlineData("--kind", "CachedCall")]
|
||||
@@ -449,6 +494,7 @@ public class AuditQueryCommandTests
|
||||
Assert.Empty(parse.Errors);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a multi-value channel filter containing one unrecognised name still parses.</summary>
|
||||
[Fact]
|
||||
public void Query_MultiValueChannel_WithOneUnrecognisedName_StillParses()
|
||||
{
|
||||
@@ -459,6 +505,9 @@ public class AuditQueryCommandTests
|
||||
Assert.Empty(parse.Errors);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a filter value in any letter case is accepted.</summary>
|
||||
/// <param name="option">The filter option name.</param>
|
||||
/// <param name="value">The filter value to pass.</param>
|
||||
[Theory]
|
||||
[InlineData("--channel", "apioutbound")]
|
||||
[InlineData("--kind", "apicall")]
|
||||
|
||||
Reference in New Issue
Block a user