During SDK testing, it’s often useful to simulate real-world conditions or inspect communication between a client and a backend service. This lightweight local proxy helps developers spy on and inject both HTTP and WebSocket traffic for more effective debugging, experimentation, and test automation.
- Spy on Outgoing HTTP Requests
- Modify Incoming HTTP Responses
- Spy on Outgoing WebSocket Messages
- Modify Incoming WebSocket Messages
- Inject WebSocket Messages
- Validate SDK behavior against specific message sequences.
- Simulate dropped or malformed responses.
- Replay server messages for automated or regression testing.
- Monitor raw protocol-level activity to catch subtle bugs or race conditions.
Install npm dependency:
npm install --save-dev @ably-labs/local-proxyimport { createInterceptingProxy } from '@ably-labs/local-proxy';
// 1. Create and start the proxy
const proxy = createInterceptingProxy({
// options here realtimeHost, restHost
});
await proxy.start();
// 2. Configure your SDK to use proxy.options
const client = new Ably.Realtime({
...proxy.options
// aditonal option
});
// 3. Observe an outgoing HTTP request
const request = await proxy.observeNextRequest(req =>
req.url.includes('/channels')
);
// 4. Observe an incoming protocol message
proxy.observeNextIncomingProtocolMessage(msg =>
msg.action === 15 // Presence message
)
// 5. Inject a fake message into the client
proxy.injectProtocolMessage(client.connection.id, {
action: 9, // Example: SYNC
channel: 'room:test',
connectionId: client.connection.id,
msgSerial: 0,
connectionSerial: -1,
data: { custom: 'data' },
});You can also simulate faulty server responses:
proxy.replaceNextIncomingProtocolMessage(
{
action: 9, // Fake SYNC
channel: 'room:test',
data: [],
},
msg => msg.action === 9 // Replace only SYNC messages
);// Drop connection by ID (force disconnect)
proxy.dropConnection(client.connection.id);
// Pause and resume connection manually
const resume = proxy.pauseConnection();
// simulate a pause...
setTimeout(() => resume(), 5000);For more advanced use cases, register middlewares to continuously inspect or modify traffic:
const unregister = proxy.registerRestMiddleware(req => {
if (req.url.includes('/channels')) {
console.log('Intercepted REST request:', req);
// You can modify headers, body, or response here
}
});
// Later...
unregister();