dohertj2/lmxopcua
1
0
Fork 0
Code Issues 2 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(audit): S7-Test-Fixture.md — accuracy pass

Browse Source 
STALE-STATUS (Snap7ServerFixture.cs:40):
- TL;DR + "What the fixture is": localhost:1102 → 10.100.0.35:1102 (shared
  Docker host migrated 2026-04-28; fixture already defaults to 10.100.0.35)

CODE-REALITY (S7_1500SmokeTests.cs exists and sends real S7comm):
- "What it does NOT cover" §1 ("No ISO-on-TCP frame is ever sent") was
  simply wrong — the integration suite DOES send real S7comm. Rewritten
  to clarify that the unit suite uses IS7Client fakes while the integration
  suite exercises the full wire path.
- "What it does NOT cover" §2 ("successful read not tested end-to-end")
  was also wrong — Driver_reads_seeded_u16_through_real_S7comm does exactly
  that. Rewritten to scope the error-branch-only claim to unit tests.
- "When to trust" table: added Integration (python-snap7) column reflecting
  what the existing S7_1500SmokeTests actually answer.
- "Follow-up candidates" §1: removed the suggestion to build a Snap7 server
  fixture — python-snap7 fixture (task #216) already ships. Follow-ups now
  correctly list Plcsim Advanced and real lab rig only.

INLINE COMPLETENESS:
- "Key fixture / config files": was missing all integration test artefacts.
  Added Snap7ServerFixture.cs, S7_1500SmokeTests.cs, Docker/docker-compose.yml,
  and Docker/profiles/s7_1500.json with descriptions matching file contents.

STRUCTURAL: no broken links in links-report.md for this doc.
VERIFY: check_links.py — 0 rows for S7-Test-Fixture.md.
This commit is contained in:
Joseph Doherty
2026-06-03 16:01:58 -04:00
parent d686e12123
commit 2eb3ceb961
1 changed files with 45 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/drivers/S7-Test-Fixture.md
+45 -32
View File
@@ -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