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.88 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/

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/"
      ]
    }
  ]
}

• 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 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 -p force-app "MyClass.myMethod();". 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

Run tests from the Testing view

The extension registers your Apex tests with VS Code’s Testing view, so you can run, debug, and watch tests without leaving the editor. Four run profiles are available:

• Run Apex Tests runs the selected tests.
• Run Apex Tests with Coverage runs them with aer test --coverage and reports covered and uncovered lines to VS Code. Covered lines are marked in the editor gutter and summarized in the Test Coverage view. Unit and integration selections merge, with a line counted as covered when either run executed it.
• Debug Apex Tests starts the selected tests under the debugger with the same source paths and flags the Testing view uses.
• Watch Apex Tests re-runs the selected tests as files change.

Project settings from sfdx-project.json

When aer.useSfdxProject is enabled, which is the default, the extension reads sfdx-project.json at or above the workspace and derives its configuration from it:

• packageDirectories become the source paths passed to the language server, test runner, watch mode, and debugger.
• namespace becomes the default namespace.
• replacements are applied by staging source into a temporary directory before running, matching what sf project deploy start would deploy. Failure locations map back to the real files, and in watch mode edits are mirrored into the staging directory.
• Each package directory’s unpackagedMetadata.path is loaded alongside the packaged source, so tests compile and run against that metadata.
• apexTestAccess.permissionSets are passed to aer as --assign-perms, combined with the aer.assignPermissionSets setting.

Explicit aer.sourcePaths and aer.defaultNamespace settings take precedence over the values derived from sfdx-project.json. Set aer.useSfdxProject to false in .vscode/settings.json to ignore the file entirely.

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.

Interactive debugging complements watch mode: reach for aer test --watch for rapid feedback while editing, and switch to a debug session when you need to inspect state at specific breakpoints.