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/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). Scaffold passes the skip-when-absent contract cleanly. Wire-level round-trip against ab_server PCCC mode currently fails with BadCommunicationError on read/write (verified 2026-04-20) — ab_server's PCCC server-side coverage is narrower than libplctag's PCCC client expects. The smoke tests target the correct shape for real hardware + should pass when AB_LEGACY_ENDPOINT points at a real SLC 5/05 / MicroLogix. Unit tests via FakeAbLegacyTag still carry the contract coverage.

What the fixture is

Integration layer (task #224, scaffolded with a known ab_server gap): tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/ with AbLegacyServerFixture (TCP-probes localhost:44818) + 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 ab_server PCCC round-trip gap + resolution paths.

Unit layer: tests/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.

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.)
• AbLegacyArrayTests — PR 7 array contiguous-block addressing: parser positives + rejects for ,N / [N] suffixes, options-override (ArrayLength), driver IsArray discovery, and array decoding for N / F / L / B files (Rockwell convention: one BOOL per word for B3:0,10). Latency benchmark against the Docker fixture is a perf-flagged integration case in AbLegacyArrayReadTests — runs only when ab_server is reachable.
• 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
• AbLegacyDiagnosticsTests — PR ablegacy-10 / #253 per-device diagnostic counters: 5 reads (3 ok / 2 fail) → RequestCount=5, ResponseCount=3, ErrorCount=2; LastErrorCode reflects the most recent libplctag status; RetryCount increments per retry attempt beyond the first; counters reset on ReinitializeAsync; discovery emits exactly 7 diagnostic variables per device under _Diagnostics/; collision rejection at InitializeAsync for user tags shadowing reserved names or _Diagnostics/ addresses; the _Diagnostics/<host>/<name> short-circuit returns the live snapshot through ReadAsync without bumping RequestCount; two devices keep counters independent.
• AbLegacyDeadbandTests — PR 8 per-tag deadband / change filter: absolute-only suppression sequence [10.0, 10.5, 11.5, 11.6] -> [10.0, 11.5], percent-only suppression with a zero-prev short-circuit, both-set logical-OR semantics (Kepware), Boolean edge-only publish, string change-only publish, status-change always-publish, first-seen always-publish, ReinitializeAsync cache wipe, JSON DTO round-trip.

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 or IHistoryProvider — 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. Expand ab_server PCCC coverage — the smoke suite passes today for N (Int16), F (Float32), and L (Int32) files across SLC500 / MicroLogix / PLC-5 modes with the /1,0 cip-path workaround in place. Known residual gap: bit-file writes (B3:0/5) surface 0x803D0000. Contributing a patch to libplctag/libplctag to close this + documenting ab_server's empty-path rejection in its README would remove the last Docker-vs-hardware divergences.
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.

Per-device options (AbLegacyDeviceOptions)

Each entry in AbLegacyDriverOptions.Devices carries:

Field	Type	Default	Notes
HostAddress	string	required	ab://host[:port]/cip-path
PlcFamily	enum	Slc500	Slc500 / MicroLogix / Plc5 / LogixPccc
DeviceName	string	null	Friendly label used in browse + diagnostics
Timeout	TimeSpan?	null → driver-wide default	PR 9 / #252 — wins over the driver-wide Timeout. Mix-and-match: SLC 5/01 ≈ 5 s, SLC 5/05 ≈ 2 s, MicroLogix 1100 ≈ 3 s
Retries	int?	null → driver-wide default → 0	PR 9 / #252 — retries on transient BadCommunicationError; terminal errors surface on the first attempt

JSON shape (mirrored on AbLegacyDeviceDto):

{
  "HostAddress": "ab://192.168.1.10/1,0",
  "PlcFamily": "Slc500",
  "DeviceName": "slc-5-01-line-A",
  "TimeoutMs": 5000,
  "Retries": 1
}

Per-device overrides also flow into the probe loop — slow chassis won't be falsely marked Stopped just because the driver-wide probe timeout is tight.

Key fixture / config files

• tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyServerFixture.cs — TCP probe + skip attributes + env-var parsing
• tests/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/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml — compose profiles reusing AB CIP Dockerfile
• tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/README.md — known-limitations write-up + resolution paths
• tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/FakeAbLegacyTag.cs — in-process fake + factory
• src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs — scope remarks at the top of the file