Merge remote-tracking branch 'origin/main' into agent-3/issue-32-implement-heartbeat-and-watchdog
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,106 @@
|
||||
# Client Behavior Fixtures
|
||||
|
||||
Client behavior fixtures define the shared expectations used by the official
|
||||
.NET, Go, Rust, Python, and Java clients. They keep wrapper behavior aligned
|
||||
while each language exposes idiomatic APIs over the same protobuf contract.
|
||||
|
||||
## Fixture Set
|
||||
|
||||
The fixture manifest is `clients/proto/fixtures/behavior/manifest.json`.
|
||||
`clients/proto/proto-inputs.json` references the fixture root through
|
||||
`behaviorFixtureRoot` so generators and client test projects can discover the
|
||||
same files they use for descriptor inputs.
|
||||
|
||||
The fixture set contains:
|
||||
|
||||
- command reply protobuf JSON,
|
||||
- ordered event stream protobuf JSON samples,
|
||||
- `MxValue` conversion case sets,
|
||||
- `MxStatusProxy` conversion case sets,
|
||||
- authentication and authorization error expectations,
|
||||
- timeout and cancellation behavior expectations.
|
||||
|
||||
Protobuf message fixtures use protobuf JSON field names and enum values. Files
|
||||
that describe client wrapper behavior use explicit JSON fields instead of a
|
||||
proto message because those expectations apply above the generated transport
|
||||
types.
|
||||
|
||||
## Command Replies
|
||||
|
||||
Command reply fixtures live in
|
||||
`clients/proto/fixtures/behavior/command-replies/`. They parse as
|
||||
`mxaccess_gateway.v1.MxCommandReply`.
|
||||
|
||||
Clients use these fixtures to verify that successful and failed MXAccess
|
||||
commands both carry the full reply details:
|
||||
|
||||
- `protocolStatus`,
|
||||
- `hresult`,
|
||||
- `returnValue`,
|
||||
- repeated `statuses`,
|
||||
- method-specific reply payloads when MXAccess returns out parameters.
|
||||
|
||||
MXAccess failures remain command replies when the gateway reached the worker and
|
||||
the worker captured HRESULT or `MXSTATUS_PROXY` details. Client wrappers should
|
||||
map those replies to rich command errors without discarding the raw reply.
|
||||
|
||||
## Event Streams
|
||||
|
||||
Event stream fixtures live in
|
||||
`clients/proto/fixtures/behavior/event-streams/`. Each file contains an ordered
|
||||
`events` array whose entries parse as `mxaccess_gateway.v1.MxEvent`.
|
||||
|
||||
Clients use these fixtures to verify that stream helpers preserve
|
||||
`workerSequence` order and expose each native event family:
|
||||
|
||||
- `OnDataChange`,
|
||||
- `OnWriteComplete`,
|
||||
- `OperationComplete`,
|
||||
- `OnBufferedDataChange`.
|
||||
|
||||
Wrappers must not reorder, coalesce, or drop events while reading the fixture.
|
||||
|
||||
## Value And Status Conversion
|
||||
|
||||
Value fixtures live in `clients/proto/fixtures/behavior/values/`. Each case
|
||||
contains a `value` object that parses as `mxaccess_gateway.v1.MxValue`.
|
||||
|
||||
Status fixtures live in `clients/proto/fixtures/behavior/statuses/`. Each case
|
||||
contains a `status` object that parses as
|
||||
`mxaccess_gateway.v1.MxStatusProxy`.
|
||||
|
||||
Clients use these fixtures to verify typed projections and raw fallback
|
||||
behavior. A language helper may expose native booleans, integers, strings,
|
||||
arrays, and timestamps, but it must keep `rawDiagnostic`, raw data type fields,
|
||||
and raw byte payloads accessible when conversion is incomplete.
|
||||
|
||||
## Auth, Timeout, And Cancel Behavior
|
||||
|
||||
Authentication fixtures live in `clients/proto/fixtures/behavior/auth/`. They
|
||||
separate `UNAUTHENTICATED` from `PERMISSION_DENIED` so clients map missing or
|
||||
invalid credentials differently from missing scopes. Expected output strings
|
||||
contain only redacted credentials.
|
||||
|
||||
Timeout and cancellation fixtures live in
|
||||
`clients/proto/fixtures/behavior/timeout-cancel/`. They document that canceling
|
||||
or timing out a client call stops the client from waiting, but it does not abort
|
||||
an in-flight MXAccess COM call on the worker STA. Clients should follow up with
|
||||
`GetSessionState` or `CloseSession` before reusing handles after an uncertain
|
||||
command timeout.
|
||||
|
||||
## Validation
|
||||
|
||||
Run the fixture validation tests after changing the behavior fixture set:
|
||||
|
||||
```bash
|
||||
powershell -ExecutionPolicy Bypass -File scripts/validate-client-behavior-fixtures.ps1
|
||||
```
|
||||
|
||||
The script runs the focused C# contract tests that parse all protobuf JSON
|
||||
fixtures and validate deterministic wrapper expectation files.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Client Proto Generation](./client-proto-generation.md)
|
||||
- [Client Libraries Detailed Design](./client-libraries-design.md)
|
||||
- [Protobuf Contracts](./Contracts.md)
|
||||
@@ -29,6 +29,7 @@ Language-specific plans:
|
||||
Shared generation inputs:
|
||||
|
||||
- `docs/client-proto-generation.md`
|
||||
- `docs/ClientBehaviorFixtures.md`
|
||||
- `clients/proto/proto-inputs.json`
|
||||
|
||||
Language style guides:
|
||||
@@ -310,6 +311,11 @@ CLI output should support JSON for automated tests.
|
||||
Unit tests must run without a live gateway. Use fake gRPC services, mock
|
||||
transports, or generated test servers depending on language.
|
||||
|
||||
Shared behavior fixtures live in `clients/proto/fixtures/behavior`. Every
|
||||
client should include tests that load the fixture manifest and verify wrapper
|
||||
behavior against the common command reply, event stream, value conversion,
|
||||
status conversion, auth error, and timeout/cancel cases.
|
||||
|
||||
Required unit test areas:
|
||||
|
||||
- options parsing,
|
||||
|
||||
@@ -16,6 +16,7 @@ records:
|
||||
- the public and worker source files,
|
||||
- the descriptor set path,
|
||||
- golden fixture locations,
|
||||
- behavior fixture locations,
|
||||
- generated-code output directories for each planned client.
|
||||
|
||||
The source files listed by the manifest are:
|
||||
@@ -125,9 +126,30 @@ The fixtures use protobuf JSON field names and enum values. Contract tests parse
|
||||
them with the generated C# types so schema drift is caught before client
|
||||
generation work starts.
|
||||
|
||||
## Behavior Fixtures
|
||||
|
||||
Cross-language behavior fixtures live in
|
||||
`clients/proto/fixtures/behavior`. The manifest
|
||||
`clients/proto/fixtures/behavior/manifest.json` lists command replies, ordered
|
||||
event stream samples, value conversion cases, status conversion cases, auth
|
||||
error expectations, and timeout/cancel expectations.
|
||||
|
||||
The behavior fixtures let each generated client wrapper test the same
|
||||
expectations without a live gateway. Protobuf message fixtures parse with the
|
||||
generated types. Auth and timeout/cancel files describe wrapper behavior above
|
||||
the generated transport layer, including credential redaction and the rule that
|
||||
client cancellation does not abort an in-flight MXAccess COM call.
|
||||
|
||||
Run the focused validation script after changing these fixtures:
|
||||
|
||||
```powershell
|
||||
scripts/validate-client-behavior-fixtures.ps1
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Protobuf Contracts](./Contracts.md)
|
||||
- [Client Libraries Detailed Design](./client-libraries-design.md)
|
||||
- [Client Behavior Fixtures](./ClientBehaviorFixtures.md)
|
||||
- [Client Libraries Implementation Plan](./implementation-plan-clients.md)
|
||||
- [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md)
|
||||
|
||||
Reference in New Issue
Block a user