dohertj2/lmxopcua
1
0
Fork 0
Code Issues 17 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(mtconnect): ITagDiscovery streams tree + SupportsOnlineDiscovery opt-in (Task 12)

Browse Source
This commit is contained in:
Joseph Doherty
2026-07-24 16:41:21 -04:00
parent 9a67ed918a
commit 13dd9fcd70
3 changed files with 1053 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests/CapturingBuilder.cs
+132
View File
@@ -0,0 +1,132 @@
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests;
/// <summary>
/// An <see cref="IAddressSpaceBuilder"/> that records the tree a driver streams into it, so
/// <c>DiscoverAsync</c> can be asserted on <b>shape</b> (which node landed under which folder)
/// and not merely on a flat list of leaves.
/// </summary>
/// <remarks>
/// <para>
/// <b>Why this exists rather than a reference to the shipped capturing builder.</b> Two
/// production capturing builders exist — <c>Commons.Browsing.CapturingAddressSpaceBuilder</c>
/// (universal browser) and <c>Runtime.Drivers.CapturingAddressSpaceBuilder</c> (deploy-time
/// discovery) — but this suite deliberately references only the driver and its
/// <c>.Contracts</c>, so neither is reachable without pulling the whole server stack into a
/// driver unit-test project. Both also flatten differently from what these tests must prove:
/// the browser's node id for a folder is a synthetic path while a leaf's id is its
/// <c>FullName</c>, which is exactly the conflation a "did the device-level data item land in
/// the device folder?" assertion needs to see through.
/// </para>
/// <para>
/// <b>Deliberately not thread-safe.</b> A driver streams discovery on one caller; recording
/// behind a lock would hide a driver that fanned out onto other threads.
/// </para>
/// </remarks>
internal sealed class CapturingBuilder : IAddressSpaceBuilder
{
private readonly State _state;
private readonly string _path;
/// <summary>Creates a root builder — the scope a driver's <c>DiscoverAsync</c> is handed.</summary>
public CapturingBuilder()
{
_state = new State();
_path = string.Empty;
}
private CapturingBuilder(State state, string path)
{
_state = state;
_path = path;
}
/// <summary>Every folder streamed, in call order, with the slash-joined path it landed at.</summary>
public IReadOnlyList<CapturedFolder> Folders => _state.Folders;
/// <summary>Every variable streamed, in call order, with the folder path it landed under.</summary>
public IReadOnlyList<CapturedVariable> Variables => _state.Variables;
/// <summary>Every property streamed, with the scope path it was added to.</summary>
public IReadOnlyList<CapturedProperty> Properties => _state.Properties;
/// <inheritdoc/>
public IAddressSpaceBuilder Folder(string browseName, string displayName)
{
var path = _path.Length == 0 ? browseName : $"{_path}/{browseName}";
_state.Folders.Add(new CapturedFolder(path, _path, browseName, displayName));
return new CapturingBuilder(_state, path);
}
/// <inheritdoc/>
public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo attributeInfo)
{
var captured = new CapturedVariable(_path, browseName, displayName, attributeInfo);
_state.Variables.Add(captured);
return new CapturedVariableHandle(captured);
}
/// <inheritdoc/>
public void AddProperty(string browseName, DriverDataType dataType, object? value) =>
_state.Properties.Add(new CapturedProperty(_path, browseName, dataType, value));
private sealed class State
{
public List<CapturedFolder> Folders { get; } = [];
public List<CapturedVariable> Variables { get; } = [];
public List<CapturedProperty> Properties { get; } = [];
}
private sealed class CapturedVariableHandle(CapturedVariable variable) : IVariableHandle
{
public string FullReference => variable.Attr.FullName;
public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info)
{
variable.AlarmConditions.Add(info);
return new NullSink();
}
private sealed class NullSink : IAlarmConditionSink
{
public void OnTransition(AlarmEventArgs args)
{
// Nothing to record: no test in this suite drives an alarm transition through
// discovery, and a sink that threw would fail a driver that legitimately never
// pushes one.
}
}
}
}
/// <summary>One folder captured from a discovery stream.</summary>
/// <param name="Path">Slash-joined path of the folder itself.</param>
/// <param name="ParentPath">Slash-joined path of the scope it was added to (empty at the root).</param>
/// <param name="BrowseName">The browse name the driver supplied.</param>
/// <param name="DisplayName">The display name the driver supplied.</param>
internal sealed record CapturedFolder(string Path, string ParentPath, string BrowseName, string DisplayName);
/// <summary>One variable captured from a discovery stream.</summary>
/// <param name="ParentPath">Slash-joined path of the folder it landed under (empty at the root).</param>
/// <param name="BrowseName">The browse name the driver supplied.</param>
/// <param name="DisplayName">The display name the driver supplied.</param>
/// <param name="Attr">The driver-side attribute metadata the driver stamped on it.</param>
internal sealed record CapturedVariable(
string ParentPath, string BrowseName, string DisplayName, DriverAttributeInfo Attr)
{
/// <summary>Alarm conditions the driver marked this variable with, if any.</summary>
public List<AlarmConditionInfo> AlarmConditions { get; } = [];
}
/// <summary>One property captured from a discovery stream.</summary>
/// <param name="ScopePath">Slash-joined path of the node it was added to.</param>
/// <param name="BrowseName">The property browse name.</param>
/// <param name="DataType">The property data type.</param>
/// <param name="Value">The property value.</param>
internal sealed record CapturedProperty(string ScopePath, string BrowseName, DriverDataType DataType, object? Value);
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests/MTConnectDiscoverTests.cs
+680
View File
@@ -0,0 +1,680 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests;
/// <summary>
/// Task 12 — <see cref="MTConnectDriver"/>'s <see cref="ITagDiscovery"/> half: the
/// <c>/probe</c> device model streamed into an <see cref="IAddressSpaceBuilder"/> as
/// Device → Component → DataItem, and the one-member browse opt-in
/// (<see cref="ITagDiscovery.SupportsOnlineDiscovery"/>) the Wave-0 universal browser keys off.
/// </summary>
/// <remarks>
/// <para>
/// <b>The load-bearing assertion is <c>FullName == DataItem@id</c>.</b> The universal
/// browser commits a browsed leaf's <see cref="DriverAttributeInfo.FullName"/> straight into
/// <c>TagConfig.FullName</c>, and that is the key <c>ReadAsync</c> / the <c>/sample</c> pump
/// resolve an observation against (<see cref="MTConnectObservationIndex"/> is keyed by
/// <c>DataItem@id</c>). Streaming the browse <i>name</i> instead would produce a picker that
/// looks perfect and commits tags that can never report a value — every one of them stuck at
/// <c>BadWaitingForInitialData</c> behind a Healthy driver.
/// </para>
/// <para>
/// <b>The second load-bearing assertion is the type shape.</b> Discovery must stamp exactly
/// what <see cref="MTConnectDataTypeInference"/> returns, including the array shape — the
/// AdminUI typed editor calls the same function, so any local recomputation here makes the
/// picker and the editor disagree about the same data item. <c>PART_COUNT → Int64</c> is
/// called out on its own because the probe document's UPPER_SNAKE spelling is the case a
/// PascalCase-only match silently types as <c>String</c>.
/// </para>
/// </remarks>
public sealed class MTConnectDiscoverTests
{
private const string AgentUri = "http://fixture-agent:5000";
/// <summary>Every DataItem id the canned <c>Fixtures/probe.xml</c> declares.</summary>
private static readonly string[] FixtureDataItemIds =
[
"dev1_avail",
"dev1_pos",
"dev1_vibration_ts",
"dev1_partcount",
"dev1_execution",
"dev1_program",
"dev1_system_cond",
];
private static MTConnectDriverOptions Opts(string? deviceName = null) =>
new()
{
AgentUri = AgentUri,
DeviceName = deviceName,
// Discovery is a pure read of the /probe device model: it must enumerate what the Agent
// declares, NOT what an operator has already authored. Left empty on purpose so a driver
// that streamed its authored tag table instead could not pass.
Tags = [],
};
private static (MTConnectDriver Driver, CannedAgentClient Client) NewDriver(
MTConnectDriverOptions? options = null, MTConnectProbeModel? probe = null)
{
var client = CannedAgentClient.FromFixtures();
if (probe is not null)
{
client.Probe = probe;
}
return (new MTConnectDriver(options ?? Opts(), "mt1", _ => client), client);
}
private static async Task<(MTConnectDriver Driver, CannedAgentClient Client)> InitializedDriverAsync(
MTConnectDriverOptions? options = null, MTConnectProbeModel? probe = null)
{
var (driver, client) = NewDriver(options, probe);
await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
return (driver, client);
}
private static async Task<CapturingBuilder> DiscoverAsync(MTConnectDriver driver)
{
var builder = new CapturingBuilder();
await driver.DiscoverAsync(builder, TestContext.Current.CancellationToken);
return builder;
}
// ---- the plan's headline test ----
/// <summary>
/// The whole contract in one place: the fixture's Device → Controller → Path tree reaches the
/// builder, the CONDITION data item is present under its own <c>id</c>, it types as
/// <see cref="DriverDataType.String"/>, and the driver declares the browse opt-in the
/// universal browser gates on.
/// </summary>
[Fact]
public async Task Discover_streams_device_component_dataitem_tree_leaf_fullname_is_dataitemid()
{
var (driver, _) = await InitializedDriverAsync();
var cap = await DiscoverAsync(driver);
cap.Variables.Select(v => v.Attr.FullName).ShouldContain("dev1_system_cond");
cap.Variables.Single(v => v.Attr.IsAlarm).Attr.DriverDataType.ShouldBe(DriverDataType.String);
driver.SupportsOnlineDiscovery.ShouldBeTrue();
driver.RediscoverPolicy.ShouldBe(DiscoveryRediscoverPolicy.Once);
}
// ---- tree shape ----
/// <summary>
/// The folder tree mirrors the probe document exactly: one folder per Device (named by its
/// <c>name</c>), then one per nested Component to arbitrary depth, each under its own parent.
/// </summary>
[Fact]
public async Task Discover_materialises_a_folder_per_device_and_nested_component()
{
var (driver, _) = await InitializedDriverAsync();
var cap = await DiscoverAsync(driver);
cap.Folders.Select(f => f.Path).ShouldBe(
["VMC-3Axis", "VMC-3Axis/controller", "VMC-3Axis/controller/path"], ignoreOrder: true);
// Parentage, not just membership: a flat "three folders exist" assertion passes for a walker
// that streamed all three onto the root builder.
cap.Folders.Single(f => f.Path == "VMC-3Axis").ParentPath.ShouldBe(string.Empty);
cap.Folders.Single(f => f.Path == "VMC-3Axis/controller").ParentPath.ShouldBe("VMC-3Axis");
cap.Folders.Single(f => f.Path == "VMC-3Axis/controller/path").ParentPath.ShouldBe("VMC-3Axis/controller");
}
/// <summary>
/// <c>dev1_avail</c> hangs directly off <c>&lt;Device&gt;&lt;DataItems&gt;</c>, outside every
/// Component. A walker that only recursed <c>&lt;Components&gt;</c> would drop it silently, so
/// it is asserted to land in the <b>device</b> folder while the Path-owned items land in the
/// path folder.
/// </summary>
[Fact]
public async Task Discover_places_device_level_data_items_in_the_device_folder()
{
var (driver, _) = await InitializedDriverAsync();
var cap = await DiscoverAsync(driver);
cap.Variables.Single(v => v.Attr.FullName == "dev1_avail").ParentPath.ShouldBe("VMC-3Axis");
cap.Variables
.Where(v => v.Attr.FullName != "dev1_avail")
.ShouldAllBe(v => v.ParentPath == "VMC-3Axis/controller/path");
}
/// <summary>
/// Every DataItem the fixture declares is streamed exactly once, and every leaf's
/// <see cref="DriverAttributeInfo.FullName"/> is its <c>DataItem@id</c> — the read/subscribe
/// key, aligned with the browser's commit by construction.
/// </summary>
[Fact]
public async Task Discover_streams_every_data_item_once_with_fullname_equal_to_its_id()
{
var (driver, _) = await InitializedDriverAsync();
var cap = await DiscoverAsync(driver);
cap.Variables.Count.ShouldBe(FixtureDataItemIds.Length);
cap.Variables.Select(v => v.Attr.FullName).ShouldBe(FixtureDataItemIds, ignoreOrder: true);
}
/// <summary>
/// The <c>FullName</c>-is-the-<c>id</c> rule, asserted where the two can actually differ.
/// </summary>
/// <remarks>
/// <b>The fixture cannot prove this on its own</b> — its data items declare no <c>name</c>, so
/// <c>browseName</c> and <c>id</c> coincide and a driver that streamed the browse name as the
/// <c>FullName</c> would pass every fixture-based assertion in this file. This model gives
/// every data item a name that is disjoint from its id, so the two sets cannot be confused:
/// the commit key must be the id set, and the presentation must be the name set.
/// </remarks>
[Fact]
public async Task Discover_fullname_is_the_id_even_when_the_data_item_declares_a_different_name()
{
var probe = ModelWith(
new MTConnectDataItem("id_pos", "Xpos", "SAMPLE", "POSITION", null, "MILLIMETER", null, null),
new MTConnectDataItem("id_count", "PartsMade", "EVENT", "PART_COUNT", null, null, null, null),
new MTConnectDataItem("id_cond", "SystemHealth", "CONDITION", "SYSTEM", null, null, null, null),
new MTConnectDataItem(
"id_series", "Feed", "SAMPLE", "PATH_FEEDRATE", null, null, "TIME_SERIES", 10));
var (driver, _) = await InitializedDriverAsync(probe: probe);
var cap = await DiscoverAsync(driver);
cap.Variables.Select(v => v.Attr.FullName)
.ShouldBe(["id_pos", "id_count", "id_cond", "id_series"], ignoreOrder: true);
cap.Variables.Select(v => v.BrowseName)
.ShouldBe(["Xpos", "PartsMade", "SystemHealth", "Feed"], ignoreOrder: true);
// …and the id-keyed metadata still lands on the right leaf once the two differ.
cap.Variables.Single(v => v.Attr.FullName == "id_count").Attr.DriverDataType
.ShouldBe(DriverDataType.Int64);
cap.Variables.Single(v => v.Attr.IsAlarm).Attr.FullName.ShouldBe("id_cond");
cap.Variables.Single(v => v.Attr.IsArray).Attr.FullName.ShouldBe("id_series");
}
// ---- type shape (must equal MTConnectDataTypeInference, not a local recomputation) ----
/// <summary>
/// The per-category defaults reach the builder unchanged: SAMPLE ⇒ Float64, controlled
/// vocabulary / free-text EVENT ⇒ String, CONDITION ⇒ String.
/// </summary>
[Theory]
[InlineData("dev1_pos", DriverDataType.Float64)]
[InlineData("dev1_avail", DriverDataType.String)]
[InlineData("dev1_execution", DriverDataType.String)]
[InlineData("dev1_program", DriverDataType.String)]
[InlineData("dev1_system_cond", DriverDataType.String)]
public async Task Discover_stamps_the_inferred_data_type(string dataItemId, DriverDataType expected)
{
var (driver, _) = await InitializedDriverAsync();
var cap = await DiscoverAsync(driver);
cap.Variables.Single(v => v.Attr.FullName == dataItemId).Attr.DriverDataType.ShouldBe(expected);
}
/// <summary>
/// <c>PART_COUNT</c> is the live-only bug this driver's inference was already fixed for once:
/// the probe document spells it UPPER_SNAKE, so a match written against the Streams
/// document's <c>PartCount</c> types every real agent's part counter as
/// <see cref="DriverDataType.String"/> while a PascalCase unit test stays green. Asserted at
/// the discovery seam because that is where the probe spelling is actually read.
/// </summary>
[Fact]
public async Task Discover_types_the_upper_snake_PART_COUNT_event_as_Int64()
{
var (driver, _) = await InitializedDriverAsync();
var cap = await DiscoverAsync(driver);
cap.Variables.Single(v => v.Attr.FullName == "dev1_partcount").Attr.DriverDataType
.ShouldBe(DriverDataType.Int64);
}
/// <summary>
/// A <c>TIME_SERIES</c> SAMPLE is an array whose length is the probe-declared
/// <c>sampleCount</c>. The shape comes from <see cref="MTConnectDataTypeInference"/>'s
/// returned record — recomputing it inline at this seam is what makes discovery and the
/// AdminUI editor disagree.
/// </summary>
[Fact]
public async Task Discover_carries_the_time_series_array_shape_from_the_inference()
{
var (driver, _) = await InitializedDriverAsync();
var cap = await DiscoverAsync(driver);
var series = cap.Variables.Single(v => v.Attr.FullName == "dev1_vibration_ts").Attr;
series.DriverDataType.ShouldBe(DriverDataType.Float64);
series.IsArray.ShouldBeTrue();
series.ArrayDim.ShouldBe(10u);
}
/// <summary>
/// A <c>DATA_SET</c> SAMPLE demotes to <see cref="DriverDataType.String"/> and stays scalar —
/// a rule that lives <b>only</b> inside the inference. An inline
/// "IsArray = representation == TIME_SERIES, DataType = category == SAMPLE ? Float64 : String"
/// at this seam would type it Float64 and go Bad on every parse, and no fixture-only test
/// would notice.
/// </summary>
[Fact]
public async Task Discover_demotes_a_data_set_sample_to_string_per_the_inference()
{
var probe = ModelWith(
new MTConnectDataItem(
"dev9_toolset", null, "SAMPLE", "POSITION", null, "MILLIMETER", "DATA_SET", 4));
var (driver, _) = await InitializedDriverAsync(probe: probe);
var cap = await DiscoverAsync(driver);
var attr = cap.Variables.Single(v => v.Attr.FullName == "dev9_toolset").Attr;
attr.DriverDataType.ShouldBe(DriverDataType.String);
attr.IsArray.ShouldBeFalse();
attr.ArrayDim.ShouldBeNull();
}
/// <summary>
/// <c>TIME_SERIES</c> is defined for SAMPLE only; on an EVENT the inference ignores it. Pins
/// the other half of "use the inference's answer, do not recompute the array shape".
/// </summary>
[Fact]
public async Task Discover_ignores_time_series_on_a_non_sample_per_the_inference()
{
var probe = ModelWith(
new MTConnectDataItem("dev9_msg", null, "EVENT", "MESSAGE", null, null, "TIME_SERIES", 8));
var (driver, _) = await InitializedDriverAsync(probe: probe);
var cap = await DiscoverAsync(driver);
var attr = cap.Variables.Single(v => v.Attr.FullName == "dev9_msg").Attr;
attr.DriverDataType.ShouldBe(DriverDataType.String);
attr.IsArray.ShouldBeFalse();
attr.ArrayDim.ShouldBeNull();
}
// ---- the flags this seam owns ----
/// <summary>
/// <see cref="DriverAttributeInfo.IsAlarm"/> is the caller's job — the inference deliberately
/// does not compute it. Exactly the CONDITION data item carries it.
/// </summary>
[Fact]
public async Task Discover_marks_only_the_condition_data_item_as_an_alarm()
{
var (driver, _) = await InitializedDriverAsync();
var cap = await DiscoverAsync(driver);
cap.Variables.Where(v => v.Attr.IsAlarm).Select(v => v.Attr.FullName).ShouldBe(["dev1_system_cond"]);
}
/// <summary>
/// MTConnect is a read-only protocol and this driver implements no <c>IWritable</c>, so every
/// browsed leaf is <see cref="SecurityClassification.ViewOnly"/> — the tier that is read-only
/// from OPC UA. Nothing is historized by discovery either: historization is authored per tag,
/// never inferred from a device model.
/// </summary>
[Fact]
public async Task Discover_streams_every_leaf_view_only_and_not_historized()
{
var (driver, _) = await InitializedDriverAsync();
var cap = await DiscoverAsync(driver);
cap.Variables.ShouldAllBe(v => v.Attr.SecurityClass == SecurityClassification.ViewOnly);
cap.Variables.ShouldAllBe(v => !v.Attr.IsHistorized);
cap.Variables.ShouldAllBe(v => v.Attr.Source == NodeSourceKind.Driver);
}
// ---- browse names ----
/// <summary>
/// The browse name is the DataItem's <c>name</c> when it declares one and its <c>id</c>
/// otherwise — the fixture's data items declare none, so the fallback is the normal case for
/// this protocol, not an edge case.
/// </summary>
[Fact]
public async Task Discover_browse_name_prefers_the_data_item_name_and_falls_back_to_its_id()
{
var probe = ModelWith(
new MTConnectDataItem("dev9_named", "Xpos", "SAMPLE", "POSITION", null, "MILLIMETER", null, null),
new MTConnectDataItem("dev9_unnamed", null, "EVENT", "PROGRAM", null, null, null, null));
var (driver, _) = await InitializedDriverAsync(probe: probe);
var cap = await DiscoverAsync(driver);
var named = cap.Variables.Single(v => v.Attr.FullName == "dev9_named");
named.BrowseName.ShouldBe("Xpos");
named.DisplayName.ShouldBe("Xpos");
var unnamed = cap.Variables.Single(v => v.Attr.FullName == "dev9_unnamed");
unnamed.BrowseName.ShouldBe("dev9_unnamed");
// The browse name is presentation; the read key is not. Restated here because this is the
// one test where the two legitimately differ.
named.Attr.FullName.ShouldBe("dev9_named");
}
/// <summary>
/// A Device or Component with no <c>name</c> attribute falls back to its <c>id</c> rather
/// than materialising a blank folder.
/// </summary>
[Fact]
public async Task Discover_folder_names_fall_back_to_the_id_when_no_name_is_declared()
{
var probe = new MTConnectProbeModel(
[
new MTConnectDevice(
"dev9",
null,
[
new MTConnectComponent(
"dev9_axes",
null,
[],
[new MTConnectDataItem("dev9_x", null, "SAMPLE", "POSITION", null, null, null, null)]),
],
[]),
]);
var (driver, _) = await InitializedDriverAsync(probe: probe);
var cap = await DiscoverAsync(driver);
cap.Folders.Select(f => f.Path).ShouldBe(["dev9", "dev9/dev9_axes"], ignoreOrder: true);
cap.Variables.Single().ParentPath.ShouldBe("dev9/dev9_axes");
}
// ---- DeviceName scoping ----
/// <summary>
/// With no <c>DeviceName</c> the driver is agent-wide and every device's subtree is streamed.
/// The control for the scoping test below — without it, a discovery that dropped the second
/// device for an unrelated reason would look like correct scoping.
/// </summary>
[Fact]
public async Task Discover_without_a_device_scope_streams_every_device()
{
var (driver, _) = await InitializedDriverAsync(probe: TwoDeviceModel());
var cap = await DiscoverAsync(driver);
cap.Folders.Where(f => f.ParentPath.Length == 0).Select(f => f.BrowseName)
.ShouldBe(["VMC-3Axis", "Lathe-2Axis"], ignoreOrder: true);
cap.Variables.Select(v => v.Attr.FullName).ShouldContain("dev2_avail");
}
/// <summary>
/// With <c>DeviceName</c> set, only that device's subtree is streamed.
/// </summary>
/// <remarks>
/// Belt-and-braces rather than dead code: the production client already narrows the request
/// to <c>{AgentUri}/{DeviceName}/probe</c>, so a conforming Agent answers with one device
/// anyway. But a non-conforming Agent (or a proxy that drops the path segment) that answered
/// agent-wide would otherwise publish every other machine's data items into an instance
/// scoped to one — and the operator's only evidence would be a picker full of ids they never
/// configured.
/// </remarks>
[Fact]
public async Task Discover_with_a_device_scope_streams_only_that_device_subtree()
{
var (driver, _) = await InitializedDriverAsync(Opts(deviceName: "Lathe-2Axis"), TwoDeviceModel());
var cap = await DiscoverAsync(driver);
cap.Folders.Select(f => f.Path).ShouldBe(["Lathe-2Axis"]);
cap.Variables.Select(v => v.Attr.FullName).ShouldBe(["dev2_avail"]);
}
/// <summary>
/// A device scope naming a device the Agent does not declare streams nothing. Kept explicit
/// because the alternative reading ("scope did not match, so stream everything") would hand a
/// mis-typed device name a picker showing the whole plant.
/// </summary>
[Fact]
public async Task Discover_with_an_unmatched_device_scope_streams_nothing()
{
var (driver, _) = await InitializedDriverAsync(Opts(deviceName: "not-a-device"), TwoDeviceModel());
var cap = await DiscoverAsync(driver);
cap.Folders.ShouldBeEmpty();
cap.Variables.ShouldBeEmpty();
}
/// <summary>
/// A device with no <c>name</c> is addressable by its <c>id</c> — which is what a scoped
/// Agent URL would carry for it too.
/// </summary>
[Fact]
public async Task Discover_device_scope_matches_a_nameless_device_by_id()
{
var probe = new MTConnectProbeModel(
[
new MTConnectDevice(
"dev9", null, [], [new MTConnectDataItem("dev9_a", null, "EVENT", "PROGRAM", null, null, null, null)]),
new MTConnectDevice(
"dev8", "Other", [], [new MTConnectDataItem("dev8_a", null, "EVENT", "PROGRAM", null, null, null, null)]),
]);
var (driver, _) = await InitializedDriverAsync(Opts(deviceName: "dev9"), probe);
var cap = await DiscoverAsync(driver);
cap.Variables.Select(v => v.Attr.FullName).ShouldBe(["dev9_a"]);
}
// ---- the probe-cache contract (anti-wedge) ----
/// <summary>
/// Discovery is served from the cache <c>InitializeAsync</c> already populated — a browse
/// does not re-hit the Agent for a model it is holding.
/// </summary>
[Fact]
public async Task Discover_serves_from_the_cached_probe_model()
{
var (driver, client) = await InitializedDriverAsync();
client.ProbeCallCount.ShouldBe(1);
await DiscoverAsync(driver);
client.ProbeCallCount.ShouldBe(1);
}
/// <summary>
/// …and after <see cref="MTConnectDriver.FlushOptionalCachesAsync"/> has dropped that cache,
/// discovery re-fetches and still streams the full tree. This is the whole reason discovery
/// must go through <c>GetOrFetchProbeModelAsync</c> rather than reading the cached field: a
/// memory-budget flush must never leave browse permanently answering "this agent has no data
/// items".
/// </summary>
[Fact]
public async Task Discover_refetches_the_probe_model_after_a_cache_flush()
{
var (driver, client) = await InitializedDriverAsync();
await driver.FlushOptionalCachesAsync(TestContext.Current.CancellationToken);
driver.CachedProbeModel.ShouldBeNull();
var cap = await DiscoverAsync(driver);
client.ProbeCallCount.ShouldBe(2);
cap.Variables.Select(v => v.Attr.FullName).ShouldBe(FixtureDataItemIds, ignoreOrder: true);
driver.CachedProbeModel.ShouldNotBeNull();
}
// ---- discovery never touches the subscription surface ----
/// <summary>
/// Discovery is a pure read of the device model: it does not write the shared observation
/// index (the <c>/sample</c> pump is its sole writer) and it does not issue a <c>/current</c>.
/// A discovery that folded a snapshot into the index would be a second writer racing the
/// pump, rolling subscribed values backwards.
/// </summary>
[Fact]
public async Task Discover_does_not_touch_the_observation_index_or_call_current()
{
var options = new MTConnectDriverOptions
{
AgentUri = AgentUri,
Tags = [new MTConnectTagDefinition("dev1_pos", DriverDataType.Float64)],
};
var (driver, client) = await InitializedDriverAsync(options);
var index = driver.ObservationIndex;
var indexed = index.Count;
var currentCalls = client.CurrentCallCount;
await DiscoverAsync(driver);
ReferenceEquals(driver.ObservationIndex, index).ShouldBeTrue();
driver.ObservationIndex.Count.ShouldBe(indexed);
client.CurrentCallCount.ShouldBe(currentCalls);
}
// ---- failure posture: loud, never a silently-empty tree ----
/// <summary>
/// Discovery before <c>InitializeAsync</c> throws rather than streaming an empty tree.
/// </summary>
/// <remarks>
/// <b>This is the deliberate opposite of <see cref="MTConnectDriver.ReadAsync"/>'s
/// never-throw posture, and the difference is what the caller can do with the answer.</b> A
/// read has per-reference Bad status codes to report a failure <i>in-band</i>; a discovery
/// stream has no such channel — an empty tree is indistinguishable from "this Agent declares
/// no data items", which is the #485 shape (failure wearing success's clothes) and would read
/// to an operator in the browse picker as a working connection to an empty machine. Both
/// production callers handle the throw: the universal browser surfaces it as a failed browse,
/// and <c>DriverInstanceActor</c> logs it and retries.
/// </remarks>
[Fact]
public async Task Discover_before_initialize_throws_and_streams_nothing()
{
var (driver, client) = NewDriver();
var builder = new CapturingBuilder();
await Should.ThrowAsync<InvalidOperationException>(
() => driver.DiscoverAsync(builder, TestContext.Current.CancellationToken));
builder.Folders.ShouldBeEmpty();
builder.Variables.ShouldBeEmpty();
client.ProbeCallCount.ShouldBe(0);
}
/// <summary>Same posture after <c>ShutdownAsync</c> — a stopped driver has no model to browse.</summary>
[Fact]
public async Task Discover_after_shutdown_throws_and_streams_nothing()
{
var (driver, _) = await InitializedDriverAsync();
await driver.ShutdownAsync(TestContext.Current.CancellationToken);
var builder = new CapturingBuilder();
await Should.ThrowAsync<InvalidOperationException>(
() => driver.DiscoverAsync(builder, TestContext.Current.CancellationToken));
builder.Variables.ShouldBeEmpty();
}
/// <summary>
/// An Agent that fails the <c>/probe</c> a discovery needs fails the discovery — it does not
/// degrade to an empty tree. Same #485 reasoning as the un-initialized case.
/// </summary>
[Fact]
public async Task Discover_propagates_an_agent_probe_failure_rather_than_streaming_an_empty_tree()
{
var (driver, client) = await InitializedDriverAsync();
await driver.FlushOptionalCachesAsync(TestContext.Current.CancellationToken);
client.ProbeFailure = new HttpRequestException("agent down");
var builder = new CapturingBuilder();
await Should.ThrowAsync<HttpRequestException>(
() => driver.DiscoverAsync(builder, TestContext.Current.CancellationToken));
builder.Variables.ShouldBeEmpty();
}
/// <summary>Caller cancellation propagates, as it does on every other seam of this driver.</summary>
[Fact]
public async Task Discover_propagates_caller_cancellation()
{
var (driver, _) = await InitializedDriverAsync();
await driver.FlushOptionalCachesAsync(TestContext.Current.CancellationToken);
using var cts = new CancellationTokenSource();
await cts.CancelAsync();
await Should.ThrowAsync<OperationCanceledException>(
() => driver.DiscoverAsync(new CapturingBuilder(), cts.Token));
}
/// <summary>A null builder is a caller bug — the one thing this method is loud about up front.</summary>
[Fact]
public async Task Discover_with_a_null_builder_throws_ArgumentNullException()
{
var (driver, _) = await InitializedDriverAsync();
await Should.ThrowAsync<ArgumentNullException>(
() => driver.DiscoverAsync(null!, TestContext.Current.CancellationToken));
}
// ---- the browse opt-in ----
/// <summary>
/// The universal browser's <c>CanBrowse</c> constructs a throwaway instance purely to read
/// these two members, so they must answer on an <b>un-initialized</b> driver without
/// dialling anything.
/// </summary>
[Fact]
public void Browse_opt_in_answers_on_an_uninitialized_instance_without_connecting()
{
var (driver, client) = NewDriver();
driver.ShouldBeAssignableTo<ITagDiscovery>();
driver.SupportsOnlineDiscovery.ShouldBeTrue();
driver.RediscoverPolicy.ShouldBe(DiscoveryRediscoverPolicy.Once);
client.ProbeCallCount.ShouldBe(0);
client.CurrentCallCount.ShouldBe(0);
}
// ---- helpers ----
/// <summary>A one-device model whose single Path component owns <paramref name="dataItems"/>.</summary>
private static MTConnectProbeModel ModelWith(params MTConnectDataItem[] dataItems) =>
new(
[
new MTConnectDevice(
"dev9",
"Probe9",
[new MTConnectComponent("dev9_path", "path", [], dataItems)],
[]),
]);
/// <summary>
/// The canned fixture's device plus a second, independent one — the multi-device Agent the
/// <c>DeviceName</c> scope exists for.
/// </summary>
private static MTConnectProbeModel TwoDeviceModel()
{
var fixture = MTConnectProbeParser.Parse(File.ReadAllText("Fixtures/probe.xml"));
var second = new MTConnectDevice(
"dev2",
"Lathe-2Axis",
[],
[new MTConnectDataItem("dev2_avail", null, "EVENT", "AVAILABILITY", null, null, null, null)]);
return new MTConnectProbeModel([.. fixture.Devices, second]);
}
}