lmxopcua/docs/drivers/OpcUaClient-Test-Fixture.md

# OPC UA Client test fixture

This is the fixture and command map for the driver/browser upgrade from SDK
**1.5.378.182** to exact **2.0.1** (#782). It describes available tests; execution,
counts, skips and release decisions belong in [#782](https://gitea.dohertylan.com/dohertj2/lmxopcua/issues/782)
and the linked [execution evidence](../plans/2026-11-10-opcua-sdk-2-evidence.md).
A listed test or historical run is not candidate release evidence.

## Fixture layers

| Layer | Repository location | Scope and limitation |
|---|---|---|
| Driver unit | `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/` | Faked session contracts: lifecycle/generations, value conversion, per-item errors, policy selection, credentials, namespace remapping, subscription cleanup, discovery, alarms and host-owned reinitialization. No real secure channel. |
| Browser unit | `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser.Tests/` | Browse attributes/pagination and certificate-identity ownership, including failure cleanup. No external server. |
| In-process wire | `tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/` | Real driver against OtOpcUa: `OpcUaClientDriverWireTests`, `OpcUaClientDriverStallWireTests`, `OpcUaClientDriverReconnectWireTests`. Real channels but both sides use this repository's SDK. |
| External simulator | `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/` | `OpcUaClientSmokeTests`: real read, varied-type batch read and subscription against opc-plc. Does not prove all upstream products, secured authentication, write or alarm compatibility. |
| Browser integration | `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser.IntegrationTests/` | Separate fixture-backed browser tests; inspect fixture availability and individual results. |

The SDK 2 unit boundary cases include `OpcUaClientSdkValueBoundaryTests` and
`OpcUaClientContinuationPointReleaseTests`. They preserve CLR value types and
null/empty buffers, reject unsupported matrix items without shifting batch results,
and release abandoned browse points. Certificate tests cover lifetime through
session close; unit mocks alone do not establish trust-chain interoperability.

The in-process stall proxy holds bytes without closing the session, then resumes;
its hard-close case refuses connections. These exercise stale notification rejection,
quality transitions and explicit host reinitialization. The driver does not use
`SessionReconnectHandler` or `TransferSubscriptions`; historical transfer-based
coverage descriptions do not apply to the current lifecycle (#670/#676).

The driver has **no upstream HistoryRead capability** (#655). Its tags can be
recorded into the local server-wide historian; backend conformance and aggregate
oracles are documented in [Historian.md](../Historian.md).

## Running locally

Run from the repository root. Build first and use a fresh result directory for
**each** project. The [runbook](../plans/2026-11-10-opcua-sdk-2-rollout.md#verification-commands)
provides the result helper that preserves test exit status and rejects all-skipped
runs. For example, after defining that helper:

```bash
opc_test tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests.csproj
opc_test tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser.Tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser.Tests.csproj
opc_test tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests.csproj
```

The simulator compose file is
`tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/Docker/docker-compose.yml`.
It launches `mcr.microsoft.com/iotedge/opc-plc:2.14.10` with `--ut --aa --alm --pn=50000`.
Use the shared-host procedure in [infra/README.md](../../infra/README.md); coordinate
shared fixture use before restarting containers. These dev flags do not establish
production trust or secure-policy coverage.

`OpcPlcFixture` probes `OPCUA_SIM_ENDPOINT` (default `opc.tcp://10.100.0.35:50000`)
and skips when unavailable. With an available, reserved fixture:

```bash
export OPCUA_SIM_ENDPOINT=opc.tcp://10.100.0.35:50000
opc_test tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests.csproj
```

A nonzero suite count does not prove every required scenario ran: inspect individual
TRX results and record required skips separately. No tests were run by preparing
this documentation.

## Required compatibility evidence

Release validation must identify both application builds and SDK versions, endpoint
policy, token kind, certificate chain, configuration and executed capabilities.
Use the baseline client against the candidate server and candidate client against
the baseline server, plus the actual ScadaBridge adapter and external upstreams.
For secured paths include trusted SignAndEncrypt, API-key allow/deny/revocation,
certificate rejection and restart/rebind. Apply only operations the peer implements;
a simulator need not implement OtOpcUa's API-key or historian contract.

For alarms verify typed EventFilter select clauses, result-field indexes, actual
ConditionType/SourceNode/EventId identity, refresh, acknowledgements and no replay
after an ambiguous transport failure. For all supported paths preserve existing
operation statuses, locale behavior and null/empty filter meaning. Constructing an
empty SDK 2 `ContentFilter` is an API adaptation, not evidence of a changed filter
contract. Record any stricter protocol response and consumer impact before acceptance.

opc-plc uses the OPC Foundation stack too. Independent upstream behavior, secured
authentication variants, large publish queues, real alarm products, packet-loss
windows and performance require separate evidence. The rollout runbook links the
pending gates; no simulator run substitutes for ScadaBridge, live gateway, Windows,
Linux or mixed-version cluster validation.