126 lines
5.5 KiB
Markdown
126 lines
5.5 KiB
Markdown
# 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 `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
|
|
|
|
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 | 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) |
|
|
|
|
## 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.
|
|
|
|
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
|