This documentation is part of the "Projects with Books" initiative at zenOSmosis.

The source code for this project is available on GitHub.

Integration Tests & muxio-ext-test Harness

Loading…

Integration Tests & muxio-ext-test Harness

Relevant source files

The Muxio testing infrastructure is designed to validate the entire RPC stack, from binary framing up to high-level service definitions, across multiple runtimes (Tokio and WASM) and transport types (WS, IPC, and MPSC). While unit tests reside within individual crates, complex integration tests—especially those involving circular dependencies between the client and server—are housed in a specialized harness.

muxio-ext-test: The Integration Harness

The muxio-ext-test crate is a utility library whose primary purpose is to provide a unified environment for integration tests that require both muxio-tokio-rpc-client and muxio-tokio-rpc-server extensions/muxio-ext-test/src/lib.rs:1-8 By placing tests here, the project avoids circular dependency issues during the cargo publish process extensions/muxio-ext-test/README.md:1-3

The TestTransport Trait

To achieve transport-agnostic testing, the harness defines the TestTransport trait extensions/muxio-ext-test/src/test_transport.rs:9-37 Any transport (WS, IPC, WASM, MPSC) that implements this trait can run the entire suite of integration tests.

Method	Purpose
`connect()`	Starts a server and returns a connected client with standard handlers (Add, Mult, Echo) registered extensions/muxio-ext-test/src/test_transport.rs18
`connect_fail()`	Validates that connecting to a non-existent endpoint returns an `io::Error` extensions/muxio-ext-test/src/test_transport.rs20
`connect_with_disconnect()`	Sets up a connection that can be explicitly closed via a `oneshot::Sender` to test cleanup logic extensions/muxio-ext-test/src/test_transport.rs21
`connect_s2c()`	Establishes a connection where the server holds a handle to call the client extensions/muxio-ext-test/src/test_transport.rs:22-26

Automated Test Discovery

The harness uses a custom build.rs to automatically discover and include test files.

Scanning : It recursively scans the tests/ directory for .rs files extensions/muxio-ext-test/build.rs:19-21
Generation : It generates a file named auto_tests.rs extensions/muxio-ext-test/build.rs:24-25
Module Mapping : Each discovered file is wrapped in a unique module and included via the include! macro extensions/muxio-ext-test/build.rs:40-51

Sources: extensions/muxio-ext-test/src/test_transport.rs:1-37 extensions/muxio-ext-test/build.rs:7-57 extensions/muxio-ext-test/README.md:5-13

Unified Test Suites

The harness provides macros to instantiate test suites for specific transports. These suites are defined in src/test_suites.rs extensions/muxio-ext-test/src/test_suites.rs:1-21

Prebuffered Roundtrip Tests

Generated via the prebuffered_roundtrip_tests! macro extensions/muxio-ext-test/src/lib.rs:12-44 these validate:

Success : Concurrent execution of Add, Mult, and Echo calls using tokio::join! extensions/muxio-ext-test/src/test_suites.rs:21-36
Error Propagation : Ensures that a handler returning an error results in an RpcServiceError::Rpc with the correct message extensions/muxio-ext-test/src/test_suites.rs:40-63
Large Payloads : Validates that payloads (e.g., 100KB) exceeding chunk limits are handled correctly extensions/muxio-ext-test/src/test_suites.rs:66-70
Method Not Found : Asserts that calling an unregistered ID returns RpcServiceErrorCode::NotFound extensions/muxio-ext-test/src/test_suites.rs:73-97

Server-to-Client (S2C) Tests

Generated via server_to_client_tests! extensions/muxio-ext-test/src/lib.rs:48-107

Client Registration : The client registers a handler on its own RpcServiceEndpoint extensions/muxio-ext-test/src/test_suites.rs:178-184
Server Initiation : The server uses a ConnectionContextHandle (or RpcIpcConnectionContextHandle) to initiate a call to the client extensions/muxio-ext-test/src/test_suites.rs187
Throughput & Concurrency: Tests like concurrent_bidirectional_streaming push data in both directions simultaneously to stress the frame multiplexer extensions/muxio-ext-test/src/test_suites.rs:79-90

Transport State Tests

Generated via transport_state_tests! extensions/muxio-ext-test/src/lib.rs:111-113

State Change Handler : Verifies that set_state_change_handler triggers Connected then Disconnected transitions extensions/muxio-ext-test/src/lib.rs:126-163
Request Cancellation : Ensures that pending requests fail immediately with a ConnectionAborted error if the transport drops extensions/muxio-ext-test/src/lib.rs:166-189

Sources: extensions/muxio-ext-test/src/test_suites.rs:21-198 extensions/muxio-ext-test/src/lib.rs:12-189 extensions/muxio-ext-test/README.md:17-25

Transport-Specific Implementations

Each transport implements the TestTransport trait to hook into the unified suites.

WebSocket (WS) & IPC

The WS implementation (src/transports/ws.rs) uses setup_ws_server and connect_ws_client helpers extensions/muxio-ext-test/src/transports/ws.rs:28-33 The IPC implementation (src/transports/ipc.rs) utilizes interprocess to create local sockets with unique names extensions/muxio-ext-test/src/transports/ipc.rs:19-45

WASM Bridge Implementation

Since RpcWasmClient is designed for browser environments, the integration test uses a setup_wasm_bridge helper extensions/muxio-ext-test/src/transports/wasm.rs:157-163

Title: WASM Integration Test Data Flow

Sources: extensions/muxio-ext-test/src/transports/ws.rs:19-141 extensions/muxio-ext-test/src/transports/ipc.rs:25-156 extensions/muxio-ext-test/src/transports/wasm.rs:18-190

Complex Integration Scenarios

Proxy Error Propagation

This test validates error handling in a multi-hop scenario: Client A - > Server (Proxy) -> Client B (Provider) extensions/muxio-ext-test/tests/muxio-tokio-rpc-server/proxy_error_propagation_tests.rs:1-6

The Proxy : The server registers an Echo handler that internally calls Echo::call on Client B’s handle extensions/muxio-ext-test/tests/muxio-tokio-rpc-server/proxy_error_propagation_tests.rs:78-99
Failure Injection : Client B is disconnected while Client A’s call is pending.
Verification : The server must catch the failure and return a ConnectionAborted error to Client A extensions/muxio-ext-test/tests/muxio-tokio-rpc-server/proxy_error_propagation_tests.rs:106-115

Streaming & Registration Conflicts

Streaming Handler : tests/streaming_handler_tests.rs validates the register_stream_handler pipeline, ensuring RpcStreamEvent (Payload/End) sequences are correctly delivered extensions/muxio-ext-test/src/transports/ipc.rs:125-144
Registration Conflicts : tests/registration_conflict_tests.rs ensures that attempting to register the same METHOD_ID twice on an RpcServiceEndpoint returns an error.

classDiagram
    class TestTransport {<<trait>>\n+connect()\n+connect_s2c()}
    class RpcIpcClient {
        +get_endpoint()
    }
    class RpcWasmClient {+handle_connect()\n+read_bytes()}
    class RpcClient {+new()}
    
    TestTransport <|-- RpcIpcClient
    TestTransport <|-- RpcWasmClient
    TestTransport <|-- RpcClient
    
    RpcIpcClient ..> RpcIpcServer : tests against
    RpcClient ..> RpcServer : tests against
    RpcWasmClient ..> RpcServer : tests via bridge

Title: Transport Component Relationships

Sources: extensions/muxio-ext-test/tests/muxio-tokio-rpc-server/proxy_error_propagation_tests.rs:25-126 extensions/muxio-ext-test/src/test_suites.rs:125-155 extensions/muxio-ext-test/src/transports/mod.rs:1-10

Keyboard shortcuts

rust-muxio Documentation