Files

Joseph Doherty 1d3544f18e S7 integration fixture — python-snap7 server closes the wire-level coverage gap (#216 ) + per-driver fixture coverage docs for every driver in the fleet. Closes #216 . Two shipments in one PR because the docs landed as I surveyed each driver's fixture + the S7 work is the first wire-level-gap closer pulled from that survey.

S7 integration — AbCip/Modbus already have real-simulator integration suites; S7 had zero wire-level coverage despite being a Tier-A driver (all unit tests mocked IS7Client). Picked python-snap7's `snap7.server.Server` over raw Snap7 C library because `pip install` beats per-OS binary-pin maintenance, the package ships a Python __main__ shim that mirrors our existing pymodbus serve.ps1 + *.json pattern structurally, and the python-snap7 project is actively maintained. New project `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/` with four moving parts: (a) `Snap7ServerFixture` — collection-scoped TCP probe on `localhost:1102` that sets `SkipReason` when the simulator's not running, matching the `ModbusSimulatorFixture` shape one directory over (same S7_SIM_ENDPOINT env var override convention for pointing at a real S7 CPU on port 102); (b) `PythonSnap7/` — `serve.ps1` wrapper + `server.py` shim + `s7_1500.json` seed profile + `README.md` documenting install / run / known limitations; (c) `S7_1500/S7_1500Profile.cs` — driver-side `S7DriverOptions` whose tag addresses map 1:1 to the JSON profile's seed offsets (DB1.DBW0 u16, DB1.DBW10 i16, DB1.DBD20 i32, DB1.DBD30 f32, DB1.DBX50.3 bool, DB1.DBW100 scratch); (d) `S7_1500SmokeTests` — three tests proving typed reads + write-then-read round-trip work through real S7netplus + real ISO-on-TCP + real snap7 server. Picked port 1102 default instead of S7-standard 102 because 102 is privileged on Linux + triggers Windows Firewall prompt; S7netplus 0.20 has a 5-arg `Plc(CpuType, host, port, rack, slot)` ctor that lets the driver honour `S7DriverOptions.Port`, but the existing driver code called the 4-arg overload + silently hardcoded 102. One-line driver fix (S7Driver.cs:87) threads `_options.Port` through — the S7 unit suite (58/58) still passes unchanged because every unit test uses a fake IS7Client that never sees the real ctor. Server seed-type matrix in `server.py` covers u8 / i8 / u16 / i16 / u32 / i32 / f32 / bool-with-bit / ascii (S7 STRING with max_len header). register_area takes the SrvArea enum value, not the string name — a 15-minute debug after the first test run caught that; documented inline.

Per-driver test-fixture coverage docs — eight new files in `docs/drivers/` laying out what each driver's harness actually benchmarks vs. what's trusted from field deployments. Pattern mirrors the AbServer-Test-Fixture.md doc that shipped earlier in this arc: TL;DR → What the fixture is → What it actually covers → What it does NOT cover → When-to-trust table → Follow-up candidates → Key files. Ugly truth the survey made visible: Galaxy + Modbus + (now) S7 + AB CIP have real wire-level coverage; AB Legacy / TwinCAT / FOCAS / OpcUaClient are still contract-only because their libraries ship no fake + no open-source simulator exists (AB Legacy PCCC), no public simulator exists (FOCAS), the vendor SDK has no in-process fake (TwinCAT/ADS.NET), or the test wiring just hasn't happened yet (OpcUaClient could trivially loopback against this repo's own server — flagged as #215). Each doc names the specific follow-up route: Snap7 server for S7 (done), TwinCAT 3 developer-runtime auto-restart for TwinCAT, Tier-C out-of-process Host for FOCAS, lab rigs for AB Legacy + hardware-gated bits of the others. `docs/drivers/README.md` gains a coverage-map section linking all eight. Tracking tasks #215-#222 filed for each PR-able follow-up.

Build clean (driver + integration project + docs); S7.Tests 58/58 (unchanged); S7.IntegrationTests 3/3 (new, verified end-to-end against a live python-snap7 server: `driver_reads_seeded_u16_through_real_S7comm`, `driver_reads_seeded_typed_batch`, `driver_write_then_read_round_trip_on_scratch_word`). Next fixture follow-up is #215 (OpcUaClient loopback against own server) — highest ROI of the remaining set, zero external deps.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-20 11:29:15 -04:00

6.0 KiB

Raw Blame History

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:

Prosys OPC UA Simulation Server — free, Windows-available, scriptable.
UaExpert Server-Side Simulator — Unified Automation's sample server; good coverage of typed ConditionType events.
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

6.0 KiB Raw Blame History Unescape Escape