feat(cli): historyread --events reads event history over the wire (lmxopcua#776)
v2-ci / unit-tests (push) Has been cancelled

Item 1 of #776 (the B2 over-the-wire ask): Client.CLI had no way to issue a
HistoryReadEvents. `historyread --events` now sends ReadEventDetails to an
event notifier and prints one line per event in select-clause order.
--fields picks the select clauses (default EventId, EventType, Time,
SourceName, Severity, Message, ConditionName (on ConditionType), SourceNode);
--of-type adds an OfType where-clause. --events is exclusive with --modified /
--aggregate, and --fields / --of-type require it.

Client.Shared gains IOpcUaClientService/ISessionAdapter.HistoryReadEventsAsync
(default-implemented as NotSupported for other implementations) backed by the
real session adapter through HistoryReadPaging, so continuation points are
followed up to --max and a Bad node status is surfaced, not printed as empty.

Tests: CLI tests over the fake service (default filter, --fields/--of-type
filter, option conflicts); an over-the-wire test drives the shared client's
event read against the in-process server — the default fields come back
non-null, OfType filters, an invalid where-clause is BadEventFilterInvalid.
The other #776 items are decisions and are left open.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 16:07:11 -05:00
parent e790938f94
commit 380ec541c2
11 changed files with 369 additions and 4 deletions
@@ -344,6 +344,21 @@ public sealed class FakeOpcUaClientService : IOpcUaClientService
return Task.FromResult(HistoryReadModifiedResult);
}
/// <summary>Gets the (NodeId, start, end, filter, maxEvents) tuples from HistoryReadEventsAsync calls.</summary>
public List<(NodeId NodeId, DateTime Start, DateTime End, EventFilter Filter, int MaxEvents)> HistoryReadEventsCalls { get; } = [];
/// <summary>Gets or sets the events returned by HistoryReadEventsAsync.</summary>
public IReadOnlyList<HistoryEventEntry> HistoryReadEventsResult { get; set; } = [];
/// <inheritdoc />
public Task<IReadOnlyList<HistoryEventEntry>> HistoryReadEventsAsync(NodeId nodeId, DateTime startTime, DateTime endTime,
EventFilter filter, int maxEvents = 1000, CancellationToken ct = default)
{
HistoryReadEventsCalls.Add((nodeId, startTime, endTime, filter, maxEvents));
if (HistoryReadException != null) throw HistoryReadException;
return Task.FromResult(HistoryReadEventsResult);
}
/// <summary>Gets the details passed to HistoryUpdateAsync.</summary>
public List<HistoryUpdateDetails> HistoryUpdateCalls { get; } = [];
@@ -182,6 +182,98 @@ public class HistoryReadCommandTests
output.ShouldContain("2 modifications returned.");
}
/// <summary>#776: --events reads event history with the default select clauses and prints one line per event.</summary>
[Fact]
public async Task Execute_EventRead_CallsHistoryReadEvents_with_the_default_fields_and_prints_each_event()
{
var t = new DateTime(2025, 6, 15, 10, 0, 0, DateTimeKind.Utc);
var fakeService = new FakeOpcUaClientService
{
HistoryReadEventsResult =
[
new HistoryEventEntry([
new Variant(new byte[] { 0xAB, 0x01 }), new Variant(ObjectTypeIds.LimitAlarmType), new Variant(t),
new Variant("Tank1"), new Variant((ushort)700), new Variant(new LocalizedText("high level")),
new Variant("temp_hi"), Variant.Null,
]),
],
};
var command = new HistoryReadCommand(new FakeOpcUaClientServiceFactory(fakeService))
{
Url = "opc.tcp://localhost:4840",
NodeId = "ns=2;s=Area/Line/Tank1",
Events = true,
MaxValues = 25,
};
using var console = TestConsoleHelper.CreateConsole();
await command.ExecuteAsync(console);
var call = fakeService.HistoryReadEventsCalls.ShouldHaveSingleItem();
call.MaxEvents.ShouldBe(25);
call.Filter.SelectClauses.Select(c => c.BrowsePath.ShouldHaveSingleItem().Name)
.ShouldBe(["EventId", "EventType", "Time", "SourceName", "Severity", "Message", "ConditionName", "SourceNode"]);
call.Filter.SelectClauses.Single(c => c.BrowsePath[0].Name == "ConditionName").TypeDefinitionId
.ShouldBe(ObjectTypeIds.ConditionType);
call.Filter.WhereClause.Elements.ShouldBeEmpty("no --of-type, no where-clause");
fakeService.HistoryReadRawCalls.ShouldBeEmpty();
var output = TestConsoleHelper.GetOutput(console);
output.ShouldContain("Event history for ns=2;s=Area/Line/Tank1");
output.ShouldContain("EventId | EventType | Time | SourceName | Severity | Message | ConditionName | SourceNode");
output.ShouldContain($"AB01 | {ObjectTypeIds.LimitAlarmType} | {t:O} | Tank1 | 700 | high level | temp_hi | -");
output.ShouldContain("1 events returned.");
}
/// <summary>#776: --fields picks the select clauses and --of-type adds an OfType where-clause.</summary>
[Fact]
public async Task Execute_EventRead_with_fields_and_of_type_builds_that_filter()
{
var fakeService = new FakeOpcUaClientService();
var command = new HistoryReadCommand(new FakeOpcUaClientServiceFactory(fakeService))
{
Url = "opc.tcp://localhost:4840",
NodeId = "ns=2;s=Area/Line/Tank1",
Events = true,
Fields = "EventType, Severity",
OfType = "i=2955",
};
using var console = TestConsoleHelper.CreateConsole();
await command.ExecuteAsync(console);
var filter = fakeService.HistoryReadEventsCalls.ShouldHaveSingleItem().Filter;
filter.SelectClauses.Select(c => c.BrowsePath[0].Name).ShouldBe(["EventType", "Severity"]);
var element = filter.WhereClause.Elements.ShouldHaveSingleItem();
element.FilterOperator.ShouldBe(FilterOperator.OfType);
((LiteralOperand)ExtensionObject.ToEncodeable(element.FilterOperands[0])).Value.Value
.ShouldBe(ObjectTypeIds.LimitAlarmType);
TestConsoleHelper.GetOutput(console).ShouldContain("0 events returned.");
}
/// <summary>#776: --events cannot be mixed with the other read modes, and --fields/--of-type need --events.</summary>
[Theory]
[InlineData(true, true, null, null)]
[InlineData(true, false, "Average", null)]
[InlineData(false, false, null, "EventType")]
public async Task Execute_EventRead_option_conflicts_throw(bool events, bool modified, string? aggregate, string? fields)
{
var fakeService = new FakeOpcUaClientService();
var command = new HistoryReadCommand(new FakeOpcUaClientServiceFactory(fakeService))
{
Url = "opc.tcp://localhost:4840",
NodeId = "ns=2;s=HistNode",
Events = events,
Modified = modified,
Aggregate = aggregate,
Fields = fields,
};
using var console = TestConsoleHelper.CreateConsole();
await Should.ThrowAsync<CliFx.Exceptions.CommandException>(async () => await command.ExecuteAsync(console));
fakeService.HistoryReadEventsCalls.ShouldBeEmpty();
}
/// <summary>--modified cannot be combined with --aggregate.</summary>
[Fact]
public async Task Execute_ModifiedWithAggregate_ThrowsCommandException()