# OPC UA Client test fixture

Coverage map + gap inventory for the OPC UA Client (gateway / aggregation)
driver.

**TL;DR: there is no integration fixture.** Tests mock the OPC UA SDK's
`Session` + `Subscription` types directly; there is no upstream OPC UA
server standup in CI. The irony is not lost — this repo *is* an OPC UA
server, and the integration fixtures for `OpcUaApplicationHost`
(`tests/ZB.MOM.WW.OtOpcUa.Server.Tests/OpcUaServerIntegrationTests.cs` +
`OpcUaEquipmentWalkerIntegrationTests.cs`) stand up the server-side stack
end-to-end. The client-side driver could in principle wire against one of
those, but doesn't today.

## What the fixture is

Nothing at the integration layer.
`tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/` is unit-only. Tests
inject fakes through the driver's construction path; the
OPCFoundation.NetStandard `Session` surface is wrapped behind an interface
the tests mock.

## What it actually covers (unit only)

The surface is broad because `OpcUaClientDriver` is the richest-capability
driver in the fleet (it's a gateway for another OPC UA server, so it
mirrors the full capability matrix):

- `OpcUaClientDriverScaffoldTests` — `IDriver` lifecycle
- `OpcUaClientReadWriteTests` — read + write lifecycle
- `OpcUaClientSubscribeAndProbeTests` — monitored-item subscription + probe
  state transitions
- `OpcUaClientDiscoveryTests` — `GetEndpoints` + endpoint selection
- `OpcUaClientAttributeMappingTests` — OPC UA node attribute → driver value
  mapping
- `OpcUaClientSecurityPolicyTests` — `SignAndEncrypt` / `Sign` / `None`
  policy negotiation contract
- `OpcUaClientCertAuthTests` — cert store paths, revocation-list config
- `OpcUaClientReconnectTests` — SDK reconnect hook + `TransferSubscriptions`
  across the disconnect boundary
- `OpcUaClientFailoverTests` — primary → secondary session fallback per
  driver config
- `OpcUaClientAlarmTests` — A&E severity bucket (1–1000 → Low / Medium /
  High / Critical), subscribe / unsubscribe / ack contract
- `OpcUaClientHistoryTests` — historical data read + interpolation contract

Capability surfaces whose contract is verified: `IDriver`, `ITagDiscovery`,
`IReadable`, `IWritable`, `ISubscribable`, `IHostConnectivityProbe`,
`IAlarmSource`, `IHistoryProvider`.

## What it does NOT cover

### 1. Real stack exchange

No UA Secure Channel is ever opened. Every test mocks `Session.ReadAsync`,
`Session.CreateSubscription`, `Session.AddItem`, etc. — the SDK itself is
trusted. Certificate validation, signing, nonce handling, chunk assembly,
keep-alive cadence — all SDK-internal and untested here.

### 2. Subscription transfer across reconnect

Contract test: "after a simulated reconnect, `TransferSubscriptions` is
called with the right handles." Real behavior: SDK re-publishes against the
new channel and some events can be lost depending on publish-queue state.
The lossy window is not characterized.

### 3. Large-scale subscription stress

100+ monitored items with heterogeneous publish intervals under a single
session — the shape that breaks publish-queue-size tuning in the wild — is
not exercised.

### 4. Real historian mappings

`IHistoryProvider.ReadRawAsync` + `ReadProcessedAsync` +
`ReadAtTimeAsync` + `ReadEventsAsync` are contract-mocked. Against a real
historian (AVEVA Historian, Prosys historian, Kepware LocalHistorian) each
has specific interpolation + bad-quality-handling quirks the contract test
doesn't see.

### 5. Real A&E events

Alarm subscription is mocked via filtered monitored items; the actual
`EventFilter` select-clause behavior against a server that exposes typed
ConditionType events (non-base `BaseEventType`) is not verified.

### 6. Authentication variants

- Anonymous, UserName/Password, X509 cert tokens — each is contract-tested
  but not exchanged against a server that actually enforces each.
- LDAP-backed `UserName` (matching this repo's server-side
  `LdapUserAuthenticator`) requires a live LDAP round-trip; not tested.

## When to trust OpcUaClient tests, when to reach for a server

| Question | Unit tests | Real upstream server |
| --- | --- | --- |
| "Does severity 750 bucket as High?" | yes | yes |
| "Does the driver call `TransferSubscriptions` after reconnect?" | yes | yes |
| "Does a real OPC UA read/write round-trip work?" | no | yes (required) |
| "Does event-filter-based alarm subscription return ConditionType events?" | no | yes (required) |
| "Does history read from AVEVA Historian return correct aggregates?" | no | yes (required) |
| "Does the SDK's publish queue lose notifications under load?" | no | yes (stress) |

## Follow-up candidates

The easiest win here is to **wire the client driver tests against this
repo's own server**. The integration test project
`tests/ZB.MOM.WW.OtOpcUa.Server.Tests/OpcUaServerIntegrationTests.cs`
already stands up a real OPC UA server on a non-default port with a seeded
FakeDriver. An `OpcUaClientLiveLoopbackTests` that connects the client
driver to that server would give:

- Real Secure Channel negotiation
- Real Session / Subscription / MonitoredItem exchange
- Real read/write round-trip
- Real certificate validation (the integration test already sets up PKI)

It wouldn't cover upstream-server-specific quirks (AVEVA Historian, Kepware,
Prosys), but it would cover 80% of the SDK surface the driver sits on top
of.

Beyond that:

1. **Prosys OPC UA Simulation Server** — free, Windows-available, scriptable.
2. **UaExpert Server-Side Simulator** — Unified Automation's sample server;
   good coverage of typed ConditionType events.
3. **Dedicated historian integration lab** — only path for
   historian-specific coverage.

## Key fixture / config files

- `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/` — unit tests with
  mocked `Session`
- `src/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/OpcUaClientDriver.cs` — ctor +
  session-factory seam tests mock through
- `tests/ZB.MOM.WW.OtOpcUa.Server.Tests/OpcUaServerIntegrationTests.cs` —
  the server-side integration harness a future loopback client test could
  piggyback on