Debug Surefire

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