# 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 the canonical diagnostic variables
  per device under `_Diagnostics/` (now 9 with PR ablegacy-12); 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.
- `AbLegacyAutoDemoteTests` — **PR ablegacy-12 / #255** auto-demote on comm
  failure: 3 consecutive failures arm the demote window and surface
  `HostState.Demoted`; subsequent reads short-circuit with
  `BadCommunicationError` *without invoking libplctag* (verified via
  `factory.Tags["N7:0"].ReadCount` not advancing); successful read resets
  the consecutive-failure counter; failure-success-failure pattern doesn't
  cross the threshold; `DemoteCount` + `LastDemotedUtc` surface via
  `_Diagnostics/`; `Enabled=false` opts out (failures still count, demotion
  never fires); `ReinitializeAsync` clears the active window but preserves
  cumulative `DemoteCount`; cool-down expiry allows the next read through;
  two devices in one driver — one faulty, one healthy — proves the faulty
  side's demotion doesn't starve the healthy side; `BadNodeIdUnknown`
  (terminal) does not count toward the comm-failure tally; DTO JSON
  round-trip preserves `FailureThreshold` / `DemoteForMs` / `Enabled` at
  the per-device level; `HostState.Demoted` enum value is wired through
  `Core.Abstractions`. Companion integration test in
  `tests/.../IntegrationTests/AbLegacyAutoDemoteTests.cs` runs the
  two-device-one-unreachable scenario against a live ab_server fixture
  using `127.0.0.1:1` as the unreachable peer.
- `RsLogixSymbolImportTests` — ablegacy-11 / #254 RSLogix CSV symbol-import parser:
  canonical 8-row CSV (one row per N/F/B/L/ST/T/C/R) → 8 typed
  `AbLegacyTagDefinition`s with the right `DataType`; header + comment-line
  (`;` / `#`) skipping; malformed-row → log warning + skip (`IgnoreInvalid=true`
  default) vs. `InvalidDataException` (`IgnoreInvalid=false`); empty stream →
  empty result; UTF-8 BOM survival; embedded comma in quoted Description;
  doubled-quote escape; `--scope` filter (Global vs. Local:N); `MaxRowsToImport`
  cap; missing required header column → `InvalidDataException` regardless of
  `IgnoreInvalid`; `TryResolveDataType` rejects garbage + bit-suffix overrides
  the file letter (`N7:0/3` → Bit).
- `RsLogixSymbolImportGoldenTests` — golden-snapshot integration: loads
  `Fixtures/rslogix-canonical.csv` (8-row canonical export covering every v1
  file letter), serialises the resulting tag list, and compares to
  `Fixtures/rslogix-canonical-expected.json`. On mismatch the actual JSON is
  dumped to `%TEMP%/rslogix-canonical-actual.json` and the path printed in the
  failure message so the dev can `cp` the golden after reviewing the diff.
- `AbLegacyDriverFactoryAddRsLogixImportTests` — covers the
  `AbLegacyDriverFactoryExtensions.AddRsLogixImport` extension method:
  appends imported tags onto an existing options object without dropping the
  hand-rolled tags or the device list; mutates by-copy (immutability
  guarantee); `AddRsLogixImportWithResult` tuple overload returns both the
  modified options and the import counters.
- `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.

### 3a. DH+ via 1756-DHRIO bridging (PR ablegacy-13 / #256)

Unit-only — coverage lives in `AbLegacyDhPlusBridgingTests`. The CIP-path
parser positive / negative cases (octal-station validation, slot bounds, port
shape) and the PLC-5-only family guard at `InitializeAsync` are exercised
against fakes. There is no Docker fixture for DH+ because libplctag's
`ab_server` doesn't simulate the DHRIO + DH+ + PLC-5 stack — wire-level
validation requires real hardware. See
[`AbLegacy-DH-Bridging.md`](AbLegacy-DH-Bridging.md) for the manual smoke
procedure.

### 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`):

```json
{
  "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
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/Fixtures/rslogix-canonical.csv`
  — ablegacy-11 / #254 8-row canonical RSLogix CSV symbol export, one row per
  v1 file letter (N/F/B/L/ST/T/C/R)
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/Fixtures/rslogix-canonical-expected.json`
  — golden snapshot the import tests compare against
- `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — scope remarks
  at the top of the file