lmxopcua/docs/drivers/FOCAS-Test-Fixture.md

# FOCAS test fixture

Coverage map + gap inventory for the FANUC FOCAS2 CNC driver.

**TL;DR: there is no integration fixture.** Every test uses a
`FakeFocasClient` injected via `IFocasClientFactory`. Fanuc's FOCAS library
(`Fwlib32.dll`) is closed-source proprietary with no public simulator;
CNC-side behavior is trusted from field deployments.

## What the fixture is

Nothing at the integration layer.
`tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/` is unit-only. The driver ships
as Tier C (process-isolated) per `docs/v2/driver-stability.md` because the
FANUC DLL has known crash modes; tests can't replicate those in-process.

## What it actually covers (unit only)

- `FocasCapabilityTests` — data-type mapping (PMC bit / word / float,
  macro variable types, parameter types)
- `FocasCapabilityMatrixTests` — per-CNC-series range validation (macro
  / parameter / PMC letter + number) across 16i / 0i-D / 0i-F /
  30i / PowerMotion. See [`docs/v2/focas-version-matrix.md`](../v2/focas-version-matrix.md)
  for the authoritative matrix. 46 theory cases lock every documented
  range boundary — widening a range without updating the doc fails a
  test.
- `FocasReadWriteTests` — read + write against the fake, FOCAS native status
  → OPC UA StatusCode mapping
- `FocasScaffoldingTests` — `IDriver` lifecycle + multi-device routing
- `FocasPmcBitRmwTests` — PMC bit read-modify-write synchronization (per-byte
  `SemaphoreSlim`, mirrors the AB / Modbus pattern from #181)
- `FwlibNativeHelperTests` — `Focas32.dll` → `Fwlib32.dll` bridge validation
  + P/Invoke signature validation

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

Pre-flight validation runs in `FocasDriver.InitializeAsync` — configs
referencing out-of-range addresses fail at load time with a diagnostic
message naming the CNC series + documented limit. This closes the
cheap half of the hardware-free stability gap; Tier-C process
isolation (task #220) closes the expensive half — see
[`docs/v2/implementation/focas-isolation-plan.md`](../v2/implementation/focas-isolation-plan.md).

## What it does NOT cover

### 1. FOCAS wire traffic

No FOCAS TCP frame is sent. `Fwlib32.dll`'s TCP-to-FANUC-gateway exchange is
closed-source; the driver trusts the P/Invoke layer per #193. Real CNC
correctness is trusted from field deployments.

### 2. Alarm / parameter-change callbacks

FOCAS has no push model — the driver polls via the shared `PollGroupEngine`.
There are no CNC-initiated callbacks to test; the absence is by design.

### 3. Macro / ladder variable types

FANUC has CNC-specific extensions (macro variables `#100-#999`, system
variables `#1000-#5000`, PMC timers / counters / keep-relays) whose
per-address semantics differ across 0i-F / 30i / 31i / 32i Series. Driver
covers the common address shapes; per-model quirks are not stressed.

### 4. Model-specific behavior

- Alarm retention across power cycles (model-specific CNC behavior)
- Parameter range enforcement (CNC rejects out-of-range writes)
- MTB (machine tool builder) custom screens that expose non-standard data

### 5. Tier-C process isolation — architecture shipped, Fwlib32 integration hardware-gated

The Tier-C architecture is now in place as of PRs #169–#173 (FOCAS
PR A–E, task #220):

- `Driver.FOCAS.Shared` carries MessagePack IPC contracts
- `Driver.FOCAS.Host` (.NET 4.8 x86 Windows service via NSSM) accepts
  a connection on a strictly-ACL'd named pipe + dispatches frames to
  an `IFocasBackend`
- `Driver.FOCAS.Ipc.IpcFocasClient` implements the `IFocasClient` DI
  seam by forwarding over IPC — swap the DI registration and the
  driver runs Tier-C with zero other changes
- `Driver.FOCAS.Supervisor.FocasHostSupervisor` owns the spawn +
  heartbeat + respawn + 3-in-5min crash-loop breaker + sticky alert
- `Driver.FOCAS.Host.Stability.PostMortemMmf` ↔
  `Driver.FOCAS.Supervisor.PostMortemReader` — ring-buffer of the
  last ~1000 IPC operations survives a Host crash

The one remaining gap is the production `FwlibHostedBackend`: an
`IFocasBackend` implementation that wraps the licensed
`Fwlib32.dll` P/Invoke. That's hardware-gated on task #222 — we
need a CNC on the bench (or the licensed FANUC developer kit DLL
with a test harness) to validate it. Until then, the Host ships
`FakeFocasBackend` + `UnconfiguredFocasBackend`. Setting
`OTOPCUA_FOCAS_BACKEND=fake` lets operators smoke-test the whole
Tier-C pipeline end-to-end without any CNC.

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

| Question | Unit tests | Real CNC |
| --- | --- | --- |
| "Does PMC address `R100.3` route to the right bit?" | yes | yes |
| "Does the FANUC status → OPC UA StatusCode map cover every documented code?" | yes (contract) | yes |
| "Does a real read against a 30i Series return correct bytes?" | no | yes (required) |
| "Does `Fwlib32.dll` crash on concurrent reads?" | no | yes (stress) |
| "Do macro variables round-trip across power cycles?" | no | yes (required) |

## Alarm history (`cnc_rdalmhistry`) — issue #267, plan PR F3-a

`FocasAlarmProjection` ships two modes:

- **`ActiveOnly`** (default) — surfaces only currently-active alarms.
  No history poll. Same back-compat shape every prior FOCAS deployment used.
- **`ActivePlusHistory`** — additionally polls `cnc_rdalmhistry` on connect
  + on the configured cadence (`HistoryPollInterval`, default 5 min). Each
  unseen entry fires an `OnAlarmEvent` with `SourceTimestampUtc` set from
  the CNC's reported timestamp, not Now.

Unit-test coverage in `FocasAlarmProjectionTests`:

- mode `ActiveOnly` — no `ReadAlarmHistoryAsync` call ever issued
- mode `ActivePlusHistory` — first poll fires on subscribe (== "on connect")
- dedup — same `(OccurrenceTime, AlarmNumber, AlarmType)` triple across two
  polls only emits once
- distinct entries with different timestamps each emit separately
- same alarm number / different type still emits both (type is part of the
  dedup key)
- `OccurrenceTime` is the wire timestamp (round-trips a year-old stamp
  without bleeding into Now)
- `HistoryDepth` clamp — user-supplied 500 collapses to 250 on the wire;
  zero / negative falls back to the 100 default
- `FocasAlarmHistoryDecoder` — round-trips through `Encode` / `Decode` and
  pins the simulator command id at `0x0F1A`

Future integration coverage (not yet shipped — no FOCAS integration test
project exists):

- a focas-mock with a per-profile ring buffer and `mock_patch_alarmhistory`
  admin endpoint will let `cnc_rdalmhistry` round-trip end-to-end through
  the wire protocol
- `FocasSimFixture.SeedAlarmHistoryAsync` will let series tests prime canned
  history without per-test JSON

## Follow-up candidates

1. **Nothing public** — Fanuc's FOCAS Developer Kit ships an emulator DLL
   but it's under NDA + tied to licensed dev-kit installations; can't
   redistribute for CI.
2. **Lab rig** — used FANUC 0i-F simulator controller (or a retired machine
   tool) on a dedicated network; only path that covers real CNC behavior.
3. **Process isolation first** — before trusting FOCAS in production at
   scale, shipping the Tier-C out-of-process Host architecture (similar to
   Galaxy) is higher value than a CI simulator.

## Key fixture / config files

- `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FakeFocasClient.cs` —
  in-process fake implementing `IFocasClient`
- `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FocasCapabilityMatrixTests.cs`
  — parameterized theories locking the per-series matrix
- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasDriver.cs` — ctor takes
  `IFocasClientFactory`
- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasCapabilityMatrix.cs` —
  per-CNC-series range validator (the matrix the doc describes)
- `docs/v2/focas-version-matrix.md` — authoritative range reference
- `docs/v2/implementation/focas-isolation-plan.md` — Tier-C isolation
  plan (task #220)
- `docs/v2/driver-stability.md` — Tier C scope + process-isolation rationale