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](https://github.com/gijzelaerr/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 `10.100.0.35:1102` (the shared Docker host; override via
`S7_SIM_ENDPOINT`). 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/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/` stands up a
python-snap7 `Server` via `Docker/docker-compose.yml --profile s7_1500`
on `10.100.0.35:1102` (the shared Docker host; override via `S7_SIM_ENDPOINT`;
pinned `python:3.12-slim-bookworm` base +
`python-snap7>=2.0`). Docker is the only supported launch path.
Tests that WRITE to the endpoint (currently `S7_1500ArrayWriteTests`) additionally require
`S7_SIM_ALLOW_WRITES=1`, because `S7_SIM_ENDPOINT` can be pointed at a real CPU; they skip without it.
`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/Drivers/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_1500CodecTests` (#632/#638) — live python-snap7 coverage of the STRING / WSTRING / CHAR / WCHAR /
  DTL / DATE / TOD / TIME / S5TIME codecs: seeded reads (DB1 800..960, distinct non-zero), BadOutOfRange
  reads of undecodable buffers, write round-trips and BadOutOfRange refused writes (scratch DB1 1100..1199;
  needs `S7_SIM_ALLOW_WRITES=1`), the `LocalTsap`/`RemoteTsap`/`ConnectionType` override keys (proves they
  reach the wire; snap7 accepts any TSAP, so TSAP semantics remain hardware-only), and the negotiated PDU
  size (`NegotiatedPduSize` / `GetDiagnostics`). Seed map in `Docker/README.md`.

### 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 (unit tests only)

The **unit** suite (`S7DriverReadWriteTests`, etc.) sends no real ISO-on-TCP
frames. S7netplus has no in-process fake mode; units contract-test via the
`IS7Client` abstraction. The **integration** suite (`S7_1500SmokeTests`, task
#216) does send real S7comm over ISO-on-TCP against the python-snap7 container
and covers the basic read / write / typed-batch path.

### 2. Error-branch unit tests vs. real round-trips

`S7DriverReadWriteTests` (unit) exercises error paths only; return values come
from the fake. The integration suite exercises the successful read / write
round-trip, but only against the python-snap7 emulator — not a real Siemens
CPU.

### 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

UDT fan-out, `STRING` with length-prefix quirks, `DTL` / `DATE_AND_TIME`,
arrays of structs — not covered.

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

| Question | Unit tests | Integration (python-snap7) | Real PLC |
| --- | --- | --- | --- |
| "Does the address parser accept X syntax?" | yes | - | - |
| "Does the driver lifecycle hang / crash?" | yes | yes | yes |
| "Does a real read against an S7-1500 return correct bytes?" | no | yes (basic scalars) | yes (required for full type matrix) |
| "Does mailbox serialization actually prevent PG timeouts?" | no | no | yes (required) |
| "Does a UDT fan-out produce usable member variables?" | no | no | yes (required) |

## Follow-up candidates

The python-snap7 fixture (task #216) covers scalar read / write / typed-batch.
Remaining gaps need one of:

1. **Plcsim Advanced** — Siemens' paid emulator; gives Optimized-DB symbolic
   access + PG/OP/S7-Basic session differentiation without real hardware.
   Licensed per-seat; fits a lab rig but not CI.
2. **Real S7 lab rig** — cheapest physical PLC (CPU 1212C) on a dedicated
   network port, wired via self-hosted runner. Only path for mailbox
   serialization / PUT-GET enforcement verification.

Without either, S7 driver correctness for variant-quirk edge cases is trusted
from field deployments, not from the test suite.

## Key fixture / config files

- `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.Tests/` — unit tests only, no harness
- `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Snap7ServerFixture.cs`
  — collection fixture; parses `S7_SIM_ENDPOINT` (default `10.100.0.35:1102`),
  TCP-probes at collection init, records `SkipReason` when unreachable
- `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/S7_1500/S7_1500SmokeTests.cs`
  — wire-level test suite (3 `[Fact]` methods: u16 read, typed batch, write-then-read)
- `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/docker-compose.yml`
  — one service per profile (`s7_1500`); binds `1102:1102` on the Docker host
- `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/profiles/s7_1500.json`
  — DB1 + MB seed layout with typed seeds at known offsets
- `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7/S7Driver.cs` — ctor takes
  `IS7ClientFactory` which tests fake