Interactive Debugging

Step through Apex tests with breakpoints, watch variables update in real time, and inspect the call stack directly inside VS Code. Interactive debugging pairs the aer runtime with the bundled aer Local Apex Debugger extension that ships with the CLI.

Prerequisites

• aer installed locally and accessible on your PATH
• VS Code 1.75 or newer with the code CLI available on your PATH
• aer test --debug automatically installs the aer Local Apex Debugger extension (octoberswimmer.aer-dap-client) the first time you run it—no manual VSIX install required
• A valid aer license for longer sessions (debug sessions without a license end after five minutes)

Initialize the debugger

From your project root, run aer test --debug with the same arguments you normally use for aer test:

aer test --debug force-app/main/default/classes

The command launches a guided setup that:

• Installs the VS Code extension if it is missing
• Generates .vscode/launch.json with a Debug Apex Tests configuration
• Opens VS Code (reusing the current window) so you can press F5 to start debugging

Re-run the command whenever you change arguments—aer will update the launch configuration automatically. --debug cannot be combined with --watch; switch back to aer test --watch after you finish debugging.

Configure VS Code

aer writes a launch configuration automatically. You usually do not need to touch it—rerun aer test --debug whenever you want to refresh the inputs. The generated file looks like this if you ever need to inspect or customize it:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "aer",
      "request": "launch",
      "name": "Debug Apex Tests",
      "aerPath": "/path/to/aer",
      "stopOnEntry": true,
      "args": [
        "force-app/main/default/classes",
        "--schema",
        "schema.gob"
      ]
    }
  ]
}

• aerPath is resolved automatically; change it only if you want to point at a different binary.
• Update the args array or rerun aer test --debug when you need to tweak paths, schema files, or package flags.
• Add optional keys such as timeout or stopOnEntry: false if you prefer different defaults.

Run an interactive session

1. Open the Apex test class you want to debug.
2. Set breakpoints in the editor gutter.
3. Select Debug Apex Tests in the Run and Debug view and press F5.

The Debug Console logs the adapter lifecycle (listening, waiting, attached). When execution pauses, use VS Code’s controls to step over (F10), step into (F11), or continue (F5). The VARIABLES pane shows locals, instance fields (This), and static members, all populated straight from the aer VM. Hover any identifier to peek its value, or add expressions to the WATCH panel (for example accounts.size()).

Want to debug anonymous Apex instead of tests? Launch VS Code via aer exec --debug force-app/main/default --exec "...". The CLI reuses the same extension, generates a separate Debug Anonymous Apex configuration, and opens the editor ready to pause in your snippet.

Use the Debug Console for quick evaluations:

sum
Test.isRunningTest()
accounts[0].Name

Tips and troubleshooting

• Breakpoints appear gray until the file loads; they turn solid red once verified.
• Keep an eye on the DEBUG CONSOLE for startup errors such as “Failed to start aer”.
• If the debugger times out immediately, verify the target directory contains tests by running aer test from the terminal.
• Sessions that extend beyond five minutes require an active aer license; otherwise the adapter stops the run.
• If the CLI reports that port 4711 is in use, end the process holding that port and rerun aer test --debug.

Interactive debugging works alongside watch mode: use aer test --watch for rapid feedback while editing and start a debug session when you need to inspect state at specific breakpoints.