Issue #49: add cross-language smoke matrix

2026-04-26 21:21:49 -04:00
parent 9159f6f093
commit 79f73e04fd
4 changed files with 662 additions and 0 deletions
@@ -0,0 +1,98 @@
+# 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:
+
+```powershell
+$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:
+
+```bash
+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](./GatewayTesting.md)
+- [Client Libraries Detailed Design](./client-libraries-design.md)
+- [Client Proto Generation](./client-proto-generation.md)