Files

Joseph Doherty 6609141493 Dockerize Modbus + AB CIP + S7 test fixtures for reproducibility. Every driver integration simulator now has a pinned Docker image alongside the existing native launcher — Docker is the primary path, native fallbacks kept for contributors who prefer them. Matches the already-Dockerized OpcUaClient/opc-plc pattern from #215 so every fixture in the fleet presents the same compose-up/test/compose-down loop. Reproducibility gain: what used to require a local pip/Python install (Modbus pymodbus, S7 python-snap7) or a per-OS C build from source (AB CIP ab_server from libplctag) now collapses to a Dockerfile + docker compose up. Modbus — new tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Docker/ with Dockerfile (python:3.12-slim-bookworm + pymodbus[simulator]==3.13.0) + docker-compose.yml with four compose profiles (standard / dl205 / mitsubishi / s7_1500) backed by the existing profile JSONs copied under Docker/profiles/ as canonical; native fallback in Pymodbus/ retained with the same JSON set (symlink-equivalent — manual re-sync when profiles change, noted in both READMEs). Port 5020 unchanged so MODBUS_SIM_ENDPOINT + ModbusSimulatorFixture work without code change. Dropped the --no_http CLI arg the old serve.ps1 + compose draft passed — pymodbus 3.13 doesn't recognize it; the simulator's http ui just binds inside the container where nothing maps it out and costs nothing. S7 — new tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/ with Dockerfile (python:3.12-slim-bookworm + python-snap7>=2.0) + docker-compose.yml with one s7_1500 compose profile; copies the existing server.py shim + s7_1500.json seed profile; runs python -u server.py ... --port 1102. Native fallback in PythonSnap7/ retained. Port 1102 unchanged. AB CIP — hardest because ab_server is a source-only C tool in libplctag's src/tools/ab_server/. New tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/ Dockerfile is multi-stage: build stage (debian:bookworm-slim + build-essential + cmake) clones libplctag at a pinned tag + cmake --build build --target ab_server; runtime stage (debian:bookworm-slim) copies just the binary from /src/build/bin_dist/ab_server. docker-compose.yml ships four compose profiles (controllogix / compactlogix / micro800 / guardlogix) with per-family ab_server CLI args matching AbServerProfile.cs. AbServerFixture updated: tries TCP probe on 127.0.0.1:44818 first (Docker path) + spawns the native binary only as fallback when no listener is there. AB_SERVER_ENDPOINT env var supported for pointing at a real PLC. AbServerFact/Theory attributes updated to IsServerAvailable() which accepts any of: live listener on 44818, AB_SERVER_ENDPOINT set, or binary on PATH. Required two CLI-compat fixes to ab_server's argument expectations that the existing native profile never caught because it was never actually run at CI: --plc is case-sensitive (ControlLogix not controllogix), CIP tags need [size] bracket notation (DINT[1] not bare DINT), ControlLogix also requires --path=1,0. Compose files carry the corrected flags; the existing native-path AbServerProfile.cs was never invoked in practice so we don't rewrite it here. Micro800 now uses the --plc=Micro800 mode rather than falling back to ControlLogix emulation — ab_server does have the dedicated mode, the old Notes saying otherwise were wrong. Updated docs: three fixture coverage docs (Modbus-Test-Fixture.md, S7-Test-Fixture.md, AbServer-Test-Fixture.md) flip their "What the fixture is" section from native-only to Docker-primary-with-native-fallback; dev-environment.md §Resource Inventory replaces the old ambiguous "Docker Desktop + ab_server native" mix with four per-driver rows (each listing the image, compose file, compose profiles, port, credentials) + a new Docker fixtures — quick reference subsection giving the one-line docker compose -f <…> --profile <…> up for each driver + the env-var override names + the native fallback install recipes. drivers/README.md coverage map table updated — Modbus/AB CIP/S7 entries now read "Dockerized …" consistent with OpcUaClient's line. Verified end-to-end against live containers: Modbus DL205 smoke 1/1, S7 3/3, AB CIP ControlLogix 4/4 (all family theory rows). Container lifecycle clean (up/test/down, no leaked state). Every fixture keeps its skip-when-absent probe + env-var endpoint override so dotnet test on a fresh clone without Docker running still gets a green run.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-20 12:09:44 -04:00

7.0 KiB

Raw Blame History

ab_server test fixture

Coverage map + gap inventory for the AB CIP integration fixture backed by libplctag's ab_server simulator.

TL;DR: ab_server is a connectivity + atomic-read smoke harness for the AB CIP driver. It does not benchmark UDTs, alarms, or any family-specific quirk. UDT / alarm / quirk behavior is verified only by unit tests with FakeAbCipTagRuntime.

What the fixture is

Binary: ab_server — a C program in libplctag's src/tools/ab_server/ (libplctag/libplctag, MIT).
Primary launcher: Docker. Docker/Dockerfile multi-stage-builds ab_server from source against a pinned libplctag tag + copies the binary into a slim runtime image. Docker/docker-compose.yml has per-family services (controllogix / compactlogix / micro800 / guardlogix); all bind :44818.
Lifecycle: AbServerFixture probes 127.0.0.1:44818 at collection init. When a Docker container is running (or AB_SERVER_ENDPOINT is set) the fixture skips its legacy spawn path + the tests dial the running container. When neither is present, it falls back to the pre-Docker path of resolving ab_server off PATH + spawning it.
Profiles: KnownProfiles.{ControlLogix, CompactLogix, Micro800, GuardLogix} in AbServerProfile.cs. Each composes a CLI arg list + seed-tag set; the Docker/docker-compose.yml command: entries mirror those args 1:1.
Tests: one smoke, AbCipReadSmokeTests.Driver_reads_seeded_DInt_from_ab_server, parametrized over all four profiles via [AbServerTheory] + [MemberData].
Skip rules via [AbServerFact] / [AbServerTheory]: accept a live listener on :44818 (Docker), an AB_SERVER_ENDPOINT override, or the native binary on PATH; skip otherwise.

What it actually covers

Read path: driver → libplctag → CIP-over-EtherNet/IP → simulator → back.
Atomic Logix types per seed: DINT, REAL, BOOL, SINT, STRING.
One DINT[16] array tag (ControlLogix profile only).
--plc controllogix and --plc compactlogix mode dispatch.
The skip-on-missing-binary behavior (AbServerFactAttribute) so a fresh clone without the simulator stays green.

What it does NOT cover

Each gap below is either stated explicitly in the profile's Notes field or inferable from the seed-tag set + smoke-test surface.

1. UDTs / CIP Template Object (class 0x6C)

ControlLogix profile Notes: "ab_server lacks full UDT emulation."

Unverified against ab_server:

PR 6 structured read/write (AbCipStructureMember fan-out)
#179 Template Object shape reader (CipTemplateObjectDecoder + FetchUdtShapeAsync)
#194 whole-UDT read optimization (AbCipUdtReadPlanner + AbCipUdtMemberLayout + the ReadGroupAsync path in AbCipDriver)

Unit coverage: AbCipFetchUdtShapeTests, CipTemplateObjectDecoderTests, AbCipUdtMemberLayoutTests, AbCipUdtReadPlannerTests, AbCipDriverWholeUdtReadTests — all with golden Template-Object byte buffers

offset-keyed FakeAbCipTag values.

2. ALMD / ALMA alarm projection (#177)

Depends on the ALMD UDT shape, which ab_server cannot emulate. The OnAlarmEvent raise/clear path + ack-write semantics are not exercised end-to-end.

Unit coverage: AbCipAlarmProjectionTests — fakes feed InFaulted / Severity via ValuesByOffset + assert the emitted AlarmEventArgs.

3. Micro800 unconnected-only path

Micro800 profile Notes: "ab_server has no --plc micro800 — falls back to controllogix emulation."

The empty routing path + unconnected-session requirement (PR 11) is unit-tested but never challenged at the CIP wire level. Real Micro800 (2080-series) on a lab rig would be the authoritative benchmark.

4. GuardLogix safety subsystem

GuardLogix profile Notes: "ab_server doesn't emulate the safety subsystem."

Only the _S-suffix naming classifier (PR 12, SecurityClassification.ViewOnly forced on safety tags) runs. Actual safety-partition write rejection — what happens when a non-safety write lands on a real 1756-L8xS — is not exercised.

5. CompactLogix narrow ConnectionSize cap

CompactLogix profile Notes: "ab_server lacks the narrower limit itself."

Driver-side AbCipPlcFamilyProfile caps ConnectionSize at the CompactLogix value per PR 10, but ab_server accepts whatever the client asks for — the cap's correctness is trusted from its unit test, never stressed against a simulator that rejects oversized requests.

6. BOOL-within-DINT read-modify-write (#181)

The AbCipDriver.WriteBitInDIntAsync RMW path + its per-parent SemaphoreSlim serialization is unit-tested only (AbCipBoolInDIntRmwTests). ab_server seeds a plain TestBOOL tag; the .N bit-within-DINT syntax that triggers the RMW path is not exercised end-to-end.

7. Capability surfaces beyond read

No smoke test for:

IWritable.WriteAsync
ITagDiscovery.DiscoverAsync (@tags walker)
ISubscribable.SubscribeAsync (poll-group engine)
IHostConnectivityProbe state transitions under wire failure
IPerCallHostResolver multi-device routing

The driver implements all of these + they have unit coverage, but the only end-to-end path ab_server validates today is atomic ReadAsync.

When to trust ab_server, when to reach for a rig

Question	ab_server	Unit tests	Lab rig
"Does the driver talk CIP at all?"	yes	-	-
"Is my atomic read path wired correctly?"	yes	yes	yes
"Does whole-UDT grouping work?"	no	yes	yes (required)
"Do ALMD alarms raise + clear?"	no	yes	yes (required)
"Is Micro800 unconnected-only enforced wire-side?"	no (emulated as CLX)	partial	yes (required)
"Does GuardLogix reject non-safety writes on safety tags?"	no	no	yes (required)
"Does CompactLogix refuse oversized ConnectionSize?"	no	partial	yes (required)
"Does BOOL-in-DINT RMW race against concurrent writers?"	no	yes	yes (stress)

Follow-up candidates

If integration-level UDT / alarm / quirk proof becomes a shipping gate, the options are roughly:

Extend ab_server upstream — the project accepts PRs + already carries a CIP framing layer that UDT emulation could plug into.
Swap in a richer simulator — e.g. OpenPLC or pycomm3's test harness, if either exposes UDTs over EtherNet/IP in a way libplctag can consume.
Stand up a lab rig — physical 1756-L7x / 5069-L3x / 2080-LC30 / 1756-L8xS controllers running Rockwell Studio 5000 projects; wire into CI via a self-hosted runner. The only path that covers safety + narrow ConnectionSize + real ALMD execution.

7.0 KiB Raw Blame History