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

Siemens S7 test fixture

Coverage map + gap inventory for the S7 driver.

TL;DR: S7 now has a wire-level integration fixture backed by python-snap7's Server class (task #216). Atomic reads (u16 / i16 / i32 / f32 / bool-with-bit) + DB write-then-read round-trip are exercised end-to-end through S7netplus + real ISO-on-TCP on localhost:1102. Unit tests still carry everything else (address parsing, error-branch handling, probe-loop contract). Gaps remaining are variant-quirk-shaped: Optimized-DB symbolic access, PG/OP session types, PUT/GET-disabled enforcement — all need real hardware.

What the fixture is

Integration layer (task #216): tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/ stands up a python-snap7 Server via Docker/docker-compose.yml --profile s7_1500 on localhost:1102 (pinned python:3.12-slim-bookworm base + python-snap7>=2.0). Docker is the only supported launch path. Snap7ServerFixture probes the port at collection init + skips with a clear message when unreachable (matches the pymodbus pattern). server.py (baked into the image under Docker/) reads a JSON profile

• seeds DB/MB bytes at declared offsets; seeds are typed (u16 / i16 / i32 / f32 / bool / ascii for S7 STRING).

Unit layer: tests/ZB.MOM.WW.OtOpcUa.Driver.S7.Tests/ covers everything the wire-level suite doesn't — address parsing, error branches, probe-loop contract. All tests tagged [Trait("Category", "Unit")].

The driver ctor change that made this possible: Plc(CpuType, host, port, rack, slot) — S7netplus 0.20's 5-arg overload — wires S7DriverOptions.Port through so the simulator can bind 1102 (non-privileged) instead of 102 (root / Firewall-prompt territory).

What it actually covers

Integration (python-snap7, task #216)

• S7_1500SmokeTests.Driver_reads_seeded_u16_through_real_S7comm — DB1.DBW0 read via real S7netplus over TCP + simulator; proves handshake + read path
• S7_1500SmokeTests.Driver_reads_seeded_typed_batch — i16, i32, f32, bool-with-bit in one batch call; proves typed decode per S7DataType
• S7_1500SmokeTests.Driver_write_then_read_round_trip_on_scratch_word — DB1.DBW100 write → read-back; proves write path + buffer visibility
• S7_1500DiagnosticsTests.Driver_exposes_negotiated_pdu_size_post_init — asserts DriverHealth.Diagnostics["S7.NegotiatedPduSize"] is non-zero after InitializeAsync; proves the negotiated PDU size surfaces in driver health (Snap7 fixture pins this at 240 bytes — see fixture README)

Unit

• S7AddressParserTests — S7 address syntax (DB1.DBD0, M10.3, IW4, etc.)
• S7DriverScaffoldTests — IDriver lifecycle (init / reinit / shutdown / health)
• S7DriverReadWriteTests — error paths (uninitialized read/write, bad addresses, transport exceptions)
• S7DiscoveryAndSubscribeTests — ITagDiscovery.DiscoverAsync + polled ISubscribable contract with the shared PollGroupEngine

Capability surfaces whose contract is verified: IDriver, ITagDiscovery, IReadable, IWritable, ISubscribable, IHostConnectivityProbe. Wire-level surfaces verified: IReadable, IWritable.

What it does NOT cover

1. Wire-level anything

No ISO-on-TCP frame is ever sent during the test suite. S7netplus is the only wire-path abstraction and it has no in-process fake mode; the shipping choice was to contract-test via IS7Client rather than patch into S7netplus internals.

2. Read/write happy path

Every S7DriverReadWriteTests case exercises error branches. A successful read returning real PLC data is not tested end-to-end — the return value is whatever the fake says it is.

3. Mailbox serialization under concurrent reads

The driver's SemaphoreSlim serializes S7netplus calls because the S7 CPU's comm mailbox is scanned at most once per cycle. Contention behavior under real PLC latency is not exercised.

4. Variant quirks

S7-1200 vs S7-1500 vs S7-300/400 connection semantics (PG vs OP vs S7-Basic) not differentiated at test time.

5. Data types beyond the scalars

STRING with length-prefix quirks, DTL / DATE_AND_TIME, arrays of structs — not covered. UDT fan-out IS covered (PR-S7-D2 / #300) via the udt_layout meta-seed in Docker/profiles/s7_1500.json and the Driver_fans_out_udt_into_member_tags integration test.

When to trust the S7 tests, when to reach for a rig

Question	Unit tests	Real PLC
"Does the address parser accept X syntax?"	yes	-
"Does the driver lifecycle hang / crash?"	yes	yes
"Does a real read against an S7-1500 return correct bytes?"	no	yes (required)
"Does mailbox serialization actually prevent PG timeouts?"	no	yes (required)
"Does a UDT fan-out produce usable member variables?"	yes (Snap7 + udt_layout meta-seed)	yes

Follow-up candidates

1. Snap7 server — Snap7 ships a C-library-based S7 server that could run in-CI on Linux. A pinned build + a fixture shape similar to ab_server would give S7 parity with Modbus / AB CIP coverage.
2. Plcsim Advanced — Siemens' paid emulator. Licensed per-seat; fits a lab rig but not CI.
3. Real S7 lab rig — cheapest physical PLC (CPU 1212C) on a dedicated network port, wired via self-hosted runner.
4. PR-S7-C5 — PUT/GET-disabled pre-flight rejection. Snap7 does not model the hardened-CPU PUT/GET response (it accepts every read once the COTP handshake completes), so the failure path of the pre-flight probe — S7PutGetDisabledException thrown from InitializeAsync when the PLC rejects the probe read with ErrorCode.WrongCPU_Type / ErrorCode.ReadData — needs a real S7-1500 with PUT/GET disabled in TIA Portal. The integration suite covers the happy path (Driver_preflight_passes_when_probe_address_seeded); the failure path should be added as a --with-real-plc opt-in test that the self-hosted runner with the lab rig executes. The classifier branch (S7PreflightClassifier.IsPutGetDisabled) is unit-tested without a network in S7PreflightTests.Classifier_matches_only_PUT_GET_disabled_error_codes.

Without any of these, S7 driver correctness against real hardware is trusted from field deployments, not from the test suite.

Key fixture / config files

• tests/ZB.MOM.WW.OtOpcUa.Driver.S7.Tests/ — unit tests only, no harness
• src/ZB.MOM.WW.OtOpcUa.Driver.S7/S7Driver.cs — ctor takes IS7ClientFactory which tests fake; docstring lines 8-20 note the deferred integration fixture