# Debug a test with a session

`wdio run --debug=agent` pauses the worker on `await browser.debug()` and after a failed test, and raises the framework timeout to 24 hours. The pause covers both Mocha tests and Cucumber steps. The run prints the session name (`debug-0-0` for the first worker):

```
npx wdio run wdio.conf.ts --debug=agent

npx wdio session -s debug-0-0 snapshot

npx wdio session -s debug-0-0 exec -e "await browser.getTitle()"

npx wdio session -s debug-0-0 resume
```

`close` on that session fails the paused test with `Session closed from wdio session`. Resume when the test should continue. Close when you want the run to fail at the pause.

`browser.debug()` without `--debug=agent` still opens the [REPL](/docs/repl.md) inside the test. `--debug=agent` is the path that lets another process, including a coding agent, drive the paused worker with `wdio session`.

## Attach a REPL[​](#attach-a-repl "Direct link to Attach a REPL")

`wdio repl --session <name>` attaches to a session that is already open and leaves it running when you exit:

```
npx wdio session open chrome https://webdriver.io

npx wdio repl --session default
```

Each REPL line runs as `wdio session exec`. `.exit` prints `Detached from "default" (still running)`.

## Doctor[​](#doctor "Direct link to Doctor")

`npx wdio session doctor` checks Node.js, the browser, Appium, SDKs and cloud credentials before you open a session. `doctor <target>` checks only what that target needs. The process exits 1 when a check fails. A session that is still starting is left in place. A session whose process is gone is removed.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

| Message                            | What to do                                                                                                     |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `Session closed from wdio session` | You closed the debug session. Use `resume` when the test should continue.                                      |
| No `debug-0-0` session             | The run has not paused yet, or it used a different worker id. `wdio session list` prints the names.            |
| The pause never happens            | The command must be `wdio run --debug=agent`. A passing test does not pause unless it calls `browser.debug()`. |

## Next steps[​](#next-steps "Direct link to Next steps")

* [Debugging](/docs/debugging.md) — `browser.debug()`, breakpoints and flaky tests
* [REPL](/docs/repl.md) — the interactive shell
* [wdio session](/docs/session.md) — open a session that is not attached to a test run