blob: 7e175cd3ef04199e83692b5d5a15e6df904b5fdf [file] [view]
# Target test workflow
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](command_reference.md).
## Step 1: Start the test in the background
Run `fx test` with `--agent-debugging-mode` in the background so that you can
poll events while you monitor test output:
```posix-terminal
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`.
## Step 2: Poll for target events
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:
```posix-terminal
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:
```json
{
"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`.
## Step 3: Handle execution outcomes
Match the daemon response and `fx test` status to one of these four outcomes:
### Scenario A: Test failure or breakpoint hit
When `wait-for-event` returns a `"stopped"` event, follow these steps to inspect
the paused target:
1. **Query session state.** List active threads and attached processes:
```posix-terminal
fx debug cli get-state
```
Example response:
```json
{
"success": true,
"body": {
"threads": [
{ "thread_id": 1, "name": "initial-thread" }
],
"processes": { "12345": "my_test_binary" }
}
}
```
2. **Inspect stack traces.** Retrieve frames for one thread (`-t`) or across
all threads in a process (`-p`):
```posix-terminal
# 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:
```json
{
"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:
```json
{
"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
}
]
}
}
```
3. **Inspect local variables.** Read arguments and locals in a stack frame:
```posix-terminal
fx debug cli variables -t 1 --frame-index 0
```
4. **Evaluate expressions or run console commands.** Pass an expression
directly to `evaluate` without a `print` prefix:
```posix-terminal
fx debug cli evaluate -t 1 --frame-index 0 "my_var"
```
Example response:
```json
{
"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`:
```posix-terminal
fx debug cli console -t 1 --frame-index 0 sym-info my_var
```
5. **Stop the session.** After you finish diagnostics, stop the daemon. The
daemon detaches from targets so that `fx test` exits cleanly:
```posix-terminal
fx debug cli stop
```
### Scenario B: Clean pass
When all tests pass, the background `fx test` task exits with code 0 and reports
`FAILED: 0`.
- **Connection error edge case:** On a clean exit, `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).
- **Required action:** If `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`.
### Scenario C: Proactive breakpoints on tests that pass
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:
1. Pass `--breakpoint <source_file>:<line>` (relative to the workspace root) or
`--breakpoint <function_symbol>` to force a strong attach and load symbols
immediately:
```posix-terminal
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.
2. After compilation finishes, poll `wait-for-event` until the `"stopped"`
event arrives.
3. Inspect the target state. Then resume execution with
`fx debug cli continue <tid>`.
4. Poll `wait-for-event` again until `fx test` exits cleanly (Scenario B), or
run `fx debug cli stop` to end the session early.
### Scenario D: Unresponsive test
If a test stalls without a crash and `wait-for-event` times out, follow these
steps:
1. Run `fx debug cli get-state` to find the process KOID in `"processes"`.
2. Run `fx debug cli diagnose-hang -p <pid>` to classify blocked threads, open
handles, and async task trees (see [Live processes and
drivers](live_processes_and_drivers.md)), or run
`fx debug cli stack-trace -p <pid>`.
3. When you finish diagnostics, run `fx debug cli stop`.