chore: organize solution into module folders (Core/Server/Drivers/Client/Tooling)

Group all 69 projects into category subfolders under src/ and tests/ so the Rider Solution Explorer mirrors the module structure. Folders: Core, Server, Drivers (with a nested Driver CLIs subfolder), Client, Tooling. - Move every project folder on disk with git mv (history preserved as renames). - Recompute relative paths in 57 .csproj files: cross-category ProjectReferences, the lib/ HintPath+None refs in Driver.Historian.Wonderware, and the external mxaccessgw refs in Driver.Galaxy and its test project. - Rebuild ZB.MOM.WW.OtOpcUa.slnx with nested solution folders. - Re-prefix project paths in functional scripts (e2e, compliance, smoke SQL, integration, install). Build green (0 errors); unit tests pass. Docs left for a separate pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-17 01:55:28 -04:00
parent 69f02fed7f
commit a25593a9c6
1044 changed files with 365 additions and 343 deletions
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/Dockerfile
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/Dockerfile
@@ -0,0 +1,24 @@
+# python-snap7 S7 server container for the S7 integration suite.
+#
+# python-snap7 wraps the upstream snap7 C library; the pip install pulls
+# platform-specific binaries automatically on Debian-based images. No build
+# step needed — unlike ab_server which needs compiling from source.
+FROM python:3.12-slim-bookworm
+
+LABEL org.opencontainers.image.source="https://github.com/dohertj2/lmxopcua" \
+      org.opencontainers.image.description="python-snap7 S7 simulator for OtOpcUa S7 driver integration tests"
+
+RUN pip install --no-cache-dir "python-snap7>=2.0"
+
+WORKDIR /fixtures
+
+# server.py is the Python shim that loads a JSON profile + starts the
+# snap7.server.Server; profiles/ carries the seed definitions.
+COPY server.py /fixtures/
+COPY profiles/ /fixtures/
+
+EXPOSE 1102
+
+# -u for unbuffered stdout so `docker logs` tails the "seeded DB…"
+# diagnostics without a buffer-flush delay.
+CMD ["python", "-u", "/fixtures/server.py", "/fixtures/s7_1500.json", "--port", "1102"]
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/README.md
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/README.md
@@ -0,0 +1,92 @@
+# S7 integration-test fixture — python-snap7
+
+[python-snap7](https://github.com/gijzelaerr/python-snap7) `Server` class
+wrapped in a pinned `python:3.12-slim-bookworm` image. Docker is the
+only supported launch path — a fresh clone needs Docker Desktop and
+nothing else.
+
+| File | Purpose |
+|---|---|
+| [`Dockerfile`](Dockerfile) | `python:3.12-slim-bookworm` + `python-snap7>=2.0` + the server shim + the profile JSONs |
+| [`docker-compose.yml`](docker-compose.yml) | One service per profile; currently only `s7_1500` |
+| [`server.py`](server.py) | Same Python shim the native fallback uses — copy kept in the build context |
+| [`profiles/*.json`](profiles/) | Area-seed definitions (DB1 / MB layouts with typed seeds) |
+
+## Run
+
+From the repo root:
+
+```powershell
+docker compose -f tests\ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests\Docker\docker-compose.yml --profile s7_1500 up
+```
+
+Detached + stop:
+
+```powershell
+docker compose -f tests\...\Docker\docker-compose.yml --profile s7_1500 up -d
+docker compose -f tests\...\Docker\docker-compose.yml --profile s7_1500 down
+```
+
+## Endpoint
+
+- Default: `localhost:1102` (non-privileged; sidesteps Windows Firewall
+  prompt + Linux's root-required bind on port 102).
+- Override with `S7_SIM_ENDPOINT` to point at a real S7 CPU on `:102`.
+- The driver's S7DriverOptions.Port flows through S7netplus's 5-arg
+  `Plc(CpuType, host, port, rack, slot)` ctor so the non-standard port
+  works end-to-end.
+
+## Run the integration tests
+
+In a separate shell with the container up:
+
+```powershell
+cd C:\Users\dohertj2\Desktop\lmxopcua
+dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests
+```
+
+`Snap7ServerFixture` probes `localhost:1102` at collection init + records
+a `SkipReason` when unreachable, so tests stay green on a fresh clone
+without Docker running.
+
+## What's encoded in `profiles/s7_1500.json`
+
+DB1 (1024 bytes) + MB (256 bytes) with typed seeds at known offsets:
+
+| Address | Type | Seed | Purpose |
+|---|---|---|---|
+| `DB1.DBW0` | u16 | `4242` | read-back probe |
+| `DB1.DBW10` | i16 | `-12345` | smoke i16 read |
+| `DB1.DBD20` | i32 | `1234567890` | smoke i32 read |
+| `DB1.DBD30` | f32 | `3.14159` | smoke f32 read (big-endian) |
+| `DB1.DBX50.3` | bool | `true` | smoke bool read at bit 3 |
+| `DB1.DBW100` | u16 | `0` | scratch for write-then-read |
+| `DB1.STRING[200]` | S7 STRING | `"Hello"` | S7 STRING read |
+| `MW0` | u16 | `1` | `S7ProbeOptions.ProbeAddress` default |
+
+Seed types supported: `u8`, `i8`, `u16`, `i16`, `u32`, `i32`, `f32`,
+`bool` (with `"bit": 0..7`), `ascii` (S7 STRING).
+
+## Known limitations
+
+From the `snap7.server.Server` docstring upstream:
+
+> "Legacy S7 server implementation. Emulates a Siemens S7 PLC for testing
+> and development purposes. [...] pure Python emulator implementation that
+> simulates PLC behaviour for protocol compliance testing rather than
+> full industrial-grade functionality."
+
+Not exercised here — needs a lab rig:
+
+- S7-1500 Optimized-DB symbolic access
+- PG / OP / S7-Basic session-type differentiation
+- PUT/GET-disabled-by-default enforcement
+
+See [`docs/drivers/S7-Test-Fixture.md`](../../../docs/drivers/S7-Test-Fixture.md)
+for the full coverage map.
+
+## References
+
+- [python-snap7 GitHub](https://github.com/gijzelaerr/python-snap7)
+- [`docs/drivers/S7-Test-Fixture.md`](../../../docs/drivers/S7-Test-Fixture.md) — coverage map
+- [`docs/v2/dev-environment.md`](../../../docs/v2/dev-environment.md) §Docker fixtures
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/docker-compose.yml
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/docker-compose.yml
@@ -0,0 +1,20 @@
+# S7 integration-test fixture — python-snap7 server.
+#
+# One service per profile (only s7_1500 ships today; add S7-1200 / S7-300
+# as new profile JSONs drop into profiles/). All bind :1102 on the host;
+# run one at a time.
+#
+# Usage:
+#   docker compose --profile s7_1500 up
+services:
+  s7_1500:
+    profiles: ["s7_1500"]
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: otopcua-python-snap7:1.0
+    container_name: otopcua-python-snap7-s7_1500
+    restart: "no"
+    ports:
+      - "1102:1102"
+    command: ["python", "-u", "/fixtures/server.py", "/fixtures/s7_1500.json", "--port", "1102"]
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/profiles/s7_1500.json
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/profiles/s7_1500.json
@@ -0,0 +1,35 @@
+{
+  "_description": "S7-1500 profile — single DB1 (1024 bytes) + MB (256 bytes) with well-known seeds at named offsets for the smoke + byte-order + string tests. Big-endian Siemens wire order throughout.",
+  "areas": [
+    {
+      "area": "DB",
+      "index": 1,
+      "size": 1024,
+      "seeds": [
+        { "_desc": "DB1.DBW0 — read-back probe, S7Driver default ProbeAddress target is MW0; this shadows it",
+          "offset": 0, "type": "u16", "value": 4242 },
+        { "_desc": "DB1.DBW10 — i16 smoke value for SmokeI16 read path",
+          "offset": 10, "type": "i16", "value": -12345 },
+        { "_desc": "DB1.DBD20 — i32 smoke value for SmokeI32 read path",
+          "offset": 20, "type": "i32", "value": 1234567890 },
+        { "_desc": "DB1.DBD30 — f32 smoke value for SmokeF32 read path (IEEE-754 big-endian)",
+          "offset": 30, "type": "f32", "value": 3.14159 },
+        { "_desc": "DB1.DBX50.3 — bool bit at byte-50 bit-3 for SmokeBool read path",
+          "offset": 50, "type": "bool", "value": true, "bit": 3 },
+        { "_desc": "DB1.DBW100 — scratch for write-then-read round-trip tests; seeded 0",
+          "offset": 100, "type": "u16", "value": 0 },
+        { "_desc": "DB1.STRING[200] — S7 string 'Hello' (max 32, cur 5)",
+          "offset": 200, "type": "ascii", "value": "Hello", "max_len": 32 }
+      ]
+    },
+    {
+      "area": "MK",
+      "index": 0,
+      "size": 256,
+      "seeds": [
+        { "_desc": "MW0 — probe target for S7ProbeOptions.ProbeAddress default",
+          "offset": 0, "type": "u16", "value": 1 }
+      ]
+    }
+  ]
+}
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/server.py
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/server.py
@@ -0,0 +1,150 @@
+"""python-snap7 S7 server for integration tests.
+
+Reads a JSON profile from argv[1], allocates bytearrays for each declared area
+(DB / MB / EB / AB), poke-seeds values at declared offsets, then starts the
+snap7 Server on the configured port + blocks until Ctrl+C. Shape intentionally
+mirrors the pymodbus `serve.ps1 + *.json` pattern one directory over so
+someone familiar with the Modbus fixture can read this without re-learning.
+
+The snap7.server.Server class is the MIT-licensed S7 PLC emulator wrapped by
+python-snap7 (https://github.com/gijzelaerr/python-snap7). Its own docstring
+admits "protocol compliance testing rather than full industrial-grade
+functionality" — good enough for ISO-on-TCP wire-level round-trip but NOT
+for S7-1500 Optimized-DB symbolic access, SCL variant-specific behaviour, or
+PG/OP/S7-Basic session differentiation.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ctypes
+import json
+import signal
+import sys
+import time
+from pathlib import Path
+
+# python-snap7 installs as `snap7` package; Server class lives under `snap7.server`.
+import snap7
+from snap7.type import SrvArea
+
+
+# Map JSON area names → SrvArea enum values. PE = inputs (I/E), PA = outputs
+# (Q/A), MK = memory (M), DB = data blocks, TM = timers, CT = counters.
+AREA_MAP: dict[str, int] = {
+    "PE": SrvArea.PE,
+    "PA": SrvArea.PA,
+    "MK": SrvArea.MK,
+    "DB": SrvArea.DB,
+    "TM": SrvArea.TM,
+    "CT": SrvArea.CT,
+}
+
+
+def seed_buffer(buf: bytearray, seeds: list[dict]) -> None:
+    """Poke seed values into the area buffer at declared byte offsets.
+
+    Each seed is {"offset": int, "type": str, "value": int|float|bool|str}
+    where type ∈ {u8, i8, u16, i16, u32, i32, f32, bool, ascii}. Endianness is
+    big-endian (Siemens wire format).
+    """
+    for seed in seeds:
+        off = int(seed["offset"])
+        t = seed["type"]
+        v = seed["value"]
+        if t == "u8":
+            buf[off] = int(v) & 0xFF
+        elif t == "i8":
+            buf[off] = int(v) & 0xFF
+        elif t == "u16":
+            buf[off:off + 2] = int(v).to_bytes(2, "big", signed=False)
+        elif t == "i16":
+            buf[off:off + 2] = int(v).to_bytes(2, "big", signed=True)
+        elif t == "u32":
+            buf[off:off + 4] = int(v).to_bytes(4, "big", signed=False)
+        elif t == "i32":
+            buf[off:off + 4] = int(v).to_bytes(4, "big", signed=True)
+        elif t == "f32":
+            import struct
+            buf[off:off + 4] = struct.pack(">f", float(v))
+        elif t == "bool":
+            bit = int(seed.get("bit", 0))
+            if bool(v):
+                buf[off] |= (1 << bit)
+            else:
+                buf[off] &= ~(1 << bit) & 0xFF
+        elif t == "ascii":
+            # Siemens STRING type: byte 0 = max length, byte 1 = current length,
+            # bytes 2+ = payload. Seeds supply the payload text; we fill max/cur.
+            payload = str(v).encode("ascii")
+            max_len = int(seed.get("max_len", 254))
+            buf[off] = max_len
+            buf[off + 1] = len(payload)
+            buf[off + 2:off + 2 + len(payload)] = payload
+        else:
+            raise ValueError(f"Unknown seed type '{t}'")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="python-snap7 S7 server for integration tests")
+    parser.add_argument("profile", help="Path to profile JSON")
+    parser.add_argument("--port", type=int, default=1102, help="TCP port (default 1102 non-privileged)")
+    args = parser.parse_args()
+
+    profile_path = Path(args.profile)
+    if not profile_path.is_file():
+        print(f"profile not found: {profile_path}", file=sys.stderr)
+        return 1
+
+    with profile_path.open() as f:
+        profile = json.load(f)
+
+    server = snap7.server.Server()
+    # Keep bytearray refs alive for the server's lifetime — snap7 doesn't copy
+    # the buffer, it takes a pointer. Letting GC collect would corrupt reads.
+    buffers: list[bytearray] = []
+
+    for area_decl in profile.get("areas", []):
+        area_name = area_decl["area"]
+        if area_name not in AREA_MAP:
+            print(f"unknown area '{area_name}' (expected one of {list(AREA_MAP)})", file=sys.stderr)
+            return 1
+        index = int(area_decl.get("index", 0))  # DB number for DB area, 0 for MK/PE/PA
+        size = int(area_decl["size"])
+        buf = bytearray(size)
+        seed_buffer(buf, area_decl.get("seeds", []))
+        buffers.append(buf)
+        # register_area takes (area, index, c-array); we wrap the bytearray
+        # into a ctypes char array so the native lib can take &buf[0].
+        arr_type = ctypes.c_char * size
+        arr = arr_type.from_buffer(buf)
+        server.register_area(AREA_MAP[area_name], index, arr)
+        print(f"  seeded {area_name}{index} size={size} seeds={len(area_decl.get('seeds', []))}")
+
+    port = int(args.port)
+    print(f"Starting python-snap7 server on TCP {port}  (Ctrl+C to stop)")
+    server.start(tcp_port=port)
+
+    stop = {"sig": False}
+    def _handle(*_a):
+        stop["sig"] = True
+    signal.signal(signal.SIGINT, _handle)
+    try:
+        signal.signal(signal.SIGTERM, _handle)
+    except Exception:
+        pass  # SIGTERM not on all platforms
+
+    try:
+        while not stop["sig"]:
+            time.sleep(0.25)
+    finally:
+        print("stopping python-snap7 server")
+        try:
+            server.stop()
+        except Exception:
+            pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/S7_1500/S7_1500Profile.cs
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/S7_1500/S7_1500Profile.cs
@@ -0,0 +1,53 @@
+using S7NetCpuType = global::S7.Net.CpuType;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests.S7_1500;
+
+/// <summary>
+///     Driver-side configuration matching what <c>Docker/profiles/s7_1500.json</c> seeds
+///     into the simulator's DB1 + MB areas. Tag names here become the full references
+///     the smoke tests read/write against; addresses map 1:1 to the JSON profile's
+///     seed offsets so a seed drift in the JSON surfaces as a driver-side read
+///     mismatch, not a mystery test failure.
+/// </summary>
+public static class S7_1500Profile
+{
+    public const string ProbeTag = "ProbeProbeWord";
+    public const int ProbeSeedValue = 4242;
+
+    public const string SmokeI16Tag = "SmokeI16";
+    public const short SmokeI16SeedValue = -12345;
+
+    public const string SmokeI32Tag = "SmokeI32";
+    public const int SmokeI32SeedValue = 1234567890;
+
+    public const string SmokeF32Tag = "SmokeF32";
+    public const float SmokeF32SeedValue = 3.14159f;
+
+    public const string SmokeBoolTag = "SmokeBool";
+
+    public const string WriteScratchTag = "WriteScratch";
+
+    public static S7DriverOptions BuildOptions(string host, int port) => new()
+    {
+        Host = host,
+        Port = port,
+        CpuType = S7NetCpuType.S71500,
+        Rack = 0,
+        Slot = 0,
+        Timeout = TimeSpan.FromSeconds(5),
+        // Disable the probe loop — the integration tests run their own reads +
+        // a background probe would race with them for the S7netplus mailbox
+        // gate, injecting flakiness that has nothing to do with the code
+        // under test.
+        Probe = new S7ProbeOptions { Enabled = false },
+        Tags =
+        [
+            new S7TagDefinition(ProbeTag,     "DB1.DBW0",  S7DataType.UInt16),
+            new S7TagDefinition(SmokeI16Tag,  "DB1.DBW10", S7DataType.Int16),
+            new S7TagDefinition(SmokeI32Tag,  "DB1.DBD20", S7DataType.Int32),
+            new S7TagDefinition(SmokeF32Tag,  "DB1.DBD30", S7DataType.Float32),
+            new S7TagDefinition(SmokeBoolTag, "DB1.DBX50.3", S7DataType.Bool),
+            new S7TagDefinition(WriteScratchTag, "DB1.DBW100", S7DataType.UInt16),
+        ],
+    };
+}
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/S7_1500/S7_1500SmokeTests.cs
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/S7_1500/S7_1500SmokeTests.cs
@@ -0,0 +1,83 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests.S7_1500;
+
+/// <summary>
+///     End-to-end smoke against the python-snap7 S7-1500 profile. Drives the real
+///     <see cref="S7Driver"/> + real S7netplus ISO-on-TCP stack + real CIP-free
+///     S7comm exchange against <c>localhost:1102</c>. Success proves initialisation,
+///     typed reads (u16 / i16 / i32 / f32 / bool-with-bit), and a write-then-read
+///     round-trip all work against a real S7 server — the baseline everything
+///     S7-specific (byte-order, optimized-DB differences, probe behaviour) layers on.
+/// </summary>
+[Collection(Snap7ServerCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "S7_1500")]
+public sealed class S7_1500SmokeTests(Snap7ServerFixture sim)
+{
+    [Fact]
+    public async Task Driver_reads_seeded_u16_through_real_S7comm()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        var options = S7_1500Profile.BuildOptions(sim.Host, sim.Port);
+        await using var drv = new S7Driver(options, driverInstanceId: "s7-smoke-u16");
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var snapshots = await drv.ReadAsync(
+            [S7_1500Profile.ProbeTag], TestContext.Current.CancellationToken);
+
+        snapshots.Count.ShouldBe(1);
+        snapshots[0].StatusCode.ShouldBe(0u, "seeded u16 read must succeed end-to-end");
+        Convert.ToInt32(snapshots[0].Value).ShouldBe(S7_1500Profile.ProbeSeedValue);
+    }
+
+    [Fact]
+    public async Task Driver_reads_seeded_typed_batch()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        var options = S7_1500Profile.BuildOptions(sim.Host, sim.Port);
+        await using var drv = new S7Driver(options, driverInstanceId: "s7-smoke-batch");
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var snapshots = await drv.ReadAsync(
+            [S7_1500Profile.SmokeI16Tag, S7_1500Profile.SmokeI32Tag,
+             S7_1500Profile.SmokeF32Tag, S7_1500Profile.SmokeBoolTag],
+            TestContext.Current.CancellationToken);
+
+        snapshots.Count.ShouldBe(4);
+        foreach (var s in snapshots) s.StatusCode.ShouldBe(0u);
+
+        Convert.ToInt32(snapshots[0].Value).ShouldBe((int)S7_1500Profile.SmokeI16SeedValue);
+        Convert.ToInt32(snapshots[1].Value).ShouldBe(S7_1500Profile.SmokeI32SeedValue);
+        Convert.ToSingle(snapshots[2].Value).ShouldBe(S7_1500Profile.SmokeF32SeedValue, tolerance: 0.0001f);
+        Convert.ToBoolean(snapshots[3].Value).ShouldBeTrue();
+    }
+
+    [Fact]
+    public async Task Driver_write_then_read_round_trip_on_scratch_word()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        var options = S7_1500Profile.BuildOptions(sim.Host, sim.Port);
+        await using var drv = new S7Driver(options, driverInstanceId: "s7-smoke-write");
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        const ushort probe = 0xBEEF;
+        var writeResults = await drv.WriteAsync(
+            [new WriteRequest(S7_1500Profile.WriteScratchTag, probe)],
+            TestContext.Current.CancellationToken);
+        writeResults.Count.ShouldBe(1);
+        writeResults[0].StatusCode.ShouldBe(0u,
+            "write must succeed against snap7's DB1.DBW100 scratch register");
+
+        var readResults = await drv.ReadAsync(
+            [S7_1500Profile.WriteScratchTag], TestContext.Current.CancellationToken);
+        readResults.Count.ShouldBe(1);
+        readResults[0].StatusCode.ShouldBe(0u);
+        Convert.ToInt32(readResults[0].Value).ShouldBe(probe);
+    }
+}
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Snap7ServerFixture.cs
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Snap7ServerFixture.cs
@@ -0,0 +1,83 @@
+using System.Net.Sockets;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests;
+
+/// <summary>
+///     Reachability probe for the python-snap7 simulator Docker container (see
+///     <c>Docker/docker-compose.yml</c>) or a real S7 PLC. Parses <c>S7_SIM_ENDPOINT</c>
+///     (default <c>localhost:1102</c>) + TCP-connects once at fixture construction.
+///     Tests check <see cref="SkipReason"/> + call <c>Assert.Skip</c> when unreachable, so
+///     `dotnet test` stays green on a fresh box without the simulator installed —
+///     mirrors the <c>ModbusSimulatorFixture</c> pattern.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Default port is <b>1102</b>, not the S7-standard 102. 102 is a privileged port
+///         on Linux (needs root) + triggers the Windows Firewall prompt on first bind;
+///         1102 sidesteps both. S7netplus 0.20 supports the 5-arg <c>Plc</c> ctor that
+///         takes an explicit port (verified + wired through <c>S7DriverOptions.Port</c>),
+///         so the driver can reach the simulator on its non-standard port without
+///         hacks.
+///     </para>
+///     <para>
+///         The probe is a one-shot liveness check; tests open their own S7netplus
+///         sessions against the same endpoint. Don't share a socket — S7 CPUs serialise
+///         concurrent connections against the same mailbox anyway, but sharing would
+///         couple test ordering to socket reuse in ways this harness shouldn't care
+///         about.
+///     </para>
+///     <para>
+///         Fixture is a collection fixture so the probe runs once per test session, not
+///         per test.
+///     </para>
+/// </remarks>
+public sealed class Snap7ServerFixture : IAsyncDisposable
+{
+    // Default 1102 (non-privileged) matches Docker/server.py. Override with
+    // S7_SIM_ENDPOINT to point at a real PLC on its native 102.
+    private const string DefaultEndpoint = "localhost:1102";
+    private const string EndpointEnvVar = "S7_SIM_ENDPOINT";
+
+    public string Host { get; }
+    public int Port { get; }
+    public string? SkipReason { get; }
+
+    public Snap7ServerFixture()
+    {
+        var raw = Environment.GetEnvironmentVariable(EndpointEnvVar) ?? DefaultEndpoint;
+        var parts = raw.Split(':', 2);
+        Host = parts[0];
+        Port = parts.Length == 2 && int.TryParse(parts[1], out var p) ? p : 102;
+
+        try
+        {
+            // Force IPv4 — python-snap7 binds 0.0.0.0 (IPv4) and .NET's default
+            // dual-stack "localhost" resolves IPv6 ::1 first then times out before
+            // falling back. Same story the Modbus fixture hits.
+            using var client = new TcpClient(AddressFamily.InterNetwork);
+            var task = client.ConnectAsync(
+                System.Net.Dns.GetHostAddresses(Host)
+                    .FirstOrDefault(a => a.AddressFamily == AddressFamily.InterNetwork)
+                    ?? System.Net.IPAddress.Loopback,
+                Port);
+            if (!task.Wait(TimeSpan.FromSeconds(2)) || !client.Connected)
+            {
+                SkipReason = $"python-snap7 simulator at {Host}:{Port} did not accept a TCP connection within 2s. " +
+                             $"Start it (docker compose -f Docker/docker-compose.yml --profile s7_1500 up -d) or override {EndpointEnvVar}.";
+            }
+        }
+        catch (Exception ex)
+        {
+            SkipReason = $"python-snap7 simulator at {Host}:{Port} unreachable: {ex.GetType().Name}: {ex.Message}. " +
+                         $"Start it (docker compose -f Docker/docker-compose.yml --profile s7_1500 up -d) or override {EndpointEnvVar}.";
+        }
+    }
+
+    public ValueTask DisposeAsync() => ValueTask.CompletedTask;
+}
+
+[Xunit.CollectionDefinition(Name)]
+public sealed class Snap7ServerCollection : Xunit.ICollectionFixture<Snap7ServerFixture>
+{
+    public const string Name = "Snap7Server";
+}
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests.csproj
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests.csproj
@@ -0,0 +1,35 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <IsPackable>false</IsPackable>
+        <IsTestProject>true</IsTestProject>
+        <RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests</RootNamespace>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="xunit.v3" Version="1.1.0"/>
+        <PackageReference Include="Shouldly" Version="4.3.0"/>
+        <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0"/>
+        <PackageReference Include="xunit.runner.visualstudio" Version="3.0.2">
+            <PrivateAssets>all</PrivateAssets>
+            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        </PackageReference>
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\..\..\src\Drivers\ZB.MOM.WW.OtOpcUa.Driver.S7\ZB.MOM.WW.OtOpcUa.Driver.S7.csproj"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <None Update="Docker\**\*" CopyToOutputDirectory="PreserveNewest"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-37gx-xxp4-5rgx"/>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-w3x6-4m5h-cxqf"/>
+    </ItemGroup>
+
+</Project>