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
@@ -11,7 +11,7 @@ using IAuditWriter = ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services.IAuditWri
|
||||
namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests.Scripts;
|
||||
|
||||
/// <summary>
|
||||
/// Audit Log #23 — M4 Bundle A (Tasks A1+A2): every synchronous DB call made
|
||||
/// Every synchronous DB call made
|
||||
/// through <c>Database.Connection("name")</c> emits exactly one
|
||||
/// <c>DbOutbound</c>/<c>DbWrite</c> audit event with an <c>Extra</c> envelope
|
||||
/// distinguishing writes (<c>op="write"</c>, <c>rowsAffected=N</c>) from reads
|
||||
@@ -23,18 +23,21 @@ namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests.Scripts;
|
||||
public class DatabaseSyncEmissionTests
|
||||
{
|
||||
/// <summary>
|
||||
/// In-memory <see cref="IAuditWriter"/> mirroring the M2 Bundle F stub —
|
||||
/// In-memory <see cref="IAuditWriter"/> mirroring the shared audit-writer stub —
|
||||
/// captures every event and may be configured to throw to verify the
|
||||
/// 3-layer fail-safe (mirrors <c>CapturingAuditWriter</c> in
|
||||
/// <c>ExternalSystemCallAuditEmissionTests</c>).
|
||||
/// </summary>
|
||||
private sealed class CapturingAuditWriter : IAuditWriter
|
||||
{
|
||||
// C3 (Task 2.5): store the decomposed row view so assertions keep
|
||||
// Store the decomposed row view so assertions keep
|
||||
// reading the ScadaBridge domain fields as typed properties.
|
||||
/// <summary>Gets the captured audit rows.</summary>
|
||||
public List<AuditRowProjection.AuditRowValues> Events { get; } = new();
|
||||
/// <summary>Gets or sets whether the writer throws on every write.</summary>
|
||||
public Exception? ThrowOnWrite { get; set; }
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task WriteAsync(AuditEvent evt, CancellationToken ct = default)
|
||||
{
|
||||
if (ThrowOnWrite != null)
|
||||
@@ -53,7 +56,7 @@ public class DatabaseSyncEmissionTests
|
||||
private const string ConnectionName = "machineData";
|
||||
|
||||
/// <summary>
|
||||
/// Audit Log #23: a fixed per-execution id used by the default
|
||||
/// A fixed per-execution id used by the default
|
||||
/// <see cref="CreateHelper(IDatabaseGateway, IAuditWriter?)"/>
|
||||
/// overload so assertions can compare against a known value.
|
||||
/// </summary>
|
||||
@@ -116,6 +119,8 @@ public class DatabaseSyncEmissionTests
|
||||
return live;
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a successful insert emits one DbWrite event with Delivered status, a write op and the affected row count.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task Execute_InsertSuccess_EmitsOneEvent_KindDbWrite_StatusDelivered_OpWrite_RowsAffected()
|
||||
{
|
||||
@@ -147,6 +152,8 @@ public class DatabaseSyncEmissionTests
|
||||
Assert.StartsWith(ConnectionName, evt.Target);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a successful scalar execution emits a DbWrite event with a write op.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task ExecuteScalar_Success_EmitsKindDbWrite_OpWrite()
|
||||
{
|
||||
@@ -170,7 +177,7 @@ public class DatabaseSyncEmissionTests
|
||||
Assert.Equal(AuditKind.DbWrite, evt.Kind);
|
||||
Assert.Equal(AuditStatus.Delivered, evt.Status);
|
||||
Assert.NotNull(evt.Extra);
|
||||
// ExecuteScalar is classified as "write" per the M4 vocabulary lock
|
||||
// ExecuteScalar is classified as "write" per the audit vocabulary lock
|
||||
// (Channel=DbOutbound, Kind=DbWrite, Extra.op="write") — the
|
||||
// rowsAffected for a SELECT-on-SqlCommand is -1 in ADO.NET; the audit
|
||||
// wrapper records whatever DbCommand.ExecuteScalar returned via the
|
||||
@@ -179,6 +186,8 @@ public class DatabaseSyncEmissionTests
|
||||
Assert.Contains("rowsAffected", evt.Extra);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a failing execution emits an event with Failed status and the error message set.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task Execute_Throws_EmitsEvent_StatusFailed_ErrorMessageSet()
|
||||
{
|
||||
@@ -204,6 +213,8 @@ public class DatabaseSyncEmissionTests
|
||||
Assert.Contains("does_not_exist", evt.ErrorDetail);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a successful reader execution emits a DbWrite event with a read op and the rows returned.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task ExecuteReader_Success_EmitsKindDbWrite_OpRead_RowsReturned()
|
||||
{
|
||||
@@ -239,6 +250,8 @@ public class DatabaseSyncEmissionTests
|
||||
Assert.Contains("\"rowsReturned\":2", evt.Extra);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a throwing audit writer does not change the script call's result.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task AuditWriter_Throws_ScriptCall_ReturnsOriginalResult()
|
||||
{
|
||||
@@ -265,6 +278,8 @@ public class DatabaseSyncEmissionTests
|
||||
Assert.Empty(writer.Events);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the event provenance fields are populated from the execution context.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task Provenance_PopulatedFromContext()
|
||||
{
|
||||
@@ -288,21 +303,23 @@ public class DatabaseSyncEmissionTests
|
||||
Assert.Equal(SourceScript, evt.SourceScript);
|
||||
// Outbound channel: Actor carries the calling script identity.
|
||||
Assert.Equal(SourceScript, evt.Actor);
|
||||
// Audit Log #23: the sync DbWrite row carries the per-execution id the
|
||||
// The sync DbWrite row carries the per-execution id the
|
||||
// helper was constructed with in ExecutionId. CorrelationId is null —
|
||||
// a sync one-shot call has no operation lifecycle.
|
||||
Assert.Equal(TestExecutionId, evt.ExecutionId);
|
||||
Assert.Null(evt.CorrelationId);
|
||||
// Audit Log #23 (ParentExecutionId): null for a non-routed run — the
|
||||
// ParentExecutionId: null for a non-routed run — the
|
||||
// default CreateHelper supplies no parentExecutionId.
|
||||
Assert.Null(evt.ParentExecutionId);
|
||||
Assert.NotEqual(Guid.Empty, evt.EventId);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a sync DbWrite in a routed run stamps the parent execution id from the context.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SyncDbWrite_RoutedRun_StampsParentExecutionId_FromContext()
|
||||
{
|
||||
// Audit Log #23 (ParentExecutionId, Task 5): an inbound-API-routed run
|
||||
// ParentExecutionId: an inbound-API-routed run
|
||||
// carries the spawning execution's id; the sync DbWrite row must stamp
|
||||
// it in ParentExecutionId alongside its own fresh ExecutionId.
|
||||
using var keepAlive = new SqliteConnection("Data Source=kp;Mode=Memory;Cache=Shared");
|
||||
@@ -326,6 +343,8 @@ public class DatabaseSyncEmissionTests
|
||||
Assert.Equal(executionId, evt.ExecutionId);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a sync DbWrite in a non-routed run leaves the parent execution id null.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SyncDbWrite_NonRoutedRun_ParentExecutionIdIsNull()
|
||||
{
|
||||
@@ -349,6 +368,8 @@ public class DatabaseSyncEmissionTests
|
||||
Assert.Null(evt.ParentExecutionId);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that a sync DbWrite stamps the execution id and leaves the correlation id null.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task SyncDbWrite_StampsExecutionId_AndNullCorrelationId()
|
||||
{
|
||||
@@ -373,6 +394,8 @@ public class DatabaseSyncEmissionTests
|
||||
Assert.Null(evt.CorrelationId);
|
||||
}
|
||||
|
||||
/// <summary>Verifies that the emitted event records a non-zero duration.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task DurationMs_NonZero()
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user