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
@@ -14,7 +14,7 @@ using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
|
||||
namespace ZB.MOM.WW.ScadaBridge.InboundAPI.Tests;
|
||||
|
||||
/// <summary>
|
||||
/// Flow Debugger outbound calls (plan 2026-09-06, Task 4 / D7): every
|
||||
/// Flow Debugger outbound calls (plan 2026-09-06, D7): every
|
||||
/// <see cref="InboundDatabaseHelper"/> call made by a central method script writes ONE
|
||||
/// <c>DbOutbound.DbWrite</c> row through <see cref="ICentralAuditWriter"/> — best-effort,
|
||||
/// never into the script — using the site's <c>AuditingDbCommand</c> vocabulary
|
||||
@@ -32,6 +32,7 @@ public class InboundDatabaseHelperAuditTests
|
||||
private readonly string _cs = $"DataSource=file:dbaudit-{Guid.NewGuid():N}?mode=memory&cache=shared";
|
||||
private readonly SqliteConnection _keepAlive;
|
||||
|
||||
/// <summary>Opens the keep-alive connection and seeds the Machine table.</summary>
|
||||
public SqliteGateway()
|
||||
{
|
||||
_keepAlive = new SqliteConnection(_cs);
|
||||
@@ -41,8 +42,10 @@ public class InboundDatabaseHelperAuditTests
|
||||
cmd.ExecuteNonQuery();
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
public async Task<DbConnection> GetConnectionAsync(string name, CancellationToken ct = default)
|
||||
{ var c = new SqliteConnection(_cs); await c.OpenAsync(ct); return c; }
|
||||
/// <inheritdoc />
|
||||
public Task<ExternalCallResult> CachedWriteAsync(string c, string s,
|
||||
IReadOnlyDictionary<string, object?>? p = null, string? o = null, CancellationToken ct = default,
|
||||
TrackedOperationId? t = null, Guid? e = null, string? src = null, Guid? pe = null)
|
||||
@@ -51,8 +54,10 @@ public class InboundDatabaseHelperAuditTests
|
||||
|
||||
private sealed class ThrowingGateway : IDatabaseGateway
|
||||
{
|
||||
/// <inheritdoc />
|
||||
public Task<DbConnection> GetConnectionAsync(string name, CancellationToken ct = default)
|
||||
=> throw new InvalidOperationException("no such connection: " + name);
|
||||
/// <inheritdoc />
|
||||
public Task<ExternalCallResult> CachedWriteAsync(string c, string s,
|
||||
IReadOnlyDictionary<string, object?>? p = null, string? o = null, CancellationToken ct = default,
|
||||
TrackedOperationId? t = null, Guid? e = null, string? src = null, Guid? pe = null)
|
||||
@@ -66,11 +71,26 @@ public class InboundDatabaseHelperAuditTests
|
||||
/// </summary>
|
||||
private sealed class RecordingLogger : ILogger
|
||||
{
|
||||
/// <summary>Gets the log entries recorded so far.</summary>
|
||||
public List<(LogLevel Level, string Message, Exception? Exception)> Entries { get; } = new();
|
||||
|
||||
/// <summary>Returns no scope; scopes are not captured.</summary>
|
||||
/// <typeparam name="TState">The scope state type.</typeparam>
|
||||
/// <param name="state">The scope state (ignored).</param>
|
||||
/// <returns>Always null.</returns>
|
||||
public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
|
||||
/// <summary>Reports every log level as enabled.</summary>
|
||||
/// <param name="logLevel">The log level being queried.</param>
|
||||
/// <returns>Always true.</returns>
|
||||
public bool IsEnabled(LogLevel logLevel) => true;
|
||||
|
||||
/// <summary>Records the formatted log entry for later assertions.</summary>
|
||||
/// <typeparam name="TState">The log state type.</typeparam>
|
||||
/// <param name="logLevel">The entry's log level.</param>
|
||||
/// <param name="eventId">The entry's event id.</param>
|
||||
/// <param name="state">The entry's state.</param>
|
||||
/// <param name="exception">The exception attached to the entry, if any.</param>
|
||||
/// <param name="formatter">Formats the state and exception into the message.</param>
|
||||
public void Log<TState>(
|
||||
LogLevel logLevel, EventId eventId, TState state, Exception? exception,
|
||||
Func<TState, Exception?, string> formatter)
|
||||
@@ -87,6 +107,7 @@ public class InboundDatabaseHelperAuditTests
|
||||
private readonly Guid _exec = Guid.NewGuid();
|
||||
private readonly Guid _parent = Guid.NewGuid();
|
||||
|
||||
/// <summary>Wires the audit writer double to record written events and names the node.</summary>
|
||||
public InboundDatabaseHelperAuditTests()
|
||||
{
|
||||
_writer.WriteAsync(Arg.Do<AuditEvent>(e => _written.Add(e)), Arg.Any<CancellationToken>()).Returns(Task.CompletedTask);
|
||||
@@ -99,6 +120,8 @@ public class InboundDatabaseHelperAuditTests
|
||||
auditWriter: writer ?? _writer, nodeIdentity: _node,
|
||||
executionId: _exec, parentExecutionId: _parent, methodName: "movein", traceSink: sink);
|
||||
|
||||
/// <summary>Verifies that a successful execute writes a delivered database-write row carrying the rows-affected count.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task ExecuteAsync_WritesDbWriteDeliveredRow_WithRowsAffected()
|
||||
{
|
||||
@@ -126,6 +149,8 @@ public class InboundDatabaseHelperAuditTests
|
||||
Assert.Contains("\"@c\":\"Z28061A\"", row.RequestSummary);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a query writes a read row carrying the rows-returned count.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task QueryAsync_WritesReadRow_WithRowsReturned()
|
||||
{
|
||||
@@ -140,6 +165,8 @@ public class InboundDatabaseHelperAuditTests
|
||||
Assert.Equal("{\"op\":\"read\",\"rowsReturned\":1}", row.Extra);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a single-row query with no match writes a read row reporting zero rows returned.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task QuerySingleAsync_WritesReadRow_ZeroRowsWhenNoMatch()
|
||||
{
|
||||
@@ -152,6 +179,8 @@ public class InboundDatabaseHelperAuditTests
|
||||
Assert.Equal("{\"op\":\"read\",\"rowsReturned\":0}", row.Extra);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a gateway failure writes a failed row and the exception still reaches the script.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task ThrowingGateway_WritesFailedRow_AndRethrowsToScript()
|
||||
{
|
||||
@@ -170,6 +199,8 @@ public class InboundDatabaseHelperAuditTests
|
||||
Assert.Contains("\"sql\":\"DELETE FROM Machine\"", row.RequestSummary);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a faulting audit writer does not fail the database call.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task AuditWriterFaulting_DoesNotFailTheCall()
|
||||
{
|
||||
@@ -187,6 +218,8 @@ public class InboundDatabaseHelperAuditTests
|
||||
Assert.Equal(1, n2);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a faulting audit writer logs a warning while the call still succeeds.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task AuditWriterFaulting_LogsWarning_AndCallStillSucceeds()
|
||||
{
|
||||
@@ -213,6 +246,8 @@ public class InboundDatabaseHelperAuditTests
|
||||
Assert.Contains("MesDb", entry.Message);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the trace sink receives the same event instance before the audit writer does.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task TraceSink_ReceivesTheSameInstance_BeforeTheWriter()
|
||||
{
|
||||
@@ -226,6 +261,8 @@ public class InboundDatabaseHelperAuditTests
|
||||
Assert.Same(order[0].Evt, order[1].Evt);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a throwing trace sink does not fail the call and the writer still receives the row.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task ThrowingSink_DoesNotFailTheCall_AndWriterStillGetsTheRow()
|
||||
{
|
||||
@@ -237,6 +274,8 @@ public class InboundDatabaseHelperAuditTests
|
||||
Assert.Single(_written);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that with no writer and no sink nothing is emitted and the call still works.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task NoWriterNoSink_EmitsNothing_AndStillWorks()
|
||||
{
|
||||
@@ -248,6 +287,8 @@ public class InboundDatabaseHelperAuditTests
|
||||
Assert.Empty(_written);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the script executor passes the writer, node identity, execution id and route sink to the helper.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task Executor_WiresWriterNodeIdentityExecutionIdAndRouteSink_IntoTheHelper()
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user