# 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](https://github.com/libplctag/libplctag),
  MIT).
- **Launcher**: Docker (only supported path). `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` TCP-probes `127.0.0.1:44818` at
  collection init + records a skip reason when unreachable. Tests skip
  via `[AbServerFact]` / `[AbServerTheory]` which check the same probe.
- **Profiles**: `KnownProfiles.{ControlLogix, CompactLogix, Micro800, GuardLogix}`
  in `AbServerProfile.cs` — thin Family + ComposeProfile + Notes records;
  the compose file is the canonical source of truth for which tags get
  seeded + which `--plc` mode the simulator boots in.
- **Tests**: one smoke, `AbCipReadSmokeTests.Driver_reads_seeded_DInt_from_ab_server`,
  parametrized over all four profiles via `[AbServerTheory]` + `[MemberData]`.
- **Endpoint override**: `AB_SERVER_ENDPOINT=host:port` points the
  fixture at a real PLC instead of the local container.

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

1. **Extend `ab_server`** upstream — the project accepts PRs + already carries
   a CIP framing layer that UDT emulation could plug into.
2. **Swap in a richer simulator** — e.g.
   [OpenPLC](https://www.openplcproject.com/) or pycomm3's test harness, if
   either exposes UDTs over EtherNet/IP in a way libplctag can consume.
3. **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.

See also:

- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerFixture.cs`
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerProfile.cs`
- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbCipReadSmokeTests.cs`
- `docs/v2/test-data-sources.md` §2 — the broader test-data-source picking
  rationale this fixture slots into