In agent debug mode, fx test starts zxdb and the background daemon automatically, attaches to target test processes, and stops the session on exit. --agent-debugging-mode, --break-on-failure, and --breakpoint support target tests only and do not work with --host. For subcommand flags and JSON schemas, see Command and JSON protocol reference.
Run fx test with --agent-debugging-mode in the background so that you can poll events while you monitor test output:
fx test <test_suite_name> --agent-debugging-mode
Note: By default, fx test runs fx build before it starts the debugger daemon. Wait for compilation to finish (or build first and pass --no-build) before you poll wait-for-event.
After compilation finishes, poll the daemon for state transitions with wait-for-event. Start with --last-seen-seq 0. On later calls, set --last-seen-seq to the highest "seq" returned:
fx debug cli wait-for-event --last-seen-seq 0 --timeout 10
Note: After fx test finishes compilation, the daemon can take 1 to 2 seconds to bind its socket.
If the first call after compilation fails with Daemon socket not found, wait briefly. Then run wait-for-event again.
When a test crashes or hits a breakpoint, wait-for-event returns a "stopped" event:
{ "success": true, "events": [ { "seq": 1, "event": "stopped", "body": { "thread_id": 1, "reason": "breakpoint" } } ] }
Caution: Monitor the background fx test task while you poll wait-for-event.
Match the daemon response and fx test status to one of these four outcomes:
When wait-for-event returns a "stopped" event, follow these steps to inspect the paused target:
Query session state. List active threads and attached processes:
fx debug cli get-state
Example response:
{ "success": true, "body": { "threads": [ { "thread_id": 1, "name": "initial-thread" } ], "processes": { "12345": "my_test_binary" } } }
Inspect stack traces. Retrieve frames for one thread (-t) or across all threads in a process (-p):
# Single thread stack trace fx debug cli stack-trace -t 1 # Process-wide stack traces across all threads in pid 12345 fx debug cli stack-trace -p 12345
Example thread response:
{ "success": true, "body": { "thread_id": 1, "stack_frames": [ { "frame_index": 0, "name": "my_test_function", "source": { "name": "main_test.cc", "path": "/src/main_test.cc" }, "line": 42, "column": 1 } ], "total_frames": 1 } }
Example process response:
{ "success": true, "body": { "process_id": 12345, "stacks": [ { "thread_id": 1, "stack_frames": [ { "frame_index": 0, "name": "my_test_function", "source": { "name": "main_test.cc", "path": "/src/main_test.cc" }, "line": 42, "column": 1 } ], "total_frames": 1 }, { "thread_id": 2, "stack_frames": [ { "frame_index": 0, "name": "worker_thread_entry", "source": { "name": "worker.cc", "path": "/src/worker.cc" }, "line": 105, "column": 5 } ], "total_frames": 1 } ] } }
Inspect local variables. Read arguments and locals in a stack frame:
fx debug cli variables -t 1 --frame-index 0
Evaluate expressions or run console commands. Pass an expression directly to evaluate without a print prefix:
fx debug cli evaluate -t 1 --frame-index 0 "my_var"
Example response:
{ "success": true, "body": { "result": "42", "type": "int" } }
If the target thread is active, variables, evaluate, and console -t pause it automatically and change stack frame indices. Before you pass --frame-index, run stack-trace on the paused thread.
For zxdb commands without a dedicated subcommand (such as symbol lookup or disassembly), run console:
fx debug cli console -t 1 --frame-index 0 sym-info my_var
Stop the session. After you finish diagnostics, stop the daemon. The daemon detaches from targets so that fx test exits cleanly:
fx debug cli stop
When all tests pass, the background fx test task exits with code 0 and reports FAILED: 0.
fx test stops the background daemon automatically. Any active wait-for-event call terminates with a socket connection error (such as connection refused or closed socket).wait-for-event returns a connection error, inspect the exit code of the background fx test task. If fx test exited with code 0, treat the run as a clean pass. Do not run fx debug cli stop.Without --breakpoint, fx test attaches weakly (attach --weak --recursive). Weak attach defers symbol loading until an exception occurs, so dynamic break requests stay pending and unverified until a crash.
To debug a code path that passes or pause before a failure, follow these steps:
Pass --breakpoint <source_file>:<line> (relative to the workspace root) or --breakpoint <function_symbol> to force a strong attach and load symbols immediately:
fx test <test_name> --agent-debugging-mode --breakpoint <source_file>:<line>
Note: fx test passes --breakpoint directly to zxdb, so those startup breakpoints do not appear in get-state output. Because --breakpoint forces a strong attach, later fx debug cli break commands also verify immediately.
After compilation finishes, poll wait-for-event until the "stopped" event arrives.
Inspect the target state. Then resume execution with fx debug cli continue <tid>.
Poll wait-for-event again until fx test exits cleanly (Scenario B), or run fx debug cli stop to end the session early.
If a test stalls without a crash and wait-for-event times out, follow these steps:
fx debug cli get-state to find the process KOID in "processes".fx debug cli diagnose-hang -p <pid> to classify blocked threads, open handles, and async task trees (see Live processes and drivers), or run fx debug cli stack-trace -p <pid>.fx debug cli stop.