diff --git a/docs/drivers/S7-Test-Fixture.md b/docs/drivers/S7-Test-Fixture.md index 3dc1cafc..df6d60d7 100644 --- a/docs/drivers/S7-Test-Fixture.md +++ b/docs/drivers/S7-Test-Fixture.md @@ -6,17 +6,19 @@ Coverage map + gap inventory for the S7 driver. [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 `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. +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 `localhost:1102` (pinned `python:3.12-slim-bookworm` base + +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. `Snap7ServerFixture` probes the port at collection init + skips with a clear message when unreachable (matches the pymodbus pattern). @@ -60,18 +62,20 @@ Wire-level surfaces verified: `IReadable`, `IWritable`. ## What it does NOT cover -### 1. Wire-level anything +### 1. Wire-level anything (unit tests only) -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. +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. Read/write happy path +### 2. Error-branch unit tests vs. real round-trips -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. +`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 @@ -91,31 +95,40 @@ arrays of structs — not covered. ## 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?" | no | yes (required) | +| 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 -1. **Snap7 server** — [Snap7](https://snap7.sourceforge.net/) 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. +The python-snap7 fixture (task #216) covers scalar read / write / typed-batch. +Remaining gaps need one of: -Without any of these, S7 driver correctness against real hardware is trusted +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; docstring lines 8-20 note the deferred - integration fixture + `IS7ClientFactory` which tests fake