# TwinCAT test fixture

Coverage map + gap inventory for the Beckhoff TwinCAT ADS driver.

**TL;DR: there is no integration fixture.** Every test uses a
`FakeTwinCATClient` injected via `ITwinCATClientFactory`. Beckhoff's ADS
library has no open-source simulator; ADS traffic against real TwinCAT
runtimes is trusted from field deployments.

The silver lining: TwinCAT is the only driver outside Galaxy that uses
**native notifications** (no polling) for `ISubscribable`, and the fake
exposes a fire-event harness so notification routing is contract-tested
rigorously — just not on the wire.

## What the fixture is

Nothing at the integration layer.
`tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/` is unit-only.
`FakeTwinCATClient` also fakes the `AddDeviceNotification` flow so tests can
trigger callbacks without a running runtime.

## What it actually covers (unit only)

- `TwinCATAmsAddressTests` — `ads://<netId>:<port>` parsing + routing
- `TwinCATCapabilityTests` — data-type mapping (primitives + declared UDTs),
  read-only classification
- `TwinCATReadWriteTests` — read + write through the fake, status mapping
- `TwinCATSymbolPathTests` — symbol-path routing for nested struct members
- `TwinCATSymbolBrowserTests` — `ITagDiscovery.DiscoverAsync` via
  `ReadSymbolsAsync` (#188) + system-symbol filtering
- `TwinCATNativeNotificationTests` — `AddDeviceNotification` (#189)
  registration, callback-delivery-to-`OnDataChange` wiring, unregister on
  unsubscribe
- `TwinCATDriverTests` — `IDriver` lifecycle

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

## What it does NOT cover

### 1. AMS / ADS wire traffic

No real AMS router frame is exchanged. Beckhoff's `TwinCAT.Ads` NuGet (their
own .NET SDK, not libplctag-style OSS) has no in-process fake; tests stub
the `ITwinCATClient` abstraction above it.

### 2. Multi-route AMS

ADS supports chained routes (`<localNetId> → <routerNetId> → <targetNetId>`)
for PLCs behind an EC master / IPC gateway. Parse coverage exists; wire-path
coverage doesn't.

### 3. Notification reliability under jitter

`AddDeviceNotification` delivers at the runtime's cycle boundary; under high
CPU load or network jitter real notifications can coalesce. The fake fires
one callback per test invocation — real callback-coalescing behavior is
untested.

### 4. TC2 vs TC3 variant handling

TwinCAT 2 (ADS v1) and TwinCAT 3 (ADS v2) have subtly different
`GetSymbolInfoByName` semantics + symbol-table layouts. Driver targets TC3;
TC2 compatibility is not exercised.

### 5. Cycle-time alignment for `ISubscribable`

Native ADS notifications fire on the PLC cycle boundary. The fake test
harness assumes notifications fire on a timer the test controls;
cycle-aligned firing under real PLC control is not verified.

### 6. Alarms / history

Driver doesn't implement `IAlarmSource` or `IHistoryProvider` — not in
scope for this driver family. TwinCAT 3's TcEventLogger could theoretically
back an `IAlarmSource`, but shipping that is a separate feature.

## When to trust TwinCAT tests, when to reach for a rig

| Question | Unit tests | Real TwinCAT runtime |
| --- | --- | --- |
| "Does the AMS address parser accept X?" | yes | - |
| "Does notification → `OnDataChange` wire correctly?" | yes (contract) | yes |
| "Does symbol browsing filter TwinCAT internals?" | yes | yes |
| "Does a real ADS read return correct bytes?" | no | yes (required) |
| "Do notifications coalesce under load?" | no | yes (required) |
| "Does a TC2 PLC work the same as TC3?" | no | yes (required) |

## Follow-up candidates

1. **TwinCAT 3 runtime on CI** — Beckhoff ships a free developer runtime
   (7-day trial, restartable). Could run on a Windows CI runner with a
   helper that auto-restarts the runtime every 6 days. Works but operational
   overhead.
2. **AdsSimulator** — Beckhoff has a closed-source "ADS simulator" library
   used internally; not publicly available.
3. **Lab rig** — cheapest IPC (CX7000 / CX9020) on a dedicated network; the
   only route that covers TC2 + real notification behavior + EtherCAT I/O
   effects.

Without a rig, TwinCAT correctness is trusted from the fake matching
reality, which has held across field deployments so far.

## Key fixture / config files

- `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/FakeTwinCATClient.cs` —
  in-process fake with the notification-fire harness used by
  `TwinCATNativeNotificationTests`
- `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs` — ctor takes
  `ITwinCATClientFactory`