Files

Joseph Doherty a0cf7c5860 AB Legacy ab_server PCCC Docker fixture scaffold (#224 ) — Docker infrastructure + test-class shape in place; wire-level round-trip currently blocked by an ab_server-side PCCC coverage gap documented honestly in the fixture + coverage docs. Closes the Docker-infrastructure piece of #224 ; the remaining work is upstream (patch ab_server's PCCC server opcodes) or sideways (RSEmulate 500 golden-box tier, lab rig).

New project tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/ with four pieces. AbLegacyServerFixture — TCP probe against localhost:44818 (or AB_LEGACY_ENDPOINT override), distinct from AB_SERVER_ENDPOINT so both CIP + PCCC containers can run simultaneously. Single-public-ctor to satisfy xunit collection-fixture constraint. AbLegacyServerProfile + KnownProfiles carry the per-family (SLC500 / MicroLogix / PLC-5) ComposeProfile + Notes; drives per-theory parameterisation. AbLegacyFactAttribute / AbLegacyTheoryAttribute match the AB CIP skip-attribute pattern.

Docker/docker-compose.yml reuses the AB CIP otopcua-ab-server:libplctag-release image — `build:` block points at ../../AbCip.IntegrationTests/Docker context so `docker compose build` from here produces / reuses the same multi-stage build. Three compose profiles (slc500 / micrologix / plc5) with per-family `--plc` + `--tag=<file>[<size>]` flags matching the PCCC tag syntax (different from CIP's `Name:Type[size]`).

AbLegacyReadSmokeTests — one parametric theory reading N7:0 across all three families + one SLC500 write-then-read on N7:5. Targets the shape the driver would use against real hardware. Verified 2026-04-20 against a live SLC500 container: TCP probe passes + container accepts connections + libplctag negotiates session, but read/write returns BadCommunicationError (libplctag status 0x80050000). Root-caused to ab_server's PCCC server-side opcode coverage being narrower than libplctag's PCCC client expects — not a driver-side bug, not a scaffold bug, just an ab_server upstream limitation. Documented honestly in Docker/README.md + AbLegacy-Test-Fixture.md rather than skipping the tests or weakening assertions; tests now skip cleanly when container is absent, fail with clear message when container is up but the protocol gap surfaces. Operator resolves by filing an ab_server upstream patch, pointing AB_LEGACY_ENDPOINT at real hardware, or scaffolding an RSEmulate 500 golden-box tier.

Docker/README.md — Known limitations section leads with the PCCC round-trip gap (test date, failure signature, possible root causes, three resolution paths) before the pre-existing limitations (T/C file decomposition, ST file quirks, indirect addressing, DF1 serial). Reader can't miss the "scaffolded but blocked on upstream" framing.

docs/drivers/AbLegacy-Test-Fixture.md — TL;DR flipped from "no integration fixture" to "Docker scaffold in place; wire-level round-trip currently blocked by ab_server PCCC gap". What-the-fixture-is gains an Integration section. Follow-up candidates rewritten: #1 is now "fix ab_server PCCC upstream", #2 is RSEmulate 500 golden-box (with cost callouts matching our existing Logix Emulate + TwinCAT XAR scaffolds — license + Hyper-V conflict + binary project format), #3 is lab rig. Key-files list adds the four new files. docs/drivers/README.md coverage-map row updated from "no integration fixture" to "Docker scaffold via ab_server PCCC; wire-level round-trip currently blocked, docs call out resolution paths".

Solution file picks up the new tests/.../AbLegacy.IntegrationTests entry. AbLegacyDataType.Int used throughout (not Int16 — the enum uses SLC file-type naming). Build 0 errors; 2 smoke tests skip cleanly without container + fail with clear errors when container up (proving the infrastructure works end-to-end + the gap is specifically the ab_server protocol coverage, not the scaffold).

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

2026-04-20 13:26:19 -04:00

5.8 KiB

Raw Blame History

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.)
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 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

Fix ab_server PCCC coverage upstream — the scaffold lands the Docker infrastructure; the wire-level round-trip gap is in ab_server itself. Filing a patch to libplctag/libplctag to expand PCCC server-side opcode coverage would make the scaffolded smoke tests pass without a golden-box tier.
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.
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/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 — three wire-level smoke tests (currently blocked by ab_server PCCC gap)
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

5.8 KiB Raw Blame History