How to Inspect and Debug WebAssembly Modules in Safari Web Inspector

Modern client-side web applications increasingly compile high-performance computational workloads—such as 3D graphics rendering engines, cryptographic hashing algorithms, computer vision pipelines, audio synthesizers, and video codecs—into WebAssembly (Wasm). Because WebAssembly runs as compact, compiled binary bytecode (.wasm files), debugging logic errors or memory corruption without dedicated developer tooling can feel like examining a black box. Safari Web Inspector provides native WebAssembly debugging support, including automatic bytecode disassembly into readable WebAssembly text format (.wat), instruction breakpoints, and linear memory inspection.

In this guide, you will learn how to locate compiled Wasm modules, disassemble binary bytecode, set breakpoints on Wasm instructions, inspect the WebAssembly linear memory buffer, and step through call stacks in Safari Web Inspector on macOS.

Enabling Web Inspector and Locating WebAssembly Modules

Ensure that Safari developer tools are enabled on your Mac:

1. Open Safari on macOS.
2. Navigate to Safari > Settings > Advanced.
3. Check Show features for web developers.
4. Load your WebAssembly-enabled web application.
5. Open Web Inspector by pressing Option + Cmd + I.

In Web Inspector, click on the Sources tab. In the left navigation sidebar, navigate through the resource tree. WebAssembly modules initialized via WebAssembly.instantiate() or WebAssembly.compileStreaming() appear with a dedicated purple cube icon under your domain’s script hierarchy.

Automatic Bytecode Disassembly to WebAssembly Text (.wat)

When you select a binary .wasm resource in the Sources sidebar, Safari Web Inspector automatically disassembles the raw binary bytecode into standardized WebAssembly text format (WAT) in real time.

The disassembled view presents clean S-expressions and linear assembly instructions:

(module
  (type $t0 (func (param i32 i32) (result i32)))
  (func $add (type $t0) (param $p0 i32) (param $p1 i32) (result i32)
    local.get $p0
    local.get $p1
    i32.add)
  (export "add" (func $add)))

Line numbers displayed on the left margin correspond to sequential bytecode instructions, allowing you to debug low-level logic directly.

Setting Breakpoints and Stepping Through Bytecode

Debugging WebAssembly execution follows the same intuitive workflow as standard JavaScript:

1. Locate the target Wasm function in the disassembled code view.
2. Click directly on the line number in the left gutter to set a breakpoint (for example, on an i32.add or call instruction).
3. Trigger the action in your web application that executes the WebAssembly export.
4. Safari Web Inspector pauses execution immediately at the breakpoint.

While paused, use the standard debugger controls in the top right corner:

• Step Over (F10): Advances execution to the next Wasm instruction.
• Step Into (F11): Follows calls into internal Wasm helper functions or imported JavaScript callbacks.
• Step Out (Shift + F11): Executes the remainder of the current function and returns to the caller.

Inspecting Local Variables and the Value Stack

While paused inside a WebAssembly stack frame, examine the Scope Chain in the right-hand sidebar:

• Locals: Displays all function parameters ($p0, $p1) and locally declared variables, alongside their strict Wasm numeric types (i32, i64, f32, f64).
• Value Stack: WebAssembly is a stack-based virtual machine. Safari illustrates the evaluation stack, allowing you to see intermediate values pushed onto or popped off the stack before arithmetic or memory store operations.

Inspecting WebAssembly Linear Memory

WebAssembly modules manage raw state within a contiguous array of unmanaged bytes known as linear memory (WebAssembly.Memory). When debugging C, C++, or Rust code compiled to Wasm, tracking memory leaks or buffer bounds requires inspecting this underlying memory buffer.

To inspect linear memory in Safari Web Inspector:

1. In the Console tab while paused, query your module’s exported memory instance:

   instance.exports.memory.buffer

2. Safari returns an interactive ArrayBuffer object.
3. Expand the buffer or cast it to a typed view to inspect hexadecimal memory values:

   new Uint8Array(instance.exports.memory.buffer).slice(0, 64)

4. Use standard hexadecimal offset arithmetic to confirm that string pointers and struct byte alignments match expectations.

Debugging Source Maps with DWARF Symbols

If you compiled your WebAssembly binary from C/C++ or Rust using Emscripten or LLVM with debug flags enabled (e.g., -g or -g4):

• Safari Web Inspector automatically parses embedded DWARF symbol sections or source maps.
• Instead of displaying raw disassembled WAT instructions, the Sources tab maps bytecode directly back to your original source files (such as renderer.cpp or lib.rs).
• You can set breakpoints directly on original C++ or Rust source lines, inspecting variable values mapped from DWARF metadata seamlessly.