mxaccessgw/docs/CrossLanguageSmokeMatrix.md

Cross-Language Smoke Matrix

The cross-language smoke matrix defines the documented commands used to compare official clients against the same live gateway flow. It is a repository validation fixture and command reference; normal unit tests validate the matrix shape without connecting to a gateway.

The matrix lives in clients/proto/fixtures/smoke/cross-language-smoke-matrix.json.

Scope

The matrix covers the supported client languages:

• .NET
• Go
• Rust
• Python
• Java

Each client entry defines commands for the same required operation sequence:

1. open-session
2. register
3. add-item
4. advise
5. stream-events
6. close-session

The optional write command is documented separately because writing changes provider state and should only run when the operator supplies a safe test value.

Integration Gate

Cross-language smoke execution is opt-in. Runners should skip the matrix unless this variable is set:

$env:MXGATEWAY_INTEGRATION = "1"

The shared inputs are:

Variable	Default	Purpose
MXGATEWAY_ENDPOINT	localhost:5000	Gateway endpoint used by client CLIs.
MXGATEWAY_API_KEY	Empty	API key source for authenticated gateway deployments.
MXGATEWAY_TEST_ITEM	TestChildObject.TestInt	MXAccess item used by add-item.
MXGATEWAY_TEST_WRITE_VALUE	Empty	Enables the optional write step when set by a runner.

The commands in the matrix use MXGATEWAY_API_KEY through each CLI's api-key-env flag. They must not embed bearer tokens or raw API keys.

JSON Comparison

Every command in the matrix requests JSON output. A runner can compare the normalized smoke record across languages with these fields:

• language,
• operation,
• session id,
• server handle,
• item handle,
• event count,
• event family,
• worker sequence,
• protocol status,
• HRESULT,
• status arrays,
• close status.

Failure output must include the client language, endpoint, and redacted auth context. Auth context identifies the source, such as MXGATEWAY_API_KEY, but does not include the secret value.

Bundled Smoke Commands

Each client also exposes a bundled smoke command. Those commands are useful for quick local checks, but the full cross-language matrix uses explicit operation commands because not every bundled smoke command streams events yet. The explicit sequence remains the parity baseline for issue-level validation.

Validation

Run the matrix shape tests after changing the smoke matrix:

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

Live execution remains a separate opt-in step because it depends on a running gateway, the installed MXAccess worker path, and provider state.

Related Documentation

• Gateway Testing
• Client Libraries Detailed Design
• Client Proto Generation