lmxopcua/docs/drivers/AbLegacy-Test-Fixture.md

AB Legacy test fixture

Coverage map + gap inventory for the AB Legacy (PCCC) driver — SLC 500 / MicroLogix / PLC-5 / LogixPccc-mode.

TL;DR: Docker integration-test scaffolding lives at tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/ (task #224), reusing the AB CIP ab_server image in PCCC mode with per-family compose profiles (slc500 / micrologix / plc5). The smoke tests pass for N-file (Int16), F-file (Float32), and L-file (Int32) reads across all three families when AB_LEGACY_CIP_PATH=1,0 (the default). The earlier BadCommunicationError was traced to ab_server requiring a non-empty CIP routing path before forwarding to the PCCC dispatcher — the /1,0 workaround resolves it (see Docker/README.md §Known limitations). The old bit-file write gap (B3:0/5 giving 0x803D0000) no longer reproduces (2026-10-09, AbLegacyBitWriteTests). Unit tests via FakeAbLegacyTag carry full contract coverage for all paths.

What the fixture is

Integration layer (task #224): tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/ with AbLegacyServerFixture (TCP-probes 10.100.0.35:44818 — the shared Docker host; override with AB_LEGACY_ENDPOINT) + three smoke tests (parametric read across families, SLC500 write-then-read). Reuses the AB CIP otopcua-ab-server:libplctag-release image via a relative build: context in Docker/docker-compose.yml — one image, different --plc flags. See Docker/README.md §Known limitations for the CIP-path gate + bit-file write gap.

Unit layer: tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/ is still the primary coverage. All tests tagged [Trait("Category", "Unit")]. The driver accepts IAbLegacyTagFactory via ctor DI; every test supplies a FakeAbLegacyTag.

Per-transport suites and capture recipe

The AbLegacy.IntegrationTests suites now run once per transport (TransportMatrix: Libplctag and Native). Set AB_LEGACY_COMPOSE_PROFILE to the running profile. On the 2026-10-07 run native passed everything libplctag passed on slc500, micrologix and plc5 (the smoke tests read N7 only; the PLC-5 refusal paths and status-bit write refusals are exercised by AbLegacyUnsupportedPathTests, native only, #593 — the refusals are the driver's own, raised before the wire, so each test carries a positive-control read). Native PCCC is simulator-only. Write-capable tests (the SLC500 N7:5 round trip) require AB_SERVER_ALLOW_WRITES=1. Golden frames: scripts/ab-capture/capture.sh, fixtures under tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Ab.Transport.Tests/Captures/. Evidence: native-ab-transport-gate-results.

What it actually covers (unit only)

• AbLegacyAddressTests — PCCC address parsing for SLC / MicroLogix / PLC-5 / LogixPccc-mode (N7:0, F8:12, B3:0/5, etc.)
• AbLegacyCapabilityTests — data type mapping, read-only enforcement
• AbLegacyReadWriteTests — read + write happy + error paths against the fake
• AbLegacyBitRmwTests — bit-within-DINT read-modify-write serialization via per-parent SemaphoreSlim (mirrors the AB CIP + FOCAS PMC-bit pattern from #181)
• AbLegacyHostAndStatusTests — probe + host-status transitions driven by fake-returned statuses
• AbLegacyDriverTests — IDriver lifecycle

Capability surfaces whose contract is verified: IDriver, IReadable, IWritable, ITagDiscovery, ISubscribable, IHostConnectivityProbe, IPerCallHostResolver.

What it does NOT cover

1. Wire-level PCCC

No PCCC frame is sent by the test suite. libplctag's PCCC subset (DF1, ControlNet-over-EtherNet, PLC-5 native EtherNet) is untested here; driver-side correctness depends on libplctag being correct.

2. Family-specific behavior

• SLC 500 timeout + retry thresholds (SLC's comm module has known slow-response edges) — unit fakes don't simulate timing.
• MicroLogix 1100 / 1400 max-connection-count limits — not stressed.
• PLC-5 native EtherNet connection setup (PCCC-encapsulated-in-CIP vs raw CSPv4) — routing covered at parse level only.

3. Multi-device routing

IPerCallHostResolver contract is verified; real PCCC wire routing across multiple gateways is not.

4. Alarms / history

PCCC has no alarm object + no history object. Driver doesn't implement IAlarmSource (history is server-side for every driver) — no test coverage is the correct shape.

5. File-type coverage

PCCC has many file types (N, F, B, T, C, R, S, ST, A) — the parser tests cover the common ones but uncommon ones (R counters, S status files, A ASCII strings) have thin coverage.

When to trust AB Legacy tests, when to reach for a rig

Question	Unit tests	Real PLC
"Does N7:0/5 parse correctly?"	yes	-
"Does bit-in-word RMW serialize concurrent writers?"	yes	yes
"Does the driver lifecycle hang / crash?"	yes	yes
"Does a real read against an SLC 500 return correct bytes?"	no	yes (required)
"Does MicroLogix 1100 respect its connection-count cap?"	no	yes (required)
"Do PLC-5 ST-files round-trip correctly?"	no	yes (required)

Follow-up candidates

1. (Closed, 2026-10-09) ab_server bit-file write gap — N, F and L files round-trip with the /1,0 workaround, and B3:0/5 bit writes now pass on SLC500/MicroLogix (both transports; AbLegacyBitWriteTests). The May 2026 0x803D0000 does not reproduce; its cause is undetermined.
2. Rockwell RSEmulate 500 golden-box tier — Rockwell's real emulator for SLC/MicroLogix/PLC-5. Would close UDT-equivalent (integer-file indirection), timer/counter decomposition, and real ladder execution gaps. Costs: RSLinx OEM license, Windows-only, Hyper-V conflict matching TwinCAT XAR + Logix Emulate, no clean PR-diffable project format (SLC/ML save as binary .RSS). Scaffold like the Logix Emulate tier when operationally worth it.
3. Lab rig — used SLC 5/05 or MicroLogix 1100 on a dedicated network; parts are end-of-life but still available. PLC-5 + LogixPccc-mode behaviour + DF1 serial need specific controllers.

Key fixture / config files

• tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyServerFixture.cs — TCP probe + skip attributes + env-var parsing
• tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyReadSmokeTests.cs — wire-level smoke tests; pass against the ab_server Docker fixture with AB_LEGACY_COMPOSE_PROFILE set to the running container
• tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml — compose profiles reusing AB CIP Dockerfile
• tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/README.md — known-limitations write-up + resolution paths
• tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/FakeAbLegacyTag.cs — in-process fake + factory
• src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs — scope remarks at the top of the file