---
name: debug-surefire
description: Debug Maven Surefire unit tests by running them in JDWP "wait for debugger" mode (`-Dmaven.surefire.debug`) and attaching to the forked test JVM using **jdb** (preferred for CLI/agent debugging), IntelliJ, or VS Code. Use when asked to debug/step through a failing JUnit test, attach a debugger to a Maven test run, or run `mvn test -Dtest=Class[#method]` suspended on a port (including multi-module `-pl` runs). The JVM will block at startup until a debugger attaches; the agent should attach with `jdb -attach <host>:<port>` and drive the session from the terminal.
---

# debug-surefire

Run Maven Surefire tests **suspended in JDWP** so you can attach a debugger and step through the code.  
In headless/agent environments, **attach with `jdb`** (the JDK’s command-line debugger).

## What this does

- Runs `mvn test` with Surefire in debug mode via `-Dmaven.surefire.debug`.
- Surefire launches the **forked test JVM** with a JDWP socket and `suspend=y`, meaning:
  - the forked JVM starts,
  - prints “Listening for transport dt_socket at address: <port>”,
  - then **waits** until a debugger attaches,
  - only then does it begin executing tests.

This is important: you do **not** attach to the `mvn` process itself; you attach to the **forked JVM** running the tests.

## Quick start

1) Start a suspended test run

- Debug a test class:
  - `.codex/skills/debug-surefire/scripts/debug-surefire.sh --test-class MyTest`
- Debug a single test method (quote the `#`):
  - `.codex/skills/debug-surefire/scripts/debug-surefire.sh --test 'MyTest#shouldDoThing'`
- Debug a test in a specific module:
  - `.codex/skills/debug-surefire/scripts/debug-surefire.sh --module core/sail/shacl --test-class ShaclSailTest`
  - `.codex/skills/debug-surefire/scripts/debug-surefire.sh --module rdf4j-sail-shacl --test 'ShaclSailTest#testSomething'`

When the forked JVM is ready, you should see something like:

- `Listening for transport dt_socket at address: 55005`

2) Attach with `jdb` (preferred)

In a second terminal, attach to the printed port:

- Local attach (port only implies localhost):
  - `jdb -attach 55005`
- Explicit host+port:
  - `jdb -attach localhost:55005`

If you need source listing inside jdb, provide a sourcepath up front:

- `jdb -sourcepath module/src/main/java:module/src/test/java -attach 55005`

3) Set breakpoints / catches, then resume

Once you’re at the `jdb` prompt, set a breakpoint (or exception catch) and continue:

- `stop in com.example.MyTest.shouldDoThing`
- `catch uncaught java.lang.AssertionError`
- `cont`

Tip: right after attaching to a just-started suspended JVM, `jdb` may show:
- `No frames on the current call stack`

That’s normal. The JVM hasn’t executed into any Java frames yet. Set breakpoints first, then `cont`.

---

## Notes

- The script runs a fast pre-test install (`-Pquick` into the repo-local `.m2_repo`) and then runs `mvn test` with Surefire in debug mode.
- Use `SUREFIRE_DEBUG_PORT=8000` to change the port (default: `55005`).
- Use `--no-offline` / `--online` if offline (`-o`) resolution fails.
- Everything after `--` is passed to Maven, e.g.:
  - `.codex/skills/debug-surefire/scripts/debug-surefire.sh --test-class MyTest -- -DtrimStackTrace=false -DfailIfNoTests=false -DforkCount=1 -DreuseForks=false`

---

## jdb interaction guide

This section is optimized for quickly getting signal from a failing unit test without drowning in framework/JDK internals.

### Command cheat sheet (the ones you’ll actually use)

**Start / resume**
- `cont` — continue execution from current stop/breakpoint
- `run` — start execution *when jdb launched the VM* (less relevant when you used `-attach`)

**Breakpoints**
- `stop in <class>.<method>` — break on method entry
- `stop at <class>:<line>` — break at a specific line
- `stop` — list all breakpoints
- `clear <class>.<method>` / `clear <class>:<line>` — remove a breakpoint
- `clear` — list breakpoints (same idea as `stop` listing)

**Stepping**
- `next` — step over calls (line-level)
- `step` — step into calls (line-level)
- `step up` — run until current method returns
- `stepi` — step one bytecode instruction (rarely needed)

**Threads / stacks**
- `threads` — list threads
- `thread <id>` — select default thread
- `where` — stack trace for current thread
- `where all` — stack traces for all threads
- `up` / `down` — move the current frame up/down the stack

**Inspect state**
- `locals` — print locals in current frame
- `print <expr>` — evaluate/print an expression (same as `eval`)
- `dump <expr>` — more complete object dump
- `set <lvalue> = <expr>` — mutate a variable/field (use sparingly)

**Source**
- `list` — show source around current line
- `list <line>` or `list <method>` — show a specific region
- `use <path1>:<path2>` (aka `sourcepath`) — set where jdb looks for sources

**Exceptions**
- `catch uncaught <exception>` — break when an uncaught exception occurs
- `catch caught <exception>` — break when a caught exception occurs
- `catch all <exception>` — break for both caught+uncaught
- `ignore ...` — undo a catch

**Reduce noise**
- `exclude <pattern>,<pattern>,...` — don’t report step/method events for matching classes
- `exclude none` — clear exclusions

**Automation**
- `monitor <command>` — run a command every time the program stops (e.g., `monitor where`)
- `read <file>` — execute commands from a file
- `!!` — repeat last command
- `<n> <command>` — repeat command n times (e.g., `10 next`)

### Efficient workflow for failing JUnit tests

#### 1) Add exclusions immediately (so stepping doesn’t become a swamp)

Right after connecting, set exclusions to avoid stepping into JDK/framework code:

- `exclude java.*,javax.*,jdk.*,sun.*,com.sun.*,org.junit.*,org.junit.jupiter.*,org.assertj.*,org.hamcrest.*,org.mockito.*,org.apache.maven.*`

You can always clear this later:

- `exclude none`

#### 2) Break where it matters

Common breakpoint patterns:

- Break at the failing test method:
  - `stop in com.example.MyTest.shouldDoThing`

- Break inside the code under test:
  - `stop in com.example.service.FooService.doWork`

- Break at a specific suspicious line:
  - `stop at com.example.service.FooService:123`

If the method is overloaded, specify argument types:

- `stop in com.example.FooService.doWork(int,java.lang.String)`

Note: `jdb` supports **deferred breakpoints**. If the class isn’t loaded yet, it will still accept the breakpoint and activate it when the class loads.

#### 3) Break on the *failure*, not just your guess

For unit tests, breaking on the thrown assertion/error is often faster than guessing a line.

Useful catches:

- Classic Java assertions / many test failures:
  - `catch uncaught java.lang.AssertionError`

- Common in JUnit 5 assertions:
  - `catch uncaught org.opentest4j.AssertionFailedError`

- NPE hunting:
  - `catch uncaught java.lang.NullPointerException`

You can remove a catch with `ignore`:

- `ignore uncaught java.lang.AssertionError`

Tip: `catch all java.lang.Throwable` is the nuclear option. It works, but it can get loud.

#### 4) Resume and drive

Once breakpoints/catches are set:

- `cont`

When you hit a breakpoint:

- `where` to see the call stack
- `list` to see nearby source
- `locals` to see local variables
- `print someVar` or `print this.someField` to inspect
- `next` to step over, `step` to step into

#### 5) Find the “real” test thread quickly

Surefire + JUnit can spin up multiple threads (and Maven itself has its own). When in doubt:

- `threads`
- `where all`

Then pick the thread that’s in your test/code-under-test:

- `thread <id>`
- `where`

#### 6) Keep the JVM count predictable

Surefire forking and parallelism can make debugging confusing. If you see multiple JVMs / inconsistent behavior, pass Maven flags to keep it single and fresh:

- `-DforkCount=1 -DreuseForks=false`

Example:

- `.codex/skills/debug-surefire/scripts/debug-surefire.sh --test 'MyTest#shouldDoThing' -- -DforkCount=1 -DreuseForks=false`

#### 7) Use “thread-only” breakpoints when concurrency matters

By default, `jdb` breakpoints suspend all threads, which can create deadlocks in concurrent tests. You can tell jdb to suspend only the thread that hits the breakpoint:

- `stop thread in com.example.concurrent.Worker.run`

(You can also target a specific thread id with `stop thread <thread_id> in ...` if needed.)

---

## jdb startup customization (optional but powerful)

jdb will execute startup commands from `jdb.ini` or `.jdbrc` in either `user.home` or `user.dir`.

This is handy for keeping your default exclusions/catches consistent, e.g.:

- `exclude java.*,javax.*,jdk.*,sun.*,com.sun.*,org.junit.*,org.assertj.*`
- `catch uncaught java.lang.AssertionError`

You can also keep a project-local command file and load it on demand:

- `read .codex/skills/debug-surefire/jdb.cmds`

---

## Troubleshooting

- **jdb can’t connect**
  - Confirm the port printed by the suspended JVM matches what you used in `jdb -attach`.
  - Confirm you’re attaching to the forked JVM port (the one that prints “Listening for transport…”), not Maven’s PID.
  - If running remotely (CI box / container / VM), ensure the port is reachable or forwarded.

- **Breakpoints don’t hit**
  - Use fully qualified class names.
  - If overloaded, include argument types.
  - Use `classes` to see what’s loaded.
  - Try `stop at <class>:<line>` to avoid signature mismatch.

- **`list` can’t find source**
  - Set sourcepath:
    - `use module/src/main/java:module/src/test/java`
  - Or launch jdb with `-sourcepath ...` from the start.