1d3544f18e
S7 integration — AbCip/Modbus already have real-simulator integration suites; S7 had zero wire-level coverage despite being a Tier-A driver (all unit tests mocked IS7Client). Picked python-snap7's `snap7.server.Server` over raw Snap7 C library because `pip install` beats per-OS binary-pin maintenance, the package ships a Python __main__ shim that mirrors our existing pymodbus serve.ps1 + *.json pattern structurally, and the python-snap7 project is actively maintained. New project `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/` with four moving parts: (a) `Snap7ServerFixture` — collection-scoped TCP probe on `localhost:1102` that sets `SkipReason` when the simulator's not running, matching the `ModbusSimulatorFixture` shape one directory over (same S7_SIM_ENDPOINT env var override convention for pointing at a real S7 CPU on port 102); (b) `PythonSnap7/` — `serve.ps1` wrapper + `server.py` shim + `s7_1500.json` seed profile + `README.md` documenting install / run / known limitations; (c) `S7_1500/S7_1500Profile.cs` — driver-side `S7DriverOptions` whose tag addresses map 1:1 to the JSON profile's seed offsets (DB1.DBW0 u16, DB1.DBW10 i16, DB1.DBD20 i32, DB1.DBD30 f32, DB1.DBX50.3 bool, DB1.DBW100 scratch); (d) `S7_1500SmokeTests` — three tests proving typed reads + write-then-read round-trip work through real S7netplus + real ISO-on-TCP + real snap7 server. Picked port 1102 default instead of S7-standard 102 because 102 is privileged on Linux + triggers Windows Firewall prompt; S7netplus 0.20 has a 5-arg `Plc(CpuType, host, port, rack, slot)` ctor that lets the driver honour `S7DriverOptions.Port`, but the existing driver code called the 4-arg overload + silently hardcoded 102. One-line driver fix (S7Driver.cs:87) threads `_options.Port` through — the S7 unit suite (58/58) still passes unchanged because every unit test uses a fake IS7Client that never sees the real ctor. Server seed-type matrix in `server.py` covers u8 / i8 / u16 / i16 / u32 / i32 / f32 / bool-with-bit / ascii (S7 STRING with max_len header). register_area takes the SrvArea enum value, not the string name — a 15-minute debug after the first test run caught that; documented inline. Per-driver test-fixture coverage docs — eight new files in `docs/drivers/` laying out what each driver's harness actually benchmarks vs. what's trusted from field deployments. Pattern mirrors the AbServer-Test-Fixture.md doc that shipped earlier in this arc: TL;DR → What the fixture is → What it actually covers → What it does NOT cover → When-to-trust table → Follow-up candidates → Key files. Ugly truth the survey made visible: Galaxy + Modbus + (now) S7 + AB CIP have real wire-level coverage; AB Legacy / TwinCAT / FOCAS / OpcUaClient are still contract-only because their libraries ship no fake + no open-source simulator exists (AB Legacy PCCC), no public simulator exists (FOCAS), the vendor SDK has no in-process fake (TwinCAT/ADS.NET), or the test wiring just hasn't happened yet (OpcUaClient could trivially loopback against this repo's own server — flagged as #215). Each doc names the specific follow-up route: Snap7 server for S7 (done), TwinCAT 3 developer-runtime auto-restart for TwinCAT, Tier-C out-of-process Host for FOCAS, lab rigs for AB Legacy + hardware-gated bits of the others. `docs/drivers/README.md` gains a coverage-map section linking all eight. Tracking tasks #215-#222 filed for each PR-able follow-up. Build clean (driver + integration project + docs); S7.Tests 58/58 (unchanged); S7.IntegrationTests 3/3 (new, verified end-to-end against a live python-snap7 server: `driver_reads_seeded_u16_through_real_S7comm`, `driver_reads_seeded_typed_batch`, `driver_write_then_read_round_trip_on_scratch_word`). Next fixture follow-up is #215 (OpcUaClient loopback against own server) — highest ROI of the remaining set, zero external deps. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
96 lines
4.1 KiB
Markdown
96 lines
4.1 KiB
Markdown
# 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)
|
|
- `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`.
|
|
|
|
## 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 behavior
|
|
|
|
Per driver-stability.md, FOCAS should run process-isolated because
|
|
`Fwlib32.dll` has documented crash modes. The test suite runs in-process +
|
|
only exercises the happy path + mapped error codes — a native access
|
|
violation from the DLL would take the test host down. The process-isolation
|
|
path (similar to Galaxy's out-of-process Host) has been scoped but not
|
|
implemented.
|
|
|
|
## 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) |
|
|
|
|
## 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`
|
|
- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasDriver.cs` — ctor takes
|
|
`IFocasClientFactory`
|
|
- `docs/v2/driver-stability.md` — Tier C scope + process-isolation rationale
|