using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests;
///
/// T15 — verifies the non-blocking historian-provisioning hook in
/// . The hook fires AFTER the address-space work and
/// dispatches fire-and-forget, so a slow or
/// throwing provisioner can never block or break a deploy on the OPC UA publish actor's pinned
/// thread.
///
public sealed class AddressSpaceApplierProvisioningTests
{
/// Capturing double. Records the requests it was
/// handed and signals a when invoked, so a test can await the
/// fire-and-forget dispatch deterministically (never poll/sleep). A flag
/// simulates a synchronous provisioner fault.
private sealed class CapturingProvisioner : IHistorianProvisioning
{
private readonly TaskCompletionSource _called = new(TaskCreationOptions.RunContinuationsAsynchronously);
/// Gets the requests the hook handed to .
public List Seen { get; } = new();
/// When true, throws synchronously (a fault before any await).
public bool Throw { get; init; }
/// Completes once has been invoked.
public Task Called => _called.Task;
///
public Task EnsureTagsAsync(
IReadOnlyList requests, CancellationToken ct)
{
if (Throw)
{
_called.TrySetResult();
throw new InvalidOperationException("boom");
}
Seen.AddRange(requests);
_called.TrySetResult();
return Task.FromResult(new HistorianProvisionResult(requests.Count, requests.Count, 0, 0));
}
}
/// The hook provisions ONLY historized added tags, with the resolved historian name
/// (override when set, else the driver-side FullName).
[Fact]
public async Task Apply_provisions_only_historized_added_tags()
{
var prov = new CapturingProvisioner();
var applier = new AddressSpaceApplier(NullOpcUaAddressSpaceSink.Instance, NullLogger.Instance, prov);
// Leaf display name "Temp"; historian override "Pump1.Temp".
var plan = PlanWithAddedTags(
HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32"),
NonHistorizedTag(displayName: "Run", dataType: "Boolean"));
var outcome = applier.Apply(plan);
outcome.RebuildCalled.ShouldBeFalse(); // PureAdd — no rebuild; provisioning still fires
outcome.AddedNodes.ShouldBeGreaterThan(0);
// Fire-and-forget: await the capturing double's signal so the assertion is deterministic.
await prov.Called.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
prov.Seen.Count.ShouldBe(1);
prov.Seen[0].TagName.ShouldBe("Pump1.Temp"); // resolved historian name (override)
prov.Seen[0].DataType.ShouldBe(DriverDataType.Float32);
prov.Seen[0].Description.ShouldBe("Temp"); // leaf display name
}
/// A null/blank historian-name override resolves to the driver-side FullName — mirroring
/// the materialiser's resolution exactly.
[Fact]
public async Task Apply_resolves_historian_name_from_fullname_when_override_blank()
{
var prov = new CapturingProvisioner();
var applier = new AddressSpaceApplier(NullOpcUaAddressSpaceSink.Instance, NullLogger.Instance, prov);
// IsHistorized but no override → historian name falls back to FullName ("40001").
var plan = PlanWithAddedTags(
HistorizedTag(displayName: "Speed", historianName: null, dataType: "Int32", fullName: "40001"));
applier.Apply(plan);
await prov.Called.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
prov.Seen.Count.ShouldBe(1);
prov.Seen[0].TagName.ShouldBe("40001");
prov.Seen[0].DataType.ShouldBe(DriverDataType.Int32);
}
/// A synchronously-throwing provisioner must NOT block or break the publish: the
/// synchronous still completes its address-space work and
/// returns its normal outcome.
[Fact]
public void Provisioner_throw_does_not_block_publish()
{
var applier = new AddressSpaceApplier(
NullOpcUaAddressSpaceSink.Instance,
NullLogger.Instance,
new CapturingProvisioner { Throw = true });
var outcome = applier.Apply(PlanWithAddedTags(
HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32")));
outcome.RebuildCalled.ShouldBeFalse(); // PureAdd — no rebuild; Apply still completed + provisioned
}
/// The default ctor (no provisioner) binds the no-op
/// and never faults a deploy — preserving every existing call site.
[Fact]
public void Default_ctor_uses_null_provisioning_and_does_not_throw()
{
var applier = new AddressSpaceApplier(NullOpcUaAddressSpaceSink.Instance, NullLogger.Instance);
var outcome = applier.Apply(PlanWithAddedTags(
HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32")));
outcome.RebuildCalled.ShouldBeFalse(); // PureAdd — no rebuild; default no-op provisioning still safe
outcome.AddedNodes.ShouldBeGreaterThan(0);
}
/// lmxopcua#898: Tag.DataType holds OPC UA built-in names (what the AdminUI writes). Float, Double, Byte and
/// SByte used to fail Enum.TryParse<DriverDataType> and were silently never provisioned; they now resolve
/// (Float→Float32, Double→Float64, Byte/SByte→Int16, a lossless widening). The DriverDataType spelling still works,
/// and a name with no historian mapping (Guid) is skipped without faulting the hook.
[Fact]
public async Task Apply_provisions_opc_ua_type_names_and_skips_unmapped_ones()
{
var prov = new CapturingProvisioner();
var applier = new AddressSpaceApplier(NullOpcUaAddressSpaceSink.Instance, NullLogger.Instance, prov);
var plan = PlanWithAddedTags(
HistorizedTag(displayName: "F", historianName: "P.F", dataType: "Float"),
HistorizedTag(displayName: "D", historianName: "P.D", dataType: "Double"),
HistorizedTag(displayName: "B", historianName: "P.B", dataType: "Byte"),
HistorizedTag(displayName: "S", historianName: "P.S", dataType: "SByte"),
HistorizedTag(displayName: "F32", historianName: "P.F32", dataType: "Float32"),
HistorizedTag(displayName: "G", historianName: "P.G", dataType: "Guid"));
applier.Apply(plan);
await prov.Called.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
prov.Seen.Select(r => (r.TagName, r.DataType)).ShouldBe(new[]
{
("P.F", DriverDataType.Float32),
("P.D", DriverDataType.Float64),
("P.B", DriverDataType.Int16),
("P.S", DriverDataType.Int16),
("P.F32", DriverDataType.Float32),
}, ignoreOrder: true);
}
/// lmxopcua#899: a read-only binding (historianReadOnly: true) never reaches EnsureTags — neither
/// as an add nor as a change. The owned "Control" tag is the positive control, so the absence is not a vacuous
/// no-dispatch; the override-without-the-flag tag shows the chosen default is unchanged (an override alone still
/// provisions).
[Fact]
public async Task Apply_never_provisions_a_read_only_binding()
{
var prov = new CapturingProvisioner();
var applier = new AddressSpaceApplier(NullOpcUaAddressSpaceSink.Instance, NullLogger.Instance, prov);
var readOnlyAdded = HistorizedTag("SysTime", "SysTimeSec", "Int32", fullName: "Plant/SysTime") with { HistorianReadOnly = true };
var flipToReadOnlyOld = HistorizedTag("Pulse", "SysPulse", "Boolean", fullName: "Plant/Pulse");
var flipToReadOnlyNew = flipToReadOnlyOld with { HistorianReadOnly = true, DataType = "Int32" };
var readOnlyRenamedOld = HistorizedTag("Ro", "Other.A", "Float", fullName: "Plant/Ro") with { HistorianReadOnly = true };
var readOnlyRenamedNew = readOnlyRenamedOld with { HistorianTagname = "Other.B" };
var plan = PlanWithAddedTags(
HistorizedTag("Control", "Control.Name", "Float"),
HistorizedTag("Override", "Someones.Tag", "Double", fullName: "Plant/Override"),
readOnlyAdded) with
{
ChangedRawTags = new[]
{
new AddressSpacePlan.RawTagDelta(flipToReadOnlyOld, flipToReadOnlyNew),
new AddressSpacePlan.RawTagDelta(readOnlyRenamedOld, readOnlyRenamedNew),
},
};
applier.Apply(plan);
await prov.Called.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
prov.Seen.Select(r => r.TagName).ShouldBe(new[] { "Control.Name", "Someones.Tag" }, ignoreOrder: true);
}
/// lmxopcua#899: turning read-only OFF makes the tag owned, so it provisions like a historization flip.
[Fact]
public async Task Apply_provisions_a_tag_whose_read_only_flag_is_cleared()
{
var prov = new CapturingProvisioner();
var applier = new AddressSpaceApplier(NullOpcUaAddressSpaceSink.Instance, NullLogger.Instance, prov);
var before = HistorizedTag("Own", "Mine.Tag", "Float", fullName: "Plant/Own") with { HistorianReadOnly = true };
var plan = PlanWithAddedTags() with
{
ChangedRawTags = new[] { new AddressSpacePlan.RawTagDelta(before, before with { HistorianReadOnly = false }) },
};
applier.Apply(plan);
await prov.Called.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
prov.Seen.Select(r => r.TagName).ShouldBe(new[] { "Mine.Tag" });
}
/// #600.1: a CHANGED raw tag that flips to historized, or whose historian name / data type
/// changes, is provisioned; an unchanged-historization edit and an alarm-bearing tag are not. The
/// added "Control" tag is the positive control so the absences are not a vacuous no-dispatch.
[Fact]
public async Task Apply_provisions_changed_tags_whose_historization_flips_or_name_changes()
{
var prov = new CapturingProvisioner();
var applier = new AddressSpaceApplier(NullOpcUaAddressSpaceSink.Instance, NullLogger.Instance, prov);
var flipOff = NonHistorizedTag("Flip", "Float32") with { TagId = "t-flip", NodeId = "Plant/Flip" };
var flipOn = flipOff with { IsHistorized = true };
var renOld = HistorizedTag("Ren", "Old.Name", "Float32") with { TagId = "t-ren" };
var renNew = renOld with { HistorianTagname = "New.Name" };
var sameOld = HistorizedTag("Same", "Same.Name", "Float32") with { TagId = "t-same", Writable = false };
var sameNew = sameOld with { Writable = true }; // non-historian edit
var alarmOld = NonHistorizedTag("Alm", "Float32") with { TagId = "t-alm" };
var alarmNew = alarmOld with
{
IsHistorized = true,
Alarm = new EquipmentTagAlarmInfo("AlarmCondition", 500),
};
var plan = PlanWithAddedTags(HistorizedTag("Control", "Control.Name", "Float32")) with
{
ChangedRawTags = new[]
{
new AddressSpacePlan.RawTagDelta(flipOff, flipOn),
new AddressSpacePlan.RawTagDelta(renOld, renNew),
new AddressSpacePlan.RawTagDelta(sameOld, sameNew),
new AddressSpacePlan.RawTagDelta(alarmOld, alarmNew),
},
};
applier.Apply(plan);
await prov.Called.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
prov.Seen.Select(r => r.TagName).ShouldBe(
new[] { "Control.Name", "Plant/Flip", "New.Name" }, ignoreOrder: true);
}
/// Capturing that records every log line and signals a
/// the first time a "historian provisioning completed" tally is
/// emitted, so the fire-and-forget continuation's log can be awaited deterministically.
private sealed class CapturingLogger : ILogger
{
private readonly TaskCompletionSource _provisioningLogged =
new(TaskCreationOptions.RunContinuationsAsynchronously);
/// Completes with the rendered message of the first provisioning-completed tally logged.
public Task ProvisioningLogged => _provisioningLogged.Task;
public IDisposable BeginScope(TState state) where TState : notnull => NullScope.Instance;
public bool IsEnabled(LogLevel logLevel) => true;
public void Log(
LogLevel logLevel, EventId eventId, TState state, Exception? exception,
Func formatter)
{
var message = formatter(state, exception);
if (logLevel == LogLevel.Information &&
message.Contains("historian provisioning completed", StringComparison.Ordinal))
{
_provisioningLogged.TrySetResult(message);
}
}
private sealed class NullScope : IDisposable
{
public static readonly NullScope Instance = new();
public void Dispose() { }
}
}
/// Issue 2 (observability): a fully-successful provisioning (Ensured>0, Failed=0, Skipped=0) — the
/// case that previously logged NOTHING — now emits an Information tally, so a successful provisioning is
/// observable rather than silent.
[Fact]
public async Task Apply_logs_an_information_tally_on_a_fully_successful_provisioning()
{
var logger = new CapturingLogger();
var applier = new AddressSpaceApplier(
NullOpcUaAddressSpaceSink.Instance, logger, new CapturingProvisioner());
applier.Apply(PlanWithAddedTags(
HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32")));
var message = await logger.ProvisioningLogged.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
message.ShouldContain("dispatched=1");
message.ShouldContain("ensured=1");
message.ShouldContain("failed=0");
}
/// Issue 2 (observability): the no-op path is now
/// DETECTABLE — it reports Requested=0 regardless of input, so a tally showing dispatched=1 but requested=0
/// unmistakably flags "provisioning is not wired", the invisibility that let the dormant-provisioner bug
/// ship unnoticed.
[Fact]
public async Task Apply_logs_a_detectable_tally_for_the_noop_provisioning_path()
{
var logger = new CapturingLogger();
var applier = new AddressSpaceApplier(NullOpcUaAddressSpaceSink.Instance, logger);
applier.Apply(PlanWithAddedTags(
HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32")));
var message = await logger.ProvisioningLogged.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
message.ShouldContain("dispatched=1"); // we DID hand one request to EnsureTagsAsync
message.ShouldContain("requested=0"); // ...but the no-op acknowledges nothing ⇒ dormant
}
/// Capturing double. Records the add/remove
/// ref deltas the applier feeds it. A flag simulates a faulting feed.
private sealed class CapturingSubscriptionSink : IHistorizedTagSubscriptionSink
{
/// Ref pairs the applier fed as ADDED (mux ref + historian name).
public List Added { get; } = new();
/// Ref pairs the applier fed as REMOVED.
public List Removed { get; } = new();
/// When true, throws synchronously.
public bool Throw { get; init; }
///
public void UpdateHistorizedRefs(IReadOnlyList added, IReadOnlyList removed)
{
if (Throw) throw new InvalidOperationException("boom");
Added.AddRange(added);
Removed.AddRange(removed);
}
}
/// The feed pushes ONLY historized added refs, resolved (override-or-FullName) exactly like
/// the provisioning hook — non-historized tags never reach the recorder.
[Fact]
public void Apply_feeds_historized_added_refs_to_the_subscription_sink()
{
var sink = new CapturingSubscriptionSink();
var applier = new AddressSpaceApplier(
NullOpcUaAddressSpaceSink.Instance, NullLogger.Instance,
historizedSubscriptions: sink);
var plan = PlanWithAddedTags(
HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32"),
HistorizedTag(displayName: "Speed", historianName: null, dataType: "Int32", fullName: "40001"),
NonHistorizedTag(displayName: "Run", dataType: "Boolean"));
applier.Apply(plan);
// Each ref carries BOTH identifiers: the override tag feeds (mux ref = FullName "ref", historian
// name = override "Pump1.Temp"); the no-override tag feeds (FullName "40001" as both).
sink.Added.ShouldBe(new[]
{
new HistorizedTagRef("ref", "Pump1.Temp"),
new HistorizedTagRef("40001", "40001"),
}, ignoreOrder: true);
sink.Removed.ShouldBeEmpty();
}
/// Removed historized tags are fed as REMOVED refs; a changed tag whose historian override is
/// renamed feeds the old ref removed + the new ref added (the recorder converges the full set).
[Fact]
public void Apply_feeds_removed_and_renamed_historized_refs()
{
var sink = new CapturingSubscriptionSink();
var applier = new AddressSpaceApplier(
NullOpcUaAddressSpaceSink.Instance, NullLogger.Instance,
historizedSubscriptions: sink);
var removedTag = HistorizedTag(displayName: "Old", historianName: "Pump1.Old", dataType: "Float32");
// Same TagId ("tag-T"), historian override renamed A → B (both historized) → remove A, add B.
var prev = HistorizedTag(displayName: "T", historianName: "Pump1.A", dataType: "Float32");
var cur = HistorizedTag(displayName: "T", historianName: "Pump1.B", dataType: "Float32");
var plan = new AddressSpacePlan(
AddedEquipment: Array.Empty(),
RemovedEquipment: Array.Empty(),
ChangedEquipment: Array.Empty(),
AddedDrivers: Array.Empty(),
RemovedDrivers: Array.Empty(),
ChangedDrivers: Array.Empty(),
AddedAlarms: Array.Empty(),
RemovedAlarms: Array.Empty(),
ChangedAlarms: Array.Empty())
{
RemovedRawTags = new[] { removedTag },
ChangedRawTags = new[] { new AddressSpacePlan.RawTagDelta(prev, cur) },
};
applier.Apply(plan);
// All three tags default FullName "ref" (the mux ref); the override rename changes only the
// historian name, so the changed tag feeds removed (ref, Pump1.A) + added (ref, Pump1.B).
sink.Added.ShouldBe(new[] { new HistorizedTagRef("ref", "Pump1.B") }, ignoreOrder: true);
sink.Removed.ShouldBe(new[]
{
new HistorizedTagRef("ref", "Pump1.Old"),
new HistorizedTagRef("ref", "Pump1.A"),
}, ignoreOrder: true);
}
/// lmxopcua#899: a read-only binding is never fed to the recorder (its WriteLiveValues would write into a
/// historian tag OtOpcUa does not own); flipping the flag on removes the ref, flipping it off adds it.
[Fact]
public void Apply_never_feeds_a_read_only_binding_to_the_recorder()
{
var sink = new CapturingSubscriptionSink();
var applier = new AddressSpaceApplier(
NullOpcUaAddressSpaceSink.Instance, NullLogger.Instance,
historizedSubscriptions: sink);
var owned = HistorizedTag("Own", "Mine.Tag", "Float", fullName: "Plant/Own");
var readOnly = HistorizedTag("Ro", "SysTimeSec", "Int32", fullName: "Plant/Ro") with { HistorianReadOnly = true };
var goingRo = HistorizedTag("ToRo", "X.Tag", "Float", fullName: "Plant/ToRo");
var goingOwned = HistorizedTag("ToOwn", "Y.Tag", "Float", fullName: "Plant/ToOwn") with { HistorianReadOnly = true };
var removedRo = HistorizedTag("Gone", "Z.Tag", "Float", fullName: "Plant/Gone") with { HistorianReadOnly = true };
var plan = PlanWithAddedTags(owned, readOnly) with
{
RemovedRawTags = new[] { removedRo },
ChangedRawTags = new[]
{
new AddressSpacePlan.RawTagDelta(goingRo, goingRo with { HistorianReadOnly = true }),
new AddressSpacePlan.RawTagDelta(goingOwned, goingOwned with { HistorianReadOnly = false }),
},
};
applier.Apply(plan);
sink.Added.ShouldBe(new[]
{
new HistorizedTagRef("Plant/Own", "Mine.Tag"),
new HistorizedTagRef("Plant/ToOwn", "Y.Tag"),
}, ignoreOrder: true);
sink.Removed.ShouldBe(new[] { new HistorizedTagRef("Plant/ToRo", "X.Tag") });
}
/// A synchronously-throwing subscription sink must NOT block or break the publish — the
/// address-space work still completes and returns its outcome.
[Fact]
public void Subscription_sink_throw_does_not_block_publish()
{
var applier = new AddressSpaceApplier(
NullOpcUaAddressSpaceSink.Instance,
NullLogger.Instance,
historizedSubscriptions: new CapturingSubscriptionSink { Throw = true });
var outcome = applier.Apply(PlanWithAddedTags(
HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32")));
outcome.RebuildCalled.ShouldBeFalse(); // PureAdd — no rebuild; Apply still completed + provisioned
}
// v3 Batch 4: historized value tags are RAW tags — the mux ref + historian default are the RawPath
// (== NodeId). The `fullName` param plays the role of the RawPath here (kept as a param name so the
// existing assertions — HistorizedTagRef("ref"/"40001", …) — read unchanged).
private static RawTagPlan HistorizedTag(string displayName, string? historianName, string dataType, string fullName = "ref")
=> new("tag-" + displayName, NodeId: fullName, ParentNodeId: null, DriverInstanceId: "drv", Name: displayName,
DataType: dataType, Writable: false, Alarm: null, ReferencingEquipmentPaths: Array.Empty(),
IsHistorized: true, HistorianTagname: historianName);
private static RawTagPlan NonHistorizedTag(string displayName, string dataType)
=> new("tag-" + displayName, NodeId: "ref", ParentNodeId: null, DriverInstanceId: "drv", Name: displayName,
DataType: dataType, Writable: false, Alarm: null, ReferencingEquipmentPaths: Array.Empty(),
IsHistorized: false, HistorianTagname: null);
private static AddressSpacePlan PlanWithAddedTags(params RawTagPlan[] tags) => new(
AddedEquipment: Array.Empty(),
RemovedEquipment: Array.Empty(),
ChangedEquipment: Array.Empty(),
AddedDrivers: Array.Empty(),
RemovedDrivers: Array.Empty(),
ChangedDrivers: Array.Empty(),
AddedAlarms: Array.Empty(),
RemovedAlarms: Array.Empty(),
ChangedAlarms: Array.Empty())
{
AddedRawTags = tags,
};
}