How to debug WebSocket traffic on macOS
Capture every WebSocket frame on your Mac, read JSON messages as they arrive, and pause, edit or drop frames to test how your app reacts.
Last updated 29 October 2026
Browser DevTools shows WebSocket frames for web pages, but not for a native app, a mobile app in the Simulator, or a backend service. A debugging proxy sees all of them. MinPin captures the HTTP upgrade and then every frame in both directions, while forwarding the bytes unchanged.
Capture frames
- Install MinPin and trust its certificate (Get Started → Install & Trust).
- Run the app that opens the WebSocket. Secure WebSockets (
wss://) are encrypted, so right-click the connection and choose Enable SSL for that host, then reconnect. - Select the connection and open the WebSocket tab.
The tab is a live table of frames with direction, time, type, length and a preview. Select a frame to see it pretty-printed as JSON, or as a hex dump for binary data. Filter to Sent or Received, and check the Handshake to see the upgrade headers.
Pause and edit frames (PRO)
Want to know how your app handles a malformed message, a missing field or a dropped event? Add a breakpoint for the socket's wss:// URL with Tools → Breakpoints (⌘⇧B). Each data frame then pauses before it is relayed, and you can:
- Continue (
⌘↩), after editing a text frame if you like, - Drop the frame (
⌘⌫), or - Abort the whole connection (
⌘.) to test your reconnect logic.
A paused frame continues on its own after 60 seconds, so a forgotten breakpoint cannot hang the connection for good. Protobuf payloads can be edited too.
Common problems
- The connection shows but no frames. SSL decoding is off for the host. Enable it and reconnect: decoding applies to new connections.
- The client refuses to connect after enabling SSL. The client does not trust MinPin's certificate. On a phone or simulator, install it there too (see Proxy iOS & Android).
More detail is in the WebSocket reference.