mxaccessgw/docs/GatewayTesting.md

Gateway Testing

Gateway tests run without installed MXAccess by using fake workers, fake transports, and in-process gRPC service fakes. Live MXAccess verification belongs in opt-in integration tests because it depends on installed COM components and provider state.

Fake Worker Harness

FakeWorkerHarness in src/MxGateway.Tests/Gateway/Workers/Fakes/ provides an in-process worker side for named-pipe IPC tests. It uses the same WorkerFrameReader, WorkerFrameWriter, and WorkerEnvelope contract as the gateway so tests exercise real frame validation and worker-client state changes.

Use the harness when a gateway or session test needs worker behavior without starting MxGateway.Worker.exe or loading MXAccess COM. The harness scripts:

• WorkerHello and WorkerReady startup,
• command replies with matching correlation ids,
• ordered WorkerEvent frames,
• WorkerHeartbeat frames,
• WorkerFault frames,
• shutdown acknowledgements,
• malformed protobuf payloads and oversized frame headers,
• slow or hung workers by withholding a reply.

Session-level tests can connect the harness to the pipe created by SessionWorkerClientFactory with ConnectToGatewayPipeAsync. Lower-level WorkerClient tests can use CreateConnectedPairAsync to create both pipe ends inside the test.

GatewayEndToEndFakeWorkerSmokeTests composes the real gRPC service, SessionManager, SessionWorkerClientFactory, WorkerClient, and EventStreamService with a scripted fake worker launcher. The smoke test covers OpenSession, Register, AddItem, Advise, one streamed OnDataChange event, and CloseSession without loading MXAccess COM.

Live MXAccess Smoke

WorkerLiveMxAccessSmokeTests in src/MxGateway.IntegrationTests/ composes the real gRPC service, SessionManager, SessionWorkerClientFactory, WorkerClient, WorkerProcessLauncher, and MxGateway.Worker.exe. It is skipped unless MXGATEWAY_RUN_LIVE_MXACCESS_TESTS=1 is set because it creates the installed MXAccess COM object and depends on live provider state.

The live smoke opens a gateway session, launches the x86 worker, runs Register, AddItem, and Advise, waits a bounded time for one OnDataChange, and closes the session in a finally block so the worker gets a graceful shutdown request even when a command or event assertion fails.

Build the worker before running the smoke:

dotnet build src/MxGateway.Worker/MxGateway.Worker.csproj -p:Platform=x86

Run the smoke explicitly:

$env:MXGATEWAY_RUN_LIVE_MXACCESS_TESTS = "1"
dotnet test src/MxGateway.IntegrationTests/MxGateway.IntegrationTests.csproj --filter FullyQualifiedName~WorkerLiveMxAccessSmokeTests

Optional live smoke variables:

Variable	Default	Description
MXGATEWAY_LIVE_MXACCESS_WORKER_EXE	First existing MxGateway.Worker.exe under src/MxGateway.Worker/bin/...	Worker executable path. Set this when running against a packaged worker or a non-default build output.
MXGATEWAY_LIVE_MXACCESS_ITEM	TestChildObject.TestInt	MXAccess item reference used by AddItem.
MXGATEWAY_LIVE_MXACCESS_CLIENT_NAME	MxGateway.IntegrationTests	Client name passed to Register.
MXGATEWAY_LIVE_MXACCESS_EVENT_TIMEOUT_SECONDS	15	Maximum wait for the first OnDataChange.

The test output includes session id, worker process id, command status, HRESULT/status diagnostics, event sequence and handles, close status, and worker stdout/stderr lines emitted during the run.

Client E2E Scripts

scripts/discover-testmachine-tags.ps1 queries the ZB Galaxy Repository for the deployed runtime references used by the live client e2e scripts. It reads TestMachine_001 through TestMachine_020 and the expected attributes:

• ProtectedValue
• TestChangingInt
• TestBoolArray
• TestIntArray
• TestDateTimeArray
• TestStringArray

The discovery output includes the exact fullTagReference, data type, array dimension, and security classification. The array attributes are expected to be dimension 50. ProtectedValue has security classification 2 and requires secured write semantics; the current client CLI e2e runner subscribes to it but does not attempt a normal Write.

Run discovery directly when validating the Galaxy Repository inputs:

powershell -ExecutionPolicy Bypass -File scripts/discover-testmachine-tags.ps1 -Json

scripts/run-client-e2e-tests.ps1 drives the .NET, Go, Rust, Python, and Java client CLIs through a live gateway session. For each client it opens one session, registers, verifies SubscribeBulk and UnsubscribeBulk on a bounded tag subset, adds and advises every discovered test tag, reads a bounded event stream, then closes the session in a finally path. The script writes a JSON report under artifacts/e2e/.

Build the gateway and worker, start the gateway, and provide a valid API key before running the client e2e script:

$env:MXGATEWAY_API_KEY = "<api-key>"
powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1

Useful runner options:

powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -Clients dotnet,python -MachineStart 1 -MachineEnd 2
powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -BulkTagCount 10
powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -SkipStream
powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -SkipBulk
powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -Endpoint localhost:5000 -ApiKeyEnv MXGATEWAY_API_KEY

Focused Commands

Run the cross-language smoke matrix tests after changing the documented client smoke command list:

dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~CrossLanguageSmokeMatrixTests

Run the parity fixture matrix tests after changing the integration parity scenario list:

dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~ParityFixtureMatrixTests

Run the fake worker tests after changing gateway worker IPC, session startup, or event streaming behavior:

dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~FakeWorkerHarnessTests
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~SessionWorkerClientFactoryFakeWorkerTests
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~GatewayEndToEndFakeWorkerSmokeTests
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~WorkerClientTests
dotnet test src/MxGateway.Worker.Tests/MxGateway.Worker.Tests.csproj -p:Platform=x86 --filter FullyQualifiedName~WorkerPipeSessionTests

Run the gateway test project after shared gateway test infrastructure changes:

dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj

Related Documentation

• Cross-Language Smoke Matrix
• Parity Fixture Matrix
• Gateway Process Design
• Worker Frame Protocol
• MXAccess Worker Instance Detailed Design