TwinCAT XAR integration fixture — scaffold the code + docs so the Hyper-V VM + .tsproj drop in without fixture-code changes. Mirrors the AB CIP Logix Emulate scaffold shipped in PR #165: tier-gated smoke tests that skip cleanly when the VM isn't reachable, a project README documenting exactly what the XAR needs to run, fixture-coverage doc promoting TwinCAT from "no integration fixture" to "scaffolded + needs operational setup". The actual Beckhoff-side work (provision VM, install XAR, author tsproj, rotate 7-day trial) lives in #221 + the new TwinCatProject/README.md walkthrough.

New project tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/ with four pieces. TwinCATXarFixture — TCP probe against the ADS-over-TCP port 48898 on the host from TWINCAT_TARGET_HOST env var, requires TWINCAT_TARGET_NETID for the target AmsNetId, optional TWINCAT_TARGET_PORT for runtime 2+ (default 851 = PLC runtime 1). Doesn't own a lifecycle — XAR can't run in Docker because it bypasses the Windows kernel scheduler to hit real-time cycles, so the VM stays operator-managed. Explicit skip reasons surface the setup steps (start VM, set env vars, reactivate trial license) instead of a confusing hang. TwinCATFactAttribute + TwinCATTheoryAttribute — xunit skip gate matching AbServerFactAttribute / OpcPlcCollection patterns. TwinCAT3SmokeTests — three smoke tests through the real AdsTwinCATClient + real ADS over TCP. Driver_reads_seeded_DINT_through_real_ADS reads GVL_Fixture.nCounter, asserts >= 1234 (MAIN increments every cycle so an exact match would race). Driver_write_then_read_round_trip_on_scratch_REAL writes 42.5 to GVL_Fixture.rSetpoint + reads back, catches the ADS write path regression that unit tests can't see. Driver_subscribe_receives_native_ADS_notifications_on_counter_changes validates the #189 native-notification path end-to-end — AddDeviceNotification fires OnDataChange at the PLC cycle boundary, the test observes one firing within 3 s. All three gated on TWINCAT_TARGET_HOST + NETID; skip via TwinCATFactAttribute when unset, verified in this commit with 3 clean [SKIP] results. TwinCatProject/README.md — the tsproj state the smoke tests depend on. GVL_Fixture with nCounter:DINT:=1234 + rSetpoint:REAL:=0.0 + bFlag:BOOL:=TRUE; MAIN program with the single-line ladder `GVL_Fixture.nCounter := GVL_Fixture.nCounter + 1;`; PlcTask cyclic @ 10 ms priority 20; PLC runtime 1 (AMS port 851). Explains why tsproj over the compiled bootproject (text-diffable, rebuildable, no per-install state). Full XAR VM setup walkthrough — Hyper-V Gen 2 VM, TC3 XAE+XAR install, noting the AmsNetId from the tray icon, bilateral route configuration (VM System Manager → Routes + dev box StaticRoutes.xml), project import, Activate Configuration + Run Mode. License-rotation section walks through two options — scheduled TcActivate.exe /reactivate via Task Scheduler (not officially Beckhoff-supported, reportedly works on current builds) or paid runtime license (~$1k one-time per runtime per CPU). Final section shows the exact env-var recipe + dotnet test command on the dev box. docs/drivers/TwinCAT-Test-Fixture.md — flipped TL;DR from "there is no integration fixture" to "scaffolding lives at tests/..., remaining operational work is VM + tsproj + license rotation". "What the fixture is" gains an Integration section describing the XAR VM target. "What it actually covers" gains an Integration subsection listing the three named smoke tests. Follow-up candidates rewritten — the #1 item used to be "TwinCAT 3 runtime on CI" as a speculative option; now it's concrete "XAR VM live-population" with a link to #221 + the project README for the operational walkthrough. License rotation becomes #2 with both automation paths. Key fixture / config files list adds the three new files + the project README. docs/drivers/README.md coverage-map row updated from "no integration fixture" to "XAR-VM integration scaffolding". Solution file picks up the new tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests entry alongside the existing TwinCAT.Tests. xunit CollectionDefinition added to TwinCATXarFixture after the first build revealed the [Collection("TwinCATXar")] reference on TwinCAT3SmokeTests had no matching registration. Build 0 errors; 3 skip-clean test outcomes verified. #221 stays open as in_progress until the VM + tsproj land. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-20 13:11:17 -04:00
parent b820b9a05f
commit 7b49ea13c7
7 changed files with 525 additions and 26 deletions
--- a/docs/drivers/README.md
+++ b/docs/drivers/README.md
@@ -45,7 +45,7 @@ Each driver has a dedicated fixture doc that lays out what the integration / uni
 - [Modbus](Modbus-Test-Fixture.md) — Dockerized `pymodbus` + per-family JSON profiles (4 compose profiles); best-covered driver, gaps are error-path-shaped
 - [Siemens S7](S7-Test-Fixture.md) — Dockerized `python-snap7` server; DB/MB read + write round-trip verified end-to-end on `:1102`
 - [AB Legacy](AbLegacy-Test-Fixture.md) — no integration fixture, unit-only via `FakeAbLegacyTag` (libplctag PCCC)
- [TwinCAT](TwinCAT-Test-Fixture.md) — no integration fixture, unit-only via `FakeTwinCATClient` with native-notification harness
+- [TwinCAT](TwinCAT-Test-Fixture.md) — XAR-VM integration scaffolding (task #221); three smoke tests skip when VM unreachable. Unit via `FakeTwinCATClient` with native-notification harness
 - [FOCAS](FOCAS-Test-Fixture.md) — no integration fixture, unit-only via `FakeFocasClient`; Tier C out-of-process isolation scoped but not shipped
 - [OPC UA Client](OpcUaClient-Test-Fixture.md) — no integration fixture, unit-only via mocked `Session`; loopback against this repo's own server is the obvious next step
 - [Galaxy](Galaxy-Test-Fixture.md) — richest harness: E2E Host subprocess + ZB SQL live-smoke + MXAccess opt-in
--- a/docs/drivers/TwinCAT-Test-Fixture.md
+++ b/docs/drivers/TwinCAT-Test-Fixture.md
@@ -2,24 +2,62 @@

 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.
+**TL;DR:** Integration-test scaffolding lives at
+`tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/` (task #221).
+`TwinCATXarFixture` probes TCP 48898 on an operator-supplied VM; three
+smoke tests (read / write / native notification) run end-to-end through
+the real ADS stack when the VM is reachable, skip cleanly otherwise.
+**Remaining operational work**: stand up a TwinCAT 3 XAR runtime in a
+Hyper-V VM, author the `.tsproj` project documented at
+`TwinCatProject/README.md`, rotate the 7-day trial license (or buy a
+paid runtime). Unit tests via `FakeTwinCATClient` still carry the
+exhaustive contract coverage.

-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.
+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
+at the unit layer.

 ## 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.
+**Integration layer** (task #221, scaffolded):
+`tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/` —
+`TwinCATXarFixture` TCP-probes ADS port 48898 on the host specified by
+`TWINCAT_TARGET_HOST` + requires `TWINCAT_TARGET_NETID` (AmsNetId of the
+VM). No fixture-owned lifecycle — XAR can't run in Docker because it
+bypasses the Windows kernel scheduler, so the VM stays
+operator-managed. `TwinCatProject/README.md` documents the required
+`.tsproj` project state; the file itself lands once the XAR VM is up +
+the project is authored. Three smoke tests:
+`Driver_reads_seeded_DINT_through_real_ADS`,
+`Driver_write_then_read_round_trip_on_scratch_REAL`, and
+`Driver_subscribe_receives_native_ADS_notifications_on_counter_changes`
+— all skip cleanly via `[TwinCATFact]` when the runtime isn't
+reachable.

-## What it actually covers (unit only)
+**Unit layer**: `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/` is
+still the primary coverage. `FakeTwinCATClient` also fakes the
+`AddDeviceNotification` flow so tests can trigger callbacks without a
+running runtime.
+
+## What it actually covers
+
+### Integration (XAR VM, task #221 — code scaffolded, needs VM + project)
+
+- `TwinCAT3SmokeTests.Driver_reads_seeded_DINT_through_real_ADS` — real AMS
+  handshake + ADS read of `GVL_Fixture.nCounter` (seeded at 1234, MAIN
+  increments each cycle)
+- `TwinCAT3SmokeTests.Driver_write_then_read_round_trip_on_scratch_REAL` —
+  real ADS write + read on `GVL_Fixture.rSetpoint`
+- `TwinCAT3SmokeTests.Driver_subscribe_receives_native_ADS_notifications_on_counter_changes`
+  — real `AddDeviceNotification` against the cycle-incrementing counter;
+  observes `OnDataChange` firing within 3 s of subscribe
+
+All three gated on `TWINCAT_TARGET_HOST` + `TWINCAT_TARGET_NETID` env
+vars; skip cleanly via `[TwinCATFact]` when the VM isn't reachable or
+vars are unset.
+
+### Unit

 - `TwinCATAmsAddressTests` — `ads://<netId>:<port>` parsing + routing
 - `TwinCATCapabilityTests` — data-type mapping (primitives + declared UDTs),
@@ -89,21 +127,30 @@ back an `IAlarmSource`, but shipping that is a separate feature.

 ## 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.
+1. **XAR VM live-population** — scaffolding is in place (this PR); the
+   remaining work is operational: stand up the Hyper-V VM, install XAR,
+   author the `.tsproj` per `TwinCatProject/README.md`, configure the
+   bilateral ADS route, set `TWINCAT_TARGET_HOST` + `TWINCAT_TARGET_NETID`
+   on the dev box. Then the three smoke tests transition skip → pass.
+   Tracked as #221.
+2. **License-rotation automation** — XAR's 7-day trial expires on
+   schedule. Either automate `TcActivate.exe /reactivate` via a
+   scheduled task on the VM (not officially supported; reportedly works
+   for some TC3 builds), or buy a paid runtime license (~$1k one-time
+   per runtime per CPU) to kill the rotation. The doc at
+   `TwinCatProject/README.md` §License rotation walks through both.
+3. **Lab rig** — cheapest IPC (CX7000 / CX9020) on a dedicated network;
+   the only route that covers TC2 + real EtherCAT I/O timing + cycle
+   jitter under CPU load.

 ## Key fixture / config files

+- `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCATXarFixture.cs`
+  — TCP probe + skip-attributes + env-var parsing
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCAT3SmokeTests.cs`
+  — three wire-level smoke tests
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md`
+  — project spec + VM setup + license-rotation notes
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/FakeTwinCATClient.cs` —
  in-process fake with the notification-fire harness used by
  `TwinCATNativeNotificationTests`