96940aeb24
New exception_injector.py — standalone pure-Python-stdlib Modbus/TCP server shipped alongside the pymodbus image. Speaks the wire protocol directly (MBAP header parse + FC 01/02/03/04/05/06/15/16 dispatch + store-backed happy-path reads/writes + spec-enforced length caps) and looks up each (fc, starting-address) against a rules list loaded from JSON; a matching rule makes the server respond [fc|0x80, exception_code] instead of the normal response. Zero runtime dependencies outside the stdlib — the Dockerfile just COPY's the script into /fixtures/ alongside the pymodbus profile JSONs, no new pip install needed. ~200 lines. New exception_injection.json profile carries rules for every exception code on FC03 (addresses 1000-1007, one per code), FC06 (2000-2001 for CPU-PROGRAM-mode and busy), and FC16 (3000 for server failure). New exception_injection compose profile binds :5020 like every other service + runs python /fixtures/exception_injector.py --config /fixtures/exception_injection.json. New ExceptionInjectionTests.cs in Modbus.IntegrationTests — 11 tests. Eight FC03-read theories exercise every exception code 0x01/0x02/0x03/0x04/0x05/0x06/0x0A/0x0B asserting the driver's expected OPC UA StatusCode mapping (BadNotSupported/BadOutOfRange/BadOutOfRange/BadDeviceFailure/BadDeviceFailure/BadDeviceFailure/BadCommunicationError/BadCommunicationError). Two FC06-write theories cover the write path for 0x04 (Server Failure, CPU in PROGRAM mode) + 0x06 (Server Busy). One sanity-check read at address 5 confirms the injector isn't globally broken + non-injected reads round-trip cleanly with Value=5/StatusCode=Good. All tests follow the MODBUS_SIM_PROFILE=exception_injection skip guard so they no-op on a fresh clone without Docker running. Docker/README.md gains an §Exception injection section explaining what pymodbus can and cannot emit, what the injector does, where the rules live, and how to append new ones. docs/drivers/Modbus-Test-Fixture.md follow-up item #2 (extend pymodbus profiles to inject exceptions) gets a shipped strikethrough with the new coverage inventory; the unit-level section adds ExceptionInjectionTests next to DL205ExceptionCodeTests so the split-of-responsibilities is explicit (DL205 test = natural out-of-range via dl205 profile, ExceptionInjectionTests = every other code via the injector). Test baselines: Modbus unit 182/182 green (unchanged); Modbus integration with exception_injection profile live 11/11 new tests green. Existing DL205/S7/Mitsubishi integration tests unaffected since they skip on MODBUS_SIM_PROFILE mismatch. Found + fixed during validation: a stale native pymodbus simulator from April 18 was still listening on port 5020 on IPv6 localhost (Windows was load-balancing between it + the Docker IPv4 forward, making injected exceptions intermittently come back as pymodbus's default 0x02). Killed the leftover. Documented the debugging path in the commit as a note for anyone who hits the same "my tests see exception 0x02 but the injector log has no request" symptom. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
103 lines
4.6 KiB
Markdown
103 lines
4.6 KiB
Markdown
# Modbus integration-test fixture — pymodbus simulator
|
|
|
|
The Modbus driver's integration tests talk to a
|
|
[`pymodbus`](https://pymodbus.readthedocs.io/) simulator running as a
|
|
pinned Docker container. One image, per-profile service in compose, same
|
|
port binding (`5020`) regardless of which profile is live. Docker is the
|
|
only supported launch path — a fresh clone needs Docker Desktop and
|
|
nothing else.
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| [`Dockerfile`](Dockerfile) | `python:3.12-slim-bookworm` + `pymodbus[simulator]==3.13.0` + every profile JSON + `exception_injector.py` |
|
|
| [`docker-compose.yml`](docker-compose.yml) | One service per profile (`standard` / `dl205` / `mitsubishi` / `s7_1500` / `exception_injection`); all bind `:5020` so only one runs at a time |
|
|
| [`profiles/*.json`](profiles/) | Same seed-register definitions the native launcher uses — canonical source |
|
|
| [`exception_injector.py`](exception_injector.py) | Pure-stdlib Modbus/TCP server that emits arbitrary exception codes per rule — used by the `exception_injection` profile |
|
|
|
|
## Run
|
|
|
|
From the repo root:
|
|
|
|
```powershell
|
|
# Build + start the standard profile
|
|
docker compose -f tests\ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests\Docker\docker-compose.yml --profile standard up
|
|
|
|
# DL205 quirks
|
|
docker compose -f tests\ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests\Docker\docker-compose.yml --profile dl205 up
|
|
|
|
# Mitsubishi MELSEC quirks
|
|
docker compose -f tests\ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests\Docker\docker-compose.yml --profile mitsubishi up
|
|
|
|
# Siemens S7-1500 MB_SERVER quirks
|
|
docker compose -f tests\ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests\Docker\docker-compose.yml --profile s7_1500 up
|
|
|
|
# Exception-injection — end-to-end coverage of every Modbus exception code
|
|
# (01/02/03/04/05/06/0A/0B), not just the 02 + 03 pymodbus emits naturally
|
|
docker compose -f tests\ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests\Docker\docker-compose.yml --profile exception_injection up
|
|
```
|
|
|
|
Detached + stop:
|
|
|
|
```powershell
|
|
docker compose -f tests\...\Docker\docker-compose.yml --profile dl205 up -d
|
|
docker compose -f tests\...\Docker\docker-compose.yml --profile dl205 down
|
|
```
|
|
|
|
Only one profile binds `:5020` at a time; switch by stopping the current
|
|
service + starting another. The integration tests discriminate by a
|
|
separate `MODBUS_SIM_PROFILE` env var so they skip correctly when the
|
|
wrong profile is live.
|
|
|
|
## Endpoint
|
|
|
|
- Default: `localhost:5020`
|
|
- Override with `MODBUS_SIM_ENDPOINT` (e.g. a real PLC on `:502`).
|
|
|
|
## Run the integration tests
|
|
|
|
In a separate shell with one profile live:
|
|
|
|
```powershell
|
|
cd C:\Users\dohertj2\Desktop\lmxopcua
|
|
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests
|
|
```
|
|
|
|
`ModbusSimulatorFixture` probes `localhost:5020` at collection init +
|
|
records a `SkipReason` when unreachable, so tests stay green on a fresh
|
|
clone without Docker running.
|
|
|
|
## Exception injection
|
|
|
|
pymodbus's simulator naturally emits only Modbus exception codes `0x02`
|
|
(Illegal Data Address, on reads outside its configured ranges) and
|
|
`0x03` (Illegal Data Value, on over-length requests). The driver's
|
|
`MapModbusExceptionToStatus` table translates eight codes: `0x01`,
|
|
`0x02`, `0x03`, `0x04`, `0x05`, `0x06`, `0x0A`, `0x0B`. Unit tests
|
|
lock the translation function; the integration side previously only
|
|
proved the wire-to-status path for `0x02`.
|
|
|
|
The `exception_injection` profile runs
|
|
[`exception_injector.py`](exception_injector.py) — a tiny standalone
|
|
Modbus/TCP server written against the Python stdlib (zero
|
|
dependencies outside what's in the base image). It speaks the wire
|
|
protocol directly (FC 01/02/03/04/05/06/15/16) and looks up each
|
|
incoming `(fc, address)` against the rules in
|
|
[`profiles/exception_injection.json`](profiles/exception_injection.json);
|
|
a matching rule makes the server reply with
|
|
`[fc | 0x80, exception_code]` instead of the normal response.
|
|
|
|
Current rules (see the JSON file for the canonical list):
|
|
|
|
- `FC03 @1000..1007` — one per exception code (`0x01`/`0x02`/`0x03`/`0x04`/`0x05`/`0x06`/`0x0A`/`0x0B`)
|
|
- `FC06 @2000..2001` — `0x04` Server Failure, `0x06` Server Busy (write-path coverage)
|
|
- `FC16 @3000` — `0x04` Server Failure (multi-register write path)
|
|
|
|
Adding more coverage is append-only: drop a new `{fc, address,
|
|
exception, description}` entry into the JSON, restart the service,
|
|
add an `[InlineData]` row in `ExceptionInjectionTests`.
|
|
|
|
## References
|
|
|
|
- [`docs/drivers/Modbus-Test-Fixture.md`](../../../docs/drivers/Modbus-Test-Fixture.md) — coverage map + gap inventory
|
|
- [`docs/v2/dev-environment.md`](../../../docs/v2/dev-environment.md) §Docker fixtures — full fixture inventory
|