dohertj2/ScadaBridge
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(tests): fix CommentChecker findings across tests/ — 13,392 → 0 (repo-wide scan clean)

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files
tests/ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests/Repositories/SiteRepositoryTests.cs
+30 -16
View File
@@ -6,13 +6,13 @@ using ZB.MOM.WW.ScadaBridge.TestSupport;
namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests.Repositories;
/// <summary>
/// SiteRuntime-006 / SiteRuntime-007 regression tests for the site-local repositories.
/// Regression tests for the site-local repositories.
///
/// SiteRuntime-006: the repositories must obtain a SQLite connection through
/// The repositories must obtain a SQLite connection through
/// <see cref="SiteStorageService.CreateConnection"/>, not by reading a private field
/// via reflection.
///
/// SiteRuntime-007: the synthetic integer IDs derived from entity names must be stable
/// The synthetic integer IDs derived from entity names must be stable
/// across process restarts (a freshly-constructed service/repository), so an ID handed
/// to a caller still resolves the same entity later.
/// </summary>
@@ -20,11 +20,13 @@ public class SiteRepositoryTests : IDisposable
{
private readonly TestLocalDb _localDb;
/// <summary>Initializes a temporary local database for the tests.</summary>
public SiteRepositoryTests()
{
_localDb = TestLocalDb.CreateTemp("site-repo-test");
}
/// <summary>Releases the resources held by the test fixture.</summary>
public void Dispose()
{
// Dispose first — the master connection anchors the WAL, so the sidecars
@@ -46,10 +48,11 @@ public class SiteRepositoryTests : IDisposable
=> new(_localDb.Db, NullLogger<SiteStorageService>.Instance);
/// <summary>
/// SiteRuntime-006: an external system stored via <see cref="SiteStorageService"/>
/// An external system stored via <see cref="SiteStorageService"/>
/// can be read back through the repository — proving the repository's connection
/// (now obtained from <see cref="SiteStorageService.CreateConnection"/>) is valid.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExternalSystemRepository_RoundTripsStoredDefinition()
{
@@ -71,6 +74,7 @@ public class SiteRepositoryTests : IDisposable
/// <see cref="SiteStorageService.StoreExternalSystemAsync"/> must round-trip through the
/// site SQLite store and back out via the repository, so site-side calls honor it.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task SiteStorage_ExternalSystem_TimeoutSeconds_RoundTrips()
{
@@ -93,6 +97,7 @@ public class SiteRepositoryTests : IDisposable
/// silently falling back to <c>DefaultMaxRetries</c> (50) x <c>DefaultRetryInterval</c> (30 s).
/// Before the fix the site table had no such columns and this read back 0 / TimeSpan.Zero.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task SiteStorage_ExternalSystem_RetryPolicy_RoundTrips()
{
@@ -116,6 +121,7 @@ public class SiteRepositoryTests : IDisposable
/// engine defaults apply. This is what makes the new columns behaviourally invisible until
/// an operator actually configures a policy.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task SiteStorage_ExternalSystem_RetryPolicy_DefaultsToUnset()
{
@@ -133,11 +139,12 @@ public class SiteRepositoryTests : IDisposable
}
/// <summary>
/// SiteRuntime-007: the synthetic ID for an external system must be identical when
/// The synthetic ID for an external system must be identical when
/// the storage service and repository are re-created (simulating a process restart).
/// With the old <see cref="string.GetHashCode()"/> the ID was randomized per process
/// and a by-ID lookup after a restart would fail.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExternalSystemRepository_SyntheticId_IsStableAcrossRestart()
{
@@ -162,12 +169,13 @@ public class SiteRepositoryTests : IDisposable
Assert.Equal("StableSystem", found.Name);
}
// ── ExternalSystemGateway-011: name-keyed repository lookups ──
// ── Name-keyed repository lookups ──
/// <summary>
/// ExternalSystemGateway-011: the site repository's name-keyed external-system
/// The site repository's name-keyed external-system
/// lookup returns the matching row, and the same synthetic ID as the by-ID path.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExternalSystemRepository_GetByName_ReturnsMatchingDefinition()
{
@@ -192,8 +200,9 @@ public class SiteRepositoryTests : IDisposable
}
/// <summary>
/// ExternalSystemGateway-011: a missing name resolves to <c>null</c>.
/// A missing name resolves to <c>null</c>.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExternalSystemRepository_GetByName_MissingName_ReturnsNull()
{
@@ -208,9 +217,10 @@ public class SiteRepositoryTests : IDisposable
}
/// <summary>
/// ExternalSystemGateway-011: the site repository's name-keyed method lookup
/// The site repository's name-keyed method lookup
/// returns the method scoped to its parent system, or <c>null</c> for a miss.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExternalSystemRepository_GetMethodByName_ResolvesScopedToSystem()
{
@@ -233,9 +243,10 @@ public class SiteRepositoryTests : IDisposable
}
/// <summary>
/// ExternalSystemGateway-011: the site repository's name-keyed database-connection
/// The site repository's name-keyed database-connection
/// lookup returns the matching row, or <c>null</c> for a miss.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task DatabaseConnectionRepository_GetByName_ReturnsMatchingDefinition()
{
@@ -258,18 +269,19 @@ public class SiteRepositoryTests : IDisposable
}
// NotificationRepository_SyntheticId_IsStableAcrossRestart was removed 2026-07-10
// (arch-review 08 §1.3/#23) along with the vestigial SiteNotificationRepository —
// (arch-review 08 §1.3) along with the vestigial SiteNotificationRepository —
// notification config is central-only and never lives on a site. The synthetic-ID
// stability guarantee is still exercised by ExternalSystemRepository_SyntheticId_IsStableAcrossRestart.
// ── WP2.6a: ExternalSystemDefinitionCache (arch-review misc — site external-system resolution) ──
// ── ExternalSystemDefinitionCache (arch-review misc — site external-system resolution) ──
/// <summary>
/// WP2.6a: two repository instances sharing one <see cref="ExternalSystemDefinitionCache"/>
/// Two repository instances sharing one <see cref="ExternalSystemDefinitionCache"/>
/// (the production DI shape — one singleton cache, many scoped repository instances) must
/// see the SAME cached snapshot: a row written after the cache was already populated by
/// the first repository is invisible to the second until the cache is invalidated.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExternalSystemRepository_SharedCache_HitServesStaleSnapshotUntilInvalidated()
{
@@ -298,11 +310,12 @@ public class SiteRepositoryTests : IDisposable
}
/// <summary>
/// WP2.6a: the by-ID lookups (system and method) must resolve correctly out of the
/// The by-ID lookups (system and method) must resolve correctly out of the
/// cached snapshot — proving the O(1) id-index build in <c>LoadSnapshotAsync</c> is
/// wired correctly for both entity kinds, not just the by-name path already covered
/// by ExternalSystemGateway-011.
/// by the name-keyed lookup tests.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExternalSystemRepository_SharedCache_ByIdLookups_ResolveSystemAndMethod()
{
@@ -334,12 +347,13 @@ public class SiteRepositoryTests : IDisposable
}
/// <summary>
/// WP2.6a: a repository constructed via the single-arg (no shared cache) constructor
/// A repository constructed via the single-arg (no shared cache) constructor
/// gets its own private cache — a second such repository over the same storage must
/// see rows written after the first repository's cache was already populated,
/// preserving the pre-cache "always fresh" behavior for callers that opt out of
/// sharing.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExternalSystemRepository_PrivateCache_DoesNotShareAcrossInstances()
{