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.Transport.IntegrationTests/Import/SiteInstanceImportTests.cs
+51 -18
View File
@@ -21,7 +21,7 @@ using ZB.MOM.WW.ScadaBridge.Commons.Types.Templates;
namespace ZB.MOM.WW.ScadaBridge.Transport.IntegrationTests.Import;
/// <summary>
/// Integration tests for the M8 D1 site/instance-scoped apply path of
/// Integration tests for the site/instance-scoped apply path of
/// <see cref="ZB.MOM.WW.ScadaBridge.Transport.Import.BundleImporter.ApplyAsync"/>:
/// resolve-or-create target sites + data connections from a <see cref="BundleNameMap"/>,
/// upsert instances, and rewire every cross-environment FK (connection-binding
@@ -38,6 +38,7 @@ public sealed class SiteInstanceImportTests : IDisposable
{
private readonly ServiceProvider _provider;
/// <summary>Initializes the test class with a service provider backed by an in-memory database.</summary>
public SiteInstanceImportTests()
{
var services = new ServiceCollection();
@@ -68,6 +69,7 @@ public sealed class SiteInstanceImportTests : IDisposable
_provider = services.BuildServiceProvider();
}
/// <summary>Releases the resources used by this instance.</summary>
public void Dispose() => _provider.Dispose();
// ──────────────────────────────────────────────────────────────────────
@@ -246,6 +248,8 @@ public sealed class SiteInstanceImportTests : IDisposable
// CreateNew into a fresh target
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that creating into a fresh target creates the site, connection and instance with rewired foreign keys.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_CreateNew_into_fresh_target_creates_site_connection_instance_with_rewired_FKs()
{
@@ -327,7 +331,7 @@ public sealed class SiteInstanceImportTests : IDisposable
Assert.Equal(3, result.Added);
Assert.Equal(1, result.Skipped);
// No template was overwritten and the imported instance is NotDeployed, so
// the D2 (#16) stale-instance enumeration finds nothing.
// the stale-instance enumeration finds nothing.
Assert.Empty(result.StaleInstanceIds);
}
@@ -335,11 +339,13 @@ public sealed class SiteInstanceImportTests : IDisposable
// MapToExisting into a populated target (FK remap to existing ids)
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that mapping to an existing connection remaps the binding to the existing target connection id.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_MapToExisting_remaps_binding_to_existing_target_connection_id()
{
// Source env: plant-1 / OpcUaPrimary. Build a bundle from it, then set up
// a DISTINCT target env that already has plant-1 + OpcUaPrimary with their
// Source env: plant 1 / OpcUaPrimary. Build a bundle from it, then set up
// a DISTINCT target env that already has plant 1 + OpcUaPrimary with their
// OWN surrogate ids (achieved by wiping + reseeding so ids differ from the
// source's). The import must MapToExisting and rebind to the TARGET ids.
await SeedSiteClosureAsync();
@@ -420,6 +426,8 @@ public sealed class SiteInstanceImportTests : IDisposable
// Rename an instance on import
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that applying renames the instance unique name on import.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_renames_instance_unique_name_on_import()
{
@@ -467,6 +475,8 @@ public sealed class SiteInstanceImportTests : IDisposable
// Cross-site rebind: source site maps to a DIFFERENTLY-named target site
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that applying maps the source site to a differently named target site and rebinds the connections.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_maps_source_site_to_differently_named_target_site_and_rebinds_connections()
{
@@ -475,7 +485,7 @@ public sealed class SiteInstanceImportTests : IDisposable
await WipeSiteClosureAsync();
// Target env has a DIFFERENTLY-identified site (plant-west) carrying a
// same-named connection. The operator maps plant-1 → plant-west.
// same-named connection. The operator maps plant 1 → plant-west.
int westSiteId;
int westConnId;
await using (var scope = _provider.CreateAsyncScope())
@@ -514,7 +524,7 @@ public sealed class SiteInstanceImportTests : IDisposable
await using (var scope = _provider.CreateAsyncScope())
{
var ctx = scope.ServiceProvider.GetRequiredService<ScadaBridgeDbContext>();
// No plant-1 site was created — the bundle's site mapped onto plant-west.
// No plant 1 site was created — the bundle's site mapped onto plant-west.
Assert.Equal(0, await ctx.Sites.CountAsync(s => s.SiteIdentifier == "plant-1"));
var inst = await ctx.Instances
@@ -532,6 +542,8 @@ public sealed class SiteInstanceImportTests : IDisposable
// Rollback: a mid-apply failure persists NOTHING
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that applying rolls back the site and connection when the instance pass throws.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_rolls_back_site_and_connection_when_instance_pass_throws()
{
@@ -612,6 +624,9 @@ public sealed class SiteInstanceImportTests : IDisposable
// Overwrite an existing instance: child rows replaced from the bundle
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that an overwrite cannot reassign a deployed instance.</summary>
/// <param name="state">The state of the existing instance being overwritten.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(InstanceState.Enabled)]
[InlineData(InstanceState.NotDeployed)]
@@ -662,6 +677,8 @@ public sealed class SiteInstanceImportTests : IDisposable
}
}
/// <summary>Verifies that overwriting an existing instance replaces its child rows and remaps the binding.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_Overwrite_existing_instance_replaces_child_rows_and_remaps_binding()
{
@@ -729,13 +746,15 @@ public sealed class SiteInstanceImportTests : IDisposable
// C1 — binding references a TARGET connection the bundle did NOT carry
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that a binding to a target connection omitted from the bundle resolves to the existing id rather than zero.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_binding_to_target_connection_omitted_from_bundle_resolves_to_existing_id_not_zero()
{
// C1 regression: a valid bundle can carry an instance whose binding (and
// native-alarm-source override) references a connection that exists in the
// TARGET but was NOT carried in the bundle's DataConnections. Preview does
// NOT block it (it auto-matches the target). Before the C1 Pass-2 fix the
// NOT block it (it auto-matches the target). Before the second-pass fix the
// connection map MISSED for that binding → DataConnectionId defaulted to 0
// (an invalid FK). After the fix the map resolves the EXISTING target
// connection's id and both the binding + the native-alarm override rewrite
@@ -806,7 +825,7 @@ public sealed class SiteInstanceImportTests : IDisposable
var nameMap = new BundleNameMap(
Sites: new[] { new SiteMapping("plant-1", MappingAction.MapToExisting, "plant-1") },
// No explicit connection mapping — the connection auto-matches the
// existing target connection within plant-1 (the C1 Pass-2 path).
// existing target connection within plant 1 (the second-pass path).
Connections: Array.Empty<ConnectionMapping>());
var result = await ApplyAsync(
@@ -844,6 +863,8 @@ public sealed class SiteInstanceImportTests : IDisposable
Assert.Equal(1, result.Added);
}
/// <summary>Verifies that a binding to a connection in neither the bundle nor the target fails instead of writing a zero id.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_binding_to_connection_in_neither_bundle_nor_target_fails_instead_of_writing_zero()
{
@@ -924,6 +945,8 @@ public sealed class SiteInstanceImportTests : IDisposable
// M-4 — native-alarm-source ConnectionNameOverride RENAME-REDIRECT
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that a native alarm override's connection name is rewritten to the redirected target name.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_native_alarm_override_connection_name_rewritten_to_redirected_target_name()
{
@@ -1049,14 +1072,16 @@ public sealed class SiteInstanceImportTests : IDisposable
// C2 — two sites with same-named connections resolve independently
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that two sites sharing a connection name are resolved independently per site.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_two_sites_same_connection_name_apply_per_site_resolution_independently()
{
// C2 regression: connection names are unique only WITHIN a site, so a bundle
// with plant-1/OpcUaPrimary + plant-2/OpcUaPrimary must NOT collapse onto a
// with plant 1/OpcUaPrimary + plant 2/OpcUaPrimary must NOT collapse onto a
// single resolution. Both target connections exist; the operator Overwrites
// plant-1's and Skips plant-2's. The site-qualified resolution key routes the
// Overwrite to plant-1's connection ONLY and leaves plant-2's untouched.
// plant 1's and Skips plant 2's. The site-qualified resolution key routes the
// Overwrite to plant 1's connection ONLY and leaves plant 2's untouched.
int plant1ConnId, plant2ConnId;
await using (var scope = _provider.CreateAsyncScope())
{
@@ -1143,13 +1168,13 @@ public sealed class SiteInstanceImportTests : IDisposable
{
var ctx = scope.ServiceProvider.GetRequiredService<ScadaBridgeDbContext>();
// plant-1's connection was Overwritten with the bundle's config.
// plant 1's connection was Overwritten with the bundle's config.
var c1 = await ctx.DataConnections.SingleAsync(c => c.Id == plant1ConnId);
Assert.Contains("p1-from-bundle", c1.PrimaryConfiguration!);
Assert.Equal(9, c1.FailoverRetryCount);
// plant-2's same-named connection was LEFT UNTOUCHED by the Skip — the
// bare-name collision bug would have applied plant-1's Overwrite here too.
// plant 2's same-named connection was LEFT UNTOUCHED by the Skip — the
// bare-name collision bug would have applied plant 1's Overwrite here too.
var c2 = await ctx.DataConnections.SingleAsync(c => c.Id == plant2ConnId);
Assert.Contains("p2-existing", c2.PrimaryConfiguration!);
Assert.Equal(2, c2.FailoverRetryCount);
@@ -1158,15 +1183,17 @@ public sealed class SiteInstanceImportTests : IDisposable
Assert.Equal(2, await ctx.DataConnections.CountAsync(c => c.Name == "OpcUaPrimary"));
}
// One Overwrite (plant-1 conn), three Skips (two sites + plant-2 conn).
// One Overwrite (plant 1 conn), three Skips (two sites + plant 2 conn).
Assert.Equal(1, result.Overwritten);
Assert.Equal(3, result.Skipped);
}
// ──────────────────────────────────────────────────────────────────────
// #229 — empty-ConnectionName binding is silently SKIPPED (not written)
// Empty-ConnectionName binding is silently SKIPPED (not written)
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that a binding with an empty connection name is skipped rather than written.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ApplyAsync_empty_ConnectionName_binding_is_skipped_not_written()
{
@@ -1277,9 +1304,11 @@ public sealed class SiteInstanceImportTests : IDisposable
}
// ──────────────────────────────────────────────────────────────────────
// N4 (plan R2-05 T7): warn on overrides of LOCKED template members
// Warn on overrides of LOCKED template members
// ──────────────────────────────────────────────────────────────────────
/// <summary>Verifies that an override on a locked attribute emits a warning and the import still succeeds.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Import_OverrideOnLockedAttribute_EmitsWarning_ImportStillSucceeds()
{
@@ -1323,6 +1352,8 @@ public sealed class SiteInstanceImportTests : IDisposable
}
}
/// <summary>Verifies that a preview of an override on a locked native alarm source shows a warning row.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Preview_OverrideOnLockedNativeAlarmSource_ShowsWarningRow()
{
@@ -1344,6 +1375,8 @@ public sealed class SiteInstanceImportTests : IDisposable
&& b.BlockerReason!.Contains("locked", StringComparison.OrdinalIgnoreCase));
}
/// <summary>Verifies that an override on an unlocked attribute produces no lock warning.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Import_OverrideOnUnlockedAttribute_NoLockWarning()
{
@@ -1378,7 +1411,7 @@ public sealed class SiteInstanceImportTests : IDisposable
}
/// <summary>
/// Seeds a template ("Pump") + site ("plant-1") + instance ("Pump-01") whose
/// Seeds a template ("Pump") + site ("plant 1") + instance ("Pump 01") whose
/// overrides target the given members; <paramref name="lockAttribute"/> /
/// <paramref name="lockNativeSource"/> toggle the template member's IsLocked flag.
/// The attribute override is always present; the native-source override (and its